make_settings: Make list of settings

In James-Thorson/VAST: Vector-Autoregressive Spatio-Temporal (VAST) Model

Make list of settings

Description

make_settings makes a list of settings for a given purpose

Usage

make_settings(
  n_x,
  purpose = "index",
  Region,
  fine_scale = TRUE,
  strata.limits = data.frame(STRATA = "All_areas"),
  zone = NA,
  FieldConfig,
  RhoConfig,
  OverdispersionConfig,
  ObsModel,
  bias.correct,
  Options,
  use_anisotropy,
  vars_to_correct,
  Version,
  treat_nonencounter_as_zero,
  n_categories,
  VamConfig,
  max_cells,
  knot_method,
  mesh_package
)

Arguments

n_x	the number of vertices in the SPDE mesh (determines the spatial resolution when Method="Mesh")
purpose	character indicating what purpose is intended for the model, and therefore what default settings are perhaps appropriate. Many of these have examples at the VAST wiki https://github.com/James-Thorson-NOAA/VAST/wiki. Only currently implemented for: purpose="index" Index of abundance calculated summing across space to get annual abundance values for each category purpose="index2" The same as "index" except uses gamma distribution for positive catches, restricts max_cells to 2000, and uses bias correction. This is currently recommended over "index". purpose="condition_and_density" Jointly estimate density (numbers per area) and fish condition (relative weight given length, used to predict density-weighted average condition purpose="MICE" Model of intermediate complexity to estimate species interactions spatially purpose="ordination" Multivariate ordination to identify similar species by estimating a reduced set of axes that collectively explain variability purpose="EOF" An empirical orthogonal function analysis to ordinate on years instead of categories as in "ordination". Deprecated, use "EOF2" instead. purpose="EOF2" Same as "EOF" but uses improved settings that match updates to the package. purpose="EOF3" Same as "EOF2" but ensures that spatio-temporal factors are zero-centered, such that estimated Omega represents distribution in the "average" year.
Region	a character vector, where each element is matched against potential values to create the extrapolation grid, where densities are then predicted at the midpoint of each grid cell when calculating derived quantities or visualizing model outputs. Users will typically supply a single character-string, representing the footprint of a single survey. However, it is also possible to provide a character-vector, where the extrapolation-grid will be created for each string, and then combined together; this is then helpful when extrapolating densities across multiple survey domains. Current options are: "user" User defined extrapolation-grid; also requires input input_grid. Example of building from points or shapefile can be found at https://github.com/James-Thorson-NOAA/VAST/wiki/Creating-an-extrapolation-grid the path and name for a shapefile, i.e., paste0(shapedir,"Shape.shp") Create an extrapolation-grid upon runtime by creating a grid within a user-supplied shapefile, using grid_dim_km to determine grid resolution "california_current" The spatial fooprint of the bottom trawl surveys operated by AFSC/NWFSC, including the AFSC triennial from 1977-2004 and the NWFSC combined shelf-slope survey from 2003 onward (as identified by B. Feist and C. Whitmire); specify subsets via surveyname "west_coast_hook_and_line" The spatial fooprint of the fixed-station hook-and-line survey in the California Bight operated by NWFSC (as identified by J. Harms) "british_columbia" The spatial fooprint of the various stratified-random bottom trawl surveys operated by PBS (as identified by N. Olsen); see strata_to_use for further specification "eastern_bering_sea" The spatial fooprint of the fixed station bottom trawl survey operated by AFSC in the eastern Bering Sea (as identified by J. Conner) "northern_bering_sea" The spatial fooprint of the systematic bottom trawl survey operated by AFSC in the northern Bering Sea (as identified by J. Conner) "bering_sea_slope" The spatial fooprint of the stratified random bottom trawl survey operated by AFSC in the Bering Sea slope (as identified by A. Greig) "chukchi_sea" The spatial fooprint of the systematic bottom trawl survey operated by AFSC in the Bering Sea slope (as identified by J. Conner) "st_matthews_island" The spatial fooprint of the survey area defined around St. Matthews Island, representing regular and corner stations from the eastern Bering Sea bottom trawl survey "aleutian_islands" The spatial fooprint of the stratified random bottom trawl survey operated by AFSC in the Aleutian Islands (as identified by A. Greig) "gulf_of_alaska" The spatial fooprint of the stratified random bottom trawl survey operated by AFSC in the Gulf of Alaska and containing shallow and deep stations, where the latter are not consistently sampled in later years (as identified by A. Greig) "BFISH_MHI" The spatial fooprint of the visual sampling of reef fishes in the main Hawaiian Islands (as provided by B. Richards) "CalCOFI-IMECOCAL_Winter-Spring" The spatial fooprint of the fixed station ichthyoplankton sampling design operated by CalCOFI and IMECOCAL, in a typical year during Winter and Spring months (as identified by A. Thompson) "CalCOFI_Winter-Spring" The spatial fooprint of the fixed station ichthyoplankton sampling design operated by CalCOFI, in a typical year during Winter and Spring months (as identified by A. Thompson) "IMECOCAL_Winter-Spring" The spatial fooprint of the fixed station ichthyoplankton sampling design operated by IMECOCAL, in a typical year during Winter and Spring months (as identified by A. Thompson) "CalCOFI-IMECOCAL_Summer" The spatial fooprint of the fixed station ichthyoplankton sampling design operated by CalCOFI and IMECOCAL, in a typical year during Summer months (as identified by A. Thompson) "rockfish_recruitment_coastwide" The spatial fooprint of the fixed station juvenile rockfish survey operated by SWFSC across its expanded spatial extent that is sampled during recent years (as identified by J. Field) "rockfish_recruitment_core" The spatial fooprint of the fixed station juvenile rockfish survey operated by SWFSC within its core spatial extent that is sampled consistently throughout its entire operations (as identified by J. Field) "northwest_atlantic" The spatial fooprint of the stratified random bottom trawl survey operated by NEFSC in the Northwest Altantic (as identified by D. Chevrier); see epu_to_use for further subdivisions "south_africa" The spatial fooprint of the stratified random bottom trawl survey operated by DAFF in the West or South Coast of South Africa (as identified by H. Winker); see region to select between South and West Coast surveys "gulf_of_st_lawrence" The spatial fooprint of the survey operated by DFO in Gulf of St. Lawrence (as identified by H. Benoit) "new_zealand" The spatial fooprint of the bottom trawl survey operated by NIWA in Chatham Rise (as identified by V. McGregor) "habcam" The spatial fooprint of the visual trawl survey for scallops operated by NEFSC (as identified by D. Hart) "gulf_of_mexico" The US Gulf of Mexico, surveyed by various fishery-independent surveys; using a definition provided by A. Gruss "ATL-IBTS-Q1", "ATL-IBTS-Q4", "BITS", "BTS", "BTS-VIIA", "EVHOE", "IE-IGFS", "NIGFS", "NS_IBTS", "PT-IBTS", "SP-ARSA", "SP-NORTH", "SP-PORC" ICES survey domains as defined by shapefiles provided by M. Lindegren as originated by ICES Secretariat "stream_network" Specifying a stream network for use when Method="Stream_network" "other" Automated creation of an extrapolation-grid by padding an area around observations (not recommended for operational use)
fine_scale	a Boolean indicating whether to ignore (fine_scale=FALSE) or account for (fine_scale=TRUE) fine-scale spatial heterogeneity; See details for more informatino
strata.limits	an input for determining stratification of indices (see example script)
zone	UTM zone used for projecting Lat-Lon to km distances; use zone=NA by default to automatically detect UTM zone from the location of extrapolation-grid samples
FieldConfig	See Details section of make_data for details
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)
OverdispersionConfig	a vector of format c("eta1"=0, "eta2"="AR1") governing any correlated overdispersion among categories for each level of v_i, where eta1 is for encounter probability, and eta2 is for positive catch rates, where 0 is off, code"AR1" is an AR1 process, and aninteger greater than zero (e.g., 2) is the number of elements in a factor-analysis covariance (by default, c("eta1"=0, "eta2"=0) and this turns off overdispersion)
bias.correct	Boolean indicating whether to do epsilon bias-correction; see sdreport and fit_tmb for details
Options	a tagged-vector that is empty by default Options=c(), but where the following slots might be helpful to add, either by passing Options to make_settings, or editing after a call to that function: Options["Calculate_Range"]=TRUE Turns on internal calculation and SE for center-of-gravity Options["Calculate_effective_area"]=TRUE Turns on internal calculation and SE for effective area occupied measuring range expansion/contraction Options["Calculate_Cov_SE"]=TRUE Turns on internal calculation and SE for covariance among categories (i.e. in factor model) Options["Calculate_proportion"]=TRUE Turns on internal calculation and SE for proportion of response within each category (e.g., for calculating proportion-at-age or species turnover) Options["Calculate_Synchrony"]=TRUE Turns on internal calculation and SE for Loreau metric of synchrony (a.k.a. portfolio effects) Options["report_additional_variables"]=TRUE Export additional variables to Report object, to use for diagnostics or additional exploration Options["basin_method"] Controls how the density-dependent index is generated from model variables. Default Options["basin_method"]=2) uses annual mean of betas and epsilons as index. Alternative Options["basin_method"]=4) uses a Lagrange multiplier to penalize index towards total abundance Options["range_fraction"] The decorrelation range when passing over land relative to over water; the default value Options["range_fraction"]=0.2 indicates that the range is shorter over land, i.e., that correlations are strongest via water, while changing to Options["range_fraction"]=5 would represent correlations transfer via land more than water Options["Project_factors"] Whether to estimate spatial projection of factors representing covariance among years and/or variables, as used to plot these rank-reduced patterns
use_anisotropy	Boolean indicating whether to estimate two additional parameters representing geometric anisotropy
vars_to_correct	a character-vector listing which parameters to include for bias-correction, as passed to fit_tmb
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.
treat_nonencounter_as_zero	Boolean indicating whether to treat any year-category combination as having zero biomass when generating abundance indices and resulting compositional estimates
n_categories	number of categories in a multivariate model (only necessary to specify given some values for purpose)
VamConfig	Options to estimate interactions, containing three slots: VamConfig[0] selects method for forming interaction matrix; Turn off feature using 0, or I recommend using 2 by default VamConfig[1] indicates the rank of the interaction matrix, indicating the number of community axes that have regulated dynamics VamConfig[2] Indicates whether interactions occur before spatio-temporal variation (VamConfig[2]=0) or after VamConfig[2]=1
max_cells	Maximum number of extrapolation-grid cells. If number of cells in extrapolation-grid is less than this number, then its value is ignored. Default max_cells=Inf results in no reduction in number of grid cells from the default extrapolation-grid for a given region. Using a lower value is particularly useful when fine_scale=TRUE and using epsilon bias-correction, such that the number of extrapolation-grid cells is often a limiting factor in estimation speed.
knot_method	whether to determine location of GMRF vertices based on the location of samples knot_method=`samples` or extrapolation-grid cells within the specified strata knot_method='grid'; default knot_method=NULL is coerced to knot_method=`samples`

Details

This function assembles a default set of user-decisions for a specified modelling purpose. The default settings are guessed based on generic guidance, and should be carefully reviewed for real-world purposes. If the user supplies values for individual settings e.g. FieldConfig, then these values override the defaults that are provided by interpreting purpose

Value

Tagged list containing default settings for a given purpose, use names on output to see or modify list of settings.

References

For discussion of some of these options see https://doi.org/10.1016/j.fishres.2018.10.013

See Also

VAST for general documentation, make_settings for generic settings, fit_model for model fitting, and plot_results for generic plots

Other wrapper functions: fit_model(), plot_results()

James-Thorson/VAST documentation built on Feb. 9, 2025, 9:05 a.m.