Intended for conditioning operating models for DLMtool. For data-limited stocks, this function can generate a range of potential depletion scenarios inferred from sparse data. From a historical time series of total catch or effort, and potentially age/length compositions and multiple indices of abundance, the SRA returns a range of values for depletion, selectivity, unfished recruitment (R0), historical fishing effort, and recruitment deviations for the operating model. This is done by sampling life history parameters provided by the user and fitting a statistical catch-at-age model (with the predicted catch equal to the observed catch). Alternatively one can do a single model fit and sample the covariance matrix to generate an operating model with uncertainty based on the model fit. Either a full catch (conditioned on catch) or effort (conditioned on effort) time series is needed but missing data (as NAs) are allowed for all other data types.
Sub_cpars(OM, sims = 1:OM@nsim)SRA_scope(OM, data, ...)
# S4 method for OM,list
SRA_scope(
OM,
data,
condition = c("catch", "catch2", "effort"),
selectivity = "logistic",
s_selectivity = NULL,
LWT = list(),
comp_like = c("multinomial", "lognormal"),
ESS = c(30, 30),
max_F = 3,
cores = 1L,
integrate = FALSE,
mean_fit = FALSE,
drop_nonconv = FALSE,
drop_highF = FALSE,
control = list(iter.max = 2e+05, eval.max = 4e+05),
...
)
# S4 method for OM,Data
SRA_scope(
OM,
data,
condition = c("catch", "catch2", "effort"),
selectivity = "logistic",
s_selectivity = NULL,
LWT = list(),
comp_like = c("multinomial", "lognormal"),
ESS = c(30, 30),
max_F = 3,
cores = 1L,
integrate = FALSE,
mean_fit = FALSE,
drop_nonconv = FALSE,
drop_highF = FALSE,
control = list(iter.max = 2e+05, eval.max = 4e+05),
...
)
An object of class '>SRA (see link for description of output).
Three vignettes are available for the SRA model:
Setup of selectivity settings (useful for more data-rich cases)
One of indices, age compositions, or length compositions should be provided in addition to the historical catch or effort. Not all arguments are needed to run the model (some have defaults, while others are ignored if not applicable depending on the data provided).
The data variable can be a named list that includes:
Chist - A vector of historical catch, should be of length OM@nyears. If there are multiple fleets: a matrix of OM@nyears rows and nfleet columns.
Ideally, the first year of the catch series represents unfished conditions (see also C_eq).
Ehist - A vector of historical effort, should be of length OM@nyears (see also E_eq).
Index - A vector of values of an index (of length OM@nyears). If there are multiple surveys: a matrix of historical indices of abundances, with rows indexing years and columns indexing surveys. Age-specific indices should be numbers-specific while all others are weight-based.
I_sd - A vector or matrix of standard deviations (lognormal distribution) for the indices corresponding to the entries in Index.
If not provided, this function will use values from OM@Iobs.
I_type - Obsolete as of version 2.0. See s_selectivity argument.
CAA - Fishery age composition matrix with nyears rows and OM@maxage columns. If multiple fleets: an array with dimension: nyears, OM@maxage, and nfleets.
CAL - Fishery length composition matrix with nyears rows and columns indexing the length bin. If multiple fleets: an array with dimension: nyears, length bins, and nfleets.
MS - A vector of fishery mean size (MS, either mean length or mean weight) observations (length OM@nyears), or if multiple fleets: matrix of dimension: nyears and nfleets.
Generally, mean lengths should not be used if CAL is also provided, unless mean length and length comps are independently sampled.
MS_type - A character (either "length" (default) or "weight") to denote the type of mean size data.
MS_cv - The coefficient of variation of the observed mean size. If there are multiple fleets, a vector of length nfleet. Default is 0.2.
s_CAA - Survey age composition data, an array of dimension nyears, maxage, nsurvey.
s_CAL - Survey length composition data, an array of dimension nyears, length(length_bin), nsurvey.
length_bin - A vector for the midpoints of the length bins for CAL and s_CAL. All bin widths should be equal in size.
C_eq - A numeric vector of length nfleet for the equilibrium catch for each fleet in Chist prior to the first year of the operating model.
Zero (default) implies unfished conditions in year one. Otherwise, this is used to estimate depletion in the first year of the data. Alternatively,
if one has a full CAA matrix, one could instead estimate "artificial" rec devs to generate the initial numbers-at-age (and hence initial depletion) in the first year of the model (see additional arguments).
E_eq - The equilibrium effort for each fleet in Ehist prior to the first year of the operating model.
Zero (default) implies unfished conditions in year one. Otherwise, this is used to estimate depletion in the first year of the data.
abs_I - Optional, an integer vector to indicate which indices are in absolute magnitude. Use 1 to set q = 1, otherwise use 0 to estimate q.
I_units - Optional, an integer vector to indicate whether indices are biomass based (1) or abundance-based (0). By default, all are biomass-based.
age_error - Optional, a square matrix of maxage rows and columns to specify ageing error. The aa-th column assigns a proportion of the true age in the a-th row to observed age. Thus, all rows should sum to 1. Default is an identity matrix (no ageing error).
sel_block - Optional, for time-varying fleet selectivity (in time blocks), a integer matrix of nyears rows and nfleet columns to assigns a selectivity function to a fleet for certain years. See the selectivity vignette for more details.
Alternatively, the data input can be a '>Data S4 object which will retrieve data from the following slots:
Data@Cat - catch series (single fleet with the Data S4 object)
Data@Effort - effort series
Data@CAA - fishery age composition
Data@CAL, Data@CAL_mids - fishery length composition and corresponding length bins
Data@Ind, Data@SpInd, Data@VInd, Data@AddInd - indices of abundance
Data@CV_Ind, Data@CV_SpInd, Data@CV_VInd, Data@CV_AddInd - annual coefficients of variation for the corresponding indices of abundance. CVs will be converted to lognormal standard deviations.
Data@ML - fishery mean lengths
Data@AddIndV, Data@AddIndType, Data@AddIunits - Additional information for indices in Data@AddInd: selectivity and units (i.e., biomass or abundance).
There is no slot in the Data S4 object for the equilibrium catch/effort. These can be passed in the function call, i.e., SRA_scope(OM, Data, C_eq = C_eq, ...).
For SRA_scope, additional arguments can be passed to the model via ...:
vul_par: A matrix of 3 rows and nfleet columns for starting values for fleet selectivity. The three rows correspond to LFS (length of full selectivity), L5 (length of 5 percent selectivity), and Vmaxlen (selectivity at length Linf). By default, the starting values are values from the OM object. If any selectivity = "free", then this matrix needs to be of maxage rows where the row specifies the selectivity at age. See the selectivity vignette for more information.
s_vul_par: A matrix of 3 rows and nsurvey columns for starting values for fleet selectivity. Same setup as vul_par. These values are only
used if s_selectivity = "est" for the corresponding fleet. Otherwise, placeholders should be used to complete the matrix.
map_vul_par: An integer matrix of the same dimension as vul_par. This is the 'map' argument for vul_par in TMB, see MakeADFun, which indicates whether selectivity parameters are fixed
or estimated. If an entry is NA, the corresponding parameter is fixed in the model to the starting
value. Otherwise, an integer for each independent parameter. By default, selectivity is fixed if there are no age or length composition for that fleet
or survey, otherwise estimated. Unused cells in the vul_par matrix should be given NA in the map matrix.
map_s_vul_par: The map argument for the survey selectivity parameters (same dimension as s_vul_par). Placeholder parameters should have a map value of NA.
map_log_early_rec_dev: A vector of length OM@maxage - 1 that indexes which recruitment deviates for the cohorts in the first year of the model are fixed (using NA) or estimated (a separate integer). By default, no deviates are estimated.
map_log_rec_dev: A vector of length OM@nyears that indexes which recruitment deviates are fixed (using NA) or estimated (a separate integer). By default, all deviates are estimated.
plusgroup: Logical for whether the maximum age is a plusgroup or not. By default, TRUE.
fix_dome: Logical for whether the dome selectivity parameter for fleets is fixed. Used primarily for backwards compatibility, this is overridden by map_vul_par.
resample: Logical, whether the OM conditioning parameters (recruitment, fishing mortality, SSB, selectivity, etc.) are obtained by sampling the Hessian matrix from a single model fit. By default FALSE. This feature requires identical biological parameters among simulations.
LWT is an optional named list containing the likelihood weights (values >= 0) with the possible options:
Chist, CAA, CAL, MS, C_eq: A vector of length nfleet for each.
Index, s_CAA, s_CAL: A vector of length nsurvey for each.
By default, all likelihood weights are equal to one if not specified by the user.
Weighting for CAA and CAL can also be adjusted by changing the multinomial sample size. For CAA, CAL, s_CAA, and s_CAL, the arrays should be set up so that
the annual number of observations will be equal to the presumed multinomial sample size. Argument ESS provides a shortcut
to cap the multinomial sample size for age and length comps.
Fleet selectivity is fixed to values sampled from OM if no age or length compositions are provided.
Survey selectivity is estimable only if s_CAA or s_CAL is provided. Otherwise, the selectivity should
be mirrored to a fleet (vulnerable biomass selectivity) or indexed to total or spawning biomass (see s_selectivity).
Parameters that were used in the fitting model are placed in the SRA@OM@cpars list.
If the operating model OM uses time-varying growth or M, then those trends will be used in the SRA as well.
Time-varying life history parameters can create ambiguity in the calculation and interpretation of depletion and reference points in runMSE.
See section D.5 of DLMtool::userguide().
The easiest way to turn off time-varying growth/M is by setting: OM@Msd <- OM@Linfsd <- OM@Ksd <- c(0, 0).
Sub_cpars is a convenient function to subset simulations
for the operating model, for example, to remove simulations from unconverged model fits or outlier simulations.
To play with alternative fits by excluding indices, for example, or other optional data, set the corresponding likelihood weight to zero. The model will still generate the inferred index but the data won't enter the likelihood. See section on likelihood weights.
plot.SRA '>SRA