Package 'wham'

output from fit_wham

T/F, return list? Default = FALSE, just prints to console

The compiled object

optional argument containing pre-computed Hessian matrix

(named) list of fit WHAM/ASAP models. To read in ASAP model output, use read_asap3_fit. If no names are given, 'm1', 'm2', ... will be used.

T/F, produce table of AIC and/or Mohn's rho? Default = TRUE.

T/F, produce plots? Default = TRUE.

character, path to directory to save table and/or plots. Default = getwd().

list of options to generate comparison results:

$stock

integer, which stock to include in results. Default = 1.

$region

integer, which region to include in results. Default = 1.

list of options for AIC/rho table:

$fname

character, filename to save CSV results table (.csv will be appended). Default = 'model_comparison'.

$sort

T/F, sort by AIC? Default = TRUE.

$calc.rho

T/F, calculate Mohn's rho? Retrospective analysis must have been run for all modes. Default = TRUE.

$calc.aic

T/F, calculate AIC? Default = TRUE.

$print

T/F, print table to console? Default = TRUE.

$save.csv

T/F, save table as a CSV file? Default = FALSE.

list of options for plots:

$out.type

character, either 'pdf' or 'png' (default = 'png' because I am not sure system('pdftk') will work across platforms.)

$ci

vector of T/F, length = 1 (applied to all models) or number of models

$years

vector, which years to plot? Default = all (model and projection years).

$which

vector, which plots to make? Default = all. See details.

$relative.to

character, name of "base" model to plot differences relative to.

$alpha

scalar, (1-alpha)% confidence intervals will be plotted. Default = 0.05 for 95% CI.

$ages.lab

vector, overwrite model age labels.

$kobe.yr

integer, which year to use in Kobe plot (relative status). Default = terminal model year.

$M.age

integer, which age to use in M time-series plot. Default = max(data$which_F_age) (max age of F to use for full total F).

$return.ggplot

T/F, return a list of ggplot2 objects for later modification? Default = TRUE.

$kobe.prob

T/F, print probabilities for each model in each quadrant of Kobe plot? Default = TRUE.

$refpt

"XSPR" or "MSY", which reference point to use. Default = "XSPR".

a fitted WHAM model object returned by fit_wham or project_wham.

T/F, calculate standard deviations of model parameters? See sdreport. Default = FALSE.

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport to reduce model object file size. Default = TRUE.

Optimized TMB model, output from fit_tmb.

Integer, number of peels to use in retrospective analysis. Default = 7.

Character, specifies which parameters to treat as random effects. Default = "model$input$random".

T/F, use MLEs from full model fit as initial values for each peel? If not, the initial values from full model input are used. Default = TRUE.

T/F, calculate standard deviations of model parameters for each peel? Default = FALSE.

integer, number of additional Newton steps after optimization for each peel. Default = 0.

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

T/F, Passed to argument of internal fit_peel function. Determines whether peel number is printed to screen. Default = FALSE.

T/F, should modified input list be saved for every peel? Necessary to project from a peel but increases model object size. Default = FALSE.

T/F, calculate and report biological reference points

T/F, whether to verify the wham package commit and version for the fitted model are the same as the currently used package.

a fitted WHAM model object returned by fit_wham or project_wham.

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport to reduce model object file size. Default = TRUE.

T/F whether to use the bias.correct feature of TMB::sdreport. Default = FALSE.

T/F whether to return the joint precision matrix for the fixed and random effects from TMB::sdreport. Default = FALSE.

The compiled object

Integer, number of years of data to remove before model fitting.

input with same structure as that provided by prepare_wham_input. May want to use input$par = model$parList to start at MLEs.

T/F, calculate standard deviations of model parameters? Default = FALSE.

integer, number of additional Newton steps after optimizafit_tmbtion for each peel. Default = 3.

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

T/F, Passed to argument of internal fit_peel function. Determines whether peel number is printed to screen. Default = FALSE.

T/F, should modified input list be saved? Necessary to project from a peel but increases model object size. Default = FALSE.

Output from TMB::MakeADFun.

Integer, number of additional Newton steps after optimization. Default = 3.

T/F, calculate standard deviations of model parameters? See TMB::sdreport. Default = TRUE.

T/F, check if model parameters are identifiable? Runs internal check_estimability, originally provided by https://github.com/kaskr/TMB_contrib_R/TMBhelper. Default = TRUE.

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport) to reduce model object file size. Default = FALSE.

T/F, use stats::optim instead of stats::nlminb? Default = FALSE.

list of control parameters to pass to optimizer. For nlminb default = list(iter.max = 1000, eval.max = 1000). For optim default = list(maxit=1000).

Named list with components:

$data

Data to fit the assessment model to.

$par

Parameters, a list of all parameter objects required by the user template (both random and fixed effects). See MakeADFun.

$map

Map, a mechanism for collecting and fixing parameters. See MakeADFun.

$random

Character vector defining the parameters to treat as random effect. See MakeADFun.

$years

Numeric vector of the years which the model spans. Not important for model fitting, but useful for plotting.

$model_name

Character, name of the model, e.g. "Yellowtail flounder"

$ages.lab

Character vector of the age labels, e.g. c("1","2","3","4+").

integer, number of additional Newton steps after optimization. Passed to fit_tmb. Default = 3.

T/F, calculate standard deviations of model parameters? See sdreport. Default = TRUE.

T/F, do retrospective analysis? Default = TRUE.

integer, number of peels to use in retrospective analysis. Default = 7.

T/F, calculate one-step-ahead (OSA) residuals? Default = TRUE. See details. Returned as mod$osa$residual.

list of 2 options (method, parallel) for calculating OSA residuals, passed to TMB::oneStepPredict. Default: osa.opts = list(method="oneStepGaussianOffMode", parallel=TRUE). See make_osa_residuals.

T/F, obtain sample from posterior of random effects? Default = TRUE. NOT YET IMPLEMENTED.

(optional), a previously fit wham model.

T/F, check if model parameters are identifiable? Passed to fit_tmb. Runs internal function check_estimability, originally provided by https://github.com/kaskr/TMB_contrib_R/TMBhelper. Default = TRUE.

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

T/F, Passed to argument of internal retro function. Determines whether peel number is printed to screen. Default = FALSE.

T/F, do projections? Default = FALSE. If true, runs project_wham.

a named list with the following components:

• $n.yrs (integer), number of years to project/forecast. Default = 3.

• $use.last.F (T/F), use terminal year F for projections. Default = TRUE.

• $use.FXSPR (T/F), calculate and use F at X

• $use.FMSY (T/F), calculate and use FMSY for projections.

• $proj.F (vector), user-specified fishing mortality for projections. Length must equal n.yrs.

• $proj.catch (vector), user-specified aggregate catch for projections. Length must equal n.yrs.

• $avg.yrs (vector), specify which years to average over for calculating reference points. Default = last 5 model years, tail(model$years, 5).

• $cont.ecov (T/F), continue ecov process (e.g. random walk or AR1) for projections. Default = TRUE.

• $use.last.ecov (T/F), use terminal year ecov for projections.

• $avg.ecov.yrs (vector), specify which years to average over the environmental covariate(s) for projections.

• $proj.ecov (matrix), user-specified environmental covariate(s) for projections. n.yrs x n_Ecov.

• $cont.Mre (T/F), continue M random effects (i.e. AR1_y or 2D AR1) for projections. Default = TRUE. If FALSE, M will be averaged over $avg.yrs (which defaults to last 5 model years).

• $avg.rec.yrs (vector), specify which years to calculate the CDF of recruitment for use in projections. Default = all model years.

• $percentFXSPR (scalar), percent of F_XSPR to use for calculating catch in projections, only used if proj.opts$use.FXSPR = TRUE. For example, GOM cod uses F = 75

• $percentFMSY (scalar), percent of F_MSY to use for calculating catch in projections, only used if $use.FMSY = TRUE.

T/F, fit the model using fit_tmb. Default = TRUE.

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport to reduce model object file size. Default = TRUE.

T/F, calculate and report biological reference points. Default = TRUE.

list of optimizer controlling attributes passed to fit_tmb. Default is list(use.optim = FALSE, opt.control = list(iter.max = 1000, eval.max = 1000)), so stats::nlminb is used to opitmize.

T/F whether to use the bias.correct feature of TMB::sdreport. Default = FALSE.

T/F whether TMB::sdreport should return the joint precision matrix for the fixed and random effects. Default = FALSE.

(required) location of RDS file with fitted WHAM model.

the number of different starting locations on the likelihood surface to refit the model from. Default = 10.

(optional) matrix (n_jitter x n parameters) of starting values to use for jittering.

(optional) which rows of intial_vals to use for jittering. Useful if doing jitter fits in stages.

T/F whether to do jitter fits in parallel. Requires snowfall and parallel packages to be installed. Default = TRUE.

(optional) the number of cores to use for parallel fitting.

directory where to save individual files for each jitter refit. Useful if jittering for some reason crashes R. If not provided, no files will be saved.

(optional) location of WHAM package. Useful if not using the WHAM installation in the standard library location.

(optional) directory for package repository. To be used when the function is being called during package testing rather than an installed version of WHAM.

A fit WHAM model, output from fit_wham.

A fit WHAM model, output from fit_wham with do.retro = TRUE.

output from fit_wham

character, directory to save plots to (default = getwd())

character, either 'html', 'pdf', or 'png' (default = 'html')

resolution to save .png files (dpi)

(optional) list of plot modifications

a previously fit wham model

a named list with the following components:

• $n.yrs (integer), number of years to project/forecast. Default = 3.

• $use.last.F (T/F), use terminal year F for projections. Default = TRUE.

• $use.avg.F (T/F), use average of F over certain years for projections. Default = FALSE. Years to average over determined by $avg.yrs defined below.

• $use.FXSPR (T/F), calculate and use F at X% SPR for projections. Default = FALSE.

• $use.FMSY (T/F), calculate and use FMSY for projections. Default = FALSE.

• $proj.F (vector), user-specified fishing mortality for projections. Length must equal n.yrs.

• $proj.catch (vector), user-specified aggregate catch for projections. Length must equal n.yrs.

• $avg.yrs (vector), specify which years to average over for calculating reference points. Default = last 5 model years, tail(model$years, 5).

• $cont.ecov (T/F), continue ecov process (e.g. random walk or AR1) for projections. Default = TRUE.

• $use.last.ecov (T/F), use terminal year ecov for projections.

• $avg.ecov.yrs (vector), specify which years to average over the environmental covariate(s) for projections.

• $proj.ecov (matrix), user-specified environmental covariate(s) for projections. n.yrs x n.ecov.

• $cont.M.re (T/F), continue M random effects (i.e. AR1_y or 2D AR1) for projections. Default = FALSE. If FALSE, M will be averaged over $avg.yrs (which defaults to last 5 model years).

• $cont.move.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters will be averaged over $avg.yrs (which defaults to last 5 model years).

• $cont.L.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters will be averaged over $avg.yrs (which defaults to last 5 model years).

• $avg.rec.yrs (vector), specify which years to calculate the CDF of recruitment for use in projections. Default = all model years. Only used when recruitment is estimated as fixed effects (SCAA).

• $percentFXSPR (scalar), percent of F_XSPR to use for calculating catch in projections, only used if $use.FXSPR = TRUE. For example, GOM cod uses F = 75% F_40%SPR, so proj.opts$percentFXSPR = 75. Default = 100.

• $percentFMSY (scalar), percent of F_MSY to use for calculating catch in projections, only used if $use.FMSY = TRUE.

• $proj_F_opt (vector), integers specifying how to configure each year of the projection: 1: use terminal F, 2: use average F, 3: use F at X% SPR, 4: use specified F, 5: use specified catch, 6: use Fmsy. Overrides any of the above specifications.

• $proj_Fcatch (vector or matrix), catch or F values to use each projection year: values are not used when using Fmsy, FXSPR, terminal F or average F. Overrides any of the above specifications of proj.F or proj.catch. if vector, total catch or F is supplied else matrix columns should be fleets for fleet-specific F to be found/used (n.yrs x 1 or n_fleets).

• $proj_mature (array), user-supplied maturity values for the projection years with dimensions (n_stocks x n.yrs x n_ages).

• $proj_waa (3-d array), user-supplied waa values for the projection years with first and third dimensions equal to that of model$input$data$waa (waa source x n.yrs x n_ages).

• $proj_R_opt (integer), 1: continue any RE processes for recruitment, 2: make projected recruitment consistent with average recruitment in SPR reference points and cancel any bias correction for NAA in projection years.

• $proj_NAA_init (scalar), the default starting value for all NAA random effects in projection years is exp(10), which may not be large enough for some catch specification. Use this to change the default if a call to project_wham suggests it.

T/F check whether version WHAM and TMB for fitted model match that of the version of WHAM using for projections. Default = TRUE.

(optional) list containing data and parameters (output from read_asap3_dat)

character, name of stock/model

numeric, option to specify stock-recruit model (see details)

(optional) named list of environmental covariate data and parameters (see set_ecov for full details)

(optional) list specifying selectivity options by block: models, initial values, parameters to fix, and random effects (see set_selectivity for full details)

(optional) list specifying natural mortality options: model, random effects, initial values, and parameters to fix (see set_M for full details)

(optional) list specifying options for random effect on numbers-at-age, initial numbers at age, and recruitment model (see set_NAA for full details)

(optional) list specifying options for priors and random effects on catchability (see set_q for full details)

(optional) character or named list, specifies age composition model for fleet(s) and indices (see set_age_comp for full details)

(optional) list specifying movement/migration options for models with more than 1 region (see set_move for full details)

(optional) list specifying "extra" mortality options (see set_L for full details)

(optional) list specifying fishing mortality options (see set_F for full details)

(optional) list specifying catch information (see set_catch for full details)

(optional) list specifying index informaiton (see set_indices for full details)

(optional) list of basic population information for use when asap3 is not provided (see details)

a previously fit wham model

a named list with the following components:

• $n.yrs (integer), number of years to project/forecast. Default = 3.

• $use.last.F (T/F), use terminal year F for projections. Default = TRUE.

• $use.avg.F (T/F), use average of F over certain years for projections. Default = FALSE. Years to average over determined by $avg.yrs defined below.

• $use.FXSPR (T/F), calculate and use F at X% SPR for projections. Default = FALSE.

• $use.FMSY (T/F), calculate and use FMSY for projections. Default = FALSE.

• $proj.F (vector), user-specified fishing mortality for projections. Length must equal n.yrs.

• $proj.catch (vector), user-specified aggregate catch for projections. Length must equal n.yrs.

• $avg.yrs (vector), specify which years to average over for calculating reference points. Default = last 5 model years, tail(model$years, 5).

• $cont.ecov (T/F), continue ecov process (e.g. random walk or AR1) for projections. Default = TRUE.

• $use.last.ecov (T/F), use terminal year ecov for projections.

• $avg.ecov.yrs (vector), specify which years to average over the environmental covariate(s) for projections.

• $proj.ecov (matrix), user-specified environmental covariate(s) for projections. n.yrs x n.ecov.

• $cont.M.re (T/F), continue M random effects (i.e. AR1_y or 2D AR1) for projections. Default = FALSE. If FALSE, M will be averaged over $avg.yrs (which defaults to last 5 model years).

• $cont.move.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters will be averaged over $avg.yrs (which defaults to last 5 model years).

• $cont.L.re (T/F), continue any movement random effects for projections. Default = FALSE. If FALSE, movement parameters will be averaged over $avg.yrs (which defaults to last 5 model years).

• $avg.rec.yrs (vector), specify which years to calculate the CDF of recruitment for use in projections. Default = all model years. Only used when recruitment is estimated as fixed effects (SCAA).

• $percentFXSPR (scalar), percent of F_XSPR to use for calculating catch in projections, only used if $use.FXSPR = TRUE. For example, GOM cod uses F = 75% F_40%SPR, so proj.opts$percentFXSPR = 75. Default = 100.

• $percentFMSY (scalar), percent of F_MSY to use for calculating catch in projections, only used if $use.FMSY = TRUE.

• $proj_F_opt (vector), integers specifying how to configure each year of the projection: 1: use terminal F, 2: use average F, 3: use F at X% SPR, 4: use specified F, 5: use specified catch, 6: use Fmsy. Overrides any of the above specifications.

• $proj_Fcatch (vector or matrix), catch or F values to use each projection year: values are not used when using Fmsy, FXSPR, terminal F or average F. Overrides any of the above specifications of proj.F or proj.catch. if vector, total catch or F is supplied else matrix columns should be fleets for fleet-specific F to be found/used (n.yrs x 1 or n_fleets).

• $proj_mature (array), user-supplied maturity values for the projection years with dimensions (n_stocks x n.yrs x n_ages).

• $proj_waa (3-d array), user-supplied waa values for the projection years with first and third dimensions equal to that of model$input$data$waa (waa source x n.yrs x n_ages).

• $proj_R_opt (integer), 1: continue any RE processes for recruitment, 2: make projected recruitment consistent with average recruitment in SPR reference points and cancel any bias correction for NAA in projection years.

• $proj_NAA_init (scalar), the default starting value for all NAA random effects in projection years is exp(10), which may not be large enough for some catch specification. Use this to change the default if a call to project_wham suggests it.

integer, number of additional Newton steps after optimization. Passed to fit_tmb. Default = 0 for projections.

T/F, calculate standard deviations of model parameters? See sdreport. Default = TRUE.

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

T/F, save the full TMB::sdreport object? If FALSE, only save summary.sdreport to reduce model object file size. Default = TRUE.

T/F check whether version WHAM and TMB for fitted model match that of the version of WHAM using for projections. Default = TRUE.

T/F whether to use the bias.correct feature of TMB::sdreport. Default = FALSE.

T/F whether to return the joint precision matrix for the fixed and random effects from TMB::sdreport. Default = FALSE.

character vector, names of ASAP3 .dat files. The file either needs to be in the current working directory, or filename can include the path. If multipile files, a multi-stock model will be assumed.

character, directory where ASAP3 output files are located (ex: 'C:/MY/file/directories/model/'). 5 files are needed: .rdat, .dat, .std, .cor, and .par.

character, base name of original .dat file (i.e. without the .dat extension)

scalar, user-specified percent SPR to use for reference points, expressed as 100*SSBPR(Fspr)/SSBPR(F=0). Default = 40.

output from fit_wham

(1-alpha)% confidence intervals will be calculated. Default = 0.05 for 95% CI.

list containing data, parameters, map, and random elements (output from prepare_wham_input). NOT from prepare_projection or project_wham

which of input$years to peel from the model input

(T/F) whether this is for a retro peel (Default = TRUE)

Optimized TMB model, output from fit_tmb.

Integer, number of peels to use in retrospective analysis. Default = 7.

Character, specifies which parameters to treat as random effects. Default = "model$input$random".

T/F, use MLEs from full model fit as initial values for each peel? If not, the initial values from full model input are used. Default = TRUE.

T/F, calculate standard deviations of model parameters for each peel? Default = FALSE.

integer, number of additional Newton steps after optimization for each peel. Default = 0.

T/F, Passed to silent argument of TMB::MakeADFun. Default = FALSE.

T/F, Passed to argument of internal fit_peel function. Determines whether peel number is printed to screen. Default = FALSE.

T/F, should modified input list be saved for every peel? Necessary to project from a peel but increases model object size. Default = FALSE.

T/F, calculate and report biological reference points

T/F, whether to verify the wham package commit and version for the fitted model are the same as the currently used package.

(required) location of RDS file with fitted WHAM model.

the number of simulated data sets to create and fit. Default = 10.

(optional) vector of seeds to use to generate each simulated data set.

(optional) which seeds to use for simualted data set. Useful if doing self test in stages.

T/F whether to fix rather than simulate estimated random effects. Deafult = TRUE.

(optional) list of input$map elements for altering mapping assumptions of fitted model.

T/F whether to do self-test fits in parallel. Requires snowfall and parallel packages to be installed. Default = TRUE.

(optional) the number of cores to use for parallel fitting.

directory where to save individual files for each self test fit. Useful if doing self test in stages. If not provided, no files will be saved.

(optional) location of WHAM package. Useful if not using the WHAM installation in the standard library location.

(optional) directory for package repository. To be used when the function is being called during package testing rather than an installed version of WHAM.

T/F whether to save the simulated inputs in res_dir. Default = FALSE.

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

specifies the age composition models for fleet(s) and indices. If NULL, the multinomial is used because this was the only option in ASAP.

The age composition models available are:

"multinomial"

Multinomial. This is the default because it was the only option in ASAP. 0 parameters.

"dir-mult"

Saturating Dirichlet-multinomial, parameterized such that effective-sample-size is a nonlinear and saturating function with respect to input-sample-size. 1 parameter. Effective sample size is estimated by the model (Candy 2008)

"dirichlet-pool0"

Dirichlet, pooling zero observations with adjacent age classes. 1. parameter. See Francis 2014 and Albertsen et al. 2016

"dirichlet-miss0"

Dirichlet, treating zero observations as missing. 1 parameter.

"logistic-normal-miss0"

Logistic normal, treating zero observations as missing. 1 parameter.

"logistic-normal-ar1-miss0"

Logistic normal, treating zero observations as missing. 1 parameter.

"logistic-normal-pool0"

Logistic normal, pooling zero observations with adjacent age classes. 1 parameter. See Schnute and Haigh (2007) and Francis (2014)

.

"logistic-normal-01-infl"

Zero-or-one inflated logistic normal. Inspired by zero-one inflated beta in Ospina and Ferrari (2012). 3 parameters. . No OSA residuals.

"logistic-normal-01-infl-2par"

Zero-one inflated logistic normal where p0 is a function of binomial sample size. 2 parameters. No OSA residuals.

"mvtweedie"

Multivariate-tweedie, where the product of composition proportions and input sample sizes follows a distribution with mean equal to the product of predicted proportions and input sample size, and other parameters define the ratio of effective to input sample size (with is bounded 0 to Inf) and the probability of zeros. 2 parameters. No OSA residuals.

"dir-mult-linear"

Linear Dirichlet-multinomial, parameterized such that effective-sample-size is a linear function with respect to input-sample-size, estimating 1 parameter, $log(\theta)$, where the ratio of effective and input sample size is approximately $\theta / (1+\theta)$, i.e., the logistic transformation of the estimated parameter $log(\theta)$. (Thorson et al. 2017)

The two Dirichlet-multinomial options will only differ when input-sample-size differs among years. In these cases, the linear-Dirichlet multinomial is designed to decrease the effective sample size in each year by approximately the same proportion, while the saturating-Dirichlet multinomial will decrease the years with highest input-sample-size much more than those with lower input-sample-size. One-step-ahead residuals will be calculated for all but options 8-10 when do.osa=TRUE (Nielsen et al. in prep.). An age composition model needs to be specified for each fleet and index. If you would like all fleets and indices to use the same age composition likelihood, you can simply specify one of the strings above, i.e. age_comp = "logistic-normal-miss0". If you do not want the same age composition model to be used for all fleets and indices, you must specify a named list with the following entries:

$fleets

A vector of the above strings with length = the number of fleets.

$indices

A vector of the above strings with length = the number of indices.

list containing data, parameters, map, and random elements (output from prepare_wham_input)

(optional) list specifying various aspects about catch by fleet (see details)

catch_info specifies observations, and various configuration options for fleet-specific catch observations and will overwrite attributes specified in the ASAP data file. If NULL, all settings from the ASAP data file or basic_info are used. catch_info is a list with any of the following entries:

$n_fleets

number of fleets

$fleet_regions

vector (n_fleets) of regions where each fleet operates.

$fleet_seasons

matrix (n_fleets x n_seasons) of 0/1 values flagging which seasons each fleet operates.

$fleet_names

character vector (n_fleets) of names for fleets. Used for naming results in plots and tables.

$agg_catch

matrix (n_years_model x n_fleets) of annual aggregate catches by fleet.

$agg_catch_cv

matrix (n_years_model x n_fleets) of CVs for annual aggregate catches by fleet.

$catch_paa

array (n_fleets x n_years_model x n_ages) of annual catch proportions at age by fleet.

$use_catch_paa

matrix (n_years_model x n_fleets) of 0/1 values flagging whether to use proportions at age observations.

$catch_Neff

matrix (n_years_model x n_fleets) of effective sample sizes for proportions at age observations.

$waa_pointer_fleets

vector (n_fleets) of itegers indicated waa to use for each fleet.

$selblock_pointer_fleets

matrix (n_years_model x n_fleets) of itegers indicated selblocks to use.

$initial_catch_sd_scale

vector (n_fleets) of scalar multipliers of annual log-observation standard deviation. Default = 1.

$map_catch_sd_scale

integer vector (n_fleets) specifying which sd scalar parameters to fix. Use NA to fix a parameter and integers to estimate. Use the same integer for multiple fleets to estimate a shared scalar parameter.

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

(optional) named list of environmental covariate data and parameters (see details)

ecov specifies any environmental covariate data and model as well as the effect on the population. Environmental covariate data need not span the same years as the fisheries data. It can be NULL if no environmental data are to be fit. Otherwise, it must be a named list with the following components:

$label

Name(s) of the environmental covariate(s). Used in printing.

$mean

Mean observations (matrix). number of years x number of covariates. Missing values = NA.

$logsigma

Configure observation standard errors. Options:

Matrix of $log$ standard errors with same dimensions as $mean

Specified values for each time step

log standard errors for each covariate, numeric vector or matrix w/ dim 1 x n.ecov

Specified value the same for all time steps

estimation option (for all covariates). character string:

"est_1": Estimated, one value shared among time steps. "est_re": Estimated value for each time step as random effects with two parameters (mean, var)

list of two elements.

First is the matrix of log standard errors or the vector of single values for each covariate as above. Second is a character vector of estimation options (NA, "est_1","est_re") for each covariate. For covariates with non-NA values, values in the first element are ignored.

$year

Years corresponding to observations (vector of same length as $mean and $logsigma)

$use_obs

T/F (or 1/0) vector/matrix of the same dimension as $mean and $logsigma. Use the observation? Can be used to ignore subsets of the ecov without changing data files.

$process_model

Process model for the ecov time-series. "rw" = random walk, "ar1" = 1st order autoregressive, NA = do not fit

$process_mean_vals

vector of (initial) mean values for the ecov time-series.

$process_sig_vals

vector of (initial) standard deviation values for the ecov time-series.

$process_cor_vals

vector of (initial) correlation values for the ecov time-series.

$recruitment_how

character matrix (n_Ecov x n_stocks) indicating how each ecov affects recruitment for each stock. Options are based on (see Iles & Beverton (1998)) combined with the order of orthogonal polynomial of the covariate and has the form "type-lag-order". "type" can be:

= "none"

no effect.

= "controlling"

pre-recruit density-independent mortality.

= "limiting"

maximum recruitment, e.g. ecov determines amount of suitable habitat)

= "lethal"

threshold, i.e. R –> 0 at some ecov value.

= "masking"

metabolic/growth, decreases dR/dS

= "directive"

e.g. behavioral

for type other than "none", "lag" can be:

= "lag-n"

lag = n which can be 0,1,2,.... lag-1 implies the covariate in year y affects recruitment in year y+1.

for "type" being other than "none", "order" can be:

= "linear"

the covariate effect is linear on the transformed recruitment parameter (e.g., log).

= "poly-n"

orthogonal polynomial where n = 1 (same as "linear"),2,...

so "limiting-lag-1-poly-2" would model the covariate affecting recruitment the next year (lag = 1) as a second order orthogonal polynomial ($b_0 + b_1*ecov + b_2*ecov^2 + ...$) limiting effect.

$M_how

character array (n_Ecov x n_stocks x n_ages x n_regions) indicating how each ecov affects M by age,stock,region and has the form "lag-order". "lag" can be:

= "none"

no effect.

= "lag-n"

lag = n which can be 0,1,2,.... lag-1 implies the covariate in year y affects M in year y+1.

for "lag" being other than "none", "order" can be:

= "linear"

the covariate effect is linear on the transformed M parameter (e.g., log).

= "poly-n"

orthogonal polynomial where n = 1 (same as "linear"),2,...

$M_effect_map

integer array (n_stocks x n_ages x n_regions x n_Ecov) indicating which estimated effects are common by age,stock,region. If not specified there the same effect is estimated for all M where $M_how is other than "none" for each covariate.

$q_how

character matrix (n_Ecov x n_indices) indicating whether each ecov affects catchability for each index. and has the form "lag-order". "lag" can be:

= "none"

no effect.

= "lag-n"

lag = n which can be 0,1,2,.... lag-1 implies the covariate in year y affects catchability in year y+1.

for "lag" being other than "none", "order" can be:

= "linear"

the covariate effect is linear on the transformed catchability parameter (e.g., log).

= "poly-n"

orthogonal polynomial where n = 1 (same as "linear"),2,...

$move_how

character array (n_Ecov x n_stocks x n_ages x n_seasons x n_regions x n_regions - 1) indicating whether each ecov affects movement from one region to the others by stock,age,season. and has the form "lag-order". "lag" can be:

= "none"

no effect.

= "lag-n"

lag = n which can be 0,1,2,.... lag-1 implies the covariate in year y affects a movement parameter in year y+1.

for "lag" being other than "none", "order" can be:

= "linear"

the covariate effect is linear on the transformed movement parameter (e.g., log).

= "poly-n"

orthogonal polynomial where n = 1 (same as "linear"),2,...

$move_effect_map

integer array (n_stocks x n_ages x n_seasons x n_regions x n_regions-1 x n_Ecov) indicating which estimated effects are common by age,stock,region, season etc. If not specified the same effect is estimated for all movement parameters where $move_how is other than "none" for each covariate.

$beta_R_vals

n_stocks x n_ecov x max(n_poly_R) array of initial values for effects on recruitment.

$beta_M_vals

n_stocks x n_ages x n_regions x n_ecov x max(n_poly_M) array of initial values for effects on natural mortality.

$beta_q_vals

n_indices x n_ecov x max(n_poly_q) array of initial values for effects on catchability.

$beta_mu_vals

n_stocks x n_ages x n_seasons x n_regions x n_regions - 1 x n_ecov x max(n_poly_move) array of initial values for effects on movement parameters.

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

(optional) named list of initial values for annual fully-selected fishing mortality and configuration method for estimation.

F_opts specifies a few as well as the effect on the population. Environmental covariate data need not span the same years as the fisheries data. It can be NULL if no environmental data are to be fit. Otherwise, it must be a named list with the following components:

$F

matrix (n_years x n_fleets) of (initial) values for fully-selected fishing morality.

$F_config

integer 1: (default) configure F parameters (on log scale) as an F in the initial year and then deviations from one year to the next, or 2: configure F parameters as (log) annual values.

$F_map

matrix (n_years x n_fleets) of (initial) values for fully-selected fishing morality.

$map_F

Specify whether to fix any fully-selected F parameters, corresponds to map$F_pars. integer matrix (n_years x n_fleets). Use NA to fix parameters and common integers will make those parameters equal. E.g., for a given column (fleet) values NA,1,2,... will fix the first year and estimate other years. Use unique values for all distinct parameters for each year and fleet.

list containing data, parameters, map, and random elements (output from prepare_wham_input)

(optional) list specifying various aspects about catch by indices (see details)

index_info specifies observations, and various configuration options for index-specific catch observations and will overwrite attributes specified in the ASAP data file. If NULL, all settings from the ASAP data file or basic_info are used. index_info is a list with any of the following entries:

$n_indices

number of indices

$index_regions

vector (n_indices) of regions where each fleet operates.

$index_seasons

vector (n_indices) of 0/1 values flagging which seasons each index occurs.

$index_names

character vector (n_indices) of names for indices Used for naming results in plots and tables.

$agg_indices

matrix (n_years_model x n_indices) of annual aggregate index catches.

$agg_index_cv

matrix (n_years_model x n_indices) of CVs for annual aggregate index catches.

$fracyr_indices

matrix (n_years_model x n_indices) of fractions of year at which index occurs within the season (difference between time of survey and time at start of season).

$use_indices

matrix (n_years_model x n_indices) of 0/1 values flagging whether to use aggregate observations.

$units_indices

matrix (n_years_model x n_indices) of 1/2 values flagging whether aggregate observations are biomass (1) or numbers (2).

$index_paa

array (n_indices x n_years_model x n_ages) of annual catch proportions at age by index.

$use_index_paa

matrix (n_years_model x n_indices) of 0/1 values flagging whether to use proportions at age observations.

$units_index_paa

matrix (n_years_model x n_indices) of 1/2 values flagging whether composition observations are biomass (1) or numbers (2).

$index_Neff

matrix (n_years_model x n_indices) of effective sample sizes for proportions at age observations.

$waa_pointer_indices

vector (n_indices) of itegers indicated waa to use for each index.

$selblock_pointer_indices

matrix (n_years_model x n_indices) of itegers indicated selblocks to use.

$initial_index_sd_scale

vector (n_indices) of scalar multipliers of annual log-observation standard deviation. Default = 1.

$map_index_sd_scale

integer vector (n_indices) specifying which sd scalar parameters to fix. Use NA to fix a parameter and integers to estimate. Use the same integer for multiple indices to estimate a shared scalar parameter.

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

(optional) list specifying "extra" mortality options: model, random effects, initial values, and parameters to fix (see details)

L specifies estimation options for "extra" mortality. If NULL, This mortality source is not used. L is a list with the following entries:

$model

length = n_regions. "extra" mortality model options are:

"none"

(default) no extra mortality for this region.

"constant"

estimate a single mean mortality for the region shared across all ages

"iid_re"

estimate independent random effects over years, for the region

"ar1_re"

estimate random effect correlated over years, for the region

$initial_means

Initial/mean L-at-region

$sigma_vals

Initial standard deviation by region value to use for the L random effects. Values are not used if L$model = "none".

$cor_vals

Initial correlation values to use for the L random effects. If unspecified all initial values are 0

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

(optional) list specifying natural mortality options: model, random effects, initial values, and parameters to fix (see details)

M specifies estimation options for natural mortality and can overwrite M-at-age values specified in the ASAP data file. If NULL, the M-at-age matrix from the ASAP data file is used (M fixed, not estimated). To estimate M-at-age shared/mirrored among some but not all ages, modify M$means_map (see vignette for more details). M is a list with the following entries:

$mean_model

Character describing the type of model for M stock and regional models for natural mortality. Options are:

"fixed-M"

Use initial values from ASAP3 dat files or $initial_means for (mean) M as fixed values. If no ASAP3 files and $initial_means is not provided, default is M = 0.2 for all stocks, regions and ages

"estimate-M"

estimate one or more (mean) M parameters. Default is to estimate a single M shared across all stocks and ages, but use $means_map to fix or estimate parameters for specific stocks, regions, ages.

"weight-at-age"

specifies M as a function of weight-at-age, $M_y,a = exp(b0 + b1*log(W_y,a))$, as in Lorenzen (1996) and Miller & Hyun (2018). Default is to estimate a single model shared across all stocks and regions, but use $means_map[s,r,1] to fix or estimate the intercept for specific stocks, regions. See also $logb_prior and $initial_b configuring the slope on log scale.

$initial_means

array (n_stocks x n_regions x n_ages) of initial/mean M by stock, region and age. If NULL, initial mean M-at-age values for a given stock and region are taken from the first row of the MAA matrix in the ASAP data file. If no ASAP data file, M = 0.2 is the default. If $mean_model is "weight-at-age" only elements for the first age ($initial_means[,,1]) are used (for the intercept of log(M)).

$means_map

array (n_stocks x n_regions x n_ages) of NA or integers ( 0 <= max <= n_stocks * n_regions * n_ages) indicating which ages to estimate (mean) M and whether to set any ages to be identical. E.g. in a model with 2 stock, 2 regions and 6 ages with constant M estimated for each stock across regions and ages $M_ages_map[1,,] = 1 and $M_ages_map[2,,] = 2. $M_ages_map[1,1,] = c(NA,1,1,2,2,3) will fix M for age 1 at the initial value, and estimates for ages 2 and 3 are identical as are those for ages 4 and 5 and different from age 6+ for stock 1 and region 1. If NULL, specifies all ages fixed at M$initial_means. If $mean_model is "weight-at-age" these are used for all stocks and regions and only the elements for the first age ($M_ages_map[,,1]) are used (for the intercept of log(M)).

$intial_MAA

array (n_stocks x n_regions x n_years x n_ages) of initial values for M at age. Intended to be uses when nothing pertaining to M estimated.

$b_model

"constant","stock","region", "stock-region" defining whether parameter is constant, stock-specific, region-specific, stock- and region-specific. Only used if M$mean_model = "weight-at-age".

$b_prior

T/F, should a N(mu, 0.08) prior (where mu = log(0.305) by default) be used on log_b? Based on Fig. 1 and Table 1 (marine fish) in Lorenzen (1996). (Only used if $mean_model is "weight-at-age").

$intial_b

if any elements of $mean_model is "weight-at-age", initial value for mean b for weight-at-age model.

$re_model

Character matrix (n_stocks x n_regions) of options for time- and age-varying (random effects) on M by stock and region. Possible values are:

"none"

(default) No random effects by age or year.

"iid_a"

uncorrelated M by age, constant in time.

"iid_y"

uncorrelated M by year, constant all ages.

"ar1_a"

M correlated by age (AR1), constant in time.

"ar1_y"

M correlated by year (AR1), constant all ages.

"iid_ay"

M uncorrelated by year and age (2D).

"ar1_ay"

M correlated by year and age (2D AR1), as in Cadigan (2016).

$re_map

array (n_stocks x n_regions x n_ages) of NA and integers (1 <= max <= n_ages) indicating which ages, for a given stock and region, have random effects (not NA) and whether to set RE for any ages to be identical. E.g. in a model with 2 stock, 2 regions and 6 ages, $re_map[2,1,] = c(NA,1,1,2,2,3) will not estimate RE for age 1, and those for ages 2 and 3 are identical as are those for ages 4 and 5 and different from age 6+ for stock 2 and region 1. If NULL, and $re_model specifies M random effects at age, at least two ages must be specified for correlation among ages to be estimated.

$sigma_vals

n_stocks x n_regions matrix Initial standard deviation value to use for the M random effects. Values are not used if M$re_model = "none". Otherwise, a single value. If unspecified all values are 0.1.

$cor_vals

n_stocks x n_regions x 2 array of initial correlation values to use for the M deviations. If unspecified all initial values are 0. When M$re_model =

"iid_a", "iid_y", "iid_ay" or "none"

values are not used.

"ar1_a"

first value cor_vals[s,r,1] is used.

"ar1_y"

second value cor_vals[s,r,2] is used.

"ar1_ay"

First is for "age", second is for "year".

$sigma_map

n_stocks x n_region matrix of NA or integers indicating which random effects sd is estimated and whether to set any to be identical. If not supplied a single sd will be estimated for any stock and region where $re_model is other than "none".

$cor_map

n_stocks x n_region matrix x 2 array of NA or integers indicating which random effects correlation parameters are estimated and whether to set any to be identical. If not supplied a single value for age and/or year will be estimated for any stock and region where $re_model is other than "none", "iid_a", "iid_y".

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

(optional) list specifying movement options: model, random effects, initial values, and parameters to fix (see details)

move specifies estimation options for movement. If NULL, no movement will occur. If there are multiple regions, each stock will be modeled separately in different regions without movement. move is a list with the following entries:

$stock_move

length = n_stocks, T/F whether each stock can move. If not provided then movement will be defined below for all stocks.

$separable

length = n_stocks, T/F whether movement should be modeled separably from mortality or both occuring simultaneously.

$mean_model

matrix (n_regions x (n_regions-1)): model options for fixed effects (mean and possibly variance) for each movement parameter are:

"none"

(default) no movement between regions.

"constant"

estimate a single movement rate to each region shared across all stocks, seasons, ages, years

"season"

estimate movement rates to each region for each season shared across all stocks, ages, years

"stock_constant"

estimate a movement rate for each stock to each region shared across all seasons, ages, years

"stock_season"

estimate a movement rate for each stock each season to each region shared across all ages, years

$age_re

matrix (n_regions x (n_regions-1)): options for age random effects (for each mean parameter defined in move$mean_model):

"none"

(default) no movement rate random effects by age.

"iid"

independent movement rate random effects by age.

"ar1"

allow first order autoregressive correlation of movement rate random effects by age.

$year_re

matrix (n_regions x (n_regions-1)): options for yearly random effects (for each mean parameter defined in move$mean_model):

"none"

(default) no movement rate random effects by year.

"iid"

independent movement rate random effects by year.

"ar1"

allow first order autoregressive correlation of movement rate random effects by year.

$prior_sigma

array (n_stocks x n_seasons x n_regions x n_regions - 1) of sd parameters for normal priors on mean movement parameters on transformed scale (-Inf,Inf)

$use_prior

array (n_stocks x n_seasons x n_regions x n_regions - 1) 0/1 indicator whether to include prior for mean movement parameters in joint log-likelihood.

$can_move

array (n_stocks x n_seasons x n_regions x n_regions) 0/1 indicator whether movement can occur from one region to another.

$must_move

array (n_stocks x n_seasons x n_regions) 0/1 indicator whether movement from region must occur.

$mean_vals

array (n_stocks x n_seasons x n_regions x n_regions-1) of initial movement rate parameters *from* each region. Usage depends on move$mean_model.

$sigma_vals

array (n_stocks x n_seasons x n_regions x n_regions -1) of initial standard deviations to use for random effects. Usage depends on move$age_re and move$year_re.

$cor_vals

array (n_stocks x n_seasons x n_regions x n_regions - 1x 2) of initial correlation values to use for random effects. Usage depends on move$age_re and move$year_re. cor_vals[,,,,1] is for correlation with age, and cor_vals[,,,,2] is for correlation with year.

list containing data, parameters, map, and random elements (output from prepare_wham_input)

(optional) list specifying options for numbers-at-age random effects, initial parameter values, and recruitment model (see details)

If NAA_re = NULL, a traditional statistical catch-at-age model is fit (NAA = pred_NAA for all ages, deterministic). Otherwise, NAA_re specifies numbers-at-age configuration. It is a list with the following possible entries:

$decouple_recruitment

T/F determining whether correlation structure of recruitment is independent of RE deviations for older ages (default = TRUE). Only applicable for NAA_re$sigma = "rec+1" and correlation across ages is specified. If TRUE and NAA_re$cor = "ar1_a", only deviations for ages>1 have the correlation structure. If TRUE and NAA_re$cor is "ar1_y" or "2dar1" separate year correlation parameters are estimated for recruitment and older ages.

$sigma

Which ages allow deviations from the predicted NAA given NAA from previous time step? Must be a single character string described below or a vector of length n_stocks. If length = 1, assumptions will be applied to all stocks. Options are specified with the strings:

"rec"

Random effects on recruitment (deviations), all other ages deterministic

"rec+1"

"Full state space" model with 2 estimated sigma_a, one for recruitment and one shared among other ages

$sigma_vals

Array (n_stocks x n_regions x n_ages) of initial standard deviation values to use for the NAA deviations. Values are not used if recruit_model = 1 and NAA_re$sigma is not specified. Only those for age 1 in the spawning region are used if NAA_re$sigma = "rec". If NAA_re$sigma_map is defined, the user must ensure that the configuration is compatible with NAA_re$sigma_vals

$sigma_map

You can specify a more complex parameter configuration by entering an integer array (nstocks x n_regions x n_ages), where each entry points to the NAA_sigma to use for that stock and age. E.g., for 2 stocks, 2 regions, and 6 ages, array(rep(c(1,2,2,3,3,3), each = 4),c(2,2,6)) will estimate 3 sigmas, with recruitment (age-1) deviations having their own sigma_R, ages 2-3 sharing sigma_2, and ages 4-6 sharing sigma_3. All parameters being the same for both stocks and across regions. The user must be sure that a compatible NAA_re$sigma configuration is defined. Values are not used if recruit_model = 1 and NAA_re$sigma is not specified.

$cor

Correlation structure for the NAA deviations. Must be a single character string described below or a vector of length n_stocks. If length = 1, assumptions will be applied to all stocks. Options are:

"iid"

NAA deviations vary by year and age, but uncorrelated.

"ar1_a"

NAA deviations correlated by age (AR1).

"ar1_y"

NAA deviations correlated by year (AR1).

"2dar1"

NAA deviations correlated by year and age (2D AR1).

$cor_vals

Array (n_stocks x n_regions x 3) of initial correlation values to use for the NAA deviations. The first value correspond to correlation across age. The second is for yearly correlation for NAA deviations for all ages if recruitment is not decoupled, or otherwise just ages after recruitemnt. The third correlation is for annual recruitment deviations and used only when recruitment is decoupled. If unspecified all initial values are 0. If NAA_re$cor = "iid", values are not used. If NAA_re$cor = "ar1_a", those for yearly correlation are not used, and vice versa for "ar1_y".

$cor_map

n_stocks x n_region matrix x 3 array of NA or integers indicating which random effects correlation parameters are estimated and whether to set any to be estimated identically. The 3 values for a given stock and region are for age, year ("survival"), and year ("recruitment"). Both age and years values are used for NAA_re$cor = "2dar1", but only the appropriate values are used for NAA_re$cor = "ar1_a", or "ar1_y". When NAA_re$decouple_recruitment = TRUE, the third value is used for both NAA_re$sigma = "rec" or "rec+1". For NAA_re$decouple_recruitment = FALSE, only the second value is used and applies to both recruitment and "survival" when NAA_re$sigma = "rec+1", and just recruitment when NAA_re$sigma = "rec". If not supplied stock-specific values for age and/or year will be estimated for all regions where NAA_re$cor is other than "none", "iid".

$N1_model

Character vector (n_stocks) determining which way to model the initial numbers at age:

"age-specific-fe"

(default) age- and region-specific fixed effects parameters

"equilibrium"

2 fixed effects parameters: an initial recruitment and an instantaneous fishing mortality rate to generate an equilibruim abundance at age.

"iid-re"

(default) age- and region-specific iid random effects parameters. 2 parameters: mean and sd for log NAA

"ar1-re"

(default) age- and region-specific random effects parameters. 3 parameters: mean and sd, and cor for log NAA

$N1_pars

An (n_stocks x n_regions x n_ages) array. If N1_model = 0, then this should be filled with the initial values to use for abundance at age by stock and region in the first year. If N1_model = 1 (equilibrium assumption), only the first two values in the ages dimension are used: the (s,r,1) value is recruitment for stock (and region) and (s,r,2) is the fully-selected equilibrium fishing mortality rate generating the rest of the numbers at age in the first year.

$recruit_model

Integer vector (n_stocks) determining how to model recruitment. Overrides recruit_model argument to prepare_wham_input. Must make sure NAA_re$sigma, NAA_re$cor and ecov are properly specified.

1

SCAA, estimating annual recruitments as fixed effects.

2

estimating a mean recruitment with annual recruitments as random effects

3

Beverton-Holt stock-recruitment with annual recruitments as random effects

4

Ricker stock-recruitment with annual recruitments as random effects

$recruit_pars

list (length = n_stocks) of vectors of initial parameters for recruitment model. If $recruit_model is 3 or 4, parameters are "alpha" and "beta".

list containing data, parameters, map, and random elements (output from wham::prepare_wham_input)

list containing data, parameters, map, and random elements (output from prepare_wham_input)

(optional) list specifying options for numbers-at-age random effects, initial parameter values, and recruitment model (see details)

catchability specifies options for catchability. If NULL and asap3 is not NULL, a single catchability parameter for each index is used with initial values specified in ASAP file. If both are NULL, initial catchabilities for all indices = 0.3. Otherwise, it is a list with the following optional entries:

$re

Time-varying (random effects) for each index. Vector with length = number of indices. Each entry of catchability$re must be one of the following options:

"none"

(default) are constant

"iid"

vary by year and age/par, but uncorrelated

"ar1"

correlated by year (AR1)

$initial_q

Initial catchabilities for each index. vector length = number of indices. Will override values provided in basic_info$q. If basic_info$q and asap3 are not provided, default q values are 0.3.

$q_lower

Lower bound for catchabilities for each index. vector length = number of indices. For indices with NULL components default lower values are 0.

$q_upper

Upper bound for catchabilities for each index. vector length = number of indices. For indices with NULL components default lower values are 1000.

$prior_sd

vector of NA and standard deviations to use for gaussian prior on logit transform of catchability parameter. Length = number of indices. Indices with non-NA values will have mean logit q as a random effect with mean determined by logit transform of catchability$initial_q and sigma as standard error.

$sigma_val

Vector of initial standard deviation values to use for annual random effects for each index. Values are not used if q$re = "none". Otherwise, a single value for all indices.

$sigma_map

Specify which sigma parameters to fix for the random effect deviations. Must be a vector with length = number of indices. Use NA to fix a parameter and integers to estimate. Use the same integer for multiple indices to share the same sigma parameter. Not used if re = 'none' for all indices.

$cor_vals

Vector of initial correlation values to use for annual random effects for each index. If unspecified all initial values are 0. Only used if q$re = "ar1"

$cor_map

Specify which ar1 correlation parameters to fix for the random effect deviations. Must be a vector with length = number of indices. If re = 'ar1', each element (index) must be a single value. Use NA to fix a parameter and integers to estimate. Use the same integer for multiple indices to share the same correlation parameter. Not used if re = 'none' or re = 'iid' for all indices.

list containing data, parameters, map, and random elements (output from prepare_wham_input)

(optional) list specifying options for selectivity blocks, models, initial parameter values, parameter fixing/mapping, and random effects (see details)

set_selectivity specifies options for selectivity and allows you to overwrite existing options in the input list or as specified in the ASAP data file. If selectivity = NULL, selectivity options from input are used.

prepare_wham_input(..., selectivity=selectivity) calls set_selectivity(..., selectivity=selectivity). If you already have created input with prepare_wham_input, you can also use set_selectivity(input, selectivity=selectivity) to modify the selectivity specification.

selectivity is a list with the following entries:

$model

Selectivity model for each block. Vector with length = number of selectivity blocks. Each entry must be one of: "age-specific", "logistic", "double-logistic", or "decreasing-logistic".

$re

Time-varying (random effects) for each block. Vector with length = number of selectivity blocks. If NULL, selectivity parameters in all blocks are constant over time and uncorrelated. Each entry of selectivity$re must be one of the following options, where the selectivity parameters are:

"none"

(default) are constant and uncorrelated

"iid"

vary by year and age/par, but uncorrelated

"ar1"

correlated by age/par (AR1), but not year

"ar1_y"

correlated by year (AR1), but not age/par

"2dar1"

correlated by year and age/par (2D AR1)

$initial_pars

Initial parameter values for each block. List of length = number of selectivity blocks. Each entry must be a vector of length # parameters in the block, i.e. c(2,0.2) for logistic (a50 and 1/slope) or c(0.5,0.5,0.5,1,1,0.5) for age-specific parameters when there are 6 ages. Default is to set at middle of parameter range. This is 0.5 for age-specific and n.ages/2 or logistic, double-logistic, and decreasing-logistic.

$fix_pars

Alternative to $map_pars for specifying which selectivity parameters (only fixed effects) to fix at initial values. List of length = number of selectivity blocks. E.g. model with 3 age-specific blocks and 6 ages, list(4:5, 4, 2:4)) will fix ages 4 and 5 in block 1, age 4 in block 2, and ages 2, 3, and 4 in block 3. Use NULL to not fix any parameters for a block, e.g. list(NULL, 4, 2) does not fix any pars in block 1.

$par_min

The lower bound for selectivity parameters and is used to populate data$selpars_lower. List of length = number of selectivity blocks, where each item is a vector of length = number of selectivity parameters (age-specific: n.ages, logistic: 2, double-logistic: 4).

$par_max

The upper bound for selectivity parameters and is used to populate data$selpars_upper. List of length = number of selectivity blocks, where each item is a vector of length = number of selectivity parameters (age-specific: n.ages, logistic: 2, double-logistic: 4).

$map_pars

Alternative to $fix_pars for specifying how to fix selectivity parameters (only fixed effects), corresponds to map$logit_selpars. List of length = number of selectivity blocks, where each item is a vector of length = number of selectivity parameters (age-specific: n.ages, logistic: 2, double-logistic: 4). Use NA to fix a parameter and integers to estimate. Use the same integer for multiple ages or fleets/indices to estimate a shared parameter. E.g. for a model with 3 age-specific blocks (1 fleet, 2 indices) and 6 ages, $map_pars = list(c(1,2,3,NA,NA,4), c(5,6,7,NA,8,8), c(1,2,3,NA,NA,4)) will estimate ages 1-3 and 6 in block 1 (fleet), ages 1-3 and 4-5 (shared) in block 2 (index 1), and then set the index 2 (block 3) selectivity equal to the fleet.

$sigma_vals

Initial standard deviation values to use for the random effect deviations. Must be a vector with length = number of blocks. Use natural (not log) scale, must be positive. par$sel_repars[,1] will be estimated on log-scale. Not used if re = 'none' for all blocks.

$map_sigma

Specify which SD parameters to fix for the random effect deviations. Must be a vector with length = number of blocks. Use NA to fix a parameter and integers to estimate. Use the same integer for multiple blocks to estimate a shared SD parameter. Not used if re = 'none' for all blocks.

$cor_vals

Initial correlation values to use for the random effect deviations. Must be a n_selblocks x 2 integer matrix. Columns correspond to correlation by age and year, respectively. If re = 'ar1' or re = 'ar1_y' only the corresponding values are used. Values must be between -1 and 1, but parameters are estimated on a logit transformed scale internally. Not used if re = 'none' or re = 'iid' for all blocks.

$map_cor

Specify which correlation parameters to fix for the random effect deviations. Must be a n_selblocks x 2 matrix. Columns correspond to correlation by age and year,respectively. Parameters can be shared by setting corresponding values of map_cor to the same integer. Use NA to fix a parameter. If re = 'ar1' or re = 'ar1_y', only the column for the corresponding correlation are used. Not used if re = 'none' or re = 'iid' for all blocks.

$n_selblocks

How many selectivity blocks. Optional. If unspecified and no asap3 object, then this is set to the number of fleets + indices. If specified, ensure other components of selectivity are consistent.

directory to save html file (plot_wham_output makes '.png' plot files in a 'plots_png' subdirectory of 'dir.main').

Title for HTML page.

Width of plots (in pixels).

Automatically open index.html in default browser?