specifying_demographic_parameters.RmdTo parameterize a model built with afscOM to behave like a specific population, the user needs to specify a set of population demographic parameters. These parameters all take the same computational structure: a multi-dimensional array.
These multidimensional arrays MUST always follow the same dimension structure for afscOM to work correctly. Biological parameters, such as natural mortality, maturity, and weight-at-age should all have array dimensions: [nyears, nages, nsexes, nregions]. Fishery and survey fleet parameters, such as selectivity, retention, and discard mortality, should have array dimensions: [nyears, nages, nsexes, nregions, nfleets] (for fishing fleets) or [nyears, nages, nsexes, nregions, nsurveys] (for survey fleets).
In this structure the first index along the “sex” dimension (dimension 3) will correspond to parameters for females, while the second index will correspond to parameters for males.
Required population parameters include:
mort: Natural mortality [nyears, nages, nsexes, nregions]
mat: Maturity [nyears, nages, nsexes, nregions]
waa: Weight-at-age [nyears, nages, nsexes, nregions]
sexrat: Population sex ratio [nyears, nages, nsexes, nregions]
sel: Fishery selectivity [nyears, nages, nsexes, nregions, nfleets]
ret: Fishery retention [nyears, nages, nsexes, nregions, nfleets]
dmr: Fishery discard mortality (as an instantenous rate) [nyears, nages, nsexes, nregions, nfleets]
If observations are being simulated, survey selectivity must also be specified:
surv_sel: Survey selectivity [nyears, nages, nsexes, nregions, nsurveys]
For spatial models (those where nregions > 1), a “movement” demographic matrix is also required as input. Movement can be specified to vary by age and sex, but can not currently vary through time.
movement: Movement matrix [nregions, nregions, nages, nsexes]
To facilitate easier creation of these multi-dimensional parameter matrices, a helper function generate_param_matrix(...) has been provided. This function accepts as input a single value, a vector of values, or a matrix/array of values, and a list of dimensions over which to fill a fully-formed parameter matrix with that input.
For example, if natural mortality (M) is assumed to be constant across time, age, sex, and space, the following code will create an [nyears, nages, nsexes, nregions] parameter matrix where every value is the same:
dimension_names <- list(
"time" = 1:nyears,
"age" = 2:31,
"sex" = c("F", "M"),
"region" = "alaska",
"fleet" = c("Fixed", "Trawl")
)
M <- 0.113179
mort <- generate_param_matrix(M, dimension_names = dimension_names)If maturity is assumed to vary by age, but is otherwise constant across time, sex, and space, the following code will create a properly formed parameter matrix where each age has a different maturity level:
maturity <- c(0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0, 1.0, 1.0, 1.0, 1.0)
mat <- generate_param_matrix(maturity, dimension_names = dimension_names, by="age")Finally, if weight-at-age (WAA) varies by both age and sex, the following code will create the appropriately formed parameter matrix with different values for WAA by age and sex, but repeated across time and space:
weight_mat <- matrix(NA, nrow=11, ncol=2, dimnames=dimension_names[c("age", "sex")])
weight_mat[,1] <- c(2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22)
weight_mat[,2] <- c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
waa <- generate_param_matrix(weight_mat, dimension_names = dimension_names, by=c("age", "sex"))The generate_param_matrix requires the user to specify as a parameter input the names of each dimension in the output matrix as a list. The function will work correctly regardless of the specific dimension names used, however, when filling across 2-or-more dimensions (as in the above example with weight-at-age), the input matrix (that is being used to fill the larger parameter matrix), must also have the same dimension names along the corresponding axes.
In the weight-at-age example above, the weight_mat matrix, which contained the WAAs for each age and sex, has dimension names equivalent to the dimension names along the “age” and “sex” dimensions that are provided to generate_param_matrix. If these names do not match, an error will be returned to the user indicating as such.
For fleet parameters, such as selectivity or retention, an extra dimension nfleets is required. generate_param_matrix has an additional, include_fleet_dim parameter that can be specified to indicate that the output array should have a fleet dimension in addition to the other four dimensions. If the parameter is specified to vary across fleets, the include_fleet_dim parameter will be automatically turned on.
For example:
selex_mat <- array(NA, dim=c(11, 2, 2), dimnames=dimension_names[c("age", "sex", "fleet")])
selex_mat[,1,1] <- c(0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0, 1.0, 1.0, 1.0, 1.0)
selex_mat[,2,1] <- c(0.0, 0.1, 0.2, 0.4, 0.6, 0.7, 0.8, 0.9, 1.0, 1.0, 1.0)
selex_mat[,1,2] <- c(0.3, 0.7, 1.0, 1.0, 0.9, 0.7, 0.6, 0.5, 0.4, 0.4, 0.4)
selex_mat[,2,2] <- c(0.2, 0.6, 1.0, 0.95, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.3)
sel <- generate_param_matrix(selex_mat, dimension_names = dimension_names, by=c("age", "sex", "fleet"))Once these population parameter matrices have been defined, they need to be added to a list that will be passed as a parameter to the OM:
dem_params <- list(
waa=waa,
mat=mat,
mort=mort,
sexrat=sexrat,
sel=sel,
ret=ret,
dmr=dmr,
surv_sel=survey_sel
)An additional helper function validate_dem_params, takes as input a list of population parameter matrices, and the expected dimensions, and will check if all required parameter matrices are present and of appropriate dimensions. If required parameters are missing, or are of incorrect dimensions, an error will be returned. It is recommended that this function be used prior to running the model to verify that the input parameters matrices are correctly specified.