There are a multitude of options available in how selectivity for fleets and surveys is parameterized in the model. This vignette is designed to be a step-by-step guide for setup of selectivity. It is best to first think about fleet selectivity followed by survey selectivity. Familiarity with the more general SRA vignette and the function help page (found by typing ?SRA_scope into the R console) will be helpful.
This vignette is designed to provide step-by-step information on possible model configurations, but of course it is up to the user to decide whether those configurations are appropriate for the operating model conditioning.
The general function call for SRA_scope is:
where the SRA is of class SRA, OM is a class OM object, data is a list, and ... are additional function arguments explained below.
Fleet selectivity can be vary in time blocks. Let’s say we have 2 fleets, a 10-year time series, and the first fleet selectivity changes in year 6. Thus, we have 3 selectivity blocks, a.k.a. dummy fleets each with their own selectivity. For each ‘true’ fleet and year in the model, we will assign the selectivity to one of the three dummy fleets. To do so, we create a 10 by 2 integer matrix:
data$sel_block
#> [,1] [,2]
#> [1,] 1 3
#> [2,] 1 3
#> [3,] 1 3
#> [4,] 1 3
#> [5,] 1 3
#> [6,] 2 3
#> [7,] 2 3
#> [8,] 2 3
#> [9,] 2 3
#> [10,] 2 3Thus, for the first fleet (first column), we assign the selectivity of dummy fleet #1 to years 1-5 and that of dummy fleet #2 to years 6-10. The second fleet is assigned to dummy fleet #3 for all years.
By default, a unique block is assigned to each fleet, indicating no time-varying selectivity, and the above code chunk is not needed. In other words, there’s no distinction between dummy fleets and the true fleets.
We specify the selectivity as a character vector with each entry corresponding to dummy fleet:
Thus, the selectivity of the first dummy fleet is logistic, the second is dome, and the third is free, i.e., independent parameters for selectivity-at-age.
These functions are described in Vignette #2a.
For logistic and dome selectivity, the default behavior is to generate starting values from OM@LFS, OM@L5, and OM@Vmaxlen. Custom start values are needed when selectivity uses free parameters.
Custom starting values are passed to the model with the vul_par matrix (the terms selectivity and vulnerability are used interchangeably). If only logistic or dome options are used, then vul_par is a matrix of 3 rows (corresponding to LFS, L5, and Vmaxlen) and data$nsel_block columns:
selectivity <- c("logistic", "dome", "dome")
vul_par
#> [,1] [,2] [,3]
#> [1,] 55 55.0 20.0
#> [2,] 30 30.0 19.0
#> [3,] 1 0.5 0.9Note that Vmaxlen is ultimately not used when the selectivity is logistic and the value in the third row, first column is merely an unused placeholder. If vul_par is provided, another step is needed to turn off this parameter (see next subsection).
If we have selectivity as free parameters (independent parameters for each age), vul_par has OM@maxage rows with each row giving the selectivity value to the corresponding age (first row = age-1, etc.):
OM@maxage <- 6
selectivity <- c("logistic", "dome", "free")
vul_par
#> [,1] [,2] [,3]
#> [1,] 55 45.0 0.1
#> [2,] 30 30.0 0.3
#> [3,] 1 0.5 0.7
#> [4,] NA NA 1.0
#> [5,] NA NA 1.0
#> [6,] NA NA 1.0Rows 4 to maxage for logistic and dome selectivity are unused placeholders.
Selectivity parameters may be fixed or shared. For TMB, this is accomplished by the map argument, which can be provided in SRA_scope via the map_vul_par matrix which is of identical dimension to vul_par. map_vul_par tells TMB what to do to the parameter of the corresponding row and column in vul_par. Shared parameters are assigned a unique integer amongst themselves while fixed/unused parameters are assigned NA. Let’s look at the first vul_par example again:
selectivity <- c("logistic", "dome", "dome")
vul_par
#> [,1] [,2] [,3]
#> [1,] 55 55.0 20.0
#> [2,] 30 30.0 19.0
#> [3,] 1 0.5 0.9We want:
The matrix map_vul_par that accomplishes these tasks will look like this:
For the second vul_par example, we want:
The matrix map_vul_par that accomplishes these tasks will look like this:
selectivity <- c("logistic", "dome", "free")
map_vul_par
#> [,1] [,2] [,3]
#> [1,] 1 3 6
#> [2,] 2 4 7
#> [3,] NA 5 NA
#> [4,] NA NA NA
#> [5,] NA NA NA
#> [6,] NA NA NAFinally the function call looks like this:
Next we can move on to survey selectivity. Unlike fleet selectivity, selectivity is unique to each survey and no dummy fleets are used.
The vector s_selectivity defines where the survey selectivity is defined (the terms index and survey are used interchangeably). Survey selectivity may be identical to fleet selectivity, i.e., vulnerable biomass, total biomass, or spawning biomass. If we have 4 surveys with:
The first survey is a survey of spawning biomass as denoted by “SSB” (maturity is configured in the OM), the second survey indexes total biomass as denoted by “B” (selectivity = 1 for all ages), and the third and fourth surveys have the selectivity of the first and second fleets, respectively. Note that the integers for fleets refer to the true fleet and not to selectivity blocks/dummy fleets.
No further consideration of survey selectivity is needed when selectivity is defined elsewhere, the function call can look like this:
On the other hand, if survey selectivity needs to be explicitly defined, then the s_selectivity vector can indicate the functional form, using one of logistic, dome, dome. Let’s look at another situation with 5 surveys:
For the fourth and fifth surveys, the selectivity functions are dome-shaped and free parameters, respectively. Next we need to consider what the parameters defining this functions are, either as starting values to be estimated or fixed values in the model.
Just as in the fleet parameters, the survey selectivity parameters by default use OM@LFS, OM@L5, and OM@Vmaxlen for start values when s_selectivity = "logistic" or "dome", and custom start values needed when selectivity uses free parameters.
Custom start values are passed to the SRA in the s_vul_par matrix with the same layout as that for the fleet blocks:
OM@maxage <- 6
s_selectivity <- c(2, "SSB", "B", "dome", "free")
s_vul_par
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 0 0 0 55.0 1
#> [2,] 0 0 0 40.0 0
#> [3,] 0 0 0 0.5 0
#> [4,] 0 0 0 0.0 0
#> [5,] 0 0 0 0.0 0
#> [6,] 0 0 0 0.0 0Parameter slots for surveys 1 - 3 are ignored. Again they’re placeholders for internal organization. The first three rows in column four are the start values for the three parameters of the dome function (to be estimated), and the fifth survey only selects age-1 animals, i.e., a survey of recruits.
Finally, to remove parameters from estimation either because they’re just placeholders (surveys 1-4) or they should be fixed in the model (survey 5), we provide the map argument for s_vul_par with map_s_vul_par:
map_s_vul_par
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] NA NA NA 1 NA
#> [2,] NA NA NA 2 NA
#> [3,] NA NA NA 3 NA
#> [4,] NA NA NA NA NA
#> [5,] NA NA NA NA NA
#> [6,] NA NA NA NA NAA function call utilizing this custom set-up for survey selectivity would be: