Skip to contents

Define a survey for compare_surveys()

Source: R/compare-surveys.R
survey_spec.Rd

Describes one survey index for compare_surveys(): which survey series it combines, and any model or prediction-grid settings that differ from the defaults given to compare_surveys(). Every argument except series defaults to NULL, meaning "use the compare_surveys() default", which in turn is inherited from the compiled model where possible.

Surveys differ in coverage, season, depth range and sampling frequency, so a model that suits the compiled data set rarely suits each survey on its own. A survey sampled every second year, for example, often needs AR(1) or random walk spatiotemporal fields to bridge the gaps, and two series that alternate years can be combined with the series as a fixed effect (formula = value ~ 0 + cruiseseries + s(depth)) and predicted for one of them (predict_values = list(cruiseseries = "SeriesA")).

Usage

survey_spec(
  series,
  formula = NULL,
  family = NULL,
  spatial = NULL,
  spatiotemporal = NULL,
  control = NULL,
  extra_time = NULL,
  mesh_cutoff = NULL,
  filter = NULL,
  depth_range = NULL,
  concavity = NULL,
  buffer = NULL,
  newdata = NULL,
  area = NULL,
  predict_values = NULL
)

Arguments

series

Character vector of the survey series (values of the survey_col column) included in the survey index.

formula, family, spatial, spatiotemporal, control

Model settings passed to sdmTMB::sdmTMB().

extra_time

Optional numeric vector of extra time steps passed to sdmTMB::sdmTMB(), e.g. a year without data inside the series. Indices are reported only for years with data.

mesh_cutoff

Numeric mesh cutoff (in model units, typically km).

filter

Optional function taking the survey's data frame and returning a subset of it, e.g. function(x) subset(x, lat <= 80). Applied after selecting series.

depth_range

Optional depth band for the prediction grid: a numeric vector c(min, max), or "data" to use quantiles of the survey's haul depths (see depth_quantiles in compare_surveys()). Requires a depth column in the prediction grid.

concavity, buffer

Concave-hull settings for the survey footprint (see make_survey_prediction_region()). buffer is in CRS units (typically m).

newdata

Optional prediction grid for this survey, used instead of clipping the common newdata given to compare_surveys() to the survey footprint. Useful when the survey extends outside the compiled prediction domain (e.g. deeper). If it has no time column, it is replicated over the survey years and the years of the compiled model; if it has one, it must cover every year of the compiled model for the same-area comparison. Must contain every predictor of the survey model (and of the compiled model for the same-area comparison).

area

Grid cell area for newdata. Defaults to the area given to compare_surveys().

predict_values

Optional named list of values assigned to columns of the prediction grid before predicting from the survey model, e.g. list(cruiseseries = "EggaN") to predict a multi-series model for one series.

Value

A list of class sdmTMB_survey_spec.

See also

compare_surveys()

Author

Mikko Vihtakari

Examples

# Two series that alternate years, combined with the series as a fixed
# effect and AR(1) fields that bridge the alternating gaps
survey_spec(
  c("EggaN", "EggaS"),
  formula = biomass ~ 0 + cruiseseries + s(depth),
  spatiotemporal = "ar1",
  predict_values = list(cruiseseries = "EggaN"),
  depth_range = "data"
)
#> $series
#> [1] "EggaN" "EggaS"
#> 
#> $formula
#> biomass ~ 0 + cruiseseries + s(depth)
#> <environment: 0x55ba16ee14e0>
#> 
#> $family
#> NULL
#> 
#> $spatial
#> NULL
#> 
#> $spatiotemporal
#> [1] "ar1"
#> 
#> $control
#> NULL
#> 
#> $extra_time
#> NULL
#> 
#> $mesh_cutoff
#> NULL
#> 
#> $filter
#> NULL
#> 
#> $depth_range
#> [1] "data"
#> 
#> $concavity
#> NULL
#> 
#> $buffer
#> NULL
#> 
#> $newdata
#> NULL
#> 
#> $area
#> NULL
#> 
#> $predict_values
#> $predict_values$cruiseseries
#> [1] "EggaN"
#> 
#> 
#> attr(,"class")
#> [1] "sdmTMB_survey_spec"