In this document we elaborate all configurations in SAM. The configuration options are separated into two groups. The first group contains the basic options, which are the configuration options which should be considered for all assessments. The second group contains the specialized options which are options designed to address special cases, which may not have to be considered most applications.
This document also describes a few options, which extends beyond the configuration file itself including how to use externally estimated data on observation uncertainty in SAM and how to fix specific model parameters.
Maximum age in the assessment. This is a dummy option and it should not be changed without changing all the input data first. It should be corresponding to the oldest age of any observation in the assessment.maxAge (Maximum age in assessment)
Minimum age in the assessment. This is a dummy option and it should not be changed without changing all the input data first. It should be corresponding to the youngest age of any observation in the assessment.minAge (Maximum age in assessment)
Defines if the last age group of each fleet is considered a plus (1 yes, or 0 no). If no then the last age group is considered to consist of fish only of that specific age, but it yes then the last age group is considered to consist of fish of that specific age and older.maxAgePlusGroup (Plus groups)
Example:
$maxAgePlusGroup
1 1Here both the catch and survey fleet consists of observations where the oldest age group contains that age and above, hence the plus group treatment is turned on.
Definition:
The plus group implies the following update to the stock equation: \[N_{A,y}=N_{A-1,y-1}e^{-Z_{A-1,y-1}}+N_{A,y-1}e^{-Z_{A,y-1}}\] and where the last age group of a fleet \(A_f\) is less that the last age group of the entire assessment \(A\) then the stock number used to predict the observations for the fleet is the sum of the stock numbers from \(A_f\) to \(A\).
Code:
Internally in SAM the plus group is e.g. calculated as:
for(int j=1; j<stateDimN; ++j){
predN(j)=logN(j-1,i-1) - mort.totalZ(j-1,i-1); //totF(j-1,i-1)-dat.natMor(i-1,j-1);
}
if(conf.maxAgePlusGroup(0)==1){// plusgroup adjustment if catches need them
Type v1 = predN(stateDimN-1); // Already updated above
Type v2 = logN(stateDimN-1,i-1) - mort.totalZ(stateDimN-1,i-1); // Remaining in plus group from last year
predN(stateDimN-1) = logspace_add_SAM(v1,v2); // log(exp(v1)+exp(v2))
}
The configuration keyLogFsta (Coupling fishing mortality) keyLogFsta is used to couple fishing mortality across age. In the common situation where only one fishing fleet is defined, then only the first row is used.
Description: The model defines fishing mortality as a stochastic processes (log-space random walk) for each age group, but to simplify the model and to get stable convergence, then it is often assumed that some age groups are exposed to the same fishing mortality process. A common setting is e.g. that the oldest age groups share the same fishing mortality corresponding to the assumption that above a certain age the fish are equally selected.
Example:
This example includes data on catch at age and one survey at age.
$keyLogFsta
0 1 2 3 4 5 5 5 5 5 5
-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1This configuration sets up separate fishing mortality for the five youngest ages, and a common fishing mortality for older fish. In this example we have a flat selection pattern for the six oldest ages.
Definition:
Fishing mortality in SAM is defined as a random walk on log scale, i.e., \(\log{\bf F}_y = \log {\bf F}_{y-1} + \pmb{\epsilon}_{y}^{(F)}\). The configuration keyLogFsta above defines how \(\bf F\) relates to the fishing mortality at age. In our example with 11 age groups we have that \({\bf F}_y = c(F_{1,y},...,F_{11,y})= c(F_{1,y},...,F_{5,y},F_{6,y},F_{6,y},F_{6,y},F_{6,y},F_{6,y},F_{6,y})\).
Code:
Internally in SAM the log fishing mortality at age \(a\) in fleet \(f\) at year \(y\) is extracted by
logF(conf.keyLogFsta(f-1,a),y));Where the logF matrix is the actual processes in each row (often fewer than the number of age groups) and the matrix specified in this configuration is used to selects which to use for any given age a.
The configuration corFlag (Correlation structure in fishing mortality increments) corFlag is an integer used to define correlation structures across ages in fishing mortality increments within years.
Description:
Definition:
Fishing mortality in SAM is defined as a random walk on log scale, i.e., \(\log{\bf F}_y = \log {\bf F}_{y-1} + \pmb{\epsilon}_{y}^{(F)}\). Here \(\pmb{\epsilon}_{y}^{(F)} \sim N({\bf 0},\Sigma_F)\). The configuration corFlag selects how we define \(\Sigma_F\).
Code:
Internally in SAM the covariance is calculated in a switch statement:
switch(conf.corFlag(f)){
case 0: ... //independent
case 1: ... // Compound symmetry
case 2: ... // AR1 structure
}
The configuration keyLogFpar (Survey catchability parameters) keyLogFpar is used to couple the survey catchability parameters. Normally first row is not used, as that corresponds a fleet with fishing mortality.
Description:
For survey fleets generating an index at age a catchability parameter is the proportionality constant between the stock size in that age group and the observed index at that age group. The catchability parameter can be shared between age groups. (Additional note: This options is also used to setup other options, for fleets without age-based information in which case only the first column will be used).
Example:
In this example we include data on catch at age and one survey at age.
$keyLogFpar
-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
0 1 1 1 1 2 2 2 -1 -1 -1Here the model is defined by a unique survey catchability parameter for the youngest age, a common survey catchability parameter for the four next ages, and a common catchability parameter for the older ages.
Definition:
The observation equation for the survey in the example is given by: \(\log I_{a,y} = \log ( Q_{2,a} N_{a,y})\), where \(N_{a,y}\) is the estimated abundance at age at the time of the survey in year \(y\), and \(Q_{2,a}\) is the survey catchability parameter for age \(a\). The configuration keyLogFpar defines how we couples the survey catchability paramteters \(Q\).
Code:
Internally in SAM the survey catchability parameters are stored in a vector logFpar and is extracted for age \(a\) in fleet \(f\) by
logFpar(conf.keyLogFpar(f-1,a));
The configuration keyVarF (Variance of log fishing mortality increments) keyVarF is used to couple the variances of the log fishing mortality increments. Often only the first row is used, because the remaining rows corresponds to survey fleets
Description: The coupling of the process increment variances for the age-specific \(\log F\)-processes.
Example: Here we include a separate variance parameter for fishing mortality increments for the youngest age, and a common variance parameter for all older ages.
$keyVarF
0 1 1 1 1 1 1 1 1 1 1
-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1Definition:
Fishing mortality in SAM is defined as a random walk on log scale, i.e., \(\log F_{a,y} = \log F_{a,y-1} + \epsilon_{y}^{(F_a)}\). Here \(\epsilon_{y}^{(F_a)} \sim N(0,\sigma_{F_a}^2)\). The configuration keyVarF defines how we couple \(\sigma_{F_a}^2\) across ages.
Code:
Internally in SAM the standard deviation of the increments are stored in a vector, and the standard deviation for age \(a\) is extracted e.g. by
sdLogFsta(conf.keyVarF(0,a));
This configuration provide the lowest and highest age included in the average fishing mortality (\(\bar F\)).fbarRange (Age range of average fishing mortality)
Example:
In this example ages 4 to 7 are included in the average \(F\) annually reported.
$fbarRange
# lowest and higest age included in Fbar
4 7
keyVarLogN ( Recruitment and survival process variances)
The configuration keyVarLogN is used to couple the variances of the \(\log N\) process. Typically it is assumed a separate variance parameter for the recruitment, and a common variance parameter for the survival process.
Example:
$keyVarLogN
0 1 1 1 1 1 1 1 1 1 1Here the model is set up to use a separate variance parameter for recruitment and a common variance parameter for the survival process. This a fairly typical configuration. Using the same variance parameter for recruitment and survival should generally not be attempted.
Definition:
The process equations for \(\log {\bf N}\) is given by:\[ \log N_{1,y} = \log R({\bf N}_{y-1}) + \eta_{1,y}\\ \log N_{a,y} = \log N_{a-1,y-1} - F_{a-1,y-1} - M_{a-1,y-1} + \eta_{a,y} \hspace{7mm} \text{for } 1<a<A ,\\ \log N_{A,y} = \log (N_{A-1,y-1} e^{- F_{A-1,y-1} - M_{A-1, y-1}} + N_{A,y-1} e^{ - F_{A,y-1} - M_{A, y-1}}) + \eta_{A,y}.\]
Here \(\eta_{a,y} \sim N(0,\sigma_{\eta,a}^2)\) and keyVarLogN defines how we couple the parameter \(\sigma_{\eta,a}^2\) across ages.
Code: Internally in SAM the standard deviation of the recruitment (\(\eta_{1,y}\)) and survival process (\(\eta_{a,y}\) for \(a>1\)) are stored in a vector, and the variance for age \(a\) is extracted by
varLogN(conf.keyVarLogN(a-1));
The configuration keyVarObs (Observation variance) keyVarObs is used to couple of observation variance parameters.
Description: This option defines how observation variance parameters are coupled. Each row correspond to a fleet and each column to an age (-1 are inserted where no observations are available)
Example: This example includes data on catch at age and one survey at age.
$keyVarObs
0 1 2 2 2 2 2 2 2 2 2
3 3 3 3 3 3 3 3 -1 -1 -1Here catch observations have separate variance parameters for the two youngest ages and a common variance parameter for the older fish. The survey includes a common variance parameter for all ages.
Definition:
Observations are assumed to follow the distributions \(C_{a,y} \sim N(\mu_{C,a,y},\sigma^2_{1,a})\) and \(I_{a,y} \sim N(\mu_{I,a,y},\sigma^2_{2,a})\). The configuration keyVarObs defines how we couple the variance parameters \(\sigma^2_{fleet,age}\). Predicted catches and indices follow standard observation equations elaborated in Nielsen and Berg (2014) .
Code:
Internally in SAM the observation variances are stored in a vector and can be accessed by the line
varLogObs(conf.keyVarObs(f-1,a))Here f refers to the fleet (row in configuration) and a refers to the age (column in configuration).
stockRecruitmentModelCode (Recruitment type)
The configuration stockRecruitmentModelCode defines which recruitment function to use.
constRecBreaks)
constRecBreaks (Break points in mean recruitment)
Vector of break years between which recruitment is at constant level. The break year is included in the left interval.
Note: This option is only used when the configuration stockRecruitmentModelCode is set to 3.
fixVarToWeight (External variance options)
If external variance estimates are provided in the data input, the configuration fixVarToWeight is used to say whether the external variances are included as relative weights (0) or assumed as fixed weights (1). See External variance section near the end of the document for more details on how to include data on observation variance.
Note: fixVarToWeight is only used when external variance estimates of the observations are provided.
fracMixF (t-distributed log F increments)
The configuration fracMixF can be used to make the model more adaptable to make large jumps in fishing mortality. The number provided is assumed to be the fraction of t(3) distribution in logF process increments.
Warning: fracMixF is a fancy option and should be used with care. It may make the model too flexible.
fracMixN (t-distributed log N increments)
The configuration fracMixN can be used to make the model more adaptable to make large jumps in log N increments caused by the process error. The number provided is assumed to be the fraction of t(3) distribution in logN process increments.
Warning: fracMixN is a fancy option and should be used with care. It may make the model too flexible.
fracMixObs (t-distributed observation error)
A vector with same length as number of fleets, where each element is the fraction of t(3) distribution used in the distribution of that fleet.
Warning: fracMixObs is a fancy option and should be used with care. It will reduce the weighting of potential outliers, but it will also reduce the weight of all data sources.
keyBiomassTreat (Biomass survey)
To be defined only if a biomass survey is used. The following surveys are implemented:
fbarRange indexCatch with catchability fixed at 1)
keyCorObs (Observation covariance coupling)
The configuration keyCorObs is used to couple correlation structures when obsCorStruct is set to AR(1).
Example
In this example we include data on catch at age and one survey at age.
$keyCorObs
#3-4 4-5 5-6 6-7 7-8 8-9 9-10 10-11 11-12 12-13
NA NA NA NA NA NA NA NA NA NA
0 0 0 0 1 1 1 -1 -1 -1Description:
Here we include no covariance structure for catch at age. For the index we assume all neighboring ages up to age 7 are equally correlated, and all neighboring ages from age 7 are equally correlated.
Definition:
Observations are assumed to follow the distributions \(C \sim N(\pmb{\mu}_c,\pmb{\Sigma}_c)\) and \(I_{y} \sim N(\pmb{\mu}_{I},\pmb{\Sigma}_I)\). The covariance matrices \(\Sigma\) here follow an AR1 structure where the distances between the ages are included as correlation parameters. The configuration keyCorObs defines how we couple the correlation parameters. See Berg and Nielsen (2016) for more details on the correlation structure.
Code:
Internally in SAM the observation correlation parameters are stored in a matrix and is accessed in this pseudo code line
cov = setupVarCovMatrix(..., conf.keyCorObs.col(f-1), ... );Here f refers to the fleet (row in configuration).
keyParScaledYA (Catch scaling parameters)
A matrix specifying the couplings of scaling parameters for catch (nrow = no scaled years, ncols = no ages).
Note: This configuration must be used in combination with keyScaledYears and noScaledYears
keyQpow (Density dependent observations)
The configuration keyQpow is used to couple observation density dependence parameters.
Example
In this example we include data on catch at age and one survey at age.
$keyQpow
-1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
0 0 0 0 0 1 1 1 -1 -1 -1Description:
In this example catch observations are assumed to be linearly dependent on abundance. The survey includes a density dependence parameter for the five youngest ages and a separate parameter for the older fish.
Definition:
Observations are assumed to follow the distributions \(C_{a,y} \sim N(\mu_{C,a,y}^{q_{1,a}},\sigma^2_{1,a})\) and \(I_{a,y} \sim N(\mu_{I,a,y}^{q_{2,a}},\sigma^2_{2,a})\). The configuration keyQpow defines how we couple the density dependent parameters \(q_{fleet,age}\). By default \(q_{fleet,a}\) equals 1 when keyQpow is set to -1.
Code:
Internally in SAM the density dependence parameters are stored in a vector and is accessed in the line
pred*=exp(par.logQpow(conf.keyQpow(f-1,a))); Here f refers to the fleet (row in configuration) and a refers to the age (column in configuration).
keyScaledYears (Catch scaling years)
A vector of the years where catch scaling is applied.
Note: This configuration must be used in combination with keyParScaledYA and noScaledYears
noScaledYears (Number of years with scaled catch)
Number of years in which catch scaling is applied, i.e., number of years that observed catch includes an unknown proportionality constant that is estimated within SAM. Default is 0 years.
Note: This configuration must be used in combination with keyScaledYears and keyParScaledYA
Covariance structure for each fleetobsCorStruct (Observation covariance selection)
Note: Unstructured correlation structure is seldom used because it is typically too flexible.
Example
$obsCorStruct
"ID" "AR"Here we include no correlation structure for catch, and an AR1 structure for the index. Note that we would now need to modify keyCorObs to properly define the introduces correlation structure for the survey.
obsLikelihoodFlag (Observation likelihood)
Vector with observational likelihood, current possible values are: “LN” “ALN”
predVarObsLink (Prediction-variance relation)
The configuration predVarObsLink is used to couple parameters that link observation prediction and assosiated observation uncertainty. For survey and catch data it is often the case that the relative uncertainty depends on the predicted observation, by activating predVarObsLink we accomondate for such structures.
Example
In this example we include data on catch at age and one survey at age.
$predVarObsLink
-1 -1 0 0 0 0 0 0 0 0 0
-1 -1 -1 -1 -1 -1 -1 -1 NA NA NADescription:
In this example we estimate a relation between prediction and associated variance for catch at age for the nine oldest age group. No prediction-variance relations are estimated for catch at age of the two youngest ages and survey indices.
Definition:
For sake of intuition it is convenient to illustrate the relation on natural scale. Let \(\mu_{a,y}\) be a predicted observation at age \(a\) in year \(y\) on natural scale, and let \(v_{a,y}\) be the corresponding variance. When applying the prediction-variance relation we assume that the variance is given by \(v_{a,y} = \alpha \mu_{a,y}^{\beta}\) and estimate \(\alpha\) and \(\beta\) within SAM.
On log-scale the prediction-variance relation is equivalent to that \(C_{a,y} \sim N(\mu_{C,a,y},\log \Big(\alpha_a\mu_{a,y}^{\beta_{1,a}-2} + 1\Big) )\) and \(I_{a,y} \sim N(\mu_{I,a,y},\log \Big(\alpha_a\mu_{a,y}^{\beta_{2,a}-2} + 1\Big))\). The prediction-variance relation is included by configuring predVarObsLink which couples the \(\beta_{fleet,a}\) parameters. SAM will further use the settings provided in keyVarObs to couple the \(\alpha_{fleet,a}\) parameters. See Breivik, Nielsen, and Berg (2021) for more details on the prediction variance relation.
Code:
Internally in SAM the prediction variance relation parameters (\(\beta_{fleet,a}\)) are stored in a vector and can be accessed by the line
par.predVarObs(conf.predVarObsLink(f,a))Here f refers to the fleet (row in configuration) and a refers to the age (column in configuration).
In this section we elaborate options in SAM for including data on observation variances and covaraince structures.
Variance data
Data on observation variance can be included in SAM. This is done by assigning a weight attribute to the corresponding survey or catch data before it is passed to setup.sam.data(). The weight attribute must have the same dimensions as the corresponding observation matrix, and provide the precision (1/variance) of each observation. Note that correlation structures can be estimated internally in SAM using the configuration keyCorObs simultaneously as external variances are utilized. The following example illustrates key lines where we include data on observation variance from a fleet.
Example
#Attach the precition to the survey data
attributes(surveys$`surveyName`)$weight = 1/surveyVariance
#Set up data, the external variances are now included
dat<-setup.sam.data(surveys=surveys,
...)
Description:
The data on variance are by default used in SAM as relative weights. Internally in SAM it is scaled with a time constant variance parameter that is coupled with the configuration keyVarObs. We can use the provided variance estimates as fixed variances by setting the fixVarToWeight configuration to 1.
Definition:
Observations of catches and indices are assumed to be log-normal, and by including data on variance estimates we are able to accommodate for time varying uncertainty in the data. In SAM we assume that \(\log obs_{fleet,a,y} \sim N(\mu_{fleet,a,y},\sigma^2_{fleet,a,y})\) . Notice the yearly \(y\) subscript in the observation variance. Define \(w_{fleet,a,y}\) as the provided weights (defined as 1/variance). Internally in SAM we let \(\sigma^2_{fleet,a,y} =s_{fleet,a}/w_{fleet,a,y}\), and estimate \(s_{fleet,a}\). The configuration keyVarObs defines how we couple the scaling parameters \(s_{fleet,a}\).
Covariance data
Data on yearly covariance structures of the observations can be included in SAM. This is achived by assigning a cov-weight attribute to the corresponding survey or catch data before it is passed to setup.sam.data(). The cov-weight attribute must be a list of covariance matrices for each year of data from the corresponding fleet. The following example illustrates key lines where we include data on covariance matrices from a fleet.
Example
#Attach the list of covariance matrices to the survey data
attr(surveys$`surveyName`, "cov-weight") <- covMatricesSurvey
#Set up data, the external covariances are now included
dat<-setup.sam.data(surveys=surveys,
...)
Description:
The data on correlation structures are used to define the correlation structure of the data internally in SAM, and the corresponding external variances are used as relative weights.
Definition:
Observations of catches and indices are assumed to be log-normal, and by including external covaraince estimates we are able to accommodate for time varying uncertainty and correlation structure in the data. In SAM we assume that each vector of observations from a fleet in a year is multivariate normal, i.e., \(\log {\bf obs}_{fleet,y} \sim N(\pmb{ \mu}_{fleet,y},\pmb{\Sigma}_{fleet,y})\). Let \(\Psi^{cov}_y\) be the yearly provided covariance matrices for the fleet. Internally in SAM we define \(\pmb{\Sigma}_{fleet,y} = diag({\bf s}_{fleet}) \Psi^{cov}_y diag({\bf s}_{fleet})\), where \(diag({\bf s}_{fleet})\) is a diagonal matrix with variance scaling parameters that are estimated. The scaling parameters are coupled with the configuration keyVarObs.
Correlation data
External correlation matrices of the observations can be included in SAM. This is achived by assigning a cor attribute to the corresponding survey or catch data before it is passed to setup.sam.data(). The cor attribute must be a list of correlation matrices for each year of data from the corresponding fleet.
Example
#Attach the list of correlation matrices to the survey data
attr(surveys$`surveyName`, "cor") <- corMatricesSurvey
#Set up data, the external correlations are now included
dat<-setup.sam.data(surveys=surveys,
...)
Description:
The data on correlation structures are used to define the correlation structure of the data internally in SAM.
Definition:
Observations of catches and indices are assumed to be log-normal, and by including external correlation estimates we are able to accomondate for time varying correlation in the data. In SAM we assume that each vector of observations from a fleet in a year is multivariate normal, i.e., \(\log {\bf obs}_{fleet,y} \sim N(\pmb{ \mu}_{fleet,y},\pmb{\Sigma}_{fleet,y})\). Let \(\Psi^{cor}_y\) be the yearly provided correlation matrices for the fleet. Internally in SAM we define \(\pmb{\Sigma}_{fleet,y} = diag(\pmb{\sigma}_{fleet}) \Psi^{cor}_y diag(\pmb{\sigma}_{fleet})\), where \(diag(\pmb{\sigma}_{fleet})\) is a diagonal matrix with internally estimated variance parameters coupled with the configuration keyVarObs.
Berg, Casper W, and Anders Nielsen. 2016. “Accounting for Correlated Observations in an Age-Based State-Space Stock Assessment Model.” ICES Journal of Marine Science 73 (7): 1788–97.
Breivik, Olav Nikolai, Anders Nielsen, and Casper W Berg. 2021. “Prediction–Variance Relation in a State-Space Fish Stock Assessment Model.” ICES Journal of Marine Science 78 (10): 3650–7.
Nielsen, Anders, and Casper W Berg. 2014. “Estimation of Time-Varying Selectivity in Stock Assessments Using State-Space Models.” Fisheries Research 158: 96–101.