2b. Configuring selectivity for the SRA model

Quang Huynh (q.huynh@oceans.ubc.ca)

2020-06-24


1 Introduction

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. 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:

SRA <- SRA_scope(OM, data, ...)

where the SRA is of class SRA, OM is a class OM object, data is a list, and ... are additional function arguments explained below.

2 Fleet selectivity

2.1 Time blocks for selectivity

Fleet selectivity can be vary in time blocks. We define the selectivity for each block and then assign the blocks to fleets. 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 and assign the block for each fleet and year with a 10 by 2 matrix:

data$nsel_block <- 3 # There are three blocks
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    3

By default, a unique block is assigned to each fleet, i.e., no time-varying element, and the above code chunk is not needed.

2.2 Selectivity of each block

We specify the selectivity as a character vector with each entry corresponding to block:

selectivity <- c("logistic", "dome", "free")

These functions are described in Vignette #2a.

2.3 Starting values of selectivity parameters

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.9

Note that Vmaxlen is ultimately not used, and 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.0

2.4 Fixing and sharing parameters

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. Shared parameters are assigned a unique integer while fixed 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.9

We want:

The matrix map_vul_par that accomplishes these tasks will look like this:

map_vul_par
#>      [,1] [,2] [,3]
#> [1,]    1    1    4
#> [2,]    2    2    5
#> [3,]   NA    3   NA

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   NA

3 Survey selectivity

Next we can move on to survey selectivity. Unlike fleet selectivity, selectivity is unique to each survey and no time blocks are used.

3.1 Is survey selectivity already parameterized elsewhere?

The vector data$I_type 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 5 surveys with:

data$I_type <- c(2, "SSB", "B", "est", "est")

The first survey has the selectivity of the second fleet (note the integer does not refer to selectivity blocks), while “SSB” indicates the second survey selectivity follows the maturity ogive, and “B” refers to a total biomass survey (selectivity = 1 for all ages).

If selectivity is otherwise not defined elsewhere, then “est” is used to indicate that the survey selectivity is estimated, or more precisely, this survey has its own set of parameters.

3.2 Selectivity function

After declaring I_type, the selectivity function needs to be declared for surveys with estimated parameters.

s_selectivity <- c("logistic", "logistic", "logistic", "dome", "free")

For the fourth and fifth surveys, the selectivity functions are dome-shaped and free parameters, respectively. A placeholder is needed for the first three surveys solely for internal organization so that the code correctly matches the selectivity to the survey.

3.3 Selectivity parameters

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
data$I_type <- c(2, "SSB", "B", "est", "est")
s_selectivity <- c("logistic", "logistic", "logistic", "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    0

Parameter slots for surveys 1 - 3 are ignored, the first three rows in column four are the start values for the three paramaters of the dome function, 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-3) 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   NA