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).
fit_ssm(
d,
vmax = 5,
ang = c(15, 25),
distlim = c(2500, 5000),
spdf = TRUE,
min.dt = 60,
pf = FALSE,
model = "crw",
time.step = 6,
scale = FALSE,
emf = NULL,
map = NULL,
parameters = NULL,
fit.to.subset = TRUE,
optim = "optim",
verbose = 1,
control = NULL,
inner.control = NULL,
lpsi = -Inf
)a data frame of observations including Argos KF error ellipse info (when present)
max travel rate (m/s) passed to sda to identify
outlier locations
angles (deg) of outlier location "spikes"
lengths (m) of outlier location "spikes"
(logical) turn trip::sda on (default; TRUE) or off
minimum allowable time difference between observations;
dt <= min.dt will be ignored by the SSM
just pre-filter the data, do not fit the SSM (default is FALSE)
fit either a simple random walk ("rw") or correlated random walk ("crw") as a continuous-time process model
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 location data for more efficient optimization. This should rarely be needed (default = FALSE)
optionally supplied data.frame of error multiplication factors for Argos location quality classes. Default behaviour is to use the factors supplied in foieGras::emf()
a named list of parameters as factors that are to be fixed during estimation, e.g., list(psi = factor(NA))
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 the SSM to the data subset determined by prefilter
(default is TRUE)
numerical optimizer to be used ("nlminb" or "optim")
report progress during minimization; 0 for complete silence; 1 for parameter trace; 2 for optimizer trace
list of control settings for the inner optimizer (see MakeADFun for additional details)
lower bound for the psi parameter
a list with components
callthe matched call
predictedan sf tbl of predicted location states
fittedan sf tbl of fitted locations
parmodel parameter summary
dataan augmented sf tbl of the input data
initsa list of initial values
pmthe process model fit, either "rw" or "crw"
tstime time.step in h used
optthe object returned by the optimizer
tmbthe TMB object
repTMB sdreport
aicthe calculated Akaike Information Criterion
timethe processing time for sfilter
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 prefilter and
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.
Jonsen ID, Patterson TA, Costa DP, Doherty PD, Godley BJ, Grecian WJ, Guinet C, Hoenner X, Kienle SS, Robinson PW, Votier SC. (2020) A continuous-time state-space model for rapid quality-control of Argos locations from animal-borne tags. arXiv preprint arXiv:2005.00401. May 1.
Jonsen ID, McMahon CR, Patterson TA, Auger-M<U+00E9>th<U+00E9> M, Harcourt R, Hindell MA, Bestley S. (2019) Movement responses to environment: fast inference of variation among southern elephant seals with a mixed effects model. Ecology. 100(1):e02566.
# NOT RUN {
## fit crw model to two seals with Argos LS data
data(ellies)
fit <- fit_ssm(ellies, vmax = 5, model = "crw", time.step = 48)
## time series plots of fitted value fits to both seals
plot(fit, what = "fitted", type = 1)
## track plots of predicted value fits for both seals
plot(fit, what = "predicted", type = 2)
# }
Run the code above in your browser using DataLab