sim_fit: simulate animal tracks from a 'ssm' fit

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

simulate animal tracks from a ssm fit

Description

simulate from the rw or crw process models to generate either a set of x,y or lon,lat coordinates from a ssm fit with length equal to the number of observations used in the SSM fit.

Usage

sim_fit(
  x,
  what = c("fitted", "predicted"),
  reps = 1,
  start = NULL,
  end = NULL,
  grad = NULL,
  beta = c(-300, -300),
  cpf = FALSE,
  sim_only = FALSE
)

Arguments

x	a ssm fit object with class ssm_df
what	simulate fitted (typically irregular in time) or predicted (typically regular in time) locations
reps	number of replicate tracks to simulate from an ssm model fit object
start	a 2-element vector for the simulated track start location (lon,lat or x,y)
end	a 2-element vector for the simulated track end location (lon,lat or x,y)
grad	a SpatRaster of x- and y-gradients as separate layers (see details)
beta	a 2-element vector of parameters defining the potential function magnitude in x- and y-directions (ignored if is.null(grad), ie. no potential function; see details).
cpf	logical; should simulated tracks return to their start point (ie. a central-place forager)
sim_only	logical, do not include ssm estimated location in output (default is FALSE)

Details

A potential function can be applied to the simulated paths to help avoid locations on land (or in water), using the grad and beta arguments. A coarse-resolution rasterStack of global x- and y-gradients of distance to land are provided. Stronger beta parameters result in stronger land (water) avoidance but may also introduce undesirable/unrealistic artefacts (zig-zags) in the simulated paths. See Brillinger et al. (2012) and vignette("momentuHMM", package = "momentuHMM") for more details on the use of potential functions for simulating constrained animal movements. WARNING: This application of potential functions to constrain simulated paths is experimental, likely to change in future releases, and NOT guaranteed to work enitrely as intended, especially if cpf = TRUE!

Value

a fG_sim_fit object containing the paths simulated from a ssm fit object

References

Brillinger DR, Preisler HK, Ager AA, Kie J (2012) The use of potential functions in modelling animal movement. In: Guttorp P., Brillinger D. (eds) Selected Works of David Brillinger. Selected Works in Probability and Statistics. Springer, New York. pp. 385-409.

Examples

fit <- fit_ssm(ellie, model = "crw", time.step = 24)
trs <- sim_fit(fit, what = "predicted", reps = 3)
plot(trs)

ianjonsen/foieGras documentation built on Jan. 17, 2025, 11:15 p.m.