run_msom: Run an MSOM Model

In rBatt/trawlDiversity: Long-term changes in species richness along the North American coastline

Description

Run a multispecies occupancy model on trawl data. The model is multi-year, and there are two basic versions; first one is a 'static' model for which no temporal process is explicitly modelled (the years are 'stacked'). The second is a 'dynamic' model that includes persistence and colonization parameters as processes that facilitate the state transition between years. Each of these models can be run in either JAGS or Stan. Both models accept covariates for the detection and presence processes, and both sets of covariates can be modelled as random variables, constants (varying, but known precisely), or a mixture of the two.

Usage

run_msom(reg = c("ai", "ebs", "gmex", "goa", "neus", "newf", "ngulf", "sa",
  "sgulf", "shelf", "wcann", "wctri"), regX.a1, params_out = c("params",
  "params_main", "params_random", "params_latent", "custom"),
  custom_params = NULL, model_type = c("Dynamic", "Static"), n0 = 50,
  chains = 4, cores = parallel::detectCores()/2, iter, thin = max(1,
  floor((iter/2)/200)), language = c("JAGS", "Stan"), test = FALSE,
  test_sub = list(stratum = 4, year = 3, spp = 10), seed = 1337,
  pre_save = FALSE, save_dir = ".",
  model_dir = file.path(system.file(package = "trawlDiversity"),
  tolower(language)), compiled_model = NULL, ...)

Arguments

reg	character, region name
regX.a1	optional data set formatted according to output from trim_msom; if missing, gets a data set using region name and defaults on trimming and aggregating
params_out	character vector specifying category of parameters to report in output; if custom, points to custom_params as well
custom_params	possible characters specifying custom parameters, potentially indexed; see Details
model_type	type of model. Currently both are multiyear. 'Dynamic' includes terms for persistence and colonization (species-specific), whereas 'Static' simply 'stacks' the years.
n0	integer indicating the number of species to use in data augmentation; defaults to 50, is passed to msomData
chains	integer number of chains, default is 4
cores	integer number of cores for parallel processes; default is half of avaialble cores
iter	number of iterations; the default depends on language and on test; testing in Stan is 50, non-testing is 200. Testing in JAGS is 500, non-testing is 5000.
thin	Integer, thinning rate. Default is set to yield 200 draws from the posterior, or if that is not possible, thinning rate is 1 and draws will be iter/2.
language	character indicating the language to be used — JAGS or Stan
test	Logical, whether to do this run as a 'test' run. Default is FALSE. If TRUE, fewer iterations are run (unless overridden by non-default), and the data set is subsetted
test_sub	a named list with elements 'stratum', 'year', and 'spp'. Each element should be an integer indicating the number of levels to select for each of those dimensions. Used for subsetting when test is TRUE.
seed	integer random number seed
pre_save	Logical; if TRUE (default) saves a workspace image before running the model
save_dir	Character string indicating the location of the directory to save the intermediate image; default is current directory
model_dir	Character string indicating the location of the model file; default is selected automatically based on language and model_type, and looks to models that come with this package
compiled_model	Only used when language="Stan"; a Stan model compiled using rstan::stan_model. Useful for preventing repeated model recompilation and/or reapeated loading of DLLs, which can cause an error if done enough.
...	arguments passed to rstan::sampling

Details

Both params_out and custom_params must find matches in the output of msom_params. For all parameters, use 'params'; main-effect parameters specified via 'params_main'; random-effect parameters via 'params_random'. Latent stochastic nodes/ parameters via 'params_latent'. Additional flexibility offered by specifying 'custom', which will add manually specified parameters from custom_params.

Value

Returns a named list of length two. The first element, 'out', contains a JAGS or Stan model object. The second element is a named character vector containing potential file names or prefixes to file names. These names contain collapsed information related to the model run settings, time, file paths, etc.

rBatt/trawlDiversity documentation built on Aug. 14, 2021, 1:01 p.m.