fit_ssm: Fit a continuous-time state-space model to filter Argos...

In foieGras: Fit Continuous-Time State-Space and Latent Variable Models for Quality Control of Argos Satellite (and Other) Telemetry Data and for Estimating Movement Behaviour

Description

fits either a simple random walk or a correlated random walk (a random walk on velocity) in continuous time to filter Argos LS, and/or KF/KS location data, processed light-level geolocation data (GLS), and/or GPS data. Location data of different types can combined in a single data frame (see details). Predicts locations at user-specified time intervals (regular or irregular).

Usage

fit_ssm(
  d,
  vmax = 5,
  ang = c(15, 25),
  distlim = c(2500, 5000),
  spdf = TRUE,
  min.dt = 60,
  pf = FALSE,
  model = "crw",
  time.step = NA,
  scale = FALSE,
  emf = NULL,
  map = NULL,
  parameters = NULL,
  fit.to.subset = TRUE,
  control = ssm_control(),
  inner.control = NULL,
  verbose = NULL,
  optim = NULL,
  optMeth = NULL,
  lpsi = NULL
)

Arguments

d	a data frame of observations including Argos KF error ellipse info (when present)
vmax	max travel rate (m/s) passed to sda to identify outlier locations
ang	angles (deg) of outlier location "spikes"
distlim	lengths (m) of outlier location "spikes"
spdf	(logical) turn trip::sda on (default; TRUE) or off
min.dt	minimum allowable time difference between observations; dt <= min.dt will be ignored by the SSM
pf	just pre-filter the data, do not fit the SSM (default is FALSE)
model	fit either a simple random walk ("rw") or correlated random walk ("crw") as a continuous-time process model
time.step	options: 1) the regular time interval, in hours, to predict to; 2) a vector of prediction times, possibly not regular, must be specified as a data.frame with id and POSIXt dates; 3) NA - turns off prediction and locations are only estimated at observation times.
scale	scale location data for more efficient optimization. This should rarely be needed (default = FALSE)
emf	optionally supplied data.frame of error multiplication factors for Argos location quality classes. Default behaviour is to use the factors supplied in foieGras::emf()
map	a named list of parameters as factors that are to be fixed during estimation, e.g., list(psi = factor(NA))
parameters	a list of initial values for all model parameters and unobserved states, default is to let sfilter specify these. Only play with this if you know what you are doing
fit.to.subset	fit the SSM to the data subset determined by prefilter (default is TRUE)
control	list of control settings for the outer optimizer (see ssm_control for details)
inner.control	list of control settings for the inner optimizer (see MakeADFun for additional details)
verbose	use ssm_control(verbose = 1) instead, see ssm_control for details
optim	use ssm_control(optim = "optim") instead, see ssm_control for details
optMeth	use ssm_control(method = "L-BFGS-B") instead, see ssm_control for details
lpsi	use ssm_control(lower = list(lpsi = -Inf)) instead, see ssm_control for details

Details

d is a data.frame, tibble, or sf-tibble with 5, 7 or 8 columns, depending on the tracking data type. Argos Least-Squares and GPS data should have 5 columns in the following order: "id", "date", "lc", "lon", "lat". Where "date" can be a POSIX object or text string in YYYY-MM-DD HH:MM:SS format. If a text string is supplied then the time zone is assumed to be "GMT". lc (location class) can include the following values: 3, 2, 1, 0, A, B, Z, G, or GL. The latter two are for GPS and GLS locations, respectively. Class Z values are assumed to have the same error variances as class B. By default, class G (GPS) locations are assumed to have error variances 10x smaller than Argos class 3 variances, but unlike Argos error variances the GPS variances are the same for longitude and latitude.

See emf for details on how to modify these assumptions.

Argos Kalman Filter (or Kalman Smoother) data should have 8 columns, including the above 5 plus "smaj", "smin", "eor" that contain Argos error ellipse variables (in m for "smaj", "smin" and deg for "eor").

Light-level geolocation (GLS) locations can be modelled provided each longitude and latitude has a corresponding standard error. These data should have 7 columns, including the above 5 plus "lonerr", "laterr" (in degrees). In this case, all lc values should be set to "GL".

Multiple location data types can be combined in a single data frame (see the vignette for examples).

When data are provided as an sf-tibble, the user-specified projection is respected. Otherwise, longlat data are re-projected internally to a global Mercator grid and provided as the default output. An un-projected tibble of lon,lat and x,y location estimates can be obtained by using grab with the argument as_sf = FALSE.

Value

a list with components

call	the matched call
predicted	an sf tbl of predicted location states
fitted	an sf tbl of fitted locations
par	model parameter summary
data	an augmented sf tbl of the input data
inits	a list of initial values
pm	the process model fit, either "rw" or "crw"
ts	time time.step in h used
opt	the object returned by the optimizer
tmb	the TMB object
rep	TMB sdreport
aic	the calculated Akaike Information Criterion
time	the processing time for sfilter

References

Jonsen ID, Patterson TA, Costa DP, et al. (2020) A continuous-time state-space model for rapid quality-control of Argos locations from animal-borne tags. Movement Ecology 8:31 https://doi.org/10.1186/s40462-020-00217-7

Jonsen ID, McMahon CR, Patterson TA, et al. (2019) Movement responses to environment: fast inference of variation among southern elephant seals with a mixed effects model. Ecology. 100(1):e02566 https://doi.org/10.1002/ecy.2566

See Also

sfilter

Examples

## fit crw model to Argos LS data
## se = FALSE to speed up ex
fit <- fit_ssm(sese1, vmax = 4, model = "crw", time.step = 48, 
control = ssm_control(se = FALSE)) 

## time series plots of fitted value fit to data
plot(fit, what = "fitted", type = 1, ask = FALSE)

## track plots of predicted value fit to data
plot(fit, what = "predicted", type = 2, ask = FALSE)

foieGras documentation built on April 27, 2021, 1:05 a.m.