foieGras (version 0.4.0)

fit_ssm: Fit a continuous-time state-space model to filter Argos satellite geolocation data

Description

fits either a simple random walk or a correlated random walk (a random walk on velocity) in continuous time to filter Argos KF and/or LS data, or processed light-level geolocation data. predicts locations at user-specified time intervals (regular or irregular).

Usage

fit_ssm(d, vmax = 50, ang = -1, distlim = c(2500, 5000),
  spdf = TRUE, min.dt = 60, pf = FALSE, model = "crw",
  time.step = 6, emf = NULL, map = NULL, parameters = NULL,
  fit.to.subset = TRUE, optim = "optim", verbose = 1,
  control = NULL, inner.control = NULL, lpsi = -Inf)

Arguments

d

a data frame of observations including Argos KF error ellipse info

vmax

max travel rate (m/s) passed to argosfilter::sdafilter to define outlier locations

ang

angles of outlier location "spikes" - see ?argosfilter::sdafilter for details

distlim

lengths of outlier location "spikes" - see ?argosfilter::sdafilter for details

spdf

(logical) turn argosfilter::sdafilter 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

the regular time interval, in hours, to predict to. Alternatively, a vector of prediction times, possibly not regular, must be specified as a data.frame with id and POSIXt dates.

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)

optim

numerical optimizer to be used ("nlminb" or "optim")

verbose

report progress during minimization; 0 for complete silence; 1 for progress bar only; 2 for minimizer trace but not progress bar

control

list of control settings for the outer optimizer (see ?nlminb or ?optim for details)

inner.control

list of control settings for the inner optimizer (see ?TMB::MakeADFUN for additional details)

lpsi

lower bound for the psi parameter

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

Examples

# NOT RUN {
## fit rw model to one seal with Argos KF data
data(ellie)
fit <- fit_ssm(ellie, model = "rw", time.step = 24)

## time series plots of predicted value fits
plot(fit, what = "predicted", type = 1)

## fit crw model to both seals, with Argos KF & LS data 
data(ellies)
fits <- fit_ssm(ellies, model = "crw", time.step = 24)

## track plots of fits for both seals
plot(fits, what = "predicted", type = 2)

# }