fit EcoState model — ecostate • ecostate

Estimate parameters for an EcoState model

Usage

ecostate(
  taxa,
  years,
  catch = data.frame(Year = numeric(0), Mass = numeric(0), Taxon = numeric(0)),
  biomass = data.frame(Year = numeric(0), Mass = numeric(0), Taxon = numeric(0)),
  agecomp = list(),
  weight = list(),
  PB,
  QB,
  B,
  DC,
  EE,
  X,
  type,
  U,
  fit_B = vector(),
  fit_Q = vector(),
  fit_B0 = vector(),
  fit_EE = vector(),
  fit_PB = vector(),
  fit_QB = vector(),
  fit_eps = vector(),
  fit_nu = vector(),
  sem = "",
  covariates = NULL,
  log_prior = function(p) 0,
  settings = stanza_settings(taxa = taxa),
  control = ecostate_control()
)

Arguments

taxa: Character vector of taxa included in model.
years: Integer-vector of years included in model
catch: long-form data frame with columns Mass, Year and Taxon
biomass: long-form data frame with columns Mass, Year and Taxon, where Mass is assumed to have the same units as catch
agecomp: a named list, with names corresponding to stanza_groups, where each list-element is a matrix with rownames for years and colnames for integer ages, where NA excludes the entry from inclusion and the model computes the likelihood across included ages in a given year, and the rowsum is the input-sample size for a given year
weight: a named list, with names corresponding to stanza_groups, where each list-element is a matrix with rownames for years and colnames for integer ages, where NA excludes the entry from inclusion and the model computes the lognormal likelihood for weight-at-age in each specified age-year combination
PB: numeric-vector with names matching taxa, providing the ratio of production to biomass for each taxon
QB: numeric-vector with names matching taxa, providing the ratio of consumption to biomass for each taxon
B: numeric-vector with names matching taxa, providing the starting (or fixed) value for equilibrium biomass for each taxon
DC: numeric-matrix with rownames and colnames matching taxa, where each column provides the diet proportion for a given predator
EE: numeric-vector with names matching taxa, providing the proportion of proportion of production that is subsequently modeled (termed ecotrophic efficiency)
X: numeric-matrix with rownames and colnames matching taxa, where each element gives the vulnerability parameter for a given interaction.
type: character-vector with names matching taxa and elements c("auto","hetero","detritus"), indicating whether each taxon is a primary producer, consumer/predator, or detritus, respectively.
U: numeric-vector with names matching taxa, providing the proportion of consumption that is unassimilated and therefore exported to detritus
fit_B: Character-vector listing taxa for which equilibrium biomass is estimated as a fixed effect
fit_Q: Character-vector listing taxa for which the catchability coefficient is estimated as a fixed effect
fit_B0: Character-vector listing taxa for which the ratio of initial to equilibrium biomass is estimated as a fixed effect
fit_EE: Character-vector listing taxa for which ecotrophic efficiency is estimated.
fit_PB: Character-vector listing taxa for which equilibrium production per biomass is estimated. Note that it is likely a good idea to include a prior for any species for which this is estimated.
fit_QB: Character-vector listing taxa for which equilibrium consumption per biomass is estimated. Note that it is likely a good idea to include a prior for any species for which this is estimated.
fit_eps: Character-vector listing taxa for which the model should estimate annual process errors in dB/dt
fit_nu: Character-vector listing taxa for which the model should estimate annual process errors in consumption Q_ij
sem: Optional specification for time-series structural equation model structure including lagged or simultaneous effects. Process errors for biomass, consumption, and recruitment can be included for a given taxa by prefixing taxa names for "eps_", "nu_", and "phi_", respectively. E.g., to specify an autoregressive process on biomass errors for a taxon named "i", we can specify a path eps_i -> eps_i, 1, rho_i, 0 where 1 indicates a lagged effect, rho_i is a user-provided parameter name, and 0 is a starting value. See make_dsem_ram for an introduction to DSEM path notation. make_dsem_ram for introduction to DSEM path notation.
covariates: Matrix of covariates (with one row per year) for use in dynamic structural equation model on process errors.
log_prior: A list of sampling statements representing parameter priors, or a user-provided function that takes as input the list of parameters out$obj$env$parList() where out is the output from ecostate(), and returns a numeric vector where the sum is the log-prior probability. For example log_prior = function(p) dnorm( p$logq_i[1], mean=0, sd=0.1, log=TRUE) specifies a lognormal prior probability for the catchability coefficient for the first taxa with logmean of zero and logsd of 0.1. See evaluate_prior for details.
settings: Output from stanza_settings(), used to define age-structured dynamics (called stanza-groups).
control: Output from ecostate_control(), used to define user settings.

Value

An object (list) of S3-class ecostate. Elements include:

obj: RTMB object from MakeADFun
tmb_inputs: The list of inputs passed to MakeADFun
opt: The output from nlminb
sdrep: The output from sdreport
interal: Objects useful for package function, i.e., all arguments passed during the call
rep: report file, including matrix B_ti for biomass in each year t and taxon i, g_ti for growth rate per biomass, and see dBdt for other quantities reported by year
derived: derived quantity estimates and standard errors, for rep objects as requested
call: function call record
run_time: Total runtime

This S3 class then has functions summary, print, and logLik

Details

All taxa must be included in QB, PB, B, and DC, but additional taxa can be in QB, PB, B, and DC that are not in taxa. So taxa can be used to redefine the set of modeled species without changing other inputs

References

Introducing the state-space mass-balance model:

Thorson, J. Kristensen, K., Aydin, K., Gaichas, S., Kimmel, D.G., McHuron, E.A., Nielsen, J.N., Townsend, H., Whitehouse, G.A (In press). The benefits of hierarchical ecosystem models: demonstration using a new state-space mass-balance model EcoState. Fish and Fisheries.