Skip to contents

Simulate data from a salmonid IPM

simIPM.Rd

Generate pseudo-data, group-level parameters, and states from a specified salmonIPM integrated population model given values for the hyperparameters. This may be useful, e.g., in simulation-based calibration and model sensitivity checking. It is not suitable for simulating data from a fitted model, because initial states are drawn randomly rather than being passed in.

Usage

simIPM(
  life_cycle = c("SS", "SSiter", "SMS"),
  SR_fun = c("BH", "B-H", "bh", "b-h", "Ricker", "ricker", "exp"),
  RRS = "none",
  N_age,
  max_age,
  ages = NULL,
  pars,
  par_models = NULL,
  center = TRUE,
  scale = TRUE,
  age_F = NULL,
  age_B = NULL,
  fish_data
)

Arguments

life_cycle

Character string indicating which life-cycle model to simulate. Currently available options are spawner-to-spawner ("SS", the default), iteroparous spawner-to-spawner ("SSiter"), or spawner-smolt-spawner ("SMS").

SR_fun

One of "exp" (density-independent discrete exponential), "BH" (Beverton-Holt, the default), or "Ricker", indicating which spawner-recruit function to fit. Synonyms "DI", "B-H", "bh", "b-h" and "ricker" are accepted.

RRS

A character string or vector of strings naming parameters of the function specified by SR_fun that differ between wild- and hatchery-origin spawners, such that the relative reproductive success of hatchery spawners is not equal to 1. If pool_pops == TRUE, these should be the names of the population-specific parameters, not their hyper-means. For example, if life_cycle %in% c("SS","SSiter"), the options are "none" (the default), "alpha", "Rmax", or c("alpha","Rmax"). Currently RRS is only implemented for pool_pops == FALSE.

N_age

Number of (maiden) adult age classes.

max_age

Oldest (maiden) adult age class.

ages

For multi-stage models, a named list giving the fixed ages in years of all subadult life stages. For example, if life_cycle == "SMS", list(M = a) where a is integer smolt age.

pars

Named list of (hyper)parameters to be used for simulations:

  • mu_alpha Hyper-mean of log intrinsic productivity.

  • mu_alpha_W,mu_alpha_H Hyper-means of log intrinsic productivity for wild- and hatchery-origin spawners, respectively. If they differ, both must be specified and mu_alpha must not be used (and conversely).

  • beta_alpha Vector of regression coefficients for log intrinsic productivity. Must be specified if par_models includes alpha ~ ...; otherwise will be ignored and may be omitted.

  • sigma_alpha Hyper-SD of log intrinsic productivity.

  • mu_Rmax If life_cycle == "SS", hyper-mean of log maximum recruitment.

  • mu_Rmax_W,mu_Rmax_H Hyper-means of log maximum recruitment for wild- and hatchery-origin spawners, respectively. If they differ, both must be specified and mu_Rmax must not be used (and conversely).

  • beta_Rmax If life_cycle == "SS", vector of regression coefficients for log maximum recruitment. Must be specified if par_models includes Rmax ~ ...; otherwise will be ignored and may be omitted.

  • sigma_Rmax If life_cycle == "SS", hyper-SD of log maximum recruitment.

  • rho_alphaRmax If life_cycle == "SS", correlation between population-level log(alpha) and log(Rmax).

  • rho_WH If either mu_alpha or mu_[R|M]max differ by rearing type, correlation between the respective _W and _H population-level parameters.

  • beta_R If life_cycle == "SS", vector of regression coefficients for log recruitment. Must be specified if par_models includes R ~ ...; otherwise will be ignored and may be omitted.

  • rho_R If life_cycle == "SS", AR(1) coefficient of brood-year log productivity anomalies.

  • sigma_year_R If life_cycle == "SS", hyper-SD of brood-year log productivity anomalies.

  • sigma_R If life_cycle == "SS", unique recruitment process error SD.

  • mu_Mmax If life_cycle == "SMS", hyper-mean of log maximum smolt recruitment.

  • beta_Mmax If life_cycle == "SMS", vector of regression coefficients for log maximum smolt recruitment.

  • mu_Mmax_W,mu_Mmax_H Hyper-means of log maximum smolt recruitment for wild- and hatchery-origin spawners, respectively. If they differ, both must be specified and mu_Mmax must not be used (and conversely).

  • sigma_Mmax If life_cycle == "SMS", hyper-SD of log maximum smolt recruitment.

  • rho_alphaMmax If life_cycle == "SMS", correlation between log(alpha) and log(Mmax).

  • beta_M If life_cycle == "SMS", vector of regression coefficients for log smolt recruitment. Must be specified if par_models includes M ~ ...; otherwise will be ignored and may be omitted.

  • rho_M If life_cycle == "SMS", AR(1) coefficient of spawner-smolt log productivity anomalies.

  • sigma_year_M If life_cycle == "SMS", process error SD of spawner-smolt log productivity anomalies.

  • sigma_M If life_cycle == "SMS", SD of unique spawner-smolt productivity process errors.

  • mu_MS If life_cycle == "SMS", mean SAR.

  • beta_MS If life_cycle == "SMS", vector of regression coefficients for logit SAR anomalies. Must be specified if par_models includes s_MS ~ ...; otherwise will be ignored and may be omitted.

  • rho_MS If life_cycle == "SMS", AR(1) coefficient for logit SAR anomalies.

  • sigma_year_MS If life_cycle == "SMS", process error SD of logit SAR anomalies.

  • sigma_MS If life_cycle == "SMS", SD of unique logit SAR process errors.

  • mu_p Among-population mean simplex of age distributions.

  • sigma_pop_p Vector of among-population SDs of mean log-ratio age distributions.

  • R_pop_p Among-population correlation matrix of mean log-ratio age distributions.

  • sigma_pop_p Vector of SDs of log-ratio cohort age distributions.

  • R_pop_p Correlation matrix of cohort log-ratio age distributions.

  • sigma_p Vector of SDs of log-ratio cohort age distributions.

  • R_p Correlation matrix of cohort log-ratio age distributions.

  • mu_SS If life_cycle == "SSiter", mean kelt survival.

  • beta_SS If life_cycle == "SSiter", vector of regression coefficients for logit kelt survival. Must be specified if par_models includes s_SS ~ ...; otherwise will be ignored and may be omitted.

  • rho_SS If life_cycle == "SSiter", AR(1) coefficient for annual logit kelt survival anomalies.

  • sigma_year_SS If life_cycle == "SSiter", process error SD of annual logit kelt survival anomalies.

  • sigma_SS If life_cycle == "SSiter", SD of unique logit kelt survival process errors.

  • tau If life_cycle != "SMS", spawner observation error SD.

  • tau_M If life_cycle == "SMS", smolt observation error SD.

  • tau_S If life_cycle == "SMS", pawner observation error SD.

  • S_init Scalar giving median of initial spawning population size. If both S_init and S_init_K are specified, the latter is ignored.

  • S_init_K Scalar giving median of initial spawning population size as a fraction of carrying capacity. Note that if alpha < 1, K is undefined and specifying S_init_K will result in an error.

par_models

Optional list of two-sided formulas of the form theta ~ x1 + ... + xK, where theta is a (hyper)parameter or state in the model specified by stan_model that accepts covariates (see Details for available model-parameter combinations) and x1 + ... + xK are terms involving variables in fish_data. Standard formula syntax such as : and * may be used; see stats::formula().

center

Logical indicating whether the terms in model matrices constructed from fish_data using the formulas in par_models should be centered. It is usually recommended to use the default (TRUE) so the baseline parameter estimate applies when predictors are at their sample means, but in some cases such as factor predictors center = FALSE may be appropriate. If combining categorical and numeric predictors, the latter can be centered and scaled prior to modeling.

scale

Logical indicating whether the model matrices constructed from fish_data using the formulas in par_models should be scaled to have column SDs of 1. Unit-scaling predictors is less critical than centering, but is advisable if variables have scales far from 1.

age_F

Logical or 0/1 vector of length N_age indicating whether each adult age is fully (non)selected by the fishery. The default is all selected. If life_cycle == "SSiter", N_age refers to the total number of maiden and repeat age classes (counting the repeat plus group as 1).

age_B

Logical or 0/1 vector of length N_age indicating whether each adult age is fully (non)selected in broodstock collection. The default is all selected. If life_cycle == "SSiter", N_age refers to the total number of maiden and repeat age classes (counting the repeat plus group as 1).

fish_data

Data frame with columns:

  • pop Numeric, character or factor population ID.

  • year Numeric or integer giving the year the fish spawned (i.e., the brood year).

  • A Spawning habitat size (either stream length or area). Will often be time-invariant within a population, but need not be.

  • p_HOS True fraction of hatchery-origin spawners.

  • F_rate Total harvest rate (proportion) of natural-origin fish.

  • B_rate Adult hatchery broodstock removal rate.

  • n_age_obs Number of spawners sampled for age composition.

  • n_HW_obs Number of spawners sampled for hatchery / wild origin.

  • ... Additional variables to be used as covariates.

Value

A named list with elements

  • sim_dat A data frame containing simulated data in the structure of (see salmonIPM()) appropriate for the specified life_cycle, ready to be passed to salmonIPM().

  • pars_out A named list of hyperparameters, group-level parameters, and states used in generating the pseudo-data.

See also

salmonIPM() for fitting models