Package 'Rceattle'

Description

Enforces parameter sharing by mapping parameters for fleets with a common Selectivity_index or Q_index to the same value as the initial index.

Usage

adjust_map_shared_params(map_list, data_list)

Arguments

Value

Updated map_list.

Description

Returns the model's derived population quantities in long form so that custom plots and post-processing don't have to walk the deeply nested quantities list or inherit the dimnames decisions in rename_output(). Two shapes are flattened into one tidy frame: species-by-year quantities (e.g. biomass, ssb, R, F_spp) and species-by-sex-by-age-by-year quantities (e.g. N_at_age, biomass_at_age, M_at_age). For the species-level shapes, sex and age are returned as NA. Cells of the 4D arrays that are padded out to max(nsex) / max(nages) for species with fewer sexes or ages are dropped.

Usage

## S3 method for class 'Rceattle'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  which = c("biomass", "ssb", "R", "biomass_depletion", "ssb_depletion", "F_spp"),
  ci_level = 0.95,
  ...
)

Arguments

Details

Standard errors (se) and confidence intervals (lwr, upr) are populated from the TMB sdreport for any quantity that was ADREPORT'd (currently biomass, ssb, R); other quantities and fits produced with getsd = FALSE get NA for se / lwr / upr. Set ci_level to widen or narrow the band.

Value

A data.frame with columns year, species, sex, age, quantity, value, se, lwr, upr. species is the character species name from data_list$spnames. Rows are sorted in the order which was given.

Description

A data list containing inputs for a single-species CEATTLE model fit to Aleutian Islands Atka mackerel data through 2022. See BS2017SS for format details.

Usage

Atka2022

Format

A list with the same structure as BS2017SS.

Description

A data list containing inputs for the three-species (walleye pollock, Pacific cod, arrowtooth flounder) multispecies CEATTLE model for the Eastern Bering Sea. See BS2017SS for format details.

Usage

BS2017MS

Format

A list with the same structure as BS2017SS.

Description

A dataset containing the inputs used for CEATTLE

Usage

BS2017SS

Format

Control

nspp

Number of species included in CEATTLE

styr

Start year of the hindcast

endyr

End year of the hindcast

projyr

End year of the forecast

nsex

Number of sexes to model in the population (1 = combined/1sex, 2 = models both female/male)

spawn_month

Spawning month of the population to adjust the numbers spawning

R_sexr

Percent of recruitment that is female (ignored if nsex = 1)

nages

Number of ages of each species included in the hindcast

minage

Minimum age for each population (i.e.does recruitment correspond to age 0, 1, 2?)

nlengths

Number of lengths of each species included in the hindcast

pop_wt_index

Weight-at-age (weight) index to use for calculation of each species population derived quantities (SSB, Consumption/Ration, Suitability, etc)

ssb_wt_index

Weight-at-age (weight) index to use for calculation of each species spawning biomass

pop_age_transition_index

Age transition matrix (e.g. growth trajectory) index to use for derived quantities of the population to convert age to length (also used in length-based predation estimation)

sigma_rec_prior

Standard deviation to use for recruitment

other_food

Other food in the ecosystem for each species

estDynamics

Estimate or fix numbers-at-age: 0 = estimate dynamics, 1 = use input numbers-at-age in NbyageFixed, 2 = multiply input numbers-at-age (NbyageFixed) by a single scaling coefficient, 3 = multiply input numbers-at-age (NbyageFixed) by age specific scaling coefficient.

est_M1

Estimate residual (multi-species mode) or total natural mortality (single-species mode). 0 = use fixed natural mortality from M1_base, 1 = estimate sex- and age-invariant M1, 2 = sex-specific (two-sex model), age-invariant M1, 3 = estimate sex- and age-specific M1.

fleet_control

Survey and fishery data specifications

index_data

Survey index in weight (kg) or numbers data

catch_data

Total catch in weight (kg) or numbers data

comp_data

Survey/fishery age or length composition data. Note if sex is 3, put female composition data then male composition data (similar to SS).

emp_sel

Empirical/fixed selectivity for surveys and fisheries (leave empty if not used)

age_trans_matrix

Age transition matrix (e.g. growth trajectory) used to convert age to length for length comp data. Can have multiple matrices for a species specified by Age_transition_index.

age_error

Aging error matrices. Can have only one per species.

weight

Weight-at-age (weight) to use for calculation of derived quantities (SSB, Consumption/Ration, Suitability, Total Catch, Survey Biomass, etc). Can have multiple weight-at-age data-sets for each species, but must be full for all years of the hindcast.

maturity

Maturity-at-age for each species

sex_ratio

Percent female at age for each species

M1_base

Residual natural mortality for each species

aLW

Parameters for weight-at-length power function for each species. . Used when estimating time-variant length-based gamma suitability (suitMode = 2) or time-variant length-based lognormal suitability (suitMode = 5)

Ceq

Which bioenergetics equation to use for each species for ft to scale max consumtion: 1 = Exponential (Stewart et al 1983), 2 = Temperature-dependendence for warm-water species (Kitchell et al 1977; sensu Holsman et al 2015), 3 = temperature dependence for cool and cold-water species (Thornton and Lessem 1979)

Cindex

Which environmental index in env_data to use to drive bioenergetics

Pvalue

This scales the maximum consumption used for ration for each species; Pvalue is in CmaxfTPvalue*ration_data

fday

Number of foraging days per year for each species

CA

Intercept of allometric mass function for calculating maximum consumption: CA * Weight ^ CB

CB

Slope of allometric mass function for calculating maximum consumption: CA * Weight ^ CB

Qc

Parameter for temperature scaling function of maximum consumption specified by Ceq

Tco

Parameter for temperature scaling function of maximum consumption specified by Ceq

Tcm

Parameter for temperature scaling function of maximum consumption specified by Ceq

Tcl

Parameter for temperature scaling function of maximum consumption specified by Ceq

CK1

Parameter for temperature scaling function of maximum consumption specified by Ceq

CK4

Parameter for temperature scaling function of maximum consumption specified by Ceq

env_data

Environmental indices such as bottom temperature data to incorporate into ration equation specificed by Ceq and Cindex. Also used to drive catchability if Catchability = 5. Will use the mean for missing years. Temperature should be in celcius.

ration_data

Annual relative foraging rate by age or input consumption at age. Multiplied by pvalue and fday to scale maximum consumption to the number of days in a year that foraging occurs.

UobsAge

Stomach proportion by numbers for each predator, prey, predator age, prey age combination. Can also be year specific by including the column, "Year"

UobsWtAge

Stomach proportion by weight for each predator, prey, predator age, prey age combination. Can also be year specific by including the column, "Year"

fleet_control: controls for survey and fisheries data

Fleet_name

Name of survey or fishery

Fleet_code

Index of survey/fishery ACROSS species

Fleet_type

0 or 'Off' = Do not estimate; 1 = 'Fishery'; 2 = 'Survey'

Species

Species number

Selectivity_index

index to use if selectivities of different surveys are to be the same

Selectivity

Selectivity to use for the species: 0 = "Fixed"; 1 = "Logistic"; 2 = "NonParametric" sensu Ianelli et al 2018; 3 = "DoubleLogistic"; 4 = "DescendingLogistic"; 5 = "Hake" non-parametric sensu Taylor et al; 6 = "2DAR1"; 7 = "3DAR1" sensu Cheng et al 2024; 8 = "DoubleNormal" (Gaussian ascending and descending limbs blended at a common peak — similar to SS3 pattern 24). Parameters: sel_inf[1] = peak bin/length; sel_inf[2] = logit(right_floor), right-tail floor analogous to SS3 P6/end_logit (logit=-10 → dome-shaped, logit=+10 → logistic ascending-only); log_sel_slp[1] = log(sigma_ascending); log_sel_slp[2] = log(sigma_descending). Supports the same time-varying modes as DoubleLogistic (IID, Block, RandomWalk).

Selectivity_dimension

"Age" or "Length".

Nselages

Number of ages to estimate non-parametric selectivity.

Time_varying_sel

Whether a time-varying selectivity should be estimated for logistic, double logistic selectivity, or descending logistic. 0 = "Off", 1 = "IID" penalized deviates given sel_sd_prior or random effect, 2 = "AR1" (TODO), 3 = "Block" time blocks with no penalty, 4 = "RandomWalk" following Dorn, 5 = "RandomWalkAscending" on ascending portion of double logistic only.

Time_varying_sel_sd_prior

The fixed or initial sd to use for time varying selectivity.

Bin_first_selected

Age/length bin at which selectivity is non-zero

Acuumulation_age_lower

Ages below this will be grouped to this age for composition data. For example, if set to 2, comp data for age 2 will include 1 and 2 year olds.

Acuumulation_age_upper

Ages above this will be grouped to this age for composition data. For example, if set to 9 for a species with 10 ages, comp data for age 9 will include 9 and 10 year olds.

weight1_Numbers2

Is the observation in weight (kg) set as 1, if the observation is in numbers caught, set as 2

Weight_index

Weight-at-age (weight) index to use for calculation of derived quantities

Age_transition_index

Age transition matrix (e.g. growth trajectory) index to use for derived quantities to convert age to length

Q_index

index to use if catchability coefficients are to be set the same

Catchability

Estimate catchability? (0 or "Fixed" = fixed at prior; 1 or "Estimated" = Estimate single parameter; 2 or "Estimated-with-prior" = Estimate single parameter with prior; 3 or "Analytical" = Estimate analytical q from Ludwig and Walters 1994; - 4 = Estimate power equation; - 5 or "Environmental" = Linear equation log(q_y) = q_mu + beta * index_y; 6 or "AR1" = annual AR1 catchability deviates are fit to environmental index sensu Rogers et al 2025)

Q_prior

Starting value or fixed value for catchability

Q_sd_prior

Variance of q prior: dnorm (log_q, log_q_prior, q_sd_prior)

Time_varying_q

Whether a time-varying q should be estimated. 0 = "Off", 1 = "IID" penalized deviate or random effect, 2 = "AR1" (TODO), 3 = "Block" time blocks with no penalty; 4 = "RandomWalk" random walk from mean following Dorn 2018 (dnorm(q_y - q_y-1, 0, sigma). If Catchability = 5 or 6, this determines the environmental index to be used in the equation log(q_y) = q_mu + beta * index_y

Time_varying_q_sd_prior

The sd to use for the random walk of time varying q if set to 1

Estimate_survey_sd

Estimate survey variance (0 = use CV from index_data, 1 = yes, 2 = analytically estimate following (Ludwig and Walters 1994)

Survey_sd_prior

Starting value to be used if Estimate_sigma_index = 1

Estimate_catch_sd

Estimate fishery variance (0 = use CV from index_data, 1 = yes, 2 = analytically estimate following (Ludwig and Walters 1994)

Catch_sd_prior

Starting value to be used if Estimate_sigma_catch = 1

Comp_weights

Composition weights to be used for multinomial likelihood. These are multiplied. After running model, these will update to McAllister & Ianelli 1997 weights using the harmonic mean.

Catch_units

Units used for survey: 1 = kg; 2 = numbers

proj_F_prop

The proportion of future fishing mortality assigned to this fleet

Sex

sex codes: 0=combined; 1=use female only; 2=use male only; 3 = joint female and male

Description

Function to build parameter bounds based on Holsman et al 2015 and Kinzey and Punt 2010

Usage

build_bounds(param_list = NULL, data_list)

Arguments

Value

List of upper and lower bounds

Description

Specify the growth model for Rceattle

Usage

build_growth(fun = "empirical", growth_age_L1 = NA, linkages = NULL)

Arguments

Value

A list of switches defining the growth model.

Examples

## Not run: 
# Sex-specific von Bertalanffy with temperature on K, by species + sex
build_growth(
  fun = "vonBertalanffy",   # or fun = 1
  linkages = list(
    K = linkage_spec(
      formula = ~ temp,
      by      = ~ species + sex,
      priors  = list(temp = normal(0, 1))
    )
  )
)

## End(Not run)

Description

Defines the harvest control rule and associated reference points used in the Rceattle model.

Usage

build_hcr(
  HCR = 0,
  DynamicHCR = FALSE,
  Ftarget = 0.4,
  Flimit = 0.35,
  Ptarget = 0.4,
  Plimit = 0,
  Alpha = 0.05,
  Pstar = 0.45,
  Sigma = 0.5,
  Fmult = 1,
  HCRorder = 1
)

Arguments

Details

Harvest control rule formulations currently implemented in Rceattle:

hcr = 0 or "NoFishing": No catch. Estimate the hindcast.

hcr = 1 or "CMSY": CMSY. Maximize catch across all species simultaneously. CMSY can be constrained such that depletion does not fall below Plimit.

hcr = 2 or "ConstantF": Constant input F set at Ftarget for each species (vector or single F). SPR (single-species only) based Flimit is specified via Flimit.

hcr = 3 or "ConstantFSSB": F that achieves Ftarget% of SSB0 in the end of the projection.

hcr = 4 or "ConstantFSPR": Constant Fspr set at Ftarget for each species. Can be multiplied by Fmult following NEFSC.

hcr = 5 or "NPFMC": The North Pacific Fishery Management Council (NPFMC) Tier 3 spawner-per-recruit-based harvest control rule: Stock status: $SB > SB at Ftarget$

$Fofl = Flimit$

$Fuse = Ftarget$

Stock status: $Alpha < SB / SB at Ftarget \le 1$

$Fofl = Flimit * (SB / Ptarget - Alpha) / (1 - Alpha)$

$Fuse = Ftarget * (SB / Ptarget - Alpha) / (1 - Alpha)$

Stock status: $SB / SB at Ftarget \le Alpha$ or $SB < Plimit * SB0$

$Fofl = 0$

$Fuse = 0$

hcr = 6 or "PFMC": An HCR based on the The Pacific Fishery Management Council (PFMC) category 1 40-10 annual catch limit (ABC) harvest control rule assuming Fofl is normally distributed with a standard deviation (sigma) = 0.5 and an uncertainty quantile buffer (P*) of 0.45 (PFMC 2020). The model uses Fspr if single-species or F that achieves X% of SSB0 for multi-species. Target biological reference points are calculated based on the normal cumulative distribution function (Phi(quantile,mean,standard deviation)), P*, and sigma as follows: Stock status: $SB > SB0 * Ptarget$

$Fofl = Flimit$

$Fuse = Phi(Pstar, Flimit, Sigma)$

Stock status: $SB0 * Plimit < SB \le SB0 * Ptarget$

$Fofl = Flimit$

$Fuse = Phi(Pstar, Flimit, Sigma) * \frac{SB0 * Ptarget * (SB - SB0 * Plimit)}{SB * SB0 * (Ptarget - Plimit)}$

Stock status: $SB < SB0 * Plimit$

$Fofl = 0$

$Fuse = 0$

hcr = 7 or "SESSF": An HCR based on the The Southern and Eastern Scalefish and Shark Fishery (SESSF) spawner-per-recruit-based Tier 1 harvest control rule where F_Limit=F_(20%), B_Limit=SB_20, F_Target (AFMA 2017) calculated as follows: Stock status: $SB > SB0 * Ptarget$

$Fofl = Flimit$

$Fuse = Ftarget$

Stock status: $Ptarget > SB > SB0 * Plimit$

$Fofl = Flimit * (SB / (SB0 * Ptarget) - 1)$

$Fuse = Ftarget * (SB / (SB0 * Ptarget) - 1)$

Stock status: $SB < SB0 * Plimit$

$Fofl = 0$

$Fuse = 0$

NOTE: only HCRs 1, 2, 3, and 6 will work in multi-species mode.

Value

A list containing the harvest control rule and associated biological reference points.

Description

Reads a data list and map to update the map argument based on the HCR specified in build_hcr

Usage

build_hcr_map(
  data_list,
  map,
  debug = FALSE,
  all_params_on = FALSE,
  HCRiter = 1
)

Arguments

Value

a list of map arguments for each parameter

Description

Define M1 specifications

Usage

build_M1(
  M1_model = 0,
  M1_re = 0,
  updateM1 = FALSE,
  M1_use_prior = FALSE,
  M2_use_prior = FALSE,
  M_prior = 0.4,
  M_prior_sd = 0.35,
  M1_indices = NA,
  linkages = NULL
)

Arguments

Value

A list of switches for defining the M1 model.

Examples

## Not run: 
# Sex/age-invariant M with a temperature linkage on M1
build_M1(
  M1_model = "sex_age_invariant",
  linkages = list(
    M1 = linkage_spec(
      formula = ~ temp,
      by      = ~ species,
      priors  = list(temp = normal(0, 0.5))
    )
  )
)

## End(Not run)

Description

Orchestrates the building of the TMB map object by calling specialized helper functions for each parameter block (Recruitment, M1, Predation, Selectivity, Catchability, etc.).

Usage

build_map(
  data_list,
  params,
  debug = FALSE,
  random_rec = FALSE,
  random_sel = FALSE
)

Arguments

Value

A list containing the factorized TMB map (mapFactor) and the original map matrix/array list (mapList).

Description

Maps survey catchability base parameters (index_log_q), time-varying deviations (index_q_dev), and environmental linkages (index_q_beta, index_q_rho).

Usage

build_map_catchability(map_list, data_list, nyrs_hind)

Arguments

Value

Updated map_list.

Description

Sets all parameters in the map list to NA, except the dummy parameter, for use in debug or testing modes.

Usage

build_map_debug(map_list, debug)

Arguments

Value

Updated map_list.

Description

Maps fishing mortality parameters (log_F) and related targets. Also maps data weighting parameters (catch_log_sd, comp_weights, caal_weights).

Usage

build_map_f_and_data_weights(map_list, data_list, nyrs_hind)

Arguments

Value

Updated map_list.

Description

Turns off (sets to NA) most population and fleet parameters for species where the dynamics are fixed (estDynamics > 0).

Usage

build_map_fixed_natage(map_list, data_list)

Arguments

Value

Updated map_list.

Description

Maps the fixed parameters (log_growth_pars) and the random effects parameters (log_growth_par_devs, growth_dev_log_sd, growth_rho) based on growth_model and growth_re settings.

Usage

build_map_growth(map_list, data_list, nyrs_hind)

Arguments

Value

Updated map_list.

Description

Maps the fixed parameters (log_M1) and the random effects parameters (log_M1_dev, M1_dev_log_sd, M1_rho) based on M1_model and M1_re settings.

Usage

build_map_m1(map_list, data_list, nyrs_hind)

Arguments

Value

Updated map_list.

Description

Maps predation suitability parameters (log_gam_a, log_gam_b, log_phi) and diet weight parameters based on msmMode and suitMode.

Usage

build_map_predation(map_list, data_list)

Arguments

Value

Updated map_list.

Description

Maps the recruitment deviations (rec_dev, init_dev), stock-recruitment parameters (rec_pars) and Rec dev variances (R_log_sd)

see build_srr() for options,

Usage

build_map_recruitment(map_list, data_list, nyrs_hind, nyrs_proj, random_rec)

Arguments

Value

Updated map_list.

Description

Maps base selectivity parameters (log_sel_slp, sel_inf, sel_coff) and time-varying deviations, based on Selectivity and Time_varying_sel settings in fleet_control.

Selectivity in fleet_control of the data determines shape of selectivity curve: 0 = "Fixed" empirical selectivity provided in emp_sel in the data 1 = "Logistic" 2 = "NonParametric" selecitivty sensu Ianelli et al 2018 3 = "DoubleLogistic" 4 = "DescendingLogistic" 5 = "Hake" non-parametric selectivity sensu Taylor et al 2014 (Hake) 6 = "2DAR1" across age x year 7 = "3DAR1" across age x cohort x year (Cheng et al 2024) 8 = "DoubleNormal" Gaussian ascending/descending limbs blended at peak (analogous to SS3 pattern 24). Parameters: sel_inf[1] = peak; sel_inf[2] = logit(right_floor) (right-tail floor, SS3 P6/end_logit); log_sel_slp[1] = log(sigma_asc); log_sel_slp[2] = log(sigma_desc). right_floor→0: dome-shaped; right_floor→1: logistic ascending only.

N_sel_bins Number of age/length bins to estimate non-parametric selectivity when Selectivity = 2 or 5. Not used otherwise

Time_varying_sel determines if time-varying selectivity should be estimated for logistic, double logistic selectivity, descending logistic , non-parametric, or hake (Selectivity = 1, 2, 3, 4, or 5). 0 = 'None' 1 = 'IID' penalized deviates given sel_sd_prior 3 = 'Block' time blocks with no penalty 4 = 'RandomWalk' random walk following Dorn 5 = 'RandomWalkAscending' random walk on ascending portion of double logistic only. random_sel in fit_mod treats random deviates and random walk parameters as random effects, estimating the variance.

Usage

build_map_selectivity(map_list, data_list, nyrs_hind, random_sel)

Arguments

Value

Updated map_list.

Description

Function to read a TMB cpp file and construct parameter list object for Rceattle

Usage

build_params(data_list)

Arguments

Value

a list of map arguments for each parameter

Description

Stock recruitment relationships currently implemented in Rceattle:

• srr_fun = 0 or "mean": No stock recruit relationship. Recruitment is a function of R0 and annual deviates (i.e. steepness = 0.99).

  $R_y = exp(R0 + R_{dev,y})$

• srr_fun = 2 or "BevertonHolt": Beverton-holt stock-recruitment relationship

  $R_y = \frac{\alpha_{srr} * SB_{y-minage}}{1+\beta_{srr} * SB_{y-minage}}$

• srr_fun = 4 or "Ricker": Ricker stock-recruitment relationship

  $R_y = \alpha_{srr} * SB_{y-minage} * exp(-\beta_{srr} * SB_{y-minage})$

When srr_pred_fun > 0 and srr_fun = 0 recruitment in the hindcast is estimated as in srr_fun = 0

$R_y = exp(R0 + R_{dev,y})$

, but an additional stock recruitment relationship defined by srr_pred_fun is estimated between srr_hat_styr and srr_hat_endyr and treated as an additional penalty. The stock recruitment relationship defined by srr_pred_fun is then used in the projection.

Usage

build_srr(
  srr_fun = 0,
  srr_pred_fun = srr_fun,
  proj_mean_rec = TRUE,
  srr_mse_switchyr = NULL,
  srr_hat_styr = NULL,
  srr_hat_endyr = NULL,
  srr_est_mode = 1,
  srr_prior = 4,
  srr_prior_sd = 1,
  srr_indices = NA,
  Bmsy_lim = NA,
  linkages = NULL
)

Arguments

Value

A list containing the stock recruitment relationship settings

Description

Function to load .RDs files from MSE runs

Usage

check_mse(dir = NULL, file = NULL)

Arguments

Value

list of MSE simulations/run

Description

Function to clean data prior to Rceattle runs

Usage

clean_data(data_list)

Arguments

Description

Extract estimated parameters from an Rceattle fit

Usage

## S3 method for class 'Rceattle'
coef(object, ...)

Arguments

Value

A named numeric vector of estimated fixed-effect parameters (the optimizer's par). Returns NULL if the model was not estimated.

Description

Combine data sets. Will use the env_data data set from data_set1 and diet data will have to be updated.

Usage

combine_data(data_list1 = NULL, data_list2 = NULL)

Arguments

Description

Function to evaluate the simulation performance with regard to bias using the median relative error (MRE) and precision using the coefficient of variation.

Usage

compare_sim(operating_mod, simulation_mods, object = "quantities")

Arguments

Value

A data frame summarising simulation performance metrics

Description

Runs the post-fit convergence battery and returns a single structured object. Each check yields a record with a common schema (id, tier, severity, message, data); severity is one of "OK", "NOTE", "WARN", "FAIL". The object's status is the worst severity present.

Usage

convergence_diagnostics(object, ...)

Arguments

Details

fit_mod() runs this automatically and attaches the result as fit$convergence; call convergence_diagnostics() directly to re-run it on any fit. Checks cover the optimizer gradient, Hessian positive-definiteness and conditioning, parameters on bounds, phasing, and parameter estimability.

Value

An object of class "Rceattle_convergence": a list with status (overall worst severity) and checks (named list of records).

Description

A fitted Rceattle model object for the multispecies run of CEATTLE for the Eastern Bering Sea (walleye pollock, Pacific cod, arrowtooth flounder).

Usage

EBS_ms_run

Format

An object of class Rceattle.

Description

A fitted Rceattle model object for the single-species run of CEATTLE for the Eastern Bering Sea with natural mortality estimated.

Usage

EBS_ss_M_run

Format

An object of class Rceattle.

Description

A fitted Rceattle model object for the single-species run of CEATTLE for the Eastern Bering Sea (walleye pollock, Pacific cod, arrowtooth flounder) without estimating natural mortality.

Usage

EBS_ss_run

Format

An object of class Rceattle.

Description

fit_mod() carries roughly a dozen optimizer- and reporting-related arguments (bias.correct, getsd, loopnum, newtonsteps, ...). That is a lot of surface area when the user mostly cares about "what model am I fitting" rather than "how is it being fit." fit_control() collects those knobs into a single object so calls to fit_mod() can stay focused on the model spec:

Usage

fit_control(
  bias.correct = FALSE,
  getsd = TRUE,
  getJointPrecision = TRUE,
  getReportCovariance = FALSE,
  use_gradient = TRUE,
  rel_tol = 1,
  loopnum = 5,
  newtonsteps = 0,
  phase = FALSE,
  TMBfilename = NULL,
  verbose = 1,
  nlminb_control = list(eval.max = 1e+09, iter.max = 1e+09, trace = 0)
)

Arguments

Details

fit <- fit_mod(
  data_list   = BS2017SS,
  msmMode     = 0,
  fit_control = fit_control(loopnum = 1, getsd = FALSE)
)

Pass the result via the fit_control argument to fit_mod(). When supplied, the values in the fit_control object override the corresponding individual arguments to fit_mod(). Individual arguments are kept for backward compatibility.

Value

A list of class "Rceattle_fit_control".

Examples

# Quick-and-dirty fit: skip sdreport, single optimizer pass
ctl <- fit_control(getsd = FALSE, loopnum = 1)

# Production fit with bias correction and joint precision
ctl <- fit_control(bias.correct = TRUE, getJointPrecision = TRUE)

Description

This function estimates population parameters of CEATTLE using maximum likelihood in TMB.

Usage

fit_mod(
  data_list = NULL,
  inits = NULL,
  map = NULL,
  bounds = NULL,
  file = NULL,
  estimateMode = 0,
  projection_uncertainty = FALSE,
  random_rec = FALSE,
  random_q = FALSE,
  random_sel = FALSE,
  HCR = build_hcr(),
  niter = 3,
  recFun = build_srr(),
  M1Fun = build_M1(),
  growthFun = build_growth(),
  msmMode = 0,
  avgnMode = 0,
  initMode = "NonEquilibrium",
  suitMode = 0,
  suit_styr = NULL,
  suit_endyr = NULL,
  fit_control = NULL,
  ...
)

Arguments

Details

CEATTLE is an age-structured population dynamics model that can be fit with or without predation mortality. The default is to exclude predation mortality by setting msmMode to 0. Predation mortality can be included by setting msmMode with the following options:

• 0. Single species mode

• 1. Holsman et al. 2015 predation based on multi-species virtual population analysis (MSVPA) based predation formation.

• 2. MSVPA Holling Type III

Values 3 through 9 (Kinzey & Punt 2009 functional responses – Holling Type I/II/III, predator interference, predator preemption, Hassell-Varley, Ecosim) are blocked at runtime by data_check() because the implementations have not been validated against the current parameter set. See src/TMB/predation.hpp.

Value

A list of class "Rceattle" including:

• data_list: List of data inputs

• initial_params: List of starting parameters

• bounds: Parameter bounds used for estimation

• map: List of map used in TMB

• obj: TMB model object

• opt: Optimized model object from nlminb

• sdrep: Object of class sdreport exported by TMB including the standard errors of estimated parameters

• estimated_params: List of estimated parameters

• quantities: Derived quantities from CEATTLE

• run_time: Model run time

Examples

data(BS2017SS)
ss_run <- fit_mod(
  data_list    = BS2017SS,
  estimateMode = 0,
  msmMode      = 0,
  fit_control  = fit_control(phase = FALSE, verbose = 0)
)

Description

A data list containing inputs for a multispecies CEATTLE model fit to three groundfish species on Georges Bank. See BS2017SS for format details.

Usage

GeorgesBank3spp

Format

A list with the same structure as BS2017SS.

Description

This function calculates a probability transition matrix that defines the probability of a fish of a given age belonging to specific length bins. It supports Von Bertalanffy and Richards growth models and includes a Stock Synthesis (SS) style plus-group correction.

Usage

get_growth_matrix_r(
  fracyr,
  nsex_sp,
  nages_sp,
  nlengths_sp,
  nyrs,
  lengths_sp,
  minage_sp,
  maxage_sp,
  growth_params_sp,
  growth_log_sd_sp,
  growth_model_sp
)

Arguments

Value

A 4D array of probabilities with dimensions (sex, age, length, year).

Description

Converts a growth matrix (length-at-age probabilities) into mean weight-at-age using a length-weight relationship (W = a * L^b).

Usage

get_weight_at_age_r(
  nsex_sp,
  nages_sp,
  nlengths_sp,
  nyrs,
  lengths_sp,
  length_at_age,
  growth_matrix,
  lw_params
)

Arguments

Details

The function calculates midpoints for length bins to avoid bias. For the first bin, it assumes the width is equal to the second bin's width. The final weight-at-age is the expected value across all length bins for that age.

Value

A 3D array of mean weights with dimensions (sex, age, year).

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska groundfish data through 2018. See BS2017SS for format details.

Usage

GOA2018SS

Format

A list with the same structure as BS2017SS.

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska arrowtooth flounder data. See BS2017SS for format details.

Usage

GOAatf

Format

A list with the same structure as BS2017SS.

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska arrowtooth flounder data through 2023. See BS2017SS for format details.

Usage

GOAatf2023

Format

A list with the same structure as BS2017SS.

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska Pacific cod data. See BS2017SS for format details.

Usage

GOAcod

Format

A list with the same structure as BS2017SS.

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska walleye pollock data. See BS2017SS for format details.

Usage

GOApollock

Format

A list with the same structure as BS2017SS.

Description

A list containing biomass, spawning stock biomass, and recruitment reference values from the 2018 Gulf of Alaska Stock Assessment and Fishery Evaluation (SAFE) report.

Usage

GOAsafe2018

Format

A list with components:

biomass

Total biomass time series

ssb

Spawning stock biomass time series

recruitment

Recruitment time series

Description

Run's the Rceattle model at initial values that are +- N(0, sd) from the initial parameters.

Usage

jitter(
  Rceattle = NULL,
  njitter = 50,
  sd = 0.2,
  phase = FALSE,
  seed = 123,
  cores = NULL
)

Arguments

Value

a list of Rceattle models

Examples

data(BS2017SS)
ss_run <- fit_mod(data_list = BS2017SS,
    inits = NULL, file = NULL,
    estimateMode = 0, random_rec = FALSE,
    msmMode = 0, avgnMode = 0,
    phase = FALSE, verbose = 0)
jitters <- jitter(ss_run, njitter = 10)

Description

Capture a linkage specification

Usage

linkage_spec(
  formula,
  param = NULL,
  data = NULL,
  by = ~species,
  species = NULL,
  sex = NULL,
  link = "log",
  init = NULL,
  bounds = NULL,
  priors = NULL,
  re_group = NA_character_,
  est_phase = 1L
)

Arguments

Value

An Rceattle_linkage_spec object.

Description

Function to load .RDs files from MSE runs

Usage

load_mse(dir = NULL, file = NULL, exclude = NULL, include_em = TRUE)

Arguments

Value

list of MSE simulations/run

Description

Returns the joint negative-objective from nlminb, sign-flipped, as a "logLik" object. df is the number of estimated fixed-effect parameters. The nobs attribute is intentionally omitted: counting "observations" in a stock assessment likelihood (with composition cells, indices, catches, and priors) is not well-defined, so stats::AIC() works (uses df) while stats::BIC() does not.

Usage

## S3 method for class 'Rceattle'
logLik(object, ...)

Arguments

Value

An object of class "logLik", or NULL if the model was not estimated.

Description

Model average of derived quantities

Usage

model_average(Rceattle, weights = NULL, uncertainty = FALSE, nboot = 10000)

Arguments

Value

an Rceattle object with derived quantities weighted by the specified weights. The length of the derived quantities spans the years which overlap across all models.

Description

Management strategy evaluation performance metric summary

Usage

mse_summary(mse, om_only = FALSE)

Arguments

Value

Alist of two data.frames with MSE summary statistics of performance metrics including: data.frame 1

1. Average annual catch across projection years and simulations per fleet and across fleets

2. Average interannual variation in catch (IAV) across projection years (n) per fleet and across fleets

3. % of years in which the fishery is closed across simulations (s)

4. Average relative mean squared error in estimate of spawning biomass in the terminal year across simulations

5. % of years in which the population is perceived as undergoing overfishing as determined from F_Limit across simulations via build_hcr in the EM

6. % of years in which the population is perceived to be overfished as determined from B_Limit across simulations via build_hcr in the EM

7. % of years in which the population is undergoing overfishing as determined from the “true” F_Limit across simulations via build_hcr in the OM

8. % of years in which the population is overfished as determined from the “true” B_Limit across simulations via build_hcr in the OM

9. Average ratio of spawning biomass over B_target in the terminal year across simulations in the OM 10-14. Terminal biomass, SSB, SSB depletion (relative to equilibrium), SSB depletion (relative to dynamic SB0)

Description

A data list containing inputs for a single-species CEATTLE model fit to Gulf of Alaska northern rockfish data through 2022. See BS2017SS for format details.

Usage

NorthernRockfish2022

Format

A list with the same structure as BS2017SS.

Description

Function that plots the biomass consumed trends as estimated from Rceattle. Returns and saves a figure with the biomass eaten trajectory.

Usage

plot_b_eaten(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  width = 7,
  height = 6.5,
  minyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE
)

Arguments

Description

Function that plots the biomass consumed trends as estimated from Rceattle. Returns and saves a figure with the biomass eaten trajectory.

Usage

plot_b_eaten_prop(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  spnames = NULL,
  species = NULL,
  lwd = 3,
  right_adj = 0,
  top_adj = 0.15,
  minyr = NULL,
  mohns = NULL,
  width = 7,
  height = 6.5,
  incl_proj = FALSE,
  incl_mean = FALSE,
  add_ci = FALSE,
  mod_cex = 1
)

Arguments

Description

Plots the mean minage+ biomass (million mt) and 95\

Usage

plot_biomass(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the biomass trajectory.

Description

Plot of fitted landings data on natural-scale (r4ss-style)

Usage

plot_catch(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  right_adj = 0,
  top_adj = 1.2,
  incl_proj = FALSE,
  single.plots = FALSE,
  width = NULL,
  height = NULL,
  alpha = 0.4,
  lwd = 2,
  ymax = NULL,
  maxyr = NULL,
  mse = FALSE,
  error = TRUE,
  fleets = NULL
)

Arguments

Description

Function the plots the comp data as estimated from Rceattle

Usage

plot_comp(
  Rceattle,
  file = NULL,
  model_names = NULL,
  species = NULL,
  cex = 3,
  lwd = 3,
  right_adj = 0
)

Arguments

Value

Returns and saves a figure

Description

Plots a timeline of presence/absence (and optionally relative quantity) of the data sources contributing to an Rceattle model's likelihood, by year and fleet. Modelled after Stock Synthesis's r4ss::SSplotData().

Usage

plot_data(
  Rceattle,
  file = NULL,
  subplots = 1:2,
  datatypes = "all",
  fleets = "all",
  species = "all",
  ghost = FALSE,
  fleetcol = "default",
  width = 7,
  height = 5,
  res = 200,
  ptsize = 10,
  margins = c(5.1, 2.1, 2.1, 10.1),
  cex = 2,
  lwd = 12,
  maxsize = 1,
  alphasize = 1,
  mainTitle = FALSE,
  cex.main = 1
)

Arguments

Details

Years with Year > 0 contribute to the likelihood; rows with Year < 0 (kept for fitting comparison only) are shown when ghost = TRUE. Diet data uses Year == 0 for the fixed reference stomach composition; those entries are plotted at the model endyr and labelled per predator species.

Value

Invisibly, a list with typetable — the long data frame underlying the plot (year, fleet, data type, relative size).

Description

Plots the mean biomass depletion and 95\

Usage

plot_depletion(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the biomass depletion trajectory.

Description

Plots the mean SSB depletion and 95\ Depletion reference lines for Ptarget and Plimit are drawn in blue and red respectively.

Usage

plot_depletionSSB(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the SSB depletion trajectory.

Description

If year == 0, diet data are averaged from suit_styr to suit_endyr If prey_age >= 0 diet data are diet proportion of prey-at-age in predator-at-age If prey_age < 0 diet data are diet proportion of prey-spp in predator-at-age (sum across prey ages) If prey_age < 0 and pred_age < 0, diet data are mean diet proportion of prey-spp in predator-spp (sum across prey ages and take mean across predator ages) If prey_age < 0 and pred_age < -500, diet data are weighted mean diet proportion of prey-spp in predator-spp (sum across prey ages and take weighted mean across predator ages)

Usage

plot_diet_comp(Rceattle, file = NULL, species = NULL)

Arguments

Value

Returns and saves a figure

Description

Plots the mean exploitable biomass (million mt) and 95\

Usage

plot_exploitable_biomass(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the exploitable biomass trajectory.

Description

Function that plots the F time series per species from Rceattle

Usage

plot_f(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  right_adj = 0,
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE
)

Arguments

Value

Returns and saves a figure with the population trajectory.

Description

Function to plot the functional form estimated or specified by Rceattle

Usage

plot_form(params = NULL, pred = 1, pred_age = 1, prey = 1, msmMode = 3)

Arguments

Description

Plot of fitted CPUE indices on natural-scale (r4ss-style)

Usage

plot_index(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  right_adj = 0,
  top_adj = 0.05,
  incl_proj = FALSE,
  single.plots = FALSE,
  width = NULL,
  height = NULL,
  error = TRUE
)

Arguments

Description

Plot of residuals CPUE indices on log-scale (r4ss-style)

Usage

plot_indexresidual(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  right_adj = 0,
  top_adj = 0.05,
  incl_proj = FALSE,
  single.plots = FALSE,
  width = NULL,
  height = NULL
)

Arguments

Description

Plot of fitted CPUE indices on log-scale (r4ss-style)

Usage

plot_logindex(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  right_adj = 0,
  top_adj = 0.05,
  incl_proj = FALSE,
  single.plots = FALSE,
  width = NULL,
  height = NULL
)

Arguments

Description

Function that plots the natural mortality at age (M1 + M2) as estimated from Rceattle. Returns and saves a figure with the M-at-age trajectory.

Usage

plot_m_at_age(
  Rceattle,
  file = NULL,
  age = 1,
  model_names = NULL,
  line_col = NULL,
  spnames = NULL,
  species = NULL,
  lwd = 3,
  lty = 1,
  right_adj = 0,
  minyr = NULL,
  width = 7,
  height = 6.5,
  incl_proj = FALSE,
  incl_mean = FALSE,
  add_ci = FALSE
)

Arguments

Description

Function that plots the predation mortality at age (M2) by predator as estimated from Rceattle. Returns and saves a figure with the M-at-age trajectory.

Usage

plot_m2_at_age_prop(
  Rceattle,
  file = NULL,
  age = 1,
  model_names = NULL,
  line_col = NULL,
  spnames = NULL,
  species = NULL,
  lwd = 3,
  right_adj = 0,
  top_adj = 0.15,
  minyr = NULL,
  width = 7,
  height = 6.5,
  incl_proj = FALSE,
  incl_mean = FALSE,
  add_ci = FALSE
)

Arguments

Description

Function that plots the maturity of each species

Usage

plot_maturity(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  width = 4,
  height = 5.5,
  lwd = 3
)

Arguments

Description

Function that plots the M1 and M2 as estimated from Rceattle

Usage

plot_mortality(
  Rceattle,
  file = NULL,
  incl_proj = FALSE,
  zlim = NULL,
  type = 0,
  width = 8,
  height = 5.5,
  title = NULL,
  log = FALSE,
  minyr = NULL,
  theta = 155,
  species = NULL,
  maxage = NULL,
  title_cex = 10,
  M2 = TRUE
)

Arguments

Description

Function that plots the ration across ages (minage:nages) as estimated from Rceattle. Returns and saves a figure with the ration trajectory. Ration is multiplied by biomass-at-age/sex to get population level estimates

Usage

plot_ration(
  Rceattle,
  file = NULL,
  minage = 1,
  model_names = NULL,
  line_col = NULL,
  spnames = NULL,
  species = NULL,
  lwd = 3,
  lty = 1,
  right_adj = 0,
  minyr = NULL,
  width = 7,
  height = 6.5,
  incl_proj = FALSE,
  incl_mean = FALSE,
  add_ci = FALSE
)

Arguments

Description

Plots the mean minage recruitment (millions) and 95\

Usage

plot_recruitment(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the recruitment trajectory.

Description

Function that plots the fishery and survey selectivity as estimated from Rceattle

Usage

plot_selectivity(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  width = 7,
  height = 6.5,
  species = c("Walleye pollock", "Pacific cod", "Arrowtooth flounder"),
  lwd = 3
)

Arguments

Description

Function the plots the fishery selectivity and input maturity. Useful for debugging SPR based reference points.

Usage

plot_selectivity_vs_maturity(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  width = 7,
  height = 6.5,
  species = c("Walleye pollock", "Pacific cod", "Arrowtooth flounder"),
  lwd = 3
)

Arguments

Description

Plots the mean SSB (million mt) and 95\

Usage

plot_ssb(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments

Value

Returns and saves a figure with the SSB trajectory.

Description

Deprecated alias for plot_ssb_depletion. Please use plot_ssb_depletion() instead.

Usage

plot_ssb_depletion(
  Rceattle,
  file = NULL,
  model_names = NULL,
  line_col = NULL,
  species = NULL,
  spnames = NULL,
  add_ci = FALSE,
  lwd = 3,
  save = FALSE,
  right_adj = 0,
  legend.pos = "topright",
  width = 7,
  height = 6.5,
  minyr = NULL,
  maxyr = NULL,
  incl_proj = FALSE,
  mod_cex = 1,
  lty = rep(1, length(Rceattle)),
  alpha = 0.4,
  mod_avg = rep(FALSE, length(Rceattle)),
  mse = FALSE,
  OM = TRUE,
  reference = NULL
)

Arguments