2b. Configuring selectivity for the RCM

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

2021-03-09


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. It is best to first think about fleet selectivity followed by survey selectivity. Familiarity with the more general RCM vignette and the function help page (found by typing ?RCM 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 RCM is:

output <- RCM(OM, data, ...)

where the output is of class RCModel, 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. 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    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 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.

2.2 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 selectivity-at-age.

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

Rows 4 to maxage for logistic and dome selectivity are unused placeholders.

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

Finally the function call looks like this:

output <- RCM(OM, data, selectivity = selectivity, vul_par = vul_par, map_vul_par = map_vul_par, ...)

3 Survey selectivity

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

3.1 Is survey selectivity already defined elsewhere?

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:

s_selectivity <- c("SSB", "B", 1, 2)

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:

output <- RCM(OM, data, selectivity = selectivity, s_selectivity = s_selectivity, ...)

3.2 Survey selectivity is independent of anything else in the model

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:

s_selectivity <- c(2, "SSB", "B", "dome", "free")

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.

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 RCM 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    0

Parameter 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   NA

A function call utilizing this custom set-up for survey selectivity would be:

output <- RCM(OM, data, selectivity = selectivity, s_selectivity = s_selectivity, s_vul_par = s_vul_par, map_s_vul_par = map_s_vul_par, ...)