Fit Continuous-Time Correlated Random Walk Models to Animal Movement Data

Description

The [C]orrelated [RA]ndom [W]alk [L]ibrary (I know it is not an R library, but, "crawp" did not sound as good) of R functions was designed for fitting continuous-time correlated random walk (CTCRW) models with time indexed covariates. The model is fit using the Kalman-Filter on a state space version of the continuous-time stochastic movement process.

Note

This software package is developed and maintained by scientists at the NOAA Fisheries Alaska Fisheries Science Center and should be considered a fundamental research communication. The recommendations and conclusions presented here are those of the authors and this software should not be construed as official communication by NMFS, NOAA, or the U.S. Dept. of Commerce. In addition, reference to trade names does not imply endorsement by the National Marine Fisheries Service, NOAA. While the best efforts have been made to insure the highest quality, tools such as this are under constant development and are subject to change.

Author(s)

Josh London and Devin S. Johnson

Maintainer: Devin S. Johnson <devin.johnson@noaa.gov>

References

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

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Generic subset/bracket method for crwIS classes

Description

Generic subset/bracket method for crwIS classes

Usage

## S3 method for class 'crwIS'
x[i, ..., drop = TRUE]

Arguments

Calculates AIC for all objects of class crwFit listed as arguments

Description

AIC, delta AIC, and Akaike weights for all models listed as arguments.

Usage

aic.crw(...)

Arguments

Details

The function can either be executed with a series of 'crwFit' objects (see crwMLE) without the '.crwFit' suffix or the function can be called without any arguments and it will search out all 'crwFit' objects in the current workspace and produce the model selection table for all 'crwFit' objects in the workspace. Caution should be used when executing the function in this way. ALL 'crwFit' objects will be included whether or not the same locations are used! For all of the models listed as arguments (or in the workspace), AIC, delta AIC, and Akaike weights will be calculated.

Value

A table, sorted from lowest AIC value to highest.

Author(s)

Devin S. Johnson

Transform Argos diagnostic data to covariance matrix form

Description

Using this function the user can transform the Argos diagnostic data for location error into a form usable as a covariance matrix to approximate the location error with a bivariate Gaussian distribution. The resulting data.frame should be attached back to the data with cbind to use with the crwMLE function.

Usage

argosDiag2Cov(Major, Minor, Orientation)

Arguments

Value

A data.frame with the following columns

Author(s)

Devin S. Johnson

'Flattening' a list-form crwPredict object into a data.frame

Description

“Flattens” a list form crwPredict object into a flat data.frame.

Usage

as.flat(predObj)

Arguments

Value

a data.frame version of a crwPredict list with columns for the state standard errors

Author(s)

Devin S. Johnson

See Also

northernFurSeal for use example

Bearded Seal Location Data

Description

Bearded Seal Location Data

Format

A data frame with 27,548 observations on 3 bearded seals in Alaska:

deployid

Unique animal ID

ptt

Hardware ID

instr

Hardware type

date_time

Time of location

type

Location type

quality

Argos location quality

latitude

Observed latitude

longitude

Observed longitude

error_radius

Argos error radius

error_semimajor_axis

Argos error ellipse major axis length

error_semiminor_axis

Argos error ellipse minor axis length

error_ellipse_orientation

Argos error ellipse degree orientation

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

Fit Continuous-Time Correlated Random Walk Models to Animal Telemetry Data

Description

The function uses the Kalman filter to estimate movement parameters in a state-space version of the continuous-time movement model. Separate models are specified for movement portion and the location error portion. Each model can depend on time indexed covariates. A “haul out” model where movement is allowed to completely stop, as well as, a random drift model can be fit with this function.

Usage

crwMLE(data, ...)

## Default S3 method:
crwMLE(
  data,
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  coord = c("x", "y"),
  proj = NULL,
  Time.name = "time",
  time.scale = NULL,
  theta = NULL,
  fixPar = NULL,
  method = "Nelder-Mead",
  control = NULL,
  constr = list(lower = -Inf, upper = Inf),
  prior = NULL,
  need.hess = TRUE,
  initialSANN = list(maxit = 200),
  attempts = 1,
  retrySD = 1,
  skip_check = FALSE,
  ...
)

## S3 method for class 'SpatialPoints'
crwMLE(
  data,
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  Time.name = "time",
  time.scale = NULL,
  theta = NULL,
  fixPar = NULL,
  method = "Nelder-Mead",
  control = NULL,
  constr = list(lower = -Inf, upper = Inf),
  prior = NULL,
  need.hess = TRUE,
  initialSANN = list(maxit = 200),
  attempts = 1,
  retrySD = 1,
  skip_check = FALSE,
  coord = NULL,
  ...
)

## S3 method for class 'sf'
crwMLE(
  data,
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  Time.name = "time",
  time.scale = NULL,
  theta = NULL,
  fixPar = NULL,
  method = "Nelder-Mead",
  control = NULL,
  constr = list(lower = -Inf, upper = Inf),
  prior = NULL,
  need.hess = TRUE,
  initialSANN = list(maxit = 200),
  attempts = 1,
  retrySD = 1,
  skip_check = FALSE,
  ...
)

Arguments

Details

• A full model specification involves 4 components: a movement model, an activity model, 2 location error models, and a drift indication. The movement model (mov.model) specifies how the movement parameters should vary over time. This is a function of specified, time-indexed, covariates. The movement parameters (sigma for velocity variation and beta for velocity autocorrelation) are both modeled with a log link as par = exp(eta), where eta is the linear predictor based on the covariates. The err.model specification is a list of 2 such models, one for “X (longitude)” and one for “Y (latitude)” (in that order) location error. If only one location error model is given, it is used for both coordinates (parameter values as well). If drift.model is set to TRUE, then, 2 additional parameters are estimated for the drift process, a drift variance and a beta multiplier.

• theta and fixPar are vectors with the appropriate number or parameters. theta contains only those parameters which are to be estimated, while fixPar contains all parameter values with NA for parameters which are to be estimated.

• The data set specified by data must contain a numeric or POSIXct column which is used as the time index for analysis. The column name is specified by the Time.name argument and it is strongly suggested that this column be of POSIXct type and in UTC. If a POSIXct column is used it is internally converted to a numeric vector with units of time.scale. time.scale defaults to NULL and an appropriate option will be chosen ("seconds","minutes","days","weeks") based on the median time interval. The user can override this by specifying one of those time intervals directly. If a numeric time vector is used, then the time.scale is ignored and there is no adjustment to the data. Also, for activity models, the activity covariate must be between 0 and 1 inclusive, with 0 representing complete stop of the animal (no true movement, however, location error can still occur) and 1 represent unhindered movement. The coordinate location should have NA where no location is recorded, but there is a change in the movement covariates.

• The CTCRW models can be difficult to provide good initial values for optimization. If initialSANN is specified then simulated annealing is used first to obtain starting values for the specified optimization method. If simulated annealing is used first, then the returned init list of the crwFit object will be a list with the results of the simulated annealing optimization.

• The attempts argument instructs crwMLE to attempt a fit multiple times. Each time, the fit is inspected for convergence, whether the covariance matrix could be calculated, negative values in the diag of the covariance matrix, or NA values in the standard errors. If, after n attempts, the fit is still not valid a simpleError object is returned. Users should consider increasing the number of attempts OR adjusting the standard deviation value for each attempt by setting retrySD. The default value for retrySD is 1, but users may need to increase or decrease to find a valid fit. Adjusting other model parameters may also be required.

Value

A list with the following elements:

Author(s)

Devin S. Johnson, Josh M. London

-2 * log-likelihood for CTCRW models

Description

This function is designed for primary use within the crwMLE model fitting function. But, it can be accessed for advanced R and crawl users. Uses the state-space parameterization and Kalman filter method presented in Johnson et al. (2008).

Usage

crwN2ll(
  theta,
  fixPar,
  y,
  noObs,
  delta,
  mov.mf,
  err.mfX,
  err.mfY,
  rho = NULL,
  activity = NULL,
  n.errX,
  n.errY,
  n.mov,
  driftMod,
  prior,
  need.hess,
  constr = list(lower = -Inf, upper = Inf)
)

Arguments

Details

This function calls compiled C++ code which can be viewed in the src directory of the crawl source package.

Value

-2 * log-likelihood value for specified CTCRW model.

Author(s)

Devin S. Johnson

References

Johnson, D., J. London, M. -A. Lea, and J. Durban. 2008. Continuous-time model for animal telemetry data. Ecology 89:1208-1215.

See Also

crwMLE

Simulate a value from the posterior distribution of a CTCRW model

Description

The crwPostIS draws a set of states from the posterior distribution of a fitted CTCRW model. The draw is either conditioned on the fitted parameter values or "full" posterior draw with approximated parameter posterior

Usage

crwPostIS(object.sim, fullPost = TRUE, df = Inf, scale = 1, thetaSamp = NULL)

Arguments

Details

The crwPostIS draws a posterior sample of the track state matrices. If fullPost was set to TRUE when the object.sim was build in crwSimulator then a pseudo-posterior draw will be made by first sampling a parameter value from a multivariate t distribution which approximates the marginal posterior distribution of the parameters. The covariance matrix from the fitted model object is used to scale the MVt approximation. In addition, the factor "scale" can be used to further adjust the approximation. Further, the parameter simulations are centered on the fitted values.

To correct for the MVt approximation, the importance sampling weight is also supplied. When calculating averages of track functions for Bayes estimates one should use the importance sampling weights to calculate a weighted average (normalizing first, so the weights sum to 1).

Value

List with the following elements:

Author(s)

Devin S. Johnson

See Also

See demo(northernFurSealDemo) for example.

Predict animal locations and velocities using a fitted CTCRW model and calculate measurement error fit statistics

Description

The crwMEfilter function uses a fitted model object from crwMLE to predict animal locations (with estimated uncertainty) at times in the original data set and supplemented by times in predTime. If speedEst is set to TRUE, then animal log-speed is also estimated. In addition, the measurement error shock detection filter of de Jong and Penzer (1998) is also calculated to provide a measure for outlier detection.

Usage

crwPredict(object.crwFit, predTime = NULL, return.type = "minimal", ...)

Arguments

Details

The requirements for data are the same as those for fitting the model in crwMLE.

• ("predTime") predTime can be either passed as a separate vector of POSIXct or numeric values for all prediction times expected in the returned object. Note, previous versions of crwPredict would return both times specified via predTime as well as each original observed time. This is no longer the default (see

  return.type). If the original data were provided as a POSIXct type, then crwPredict can derive a sequence of regularly spaced prediction times from the original data. This is specified by providing a character string that corresponds to the by argument of the seq.POSIXt function (e.g. '1 hour', '30 mins'). crwPredict will round the first observed time up to the nearest unit (e.g. '1 hour' will round up to the nearest hour, '30 mins' will round up to the nearest minute) and start the sequence from there. The last observation time is truncated down to the nearest unit to specify the end time.

Value

There are three possible return types specified with return.type:

Author(s)

Devin S. Johnson

References

de Jong, P. and Penzer, J. (1998) Diagnosing shocks in time series. Journal of the American Statistical Association 93:796-806.

Plot CRW predicted object

Description

Creates 2 types of plots of a crwPredict object: a plot of both coordinate axes with prediction intervals and a plot of just observed locations and predicted locations.

Usage

crwPredictPlot(object, plotType = "ll", ...)

Arguments

Value

A plot.

Author(s)

Devin S. Johnson and Sebastian Luque

See Also

See demo(northernFurSealDemo) for additional examples.

Create a weighted importance sample for posterior predictive track simulation.

Description

The crwSamplePar function uses a fitted model object from crwMLE and a set of prediction times to construct a list from which crwPostIS will draw a sample from either the posterior distribution of the state vectors conditional on fitted parameters or a full posterior draw from an importance sample of the parameters.

Usage

crwSamplePar(
  object.sim,
  method = "IS",
  size = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = T,
  force.quad
)

Arguments

Details

The crwSamplePar function uses the information in a crwSimulator object to create a set of weights for importance sample-resampling of parameters in a full posterior sample of parameters and locations using crwPostIS. This function is usually called from crwPostIS. The average user should have no need to call this function directly.

Value

List with the following elements:

Author(s)

Devin S. Johnson

See Also

See demo(northernFurSealDemo) for example.

Construct a posterior simulation object for the CTCRW state vectors

Description

The crwSimulator function uses a fitted model object from crwMLE and a set of prediction times to construct a list from which crwPostIS will draw a sample from either the posterior distribution of the state vectors conditional on fitted parameters or a full posterior draw from an importance sample of the parameters.

Usage

crwSimulator(
  object.crwFit,
  predTime = NULL,
  method = "IS",
  parIS = 1000,
  df = Inf,
  grid.eps = 1,
  crit = 2.5,
  scale = 1,
  quad.ask = TRUE,
  force.quad
)

Arguments

Details

The crwSimulator function produces a list and preprocesses the necessary components for repeated track simulation from a fitted CTCRW model from crwMLE. The method argument can be one of "IS" or "quadrature". If method="IS" is chosen standard importance sampling will be used to calculate the appropriate weights via t proposal with df degrees of freedom. If df=Inf (default) then a multivariate normal distribution is used to approximate the parameter posterior. If method="quadrature", then a regular grid over the posterior is used to calculate the weights. The argument grid.eps controls the quadrature grid. The arguments are approximately the upper and lower limit in terms of standard deviations of the posterior. The default is grid.eps, in units of 1sd. If object.crwFit was fitted with crwArgoFilter, then the returned list will also include p.out, which is the approximate probability that the observation is an outlier.

Value

List with the following elements:

Author(s)

Devin S. Johnson

See Also

See demo(northernFurSealDemo) for example.

Coerce to sf/sfc object

Description

Provides reliable conversion of "crwIS" and "crwPredict" objects into simple features objects supported in the "sf" package. Both "sf" objects with "POINT" geometry and "sfc_LINESTRING" objects are created. Coercion of "crwPredict" objects to "sfc_LINESTRING" has an option "group" argument when the "crwPredict" object includes predictions from multiple deployments. The grouping column will be used and a tibble of multiple "sf_LINESTRING" objects will be returned

Usage

crw_as_sf(data, ftype, locType, group)

## S3 method for class 'crwIS'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'crwPredict'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), group = NULL, ...)

## S3 method for class 'list'
crw_as_sf(data, ftype, locType = c("p", "o", "f"), ...)

Arguments

Methods (by class)

• crw_as_sf(crwIS): coerce crwIS object to sf (POINT or LINESTRING geometry)

• crw_as_sf(crwPredict): coerce crwPredict object to sf (POINT or LINESTRING geometry)

• crw_as_sf(list): coerce list of crwIS objects to sf (LINESTRING or MULTILINESTRING geometry)

Coerce crawl objects (crwIS and crwPredict) to tibbles

Description

Coerce crawl objects (crwIS and crwPredict) to tibbles

Usage

crw_as_tibble(crw_object, ...)

## S3 method for class 'crwIS'
crw_as_tibble(crw_object, ...)

## S3 method for class 'crwPredict'
crw_as_tibble(crw_object, ...)

## S3 method for class 'tbl'
crw_as_tibble(crw_object, ...)

Arguments

Methods (by class)

• crw_as_tibble(crwIS): coerce crwIS object to tibble

• crw_as_tibble(crwPredict): coerce crwPredict object to tibble

• crw_as_tibble(tbl):

Author(s)

Josh M. London

Detect appropriate time scale for movement analysis

Description

This function examines the time vector and evaluates the median time interval. With this, we determine what the best time scale for the movement model is likely to be.

Usage

detect_timescale(time_vector)

Arguments

Value

character of either "seconds","minutes","hours","days","weeks"

Display the order of parameters along with fixed values and starting values

Description

This function takes the model specification arguments to the crwMLE function and displays a table with the parameter names in the order that crwMLE will use during model fitting. This is useful for specifying values for the fixPar or theta (starting values for free parameters) arguments.

Usage

displayPar(
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = FALSE,
  data,
  Time.name,
  theta,
  fixPar,
  ...
)

Arguments

Value

A data frame with the following columns

Author(s)

Devin S. Johnson

See Also

demo(northernFurSealDemo) for example.

Expand a time indexed data set with additional prediction times

Description

Expands a covariate data frame (or vector) that has a separate time index by inserting prediction times and duplicating the covariate values for all prediction time between subsequent data times.

Usage

expandPred(x, Time = "Time", predTime, time.col = FALSE)

Arguments

Value

data.frame expanded by predTime

Author(s)

Devin S. Johnson

Examples

#library(crawl)
origTime <- c(1:10)
x <- cbind(rnorm(10), c(21:30))
predTime <- seq(1,10, by=0.25)
expandPred(x, Time=origTime, predTime, time.col=TRUE)

Fill missing values in data set (or matrix) columns for which there is a single unique value

Description

Looks for columns in a data set that have a single unique non-missing value and fills in all NA with that value

Usage

fillCols(data)

Arguments

Value

data.frame

Author(s)

Devin S. Johnson

Examples

#library(crawl)
data1 <- data.frame(constVals=rep(c(1,NA),5), vals=1:10)
data1[5,2] <- NA
data1
data2 <- fillCols(data1)
data2

mat1 <- matrix(c(rep(c(1,NA),5), 1:10), ncol=2)
mat1[5,2] <- NA
mat1
mat2 <- fillCols(mat1)
mat2

fix_path function id depreciated.

Description

fix_path function id depreciated.

Usage

fix_path(...)

Arguments

'Flattening' a list-form crwPredict object into a data.frame

Description

“Flattens” a list form crwPredict object into a flat data.frame.

Usage

flatten(predObj)

Arguments

Value

a data.frame version of a crwPredict list with columns for the state standard errors

Author(s)

Devin S. Johnson

See Also

northernFurSeal for use example

Harbor seal location data set used in Johnson et al. (2008)

Description

Harbor seal location data set used in Johnson et al. (2008)

Format

A data frame with 7059 observations on the following 5 variables.

Time

a numeric vector.

latitude

a numeric vector.

longitude

a numeric vector.

DryTime

a numeric vector.

Argos_loc_class

a factor with levels 0 1 2 3 A B

.

Author(s)

Devin S. Johnson

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

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

Harbor seal location data updated since Johnson et al. (2008)

Description

The original location data used in Johnson et al. (2008) was geographic (latitude/longitude) (but not explicitly documented) and provided as a simple data frame. This data updates the data to a Simple Feature Collection (as part of the sf package) with the CRS explicitly set.

Format

A Simple Feature Collection with 7059 features and 3 fields.

Time

a numeric vector.

DryTime

a numeric vector.

Argos_loc_class

a factor with levels 0 1 2 3 A B.

geometry

a list column with geometry data; CRS = EPSG:4326

Author(s)

Josh M. London

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

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

Reverse as.numeric command that is performed on a vector of type POSIXct

Description

Takes integer value produced by as.numeric(x), where x is a POSIXct vector and returns it to a POSIXct vector

Usage

intToPOSIX(timeVector, tz = "GMT")

Arguments

Value

POSIXct vector

Note

There is no check that as.numeric applied to a POSIX vector produced timeVector. So, caution is required in using this function. It was included simply because I have found it useful

Author(s)

Devin S. Johnson

Examples

#library(crawl)
timeVector <- as.numeric(Sys.time())
timeVector
intToPOSIX(timeVector, tz="")

Merge a location data set with a dry time (or other stopping) covariate

Description

The function merges a location data set with a stopping variable data set.

Usage

mergeTrackStop(
  data,
  stopData,
  Time.name = "Time",
  interp = c("zeros", "ma0"),
  win = 2,
  constCol
)

Arguments

Details

Simply merges the data frames and interpolates based on the chosen method. Both data frames have to use the same name for the time variable. Also contains stopType which = "o" if observed or "p" for interpolated.

The merged data is truncated to the first and last time in the location data set. Missing values in the stopping variable data set can be interpolated by replacing them with zeros (full movement) or first replacing with zeros then using a moving average to smooth the data. Only the missing values are then replace with this smoothed data. This allows a smooth transition to full movement.

Value

Merged data.frame with new column from stopData. Missing values in the stopping variable will be interpolated

Author(s)

Devin S. Johnson

Examples

track <- data.frame(TimeVar=sort(runif(20,0,20)), x=1:20, y=20:1)
track
stopData <- data.frame(TimeVar=0:29, stopVar=round(runif(30)))
stopData
mergeTrackStop(track, stopData, Time.name="TimeVar")

Northern fur seal pup relocation data set used in Johnson et al. (2008)

Description

Northern fur seal pup relocation data set used in Johnson et al. (2008)

Format

A data frame with 795 observations on the following 4 variables:

GMT

A POSIX time vector

loc_class

a factor with levels 3 2 1 0 A.

lat

a numeric vector. Latitude for the locations

long

a numeric vector. Longitude for the locations

Source

Marine Mammal Laboratory, Alaska Fisheries Science Center, National Marine Fisheries Service, NOAA 7600 Sand Point Way NE Seattle, WA 98115

References

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

tidy-like method for crwFit object

Description

this function mimics the approach taken by broom::tidy to present model output parameters in a tidy, data frame structure.

Usage

tidy_crwFit(fit)

Arguments