Time blocks for selectivity

Fleet selectivity can be vary in time using 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 for RCMdata@sel_block:

RCMdata@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

Thus, 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 dummy fleet is assigned to each fleet, indicating no time-varying selectivity, and the above code chunk is not needed, i.e., there is no distinction between dummy fleets and the true fleets.

Selectivity of each dummy fleet

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

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

Thus, the selectivity of the first dummy fleet is logistic, the second is dome, and the third is free, i.e., independent parameters for each age.

These functions are described here.

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 start list with a named entry for 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 nsel_block (3) columns:

selectivity <- c("logistic_length", "dome_length", "dome_length")
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 not used when the selectivity is logistic and the value in the third row, first column is merely an unused placeholder in the matrix. If vul_par is provided by the user, 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 + 1 rows with each row giving the selectivity value to the corresponding age (first row = age-0, etc.):

OM@maxage <- 5
selectivity <- c("logistic_length", "dome_length", "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

Rows 4 to maxage+1 for logistic and dome selectivity (columns 1 and 2) are unused placeholders.

Fixing and sharing parameters

Selectivity parameters may be fixed or shared. In TMB, this is accomplished by the map argument, which can be provided in RCM via the map list with named entry for 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 or unused parameters are assigned NA. Let’s look at the first vul_par example again:

selectivity <- c("logistic_length", "dome_length", "dome_length")
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:

• LFS and L5 for the first two dummy fleets to be identical
• Vmaxlen in the third dummy fleet to be fixed
• The parameter reserved for Vmaxlen for the first dummy fleet to be turned off since it’s merely a placeholder
• All remaining parameters are estimated unique parameters

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:

• Selectivity of dummy fleet #3 to be estimated only for ages 0 and 1
• The parameter reserved for Vmaxlen for the first block to be turned off since it’s a placeholder
• Rows 4-6 for the first two blocks to be turned off (they’re placeholders and undefined in the model)

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

selectivity <- c("logistic_length", "dome_length", "free_length")
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

Finally the function call looks like this:

output <- RCM(OM, RCMdata, selectivity = selectivity, 
              start = list(vul_par = vul_par), 
              map = list(vul_par = map_vul_par), 
              ...)