make_model: Build TMB object for VAST model
In James-Thorson/VAST: Vector-Autoregressive Spatio-Temporal (VAST) Model

make_model

R Documentation

Build TMB object for VAST model

Description

make_model builds a tagged list with everything necessary to run or interpret inputs to a VAST model

Usage

make_model(
  TmbData,
  Version,
  RhoConfig = c(Beta1 = 0, Beta2 = 0, Epsilon1 = 0, Epsilon2 = 0),
  Method = "Mesh",
  Npool = 0,
  ConvergeTol = 1,
  Use_REML = FALSE,
  loc_x = NULL,
  Parameters = "generate",
  Random = "generate",
  Map = "generate",
  DiagnosticDir = NULL,
  TmbDir = system.file("executables", package = "VAST"),
  RunDir = getwd(),
  CompileDir = TmbDir,
  build_model = TRUE,
  framework = "TMBad",
  intern = FALSE,
  inner.control = list(sparse = TRUE, lowrank = TRUE, trace = FALSE),
  supernodal = FALSE,
  flags = ""
)

Arguments

`TmbData`	a tagged list of data inputs generated by `Data_Fn`
`Version`	Which CPP version to use. If missing, defaults to latest version using `get_latest_version`. Can be used to specify using an older CPP, to maintain backwards compatibility.
`RhoConfig`	vector of form `c("Beta1"=0,"Beta2"=0,"Epsilon1"=0,"Epsilon2"=0)` specifying whether either intercepts (Beta1 and Beta2) or spatio-temporal variation (Epsilon1 and Epsilon2) is structured among time intervals, e.g. for component `Epsilon2` indicated in the 4rd slot: `RhoConfig[4]=0` Each year as fixed effect `RhoConfig[4]=1` Each year as an independent and identically distributed random effect, thus estimating the variance as fixed effect `RhoConfig[4]=2` Each year as a random effect following a random walk, thus estimating the variance as fixed effect `RhoConfig[4]=3` Constant among years as fixed effect `RhoConfig[4]=4` Each year as a random effect following a first-order autoregressive process, thus estimating the variance as fixed effects and a single first-order autoregression parameter `RhoConfig[4]=5` Each year as a random effect following a first-order autoregressive process, estimating the variance as fixed effects and a separate first-order autoregression parameter for each category `RhoConfig[4]=6` Only possible for `Epsilon2` or `Beta2`, and specifying that that associated hyperparameters parameters have identical values to the first component `Epsilon1` or `Beta1` If missing, the default is to assume a value of zero for each element (i.e., `RhoConfig[1:4]=0`)
`Method`	Spatial method used for estimation (determines bounds for logkappa)
`Npool`	A user-level interface to pool hyperparameters for multiple categories. For categories with few encounters, these hyperparameters are poorly informed leading to converge difficulties. A value `Npool=10` indicates that any category with fewer than `10` encounters across all years should have hyperparameters mirrored to the same value.
`ConvergeTol`	Integer specifying override for TMB convergence criteria (OPTIONAL)
`Use_REML`	boolean whether to use maximum marginal likelihood or restricted maximum likelihood (termed "REML") (OPTIONAL)
`loc_x`	location for each sample used to generate plausible bounds for scale parameter (OPTIONAL)
`Parameters`	a tagged list of starting parameters (OPTIONAL)
`Random`	a character vector of random effects (OPTIONAL)
`Map`	a tagged list of parameters to either mirror or turn off, using standard TMB interface. This input is useful, e.g., to build a model without estimating parameters, extracting Map from the list of outputs, modifying it manually, and then passing it explicitly, `make_model(Map=NewMap)` (OPTIONAL)
`DiagnosticDir`	a directory where diagonstic runtime information should be stored (OPTIONAL)
`TmbDir`	a directory where the CPP file for the VAST model can be found locally (OPTIONAL)
`RunDir`	a directory where model results are written; by default uses the working directory (OPTIONAL)
`CompileDir`	a directory where the CPP file is copied, copiled, and run (must have write privileges or else the function will crash); by default uses `TmbDir` (OPTIONAL)
`build_model`	Boolean indicating whether to build the model, `build_model=TRUE`, or simply build the inputs, `build_model=FALSE`
`framework`	Which AD framework to use ('TMBad' or 'CppAD')
`intern`	Do Laplace approximation on C++ side ? See details (Experimental - may change without notice)
`inner.control`	List controlling inner optimization.
`supernodal`	Turn on preprocessor flag to use supernodal sparse Cholesky/Inverse from system wide suitesparse library
`flags`	Character with compile flags.

Value

Object of class make_model, containing objects for running a VAST model

Obj: The built TMB object
Upper: A vector of upper bounds for parameters, optionally for use during optimization
Lower: A vector of lower bounds for parameters, optionally for use during optimization
Parameters: A tagged list of parameter starting values used when building Obj, which can be extracted, modified, and then put back into make_model to define different starting values
Map: A tagged list of parameters to be turned off or mirrored, for similar use as Parameters
Random: A character vector of random effects, for similar use as Parameters