rwalc: Correlated Random Walk Filter

View source: R/RWalc.R

rwalcR Documentation

Correlated Random Walk Filter

Description

Fit a continuous time correlated random walk to filter a track and predict locations for given time steps.

Usage

rwalc(
  data,
  predict = NULL,
  track = NULL,
  par = c(1, 1, 1, 1, 1, 1),
  betaPar = c("free", "equal", "fixed"),
  sigmaPar = c("free", "equal", "fixed"),
  tauPar = c("free", "equal", "fixed"),
  tdf = -1,
  bshrink = 1e-06,
  control = rwalcControl()
)

Arguments

data

A dataframe representing the track (see details).

predict

A vector of times (as POSIXct) or a dataframe of segments and times for which to predict locations. Ignored if 'track' is provided.

track

Dataframe representing an initial estimate of the track (see details).

par

Vector of initial parameter estimates.

betaPar

Controls the autocorrelaion parameter for x and y processes.

sigmaPar

Controls the standard deviation parameters for the stochastic innovations of the velocity for the x and y processes.

tauPar

Controls the scaling parameter for the observational errors for the x and y processes

tdf

Degrees of freedom for the multivariate t error distribution.

bshrink

Shrinkage penalty for the correlation parameter.

control

List of control parameters (see 'rwalcControl')

Details

The filter fits a continuous time correlated random walk movement model similar to that described in Johnson et al. (2008) and implemented in the package 'crawl'. Unlike the crawl model, the model implemented here has no drift or haul out components, and assumes t distributed errors as described by Albertsen et al. (2015) if 'tdf' is positive.

The input track may consist of several independent segments. These may represent either non-overlapping segments of a single track, or distinct tracks that may overlap in time. The fitted random walk is correlated within a segment, but segments are assumed independent. It is assumed the input dataframe is ordered by segment and by date within segment.

The input track to be filtered is supplied as a dataframe ('data') where each row is an observed location, with columns:

- 'segment': track segment (integer, optional) - 'date': observation time (as GMT POSIXct) - 'x': observed x coordinate - 'y': observed y coordinate - 'x.se': standard error of the x coordinate (optional) - 'y.se': standard error of the y coordinate (optional)

The filtering model assumes the errors in the spatial coordinates are have standard deviations 'x.se' and 'y.se' scaled by the \tau model parameters. If these columns are missing, they are assumed to be 1.

An estimate of the track is required to initialize the fitting process. This can be supplied by the user through the 'track' argument as a dataframe with the same format returned by 'interpolateTrack'. When this argument is 'NULL', the initial track is generated with 'interpolateTrack' from the 'data' and 'predict' arguments.

The 'predict' argument specifies prediction times for which locations along the track will be predicted when no initial track is given. When the track consists of a single segment, these argument may be a vector of POSIXct times, otherwise it must be a dataframe with columns:

- 'segment': track segment (integer, optional) - 'date': prediction time (as GMT POSIXct)

If an initial track is given, the prediction times are determined from that.

The arguments 'betaPar', 'sigmaPar' and 'tauPar' control how the correlation parameters \beta, the standard deviations of the innovations for the velocity process \sigma and the error scaling parameters \tau apply to the x and y processes:

- '"free"': independent parameters are estimated for x and y - '"equal"': a common parameter is estimated for both x and y - '"fixed"': the parameters are determined by 'par'

Value

Returns a list with components: - 'summary': parameter summary table - 'par': vector of parameter estimates - 'track': dataframe of the fitted track - 'opt': the object returned by the optimizer - 'tmb': the 'TMB' object The 'track' dataframe has columns: - 'segment': track segment - 'date': time (as GMT POSIXct) - 'x': x coordinate - 'y': y coordinate - 'x.v': x component of velocity - 'y.v': y component of velocity - 'x.se': standard error of x coordinate - 'y.se': standard error of y coordinate - 'x.v.se': standard error of x component of velocity - 'y.v.se': standard error of y component of velocity

References

Johnson, D. S., London, J. M., Lea, M. A. and Durban, J. W. (2008). Continuous-time correlated random walk model for animal telemetry data. Ecology, 89(5), 1208-1215.

Albertsen, C. M., Whoriskey, K., Yurkowski, D., Nielsen, A. and Flemming, J. M. (2015). Fast fitting of non-Gaussian state-space models to animal movement data via Template Model Builder. Ecology, 96(10), 2598-2604.

Lange, K. L., Little, R. J., & Taylor, J. M. (1989). Robust statistical modeling using the t distribution. Journal of the American Statistical Association, 84(408), 881-896.


SWotherspoon/RWalc documentation built on June 10, 2025, 6:46 a.m.