Package 'FIMS'

Description

Returns a tidy tibble of observed-vs-expected pairs drawn from the output of get_estimates(). Only rows that have both an observed value and a model-expected value are included (i.e. data-likelihood rows), so parameter rows without data observations are automatically dropped.

Usage

## S3 method for class 'FIMSFit'
augment(x, include_weights = TRUE, ...)

Arguments

Details

The returned tibble follows the conventions expected by every yardstick::metric_set() metric function:

Value

A tibble::tibble() with at least the columns .truth, .pred, and optional .weight, plus grouping-metadata columns.

See Also

get_fit_metrics(), get_estimates(), yardstick::metrics()

Examples

## Not run: 
data("data_big")
data_4_model <- FIMSFrame(data_big)

fit <- setup_default_parameters(
  data = data_4_model
) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Tidy tibble of observed vs. expected, ready for any yardstick metric
augment(fit)

## End(Not run)

Description

Calculates Mohn's rho, a diagnostic statistic that summarizes the bias in retrospective analysis. The statistic measures the average relative difference between estimates from retrospective peels and the reference model at the corresponding terminal year of each peel. A value close to zero suggests minimal retrospective bias, while larger absolute values indicate potential model misspecification or data conflicts.

The formula for Mohn's rho is:

$\rho = \frac{1}{n} \sum_{i=1}^{n} \frac{x_{peel,i} - x_{base,i}}{x_{base,i}}$

where n is the number of retrospective peels, $x_{peel,i}$ is the estimated value from peel i at its terminal year, and $x_{base,i}$ is the value from the base model at that same year.

Usage

calculate_mohns_rho(retro_fit, quantity)

Arguments

Details

Calculate Mohn's rho for retrospective analysis

Value

A numeric value representing Mohn's rho. Values close to zero indicate minimal retrospective bias. Positive values mean that, on average, each peel's terminal-year estimate is higher than the reference model's estimate for the same year (retrospective overestimation), while negative values mean retrospective underestimation.

References

Mohn (1999). The retrospective problem in sequential population analysis: An investigation using cod fishery and simulated data. ICES Journal of Marine Science, 56(4), 473-488. https://doi.org/10.1006/jmsc.1999.0481.

Hurtado-Ferro et al. (2015). Looking in the rear-view mirror: bias and retrospective patterns in integrated, age-structured stock assessment models. ICES Journal of Marine Science, 72(1), 99-110. https://doi.org/10.1093/icesjms/fsu198.

Examples

## Not run: 
library(FIMS)
# Use built-in dataset from FIMS
data("data_big")
# Prepare data for FIMS model
data_4_model <- FIMSFrame(data_big)
# Create parameters
parameters <- setup_default_parameters(data = data_4_model)

# Run retrospective analysis
retro_fit <- run_fims_retrospective(
  years_to_remove = 0:5,
  data = data_big,
  parameters = parameters,
  n_cores = 1
)

# Calculate Mohn's rho for spawning biomass
rho_ssb <- calculate_mohns_rho(retro_fit, quantity = "spawning_biomass")

# Calculate Mohn's rho for recruitment
rho_rec <- calculate_mohns_rho(retro_fit, quantity = "expected_recruitment")

## End(Not run)

Description

The following classes are exported from C++ via Rcpp. Their documentation is provided in the rendered C++ documentation. For detailed usage, see the C++ docs.

Details

• AgeComp

• BevertonHoltRecruitment

• CatchAtAge

• DlnormDistribution

• DmultinomDistribution

• DnormDistribution

• DoubleLogisticSelectivity

• EWAAGrowth

• VonBertalanffySchnuteGrowth

• Fleet

• Index

• Catch

• LengthComp

• LogDevsRecruitmentProcess

• LogRRecruitmentProcess

• LogisticMaturity

• LogisticSelectivity

• Population

• RealVector

• SharedInt

• SharedReal

• SharedString

• Variable

• VariableVector

C++ Documentation

NOAA-FIMS C++ Documentation

Description

The following functions are exported from C++ via Rcpp. Their documentation is provided in the rendered C++ documentation. For detailed usage, see the C++ docs.

Details

• clear

• get_fixed

• get_log

• get_log_errors

• get_log_warnings

• get_parameter_names

• get_random

• get_random_names

• inv_logit

• log_error

• log_info

• log_warning

• logit

• set_fixed

• set_log_throw_on_error

• set_random

• CreateTMBModel

C++ Documentation

NOAA-FIMS C++ Documentation

Description

A data frame containing the information needed to run an age-structured stock assessment model in FIMS. This data was generated using the ASSAMC package written for the model comparison project. The source code to make this dataset is in data-raw/data_big.R which is on GitHub but will not be in your local installation because it is in the .Rbuildignore file.

Usage

data_big

Format

A data frame with 2808 observations of 8 variables:

type

The type of input the row contains. Allowed types include age_comp, age_to_length_conversion, index, catch, length_bin, length_comp, and weight_at_age.

fleet

A character string providing the name of the information source that the input was collected from, e.g., "Trawl fishery" or "age_zero_survey". Entries can be NA for information that is not fleet/vessel specific.

age

An integer age. Entry can be NA if information pertains to multiple ages, e.g., total catch rather than catch of age-4 fish. In this dataset, ages start at one, therefore recruitment happens at age one not age zero.

length

A numeric length. Entry can be NA if information doesn't pertain to length. For length_comp rows, this identifies the observed length bin. For length_bin rows, this defines length-bin values used for age-to-length conversion.

timing

The timing, i.e., year the data was collected.

observed

The observed measurement of interest.

unit

A character string specifying the units of observed. Allowed units for each data type are as follows. mt is used for index, catch, and weight_at_age data. number or proportion are each viable units for the composition data, where the former is the preferred unit of measurement.

uncertainty

A right-handed formula specifying the distributional assumptions for the entry in observed. See FIMSFrame() for more information about this column.

Source

www.github.com/NOAA-FIMS/Age_Structured_Stock_Assessment_Model_Comparison

See Also

• FIMSFrame()

Description

A lookup table that maps each supported distribution family to the field name used to link observed data, the random-value generator, and the remaining parameter names for that family.

Usage

fims_distributions

Format

A data frame with columns family, sample_function, central_parameter, and other_parameters. sample_function is a character column with function names.

Description

A vector of strings that define which input types are allowed in the column labeled type in the data slot of a FIMSFrame object. Strings are composed of words separated by underscores, e.g., "weight_at_age".

Usage

fims_input_types

Format

A vector of strings.

Description

Create an object with the class of FIMSFit after running a FIMS model. This is typically done within fit_fims() but it can be create manually by the user if they have used their own bespoke code to fit a FIMS model.

Usage

FIMSFit(
  input,
  obj,
  opt = list(),
  sdreport = list(),
  run_time = c(time_total = as.difftime(0, units = "secs")),
  version = utils::packageVersion("FIMS")
)

Arguments

Value

An object with an S4 class of FIMSFit is returned. The object will have the following slots:

input:

A list containing the model setup in the same form it was passed.

obj:

A list returned from TMB::MakeADFun() in the same form it was passed.

opt:

A list containing the optimized model in the same form it was passed.

max_gradient:

The maximum gradient found when optimizing the model. The default is NA, which means that the model was not optimized.

report:

A list containing the model report from obj[["report"]]().

sdreport:

An object with the sdreport class containing the output from TMB::sdreport(obj).

run_time:

The length of time it took to run the model if it was optimized.

version:

The package version of FIMS used to fit the model or at least the version used to create this output, which will not always be the same if you are running this function yourself.

model_output:

The FIMS model output as a JSON string.

Description

All constructor functions take a single input and build an object specific to the needs of each model type within FIMS. FIMSFrame is the parent class. Future, associated child classes will have the additional slots needed for different types of models.

Usage

FIMSFrame(data)

Arguments

Details

data

The input data are both sorted (see the section below on sorting) and expanded to include -999 observations for all missing rows before returning them in the data slot.

Ages

Currently, ages must be integers, i.e., FIMS cannot accommodate numeric ages like age 1.5 but we hope that this is something that we will be able to accommodate in the future. Additionally, the first age in your data set will be the age at which fish recruit to the population. So, if you do not have age-0 age compositions and age two is the first age you have in your composition data, then recruitment will happen at age two. Furthermore, you must have composition entries for every integer between your first and last age in the model. For example, you cannot bin fish into bins that span multiple years, you must have age-2, age-3, and age-4 not just age-2 and age-4 fish in your composition data.

Uncertainty

Uncertainty information for your data contains information for fitting the model and for creating bootstrapped data sets. Right-handed formulas are used to specify the distribution your data is assumed to follow, the derived quantity in the model that the data is assumed to represent, and parameters associated with the assumed distribution. For example, catch data can be distributed using a normal or lognormal distribution and if you use a normal distribution the observation is assumed to represent catch_expected but if you use a lognormal distribution the observation is assumed to represent log_catch_expected. Therefore, for the former you would specify "~dnorm(mean = catch_expected, sd = 0.01)" and for the later you would specify "~dlnorm(meanlog = log_catch_expected, sdlog = 0.01)". Where, the input value for sd or sdlog is the standard deviation of the mean or standard deviation of the log of the mean, respectively. The distribution names and argument names match the names used in R. Use args(), e.g., args(dnorm), to get information on the argument names that are required for your distribution. And, use ?distributions to get a list of distributions that have density functions in base R. To get information on available derived quantities to set the central tendency of the distribution to, you can create a fleet object and inspect the available names, e.g., names(methods::new(Fleet)), or you can navigate to the Public Attributes section of the doxygen documentation for Fleet by running ?Fleet.

Sorting

It is important that the order of the rows in the data are correct but it is not expected that the user will do this. Instead, the returned data are sorted using dplyr::arrange() before placing them in the data slot. Data are first sorted by data type, placing all weight_at_age data next to other weight_at_age data and all catch data next to catch data. Thus, age_comp data will come first because their type is "age" and "a" is first in the alphabet. All other types will follow according to their order in the alphabet. Next, within each type, data are organized by fleet. So, age_comp information for fleet1 will come before survey1. Next, all data within type and fleet are arranged by timing, e.g., by year. That is the end of the sorting for time series data like catch and indices. The biological data are further sorted by bin. Thus, age_comp information will be arranged as follows:

length_comp data are sorted the same way but by length bin instead of by age bin. It becomes more complicated for the age_to_length_conversion data, which are sorted by type, name, timing, age, and then length. So, a full set of length, e.g., length 10, length 20, length 30, etc., is placed together for a given age. After that age, another entire set of length information will be provided for that next age. Once the year is complete for a given fleet then the next year will begin.

Value

An object of the S4 class FIMSFrame class, or one of its child classes, is validated and then returned. All objects will at a minimum have a slot called data to store the input data frame. Additional slots are dependent on the child class. Use methods::showClass() to see all available slots.

See Also

plot,FIMSFrame,missing-method() for plotting FIMSFrame objects.

Description

Fit a FIMS model (BETA)

Usage

fit_fims(
  input,
  get_sd = TRUE,
  save_sd = TRUE,
  number_of_loops = 3,
  optimize = TRUE,
  number_of_newton_steps = 0,
  control = list(eval.max = 10000, iter.max = 10000, trace = 0),
  filename = NULL,
  getReportCovariance = FALSE
)

Arguments

Details

This function is a beta version still and subject to change without warning.

Value

An object of class FIMSFit is returned, where the structure is the same regardless if optimize = TRUE or not. Uncertainty information is only included in the estimates slot if get_sd = TRUE.

See Also

• FIMSFit()

Description

There is an accessor function for each slot in the S4 class FIMSFit, where the function is named ⁠get_*()⁠ and the star can be replaced with the slot name, e.g., get_input(). These accessor functions are the preferred way to access objects stored in the available slots.

Usage

get_input(x)

## S4 method for signature 'FIMSFit'
get_input(x)

get_report(x)

## S4 method for signature 'FIMSFit'
get_report(x)

get_obj(x)

## S4 method for signature 'FIMSFit'
get_obj(x)

get_opt(x)

## S4 method for signature 'FIMSFit'
get_opt(x)

get_max_gradient(x)

## S4 method for signature 'FIMSFit'
get_max_gradient(x)

get_gradient(x)

## S4 method for signature 'FIMSFit'
get_gradient(x)

get_sdreport(x)

## S4 method for signature 'FIMSFit'
get_sdreport(x)

get_estimates(x)

## S4 method for signature 'FIMSFit'
get_estimates(x)

get_number_of_parameters(x)

## S4 method for signature 'FIMSFit'
get_number_of_parameters(x)

get_run_time(x)

## S4 method for signature 'FIMSFit'
get_run_time(x)

get_version(x)

## S4 method for signature 'FIMSFit'
get_version(x)

get_model_output(x)

## S4 method for signature 'FIMSFit'
get_model_output(x)

Arguments

Value

get_input() returns the list that was used to fit the FIMS model, which is the returned object from setup_default_parameters().

get_report() returns the TMB report, where anything that is flagged as reportable in the C++ code is returned.

get_obj() returns the output from TMB::MakeADFun().

get_opt() returns the output from nlminb(), which is the minimizer used in fit_fims().

get_max_gradient() returns the maximum gradient found when optimizing the model.

get_gradient() returns the per-parameter gradient vector at the MLE as stored during fitting. Unlike calling get_obj(x)[["gr"]](get_opt(x)[["par"]]) this function is safe to call after clear() because it reads from a stored R vector rather than the compiled C++ objective function.

get_sdreport() returns the list from TMB::sdreport().

get_estimates() returns a tibble of parameter values and their uncertainties from a fitted model.

get_number_of_parameters() returns a vector of integers specifying the number of fixed-effect parameters and the number of random-effect parameters in the model.

get_run_time() returns the amount of time it took to run the model in seconds as a difftime object.

get_version() returns the package_version of FIMS that was used to fit the model.

get_model_output() returns the finalized FIMS output as a JSON list.

See Also

• fit_fims()

• setup_default_parameters()

Description

There is an accessor function for each slot in the S4 class FIMSFrame, where the function is named ⁠get_*()⁠ and the star can be replaced with the slot name, e.g., get_data(). These accessor functions are the preferred way to access objects stored in the available slots.

Usage

get_data(x)

## S4 method for signature 'FIMSFrame'
get_data(x)

## S4 method for signature 'data.frame'
get_data(x)

get_fleets(x)

## S4 method for signature 'FIMSFrame'
get_fleets(x)

## S4 method for signature 'data.frame'
get_fleets(x)

get_n_fleets(x)

## S4 method for signature 'FIMSFrame'
get_n_fleets(x)

## S4 method for signature 'data.frame'
get_n_fleets(x)

get_n_years(x)

## S4 method for signature 'FIMSFrame'
get_n_years(x)

## S4 method for signature 'data.frame'
get_n_years(x)

get_start_year(x)

## S4 method for signature 'FIMSFrame'
get_start_year(x)

## S4 method for signature 'data.frame'
get_start_year(x)

get_end_year(x)

## S4 method for signature 'FIMSFrame'
get_end_year(x)

## S4 method for signature 'data.frame'
get_end_year(x)

get_ages(x)

## S4 method for signature 'FIMSFrame'
get_ages(x)

## S4 method for signature 'data.frame'
get_ages(x)

get_n_ages(x)

## S4 method for signature 'FIMSFrame'
get_n_ages(x)

## S4 method for signature 'data.frame'
get_n_ages(x)

get_lengths(x)

## S4 method for signature 'FIMSFrame'
get_lengths(x)

## S4 method for signature 'data.frame'
get_lengths(x)

get_n_lengths(x)

## S4 method for signature 'FIMSFrame'
get_n_lengths(x)

## S4 method for signature 'data.frame'
get_n_lengths(x)

Arguments

Value

get_data() returns a data frame of the class tbl_df containing data for a FIMS model in a long format. The tibble will potentially have the following columns depending if it fits to ages and lengths or just one of them: type, fleet, age, length, timing, observed, unit, and uncertainty.

get_fleets() returns a vector of strings containing the fleet names.

get_n_fleets() returns an integer specifying the number of fleets in the model, where fleets is inclusive of both fishing fleets and survey vessels.

get_n_years() returns an integer specifying the number of years in the model.

get_start_year() returns an integer specifying the start year of the model.

get_end_year() returns an integer specifying the end year of the model.

get_ages() returns a vector of age bins used in the model.

get_n_ages() returns an integer specifying the number of age bins used in the model.

get_lengths() returns a vector of length bins used in the model.

get_n_lengths() returns an integer specifying the number of length bins used in the model.

Description

Extracts observed-vs-expected pairs from a FIMSFit object via augment.FIMSFit() and evaluates a yardstick::metric_set() over them.

Usage

get_fit_metrics(
  x,
  metrics = yardstick::metric_set(yardstick::rmse, yardstick::mae, yardstick::rsq),
  group_by = NULL,
  weighted = FALSE,
  ...
)

Arguments

Details

By default the metrics are computed over all data streams combined. Pass one or more column names to group_by to get per-stream breakdowns (e.g., group_by = "label" gives one row per data-stream label such as "catch_expected", "age_comp_expected", etc.).

Value

A tibble::tibble() in the standard yardstick result format: columns .metric, .estimator, .estimate, plus any grouping columns.

See Also

augment.FIMSFit(), yardstick::metric_set()

Examples

## Not run: 
data("data_big")
data_4_model <- FIMSFrame(data_big)

fit <- setup_default_parameters(
  data = data_4_model
) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Overall RMSE / MAE / R^2 across all data streams
get_fit_metrics(fit)

# Per-data-stream: one row-set per label
# (e.g. "catch_expected", "index_expected", "age_comp_expected")
get_fit_metrics(fit, group_by = "label")

# Per-fleet with a custom metric set
get_fit_metrics(
  fit,
  metrics  = yardstick::metric_set(yardstick::rmse, yardstick::mape),
  group_by = "fleet"
)

# Inverse-variance weighted metrics
get_fit_metrics(fit, weighted = TRUE)

## End(Not run)

Description

Convenience filter to pull out one specific data stream (e.g. the catch for a given module) so you can pass it directly to any yardstick metric or plot it.

Usage

get_fit_stream(x, stream_label = NULL, module_id = NULL, ...)

Arguments

Details

Fleets and surveys can be told apart by the fleet column, which holds the fleet name from the data, or by module_id, where, e.g., module_id == 1 is the first fishing fleet and module_id == 2 is the first survey in the FIMS vignettes. To discover which values are present in your fit, inspect augment(fit) directly.

Value

A tibble::tibble() subset of the augmented data.

Examples

## Not run: 
data("data_big")
data_4_model <- FIMSFrame(data_big)

fit <- setup_default_parameters(
  data = data_4_model
) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Catch for the fishing fleet (module_id 1) - compute RMSE
get_fit_stream(fit, stream_label = "catch_expected", module_id = 1) |>
  yardstick::rmse(truth = .truth, estimate = .pred)

# Survey index stream (module_id 2 in the data_big example)
get_fit_stream(fit, stream_label = "index_expected", module_id = 2)

# All streams for fleet 1 (catch + age comp + length comp)
get_fit_stream(fit, module_id = 1)

## End(Not run)

Description

Returns a single-row tibble of model-level diagnostics following the generics::glance() convention. Standard information-criterion columns (logLik, AIC, BIC, nobs) are included alongside FIMS-specific diagnostics (max_gradient, marginal_nll, total_nll, converged, terminal_ssb).

Usage

## S3 method for class 'FIMSFit'
glance(x, ...)

Arguments

Value

A tibble::tibble() with one row and the following columns:

logLik

Marginal log-likelihood at the MLE (-opt$objective).

AIC

Akaike information criterion (marginal, fixed effects only).

BIC

Bayesian information criterion (marginal, fixed effects only).

nobs

Total number of data observations (rows with both an observed and an expected value in get_estimates()).

npar_fixed

Number of fixed-effect parameters.

npar_random

Number of random-effect parameters.

marginal_nll

Marginal negative log-likelihood (opt$objective); NA if the model was not optimized.

total_nll

Total (joint) negative log-likelihood from the TMB report (report$jnll).

max_gradient

Maximum absolute gradient at the MLE. Values below 0.001 are generally considered well-converged.

converged

Logical; TRUE when opt$convergence == 0 and max_gradient < 0.001.

terminal_ssb

Spawning stock biomass at the terminal year, extracted from the TMB report. Returns a list-column when multiple populations are present.

fims_version

The version of FIMS used to fit the model.

run_time

Total wall-clock time of the fit in seconds.

Information criteria

AIC and BIC are computed from the marginal log-likelihood (i.e. after integrating out random effects), using the number of fixed-effect parameters as $k$:

$AIC = 2k - 2 \ell_m$

$BIC = k \log(n) - 2 \ell_m$

where $\ell_m$ is the marginal log-likelihood and $n$ is the total number of data observations. These values will be NA when optimize = FALSE was passed to fit_fims().

See Also

tidy.FIMSFit(), get_estimates(), fit_fims()

Examples

## Not run: 
data("data_big")
data_4_model <- FIMSFrame(data_big)

fit <- setup_default_parameters(data = data_4_model) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

glance(fit)

# Compare sensitivity runs in one table
dplyr::bind_rows(
  glance(age_only_fit) |> dplyr::mutate(model = "age_only"),
  glance(length_only_fit) |> dplyr::mutate(model = "length_only")
)

## End(Not run)

Description

Use methods::new() to set up a distribution within an existing module with the necessary linkages between the two. For example, a fleet module will need a distributional assumption for parts of the data associated with it, which requires the use of initialize_data_distribution().

Usage

initialize_data_distribution(
  module,
  data_type = c("catch", "index", "age_comp", "length_comp"),
  uncertainty
)

Arguments

Value

A reference class. is returned. Use methods::show() to view the various Rcpp class fields, methods, and documentation.

See Also

• initialize_process_distribution()

Examples

## Not run: 
# Set up a new data distribution
n_years <- 30
# Create a new fleet module
fleet <- methods::new(Fleet)
# Create a distribution for the fleet module
sd_log <- rep(sqrt(log(0.01^2 + 1)), n_years)
fleet_distribution <- initialize_data_distribution(
  module = fishing_fleet,
  uncertainty = glue::glue(
    "~dlnorm(meanlog = log_index_expected, sdlog = {sd_log})"
  ),
  data_type = "index"
)

## End(Not run)

Description

This function uses information from a parameter data frame that stores the model specifications and aFIMSFrame object that stores the data to instantiate, i.e., create an instance of a class, the required C++ modules. Several C++ modules are needed to run a FIMS model and the required modules will be different for each model type. For example, for a catch-at-age model one needs to instantiate recruitment, growth, and maturity modules and at least one fleet and population module.

Usage

initialize_fims(parameters, data)

Arguments

Value

A list is returned with two elements, parameters and model. The list can be passed to the input argument of fit_fims() to fit the model. The first element of the list can also be passed to the parameters argument of TMB::MakeADFun() if you wish to have more control over the model-fitting process. The model element of the returned list stores the instantiated C++ model module, e.g., the results of methods::new(CatchAtAge) for a catch-at-age model. It is important that you only have one FIMS model initialized in your R workspace at a time. Thus, after you initialize and fit the model, you should run clear().

See Also

• setup_default_parameters()

• FIMSFrame()

• fit_fims()

• clear()

Examples

## Not run: 
# Prepare data for FIMS model
data("data_big", package = "FIMS")
data_4_model <- FIMSFrame(data_big)
# Instantiate modules
parameters_list <- setup_default_parameters(data = data_4_model) |>
  initialize_fims(data = data_4_model)
clear()

## End(Not run)

Description

Use methods::new() to set up a distribution within an existing module with the necessary linkages between the two. For example, a recruitment module, like the Beverton–Holt stock–recruit relationship, will need a distribution associated with the recruitment deviations.

Usage

initialize_process_distribution(
  module,
  par,
  family = NULL,
  sd = tibble::tibble(value = 1, estimation_type = "fixed_effects")
)

initialize_process_structure(module, par)

Arguments

Value

A reference class. is returned. Use methods::show() to view the various Rcpp class fields, methods, and documentation.

See Also

• initialize_data_distribution()

Examples

## Not run: 
# Set up a new process distribution
# Create a new recruitment module
recruitment <- methods::new(BevertonHoltRecruitment)
# view parameter names of the recruitment module
methods::show(BevertonHoltRecruitment)
# Create a distribution for the recruitment module
recruitment_distribution <- initialize_process_distribution(
  module = recruitment,
  par = "log_devs",
  family = gaussian(),
  sd = list(value = 0.4, estimation_type = "constant")
)

## End(Not run)

Description

Verbosity is set globally for FIMS using options(rlib_message_verbosity = "quiet") to stop the printing of messages from cli::cli_inform(). Using a global option allows for verbose to not have to be an argument to every function. All cli::cli_abort() messages are printed to the console no matter what the global option is set to.

Usage

is_fims_verbose()

Value

A logical is returned where TRUE ensures messages from cli::cli_inform() are printed to the console.

Examples

# function is not exported
## Not run: 
FIMS:::is_fims_verbose()

## End(Not run)

Description

Check if an object is of class FIMSFit

Usage

is.FIMSFit(x)

Arguments

Description

Family objects provide a convenient way to specify the details of the models used by functions such as stats::glm(). These functions within this package are not available within the stats package but are designed in a similar manner.

Usage

lognormal(link = "log")

multinomial(link = "logit")

Arguments

Value

An object of class family (which has a concise print method). This particular family has a truncated length compared to other distributions in stats::family().

See Also

• stats::family()

• stats::gaussian()

• stats::glm()

• stats::power()

• stats::make.link()

Examples

a_family <- multinomial()
a_family[["family"]]
a_family[["link"]]

Description

There is an accessor function for each data type needed to run a FIMS model. A FIMS model accepts vectors of data and thus each of the ⁠model_*()⁠ functions, where the star can be replaced with the data type separated by underscores, e.g., weight_at_age. These accessor functions are the preferred way to pass data to a FIMS module because the data will have the appropriate indexing.

Usage

model_catch(x, fleet)

## S4 method for signature 'FIMSFrame'
model_catch(x, fleet)

## S4 method for signature 'data.frame'
model_catch(x, fleet)

model_index(x, fleet)

## S4 method for signature 'FIMSFrame'
model_index(x, fleet)

## S4 method for signature 'data.frame'
model_index(x, fleet)

model_age_comp(x, fleet)

## S4 method for signature 'FIMSFrame'
model_age_comp(x, fleet)

## S4 method for signature 'data.frame'
model_age_comp(x, fleet)

model_length_comp(x, fleet)

## S4 method for signature 'FIMSFrame'
model_length_comp(x, fleet)

## S4 method for signature 'data.frame'
model_length_comp(x, fleet)

model_weight_at_age(x)

## S4 method for signature 'FIMSFrame'
model_weight_at_age(x)

## S4 method for signature 'data.frame'
model_weight_at_age(x)

model_age_to_length_conversion(x)

## S4 method for signature 'FIMSFrame'
model_age_to_length_conversion(x)

## S4 method for signature 'data.frame'
model_age_to_length_conversion(x)

Arguments

Details

Age_to_length_conversion data, i.e., the proportion of age "a" that are length "l", are used to convert lengths (input data) to ages (modeled) as a way to fit length data without estimating growth.

model_catch()

Returns a numeric vector of catch data (type "catch") for the specified fleet(s).

model_index()

Returns a numeric vector of index data (type "index") for the specified fleet(s).

model_age_comp()

Returns a numeric vector of age-composition data (type "age_comp") for the specified fleet(s).

model_length_comp()

Returns a numeric vector of length-composition data (type "length_comp") for the specified fleet(s). This accessor requires that age-to-length conversion data are present in the FIMSFrame object.

model_weight_at_age()

Returns a numeric vector of weight-at-age observations (type "weight_at_age"), ordered by age and year (plus one additional year) and using -999 to indicate missing observations When multiple fleets are present, values are averaged across fleets.

model_age_to_length_conversion()

Returns a numeric vector of age-to-length conversion observations. Observations are ordered by age and length in the order defined by FIMSFrame(). When multiple observations are present across a single age and length, they are averaged because age_to_length_conversion data cannot vary across fleets or time.

Value

All of the ⁠model_*()⁠ functions return vectors of data. Currently, the order of the data is the same order as the data frame because no arranging is done in FIMSFrame() and the function just extracts the appropriate column.

Description

Creates a visualization of likelihood profile results, displaying the change in log-likelihood as a function of a fixed parameter value. The plot shows profiles for different data components and the total likelihood, helping to assess parameter identifiability and uncertainty.

Usage

plot_likelihood(like_fit, group = "label")

Arguments

Details

Plot Likelihood Profile Results

The function generates line plots showing how the log-likelihood changes relative to its maximum value as a parameter is varied. Each data component (e.g., catch, index, age composition) is shown as a separate line, along with the total likelihood across all components. This reveals which data sources provide information about the parameter and whether there are conflicting signals.

The y-axis shows the change in log-likelihood from the maximum (best-fit) value. A parabolic shape indicates a well-identified parameter with symmetric uncertainty. Flat profiles suggest weak identifiability, while multiple local minima indicate potential convergence issues.

The plot automatically saves to "likelihood.png" in the current working directory in addition to returning a ggplot object that can be further customized. The total likelihood is shown in black as a solid line, while individual data components use colors from the viridis palette.

Value

A ggplot object displaying likelihood profiles. The plot includes:

• Line plots for each data component

• Total likelihood across all components (black solid line)

• Different colors (viridis palette) and line types for components

• X-axis showing the profiled parameter values

• Y-axis showing change in log-likelihood from maximum

• NOAA-themed styling via stockplotr::theme_noaa()

The plot is also automatically saved as "likelihood.png".

References

Venzon, D.J. and Moolgavkar, S.H. 1988. A method for computing profile-likelihood-based confidence intervals. Applied Statistics 37: 87-94.

Hilborn, R. and Mangel, M. 1997. The Ecological Detective: Confronting Models with Data. Princeton University Press.

See Also

• run_fims_likelihood() for running likelihood profile analysis

Other diagnostic_functions: run_fims_likelihood(), run_fims_retrospective()

Examples

## Not run: 
library(FIMS)

# Use built-in dataset from FIMS
data("data_big")
data_4_model <- FIMSFrame(data_big)

# Create parameters object
parameters <- setup_default_parameters(data = data_4_model)

# Run base model
base_model <- parameters |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Run likelihood profile
like_fit <- run_fims_likelihood(
  model = base_model,
  parameters = parameters,
  data = data_big,
  parameter_name = "log_rzero",
  n_cores = 3,
  min = -1,
  max = 1,
  length = 21
)

# Plot the likelihood profile
plot_likelihood(like_fit)

# Plot with custom grouping
plot_likelihood(like_fit, group = "label")

## End(Not run)

Description

Use ggplot2::geom_point() to plot summary information stored in the data slot of the FIMSFrame class.

Usage

## S4 method for signature 'FIMSFrame,missing'
plot(x, y, ...)

Arguments

Value

A ggplot2 object is returned that uses stockplotr::theme_noaa(). There will be one panel per input type with fleet-specific information denoted using colors.

Examples

## Not run: 
data("data_big", package = "FIMS")
data_4_model <- FIMSFrame(data_big)
plot(data_4_model)

## End(Not run)

Description

Intended for developers to remove test data to run the tests from fresh. Developers should run this function before testing if changes affect FIMS input or output.

Usage

remove_test_data()

Examples

## Not run: 
remove_test_data()

## End(Not run)

Description

This function processes the finalized FIMS JSON output and reshapes the parameter estimates into a structured tibble for easier analysis and manipulation.

Usage

reshape_json_estimates(model_output)

Arguments

Value

A tibble containing the reshaped parameter estimates. Parameters of distributions for random effects, e.g., log_sd of the recruitment deviations, are included with one row per parameter id under the module that owns the vector they apply to.

Description

This function processes the TMB std and reshapes them into a structured tibble for easier analysis and manipulation.

Usage

reshape_tmb_estimates(
  obj,
  sdreport = NULL,
  opt = NULL,
  parameter_names,
  precomputed_gradient = NULL
)

Arguments

Value

A tibble containing the reshaped estimates (i.e., parameters and derived quantities).

Description

Conducts likelihood profile analysis for a FIMS model by fixing a specified parameter at a range of values and re-optimizing all other parameters. This diagnostic tool helps assess parameter uncertainty, identifiability, and potential local minima in the likelihood surface.

Usage

run_fims_likelihood(
  model,
  parameters,
  data,
  module_name = NULL,
  parameter_name = "log_rzero",
  n_cores = NULL,
  min = -2,
  max = 2,
  length = 5
)

Arguments

Details

Run Likelihood Profile for a FIMS Model

Likelihood profiling involves systematically varying a parameter of interest across a range of values while optimizing all other parameters. At each fixed value, the negative log-likelihood is recorded, creating a profile of the likelihood surface. This reveals whether the parameter is well-estimated (sharp, parabolic profile) or poorly identified (flat profile), and can identify multiple modes or asymmetric confidence regions.

The function profiles over values specified relative to the estimated value from the base model. For example, with min = -2 and max = 2, the profile spans from 2 units below to 2 units above the estimated value. The profiled values are evenly spaced on the parameter scale (not log scale).

Models are run in parallel for computational efficiency. Use module_name when the same parameter label exists in more than 1 module. Parameters with more than 1 row in a module (for example, 1 per fleet, year, or age) cannot be profiled yet.

Value

A list with two named elements:

• vec - Numeric vector of parameter values used in the profile

• estimates - Data frame containing model estimates for each profiled value, with the following key columns:

  • label - Type of estimate (e.g., "spawning_biomass", "recruitment")

  • year_i - Year index for the estimate

  • age_i - Age index (if applicable)

  • estimated - Point estimate value

  • uncertainty - Standard error of the estimate

  • lpdf - Log probability density (negative log-likelihood component)

  • ⁠value_{parameter_name}⁠ - The fixed parameter value for this profile point

References

Venzon, D.J. and Moolgavkar, S.H. 1988. A method for computing profile-likelihood-based confidence intervals. Applied Statistics 37: 87-94.

Maunder, M.N. and Punt, A.E. 2013. A review of integrated analysis in fisheries stock assessment. Fisheries Research 142: 61-74.

See Also

• plot_likelihood() for visualizing likelihood profiles

• fit_fims() for fitting FIMS models

• setup_default_parameters() for creating parameter objects

Other diagnostic_functions: plot_likelihood(), run_fims_retrospective()

Examples

## Not run: 
library(FIMS)

# Use built-in dataset from FIMS
data("data_big")
data_4_model <- FIMSFrame(data_big)

# Create a parameters object
parameters <- setup_default_parameters(data = data_4_model)

# Run the base model with optimization
base_model <- parameters |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Run likelihood profile for log_rzero
like_fit <- run_fims_likelihood(
  model = base_model,
  parameters = parameters,
  data = data_big,
  parameter_name = "log_rzero",
  n_cores = 3,
  min = -1,
  max = 1,
  length = 21
)

# View the profiled parameter values
like_fit$vec

# View structure of estimates
head(like_fit$estimates)

## End(Not run)

Description

Performs retrospective analysis by fitting a FIMS model object multiple times, each time removing an increasing number of terminal years from the data. This diagnostic tool is used to detect retrospective patterns or bias in model estimates.

Usage

run_fims_retrospective(years_to_remove, data, parameters, n_cores = NULL)

Arguments

Details

Run Retrospective Analysis for a FIMS Model

Retrospective analysis involves refitting a model after sequentially removing one or more years of data from the end of the time series. This helps assess whether the model estimates are stable and whether there is a consistent pattern of revision as new data are added. The function runs models in parallel for computational efficiency.

The first element of years_to_remove should typically be 0 to represent the reference model with no data removed. This allows for direct comparison of retrospective peels to the base model.

Retrospective patterns can indicate model misspecification, time-varying processes not captured by the model, or data quality issues. Mohn's rho, calculated by calculate_mohns_rho(), provides a summary statistic for retrospective bias.

Value

A list with two named elements:

• years_to_remove - The input vector of years removed for each peel

• estimates - A data frame containing model estimates from all retrospective runs, with the following key columns:

  • label - Type of estimate (e.g., "spawning_biomass")

  • year_i - Year index for the estimate

  • age_i - Age index (if applicable)

  • estimated - Point estimate value

  • uncertainty - Standard error of the estimate

  • retrospective_peel - Number of years removed for this peel

References

Mohn, R. 1999. The retrospective problem in sequential population analysis: An investigation using cod fishery and simulated data. ICES Journal of Marine Science 56: 473-488.

Hurtado-Ferro, F., et al. 2015. Looking in the rear-view mirror: bias and retrospective patterns in integrated, age-structured stock assessment models. ICES Journal of Marine Science 72(1): 99-110.

See Also

• stockplotr::plot_spawning_biomass() for visualizing retrospective results

• calculate_mohns_rho() for calculating Mohn's rho statistic

• setup_default_parameters() for creating parameter objects

Other diagnostic_functions: plot_likelihood(), run_fims_likelihood()

Examples

## Not run: 
library(FIMS)

# Use built-in dataset from FIMS
data("data_big")
data_4_model <- FIMSFrame(data_big)

# Create a parameters object
parameters <- setup_default_parameters(data = data_4_model)

# Run base model
base_model <- parameters |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Run retrospective analysis with 5 peels
retro_fit <- run_fims_retrospective(
  years_to_remove = 0:5,
  data = data_big,
  parameters = parameters,
  n_cores = 1
)

# View structure of results
names(retro_fit)
head(retro_fit$estimates)

## End(Not run)

Description

Intended for developers to run the google test suite from R.

Usage

run_gtest(...)

Arguments

Details

The output from running the tests should look something like the following:

Internal ctest changing into directory: C:/github/NOAA-FIMS/FIMS/build
Test project C:/github_repos/NOAA-FIMS_org/FIMS/build
    Start 1: dlognorm.use_double_inputs
1/5 Test #1: dlognorm.use_double_inputs .......   Passed    0.04 sec
    Start 2: dlognorm.use_int_inputs
2/5 Test #2: dlognorm.use_int_inputs ..........   Passed    0.04 sec
    Start 3: modelTest.eta
3/5 Test #3: modelTest.eta ....................   Passed    0.04 sec
    Start 4: modelTest.nll
4/5 Test #4: modelTest.nll ....................   Passed    0.04 sec
    Start 5: modelTest.evaluate
5/5 Test #5: modelTest.evaluate ...............   Passed    0.04 sec

100% tests passed, 0 tests failed out of 5

If a test fails, the output will look something like the following:

Internal ctest changing into directory: C:/github/NOAA-FIMS/FIMS/build
Test project C:/github/NOAA-FIMS/FIMS/build
    Start 1: dlognorm.use_double_inputs
1/7 Test #1: dlognorm.use_double_inputs .......   Passed    0.04 sec
    Start 2: dlognorm.use_int_inputs
2/7 Test #2: dlognorm.use_int_inputs ..........   Passed    0.04 sec
    Start 3: modelTest.eta
3/7 Test #3: modelTest.eta ....................   Passed    0.04 sec
    Start 4: modelTest.nll
4/7 Test #4: modelTest.nll ....................   Passed    0.04 sec
    Start 5: modelTest.evaluate
5/7 Test #5: modelTest.evaluate ...............   Passed    0.04 sec
    Start 6: dlognormTest.DoubleInput
6/7 Test #6: dlognormTest.DoubleInput .........   Passed    0.04 sec
    Start 7: dlognormTest.IntInput
7/7 Test #7: dlognormTest.IntInput ............***Failed    0.04 sec

86% tests passed, 1 tests failed out of 7

Total Test time (real) =   0.28 sec

The following tests FAILED:
          7 - dlognormTest.IntInput (Failed)
Errors while running CTest
Output from these tests are in: C:/github/NOAA-FIMS/FIMS/build/Testing/Temporary/LastTest.log
Use "--rerun-failed --output-on-failure" to re-run the failed cases verbosely.

Description

Function to remove a given number of years of data and run FIMS model. This function is called by run_fims_retrospective()

Usage

run_modified_data_fims(years_to_remove = 0, data, parameters)

Arguments

Value

FIMS model fitted with years of data removed

Examples

## Not run: 
library(FIMS)
# Use built-in dataset from FIMS
data("data_big")
data_4_model <- FIMSFrame(data_big)
# Create a parameters object
parameters <- setup_default_parameters(data = data_4_model)
# Fit a FIMS model with 1 year of data removed
fit <- run_modified_data_fims(
  years_to_remove = 1,
  data = data_big,
  parameters = parameters
)

## End(Not run)

Description

Modify a parameter input and run a FIMS model. This function is called by run_fims_likelihood()

Usage

run_modified_pars_fims(
  new_value,
  parameter_name,
  module_name = NULL,
  parameters,
  data
)

Arguments

Value

FIMS model fitted to the new parameter input value

Examples

## Not run: 
library(FIMS)
# Use built-in dataset from FIMS
data("data_big")
data_4_model <- FIMSFrame(data_big)
# Create a parameters object
parameters <- setup_default_parameters(data = data_4_model)
# Fit a FIMS model with 1 year of data removed
fit <- run_modified_pars_fims(
  new_value = 12.9,
  parameter_name = "log_rzero",
  parameters = parameters, data = data_big
)

## End(Not run)

Description

Intended for developers to run the R integration tests.

Usage

run_r_integration_tests()

Examples

## Not run: 
run_r_integration_tests()

## End(Not run)

Description

Intended for developers to run the R unit tests.

Usage

run_r_unit_tests()

Examples

## Not run: 
run_r_unit_tests()

## End(Not run)

Description

Intended for developers to set up their local environment and run the google test suite from R.

Usage

setup_and_run_gtest(...)

Arguments

Examples

## Not run: 
setup_and_run_gtest("--rerun-failed --output-on-failure")

## End(Not run)

Description

This function sets up default parameters for a fleet module, including natural log of catchability coefficients (log_q) and fishing mortality (log_Fmort) for fleets. For fishing fleets, log_q is set to an estimation type of "constant" with a default value of 0, while log_Fmort is set to "fixed_effects". For survey fleets, log_q is set to "fixed_effects" and log_Fmort is set to "constant" with a default value of -200.

Usage

setup_default_Fleet(data, fleet)

Arguments

Details

The function builds module-specific defaults by calling helper functions for data, fleet, selectivity, recruitment, maturity, growth, and population components, then combines those defaults into one tibble. You can modify the returned tibble before fitting a model (for example, updating maturity and selectivity parameter values).

Growth defaults are chosen from the data. Models with empirical weight-at-age data default to "EWAA". Models without empirical weight-at-age data but with length-composition data default to "VonBertalanffySchnute".

To create the default initial numbers at age, this function uses the defaults from setup_default_Population() and setup_default_Recruitment(), which are passed to setup_default_init_naa() to calculate initial numbers at age.

Value

A tibble containing the default fleet parameters. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
default_fleet_parameters <- setup_default_Fleet(
  data = FIMSFrame(data_big),
  fleet = "fleet1"
)

## End(Not run)

Description

This function creates default growth parameters for a Fisheries Integrated Modeling System (FIMS) model. It generates a tibble with fields for module name, module type, label, value, and estimation type.

Usage

setup_default_Growth(
  data = NULL,
  module_type = c("EWAA", "VonBertalanffySchnute")
)

Arguments

Value

A tibble containing default growth parameters. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
# Set up default growth parameters
default_growth_parameters <- setup_default_Growth()

## End(Not run)

Description

This function sets up default parameters for a maturity module.

Usage

setup_default_Maturity(data, module_type = c("Logistic"))

Arguments

Details

The function builds module-specific defaults by calling helper functions for data, fleet, selectivity, recruitment, maturity, growth, and population components, then combines those defaults into one tibble. You can modify the returned tibble before fitting a model (for example, updating maturity and selectivity parameter values).

Growth defaults are chosen from the data. Models with empirical weight-at-age data default to "EWAA". Models without empirical weight-at-age data but with length-composition data default to "VonBertalanffySchnute".

To create the default initial numbers at age, this function uses the defaults from setup_default_Population() and setup_default_Recruitment(), which are passed to setup_default_init_naa() to calculate initial numbers at age.

Value

A tibble containing default maturity parameters. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
default_maturity_parameters <- setup_default_Maturity(
  data = FIMSFrame(data_big),
  module_type = "Logistic"
)

## End(Not run)

Description

Initializing a FIMS model, i.e., initialize_fims() requires a FIMSFrame object and a tibble of parameters. The parameter tibble can be automatically generated using this function or by building up your own tibble from helper functions used within this function. The resulting tibble will have all of the necessary parameters, specific to your data, to run a FIMS model. Initializing a FIMS model, i.e., initialize_fims() requires a FIMSFrame object and a tibble of parameters. The parameter tibble can be automatically generated using this function or by building up your own tibble from helper functions used within this function. The resulting tibble will have all of the necessary parameters, specific to your data, to run a FIMS model.

Usage

setup_default_parameters(data)

Arguments

Details

The function builds module-specific defaults by calling helper functions for data, fleet, selectivity, recruitment, maturity, growth, and population components, then combines those defaults into one tibble. You can modify the returned tibble before fitting a model (for example, updating maturity and selectivity parameter values).

Growth defaults are chosen from the data. Models with empirical weight-at-age data default to "EWAA". Models without empirical weight-at-age data but with length-composition data default to "VonBertalanffySchnute".

To create the default initial numbers at age, this function uses the defaults from setup_default_Population() and setup_default_Recruitment(), which are passed to setup_default_init_naa() to calculate initial numbers at age.

Value

A tibble containing default parameter values and metadata for your model. Key columns are listed below:

module_name:

The name of the FIMS module (e.g., "Data", "Selectivity", "Recruitment", "Growth", "Maturity"). These entries are always written in PascalCase to match the names used in the C++ code.

fleet:

The name of the fleet the module applies to. This will be NA for non-fleet-specific modules like "Recruitment".

module_type:

The specific type of the module (e.g., "Logistic" for a "Selectivity" module). This column will always be written in PascalCase to match the names used in the C++ code.

label:

The parameter name (e.g., "inflection_point").

age:

The age the parameter applies to.

length:

The length bin the parameter applies to.

timing:

The timing step (year) the parameter applies to.

value:

The initial value of the parameter.

estimation_type:

The estimation type (e.g., "constant", "fixed_effects", "random_effects").

distribution_type:

The type of distribution (e.g., "data", "process"), where a process distribution can refer to a fixed effect or a random effect but it does not fit to data, e.g., recruitment deviation.

distribution:

The distribution name (e.g., "Dlnorm", "Dmultinom"). This column will always be written in PascalCase to match the names used in the C++ code.

See Also

• FIMSFrame()

• initialize_fims()

Examples

## Not run: 
# Load the example dataset and create a FIMS data frame
data("data_big")
fims_frame <- FIMSFrame(data_big)

# Set up default parameters
default_parameters <- setup_default_parameters(data = fims_frame)

# Update selectivity parameters for survey1
updated_parameters <- default_parameters |>
  dplyr::rows_update(
    tibble::tibble(
      fleet = "survey1",
      label = c("inflection_point", "slope"),
      value = c(1.5, 2)
    ),
    by = c("fleet", "label")
  )

# Do the same as above except, model fleet1 with double logistic selectivity
# To see required parameters for double logistic selectivity, run
# show(DoubleLogisticSelectivity) and look at the Fields list
parameters_with_double_logistic <- updated_parameters |>
  dplyr::filter(!(fleet == "fleet1" & module_name == "Selectivity")) |>
  dplyr::bind_rows(
    setup_default_Selectivity(
      data = fims_frame,
      fleet = "fleet1",
      module_type = "DoubleLogistic"
    )
  )

## End(Not run)

Description

This function sets up default parameters for a population module.

Usage

setup_default_Population(
  data,
  log_M = log(0.2),
  log_init_naa = NA_real_,
  proportion_female = 0.5
)

Arguments

Details

The function creates a tibble of default population configurations, including log natural mortality rate, log initial numbers at age, and proportion of females. The function performs input checks to ensure that the provided arguments are valid.

Value

A tibble of default population configurations, including initial numbers at age, natural mortality rate, and proportion of females. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
default_population_parameters <- setup_default_Population(data = FIMSFrame(data_big))

## End(Not run)

Description

This function sets up default parameters for a recruitment module.

Usage

setup_default_Recruitment(
  data,
  module_type = c("BevertonHolt"),
  distribution = c("Dnorm", NA_character_)
)

Arguments

Details

The function builds module-specific defaults by calling helper functions for data, fleet, selectivity, recruitment, maturity, growth, and population components, then combines those defaults into one tibble. You can modify the returned tibble before fitting a model (for example, updating maturity and selectivity parameter values).

Growth defaults are chosen from the data. Models with empirical weight-at-age data default to "EWAA". Models without empirical weight-at-age data but with length-composition data default to "VonBertalanffySchnute".

To create the default initial numbers at age, this function uses the defaults from setup_default_Population() and setup_default_Recruitment(), which are passed to setup_default_init_naa() to calculate initial numbers at age.

Value

A tibble containing default recruitment parameters. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
default_recruitment_parameters <- setup_default_Recruitment(
  data = FIMSFrame(data_big),
  module_type = "BevertonHolt",
  distribution = "Dnorm"
)

## End(Not run)

Description

This function sets up default parameters for a selectivity module.

Usage

setup_default_Selectivity(
  data,
  fleet,
  module_type = c("Logistic", "DoubleLogistic", "AgeSpecific")
)

Arguments

Details

The function builds module-specific defaults by calling helper functions for data, fleet, selectivity, recruitment, maturity, growth, and population components, then combines those defaults into one tibble. You can modify the returned tibble before fitting a model (for example, updating maturity and selectivity parameter values).

Growth defaults are chosen from the data. Models with empirical weight-at-age data default to "EWAA". Models without empirical weight-at-age data but with length-composition data default to "VonBertalanffySchnute".

To create the default initial numbers at age, this function uses the defaults from setup_default_Population() and setup_default_Recruitment(), which are passed to setup_default_init_naa() to calculate initial numbers at age.

Value

A tibble containing the default selectivity parameters. See setup_default_parameters for full column descriptions.

See Also

• setup_default_parameters()

Examples

## Not run: 
default_selectivity_parameters <- FIMS:::setup_default_Selectivity(
  data = FIMSFrame(data_big),
  fleet = "fleet1",
  module_type = "Logistic"
)

## End(Not run)

Description

Intended for developers to set up their local environment prior to running the integration tests.

Usage

setup_gtest()

Examples

## Not run: 
setup_gtest()

## End(Not run)

Description

Returns one row per estimated parameter following the generics::tidy() convention. Standard columns (term, estimate, std.error, statistic, p.value) are always present; FIMS-specific columns (module_name, module_id, estimation_type, gradient) are appended so the full context is available for filtering and plotting.

Usage

## S3 method for class 'FIMSFit'
tidy(
  x,
  parameters = c("fixed_effects", "random_effects"),
  conf.int = FALSE,
  conf.level = 0.95,
  ...
)

Arguments

Value

A tibble::tibble() with columns:

term

Parameter label (from label in get_estimates()).

estimate

Point estimate at the MLE.

std.error

Standard error from TMB::sdreport().

statistic

Wald z-statistic (estimate / std.error).

p.value

Two-sided p-value for the z-test.

conf.low, conf.high

Confidence bounds (only when conf.int = TRUE).

module_name

Name of the FIMS module (e.g. "Selectivity").

module_id

Integer module identifier.

estimation_type

One of "fixed_effects", "random_effects", or "derived_quantity".

gradient

Gradient of the log-likelihood at the MLE. Values close to zero indicate a well-converged parameter.

Parameter types

FIMS distinguishes three estimation_type values:

"fixed_effects"

Directly optimized parameters (selectivity, log_Fmort, log_q, etc.).

"random_effects"

Integrated-out random effects (log_devs, etc.).

"derived_quantity"

Model outputs that are not parameters (spawning biomass, expected catches, etc.). Uncertainty here comes from the delta method via TMB::sdreport().

Pass any subset of these strings to parameters to control which rows are returned.

Inference

statistic and p.value are computed as a two-sided Wald z-test: z = estimate / std.error, ⁠p = 2 * stats::pnorm(-|z|)⁠. These are asymptotically valid for fixed effects under regularity conditions; treat them as approximate for random effects and derived quantities.

See Also

glance.FIMSFit(), get_estimates(), fit_fims()

Examples

## Not run: 
data("data_big")
data_4_model <- FIMSFrame(data_big)

fit <- setup_default_parameters(
  data = data_4_model
) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)

# Fixed and random effects (default)
tidy(fit)

# Fixed effects only, with 95% confidence intervals
tidy(fit, parameters = "fixed_effects", conf.int = TRUE)

# All rows including derived quantities
tidy(fit, parameters = c("fixed_effects", "random_effects", "derived_quantity"))

## End(Not run)

Description

This helper function generates a Google Benchmark C++ template file for a given workload and appends lines to tests/google_benchmark/CMakeLists.txt to register the benchmark as a separate executable.

Usage

use_google_benchmark_template(
  name = "FileName_ClassName_FunctionName",
  type = c("simple", "fixture")
)

Arguments

Value

If successful, this function invisibly returns TRUE to allow for the chaining of commands. If the function is unsuccessful, an error message is returned.

Messages from the usethis package and cli indicate where the new file was created and that the benchmark was registered in tests/google_benchmark/CMakeLists.txt.

Examples

## Not run: 
# Create a new benchmark file and register it in CMake:
FIMS:::use_google_benchmark_template(
  name = "Population_CatchAtAge_CatchNumbersAtAge"
)

# Create a fixture-based benchmark template:
FIMS:::use_google_benchmark_template(
  name = "Population_CatchAtAge_CatchNumbersAtAge",
  type = "fixture"
)

## End(Not run)

Description

This helper function generates a GoogleTest (gtest) C++ template file for a given function and appends lines to CMakeLists.txt to register the test.

Usage

use_gtest_template(name = "FileName_ClassName_FunctionName")

Arguments

Value

If successful, this function invisibly returns TRUE to allow for the chaining of commands. If the function is unsuccessful, an error message is returned.

Three messages are also returned from the usethis package, which is used by this function. The first states where the FIMS project is on your computer. The second states the file path of the newly created file. The file will not be automatically opened. The third states the test has been registered in tests/gtest/CMakeLists.txt.

Examples

## Not run: 
# Create a new test file named
# "test_Logistic_LogisticSelectivity_Evaluate.cpp" for
# `LogisticSelectivity::evaluate()` in
# `inst/include/population_dynamics/selectivity/functors/logistic.hpp`.

FIMS:::use_gtest_template(name = "Logistic_LogisticSelectivity_Evaluate")

## End(Not run)

Description

This helper function creates a new test file for testthat using a template available within the templates folder of this package. The test file is created under the "tests/testthat" directory with a name based on the input argument name. If the test file already exists, an error message is returned and no changes are made.

Usage

use_testthat_template(name)

Arguments

Details

There are three minimum testing criteria for FIMS, which should be validated for every R function within the package. The template file sets up a section for each of the three following test criteria:

1. Input and output correctness (IO correctness): ensure that the function behaves as expected with correct inputs and returns the expected outputs.

2. Edge-case handling (Edge handling): validate the function's performance with invalid inputs and unusual scenarios.

3. Built-in errors and warnings (Error handling): confirm that appropriate error and warning messages are triggered under exceptional conditions.

Above every expectation within the test file there should be a call to ⁠#' @description⁠ that fits on one line describing the test. The information will be used in the bookdown report of the testing results.

Value

If successful, this function invisibly returns TRUE to allow for the chaining of commands. If the function is unsuccessful, an error message is returned.

Two messages are also returned from the usethis package, which is used by this function. The first states where the FIMS project is on your computer. The second states the file path of the newly created file. The file will not be automatically opened.

Examples

# Create a new test file named "test-new_function" for `new_function()`
## Not run: 
FIMS:::use_testthat_template("new_function")

## End(Not run)