crwMLE: Fit Continuous-Time Correlated Random Walk Models to Animal...

In NMML/crawl: Fit Continuous-Time Correlated Random Walk Models to Animal Movement Data

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

data	a data set of location observations as a data.frame, tibble, SpatialPointsDataFrame ('sp' package), or a data.frame of class 'sf' that contains a geometry column of type sfc_POINT
...	further arguments passed to or from other methods
mov.model	formula object specifying the time indexed covariates for movement parameters.
err.model	A 2-element list of formula objects specifying the time indexed covariates for location error parameters.
activity	formula object giving the covariate for the activity (i.e., stopped or fully moving) portion of the model.
drift	logical indicating whether or not to include a random drift component. For most data this is usually not necessary. See northernFurSeal for an example using a drift model.
coord	A 2-vector of character values giving the names of the "X" and "Y" coordinates in data. Ignored if data inherits class 'sf' or 'sp'.
proj	A valid epsg integer code or proj4string for data that does not inherit either 'sf' or 'sp'. A valid 'crs' list is also accepted. Otherwise, ignored.
Time.name	character indicating name of the location time column. It is strongly preferred that this column be of type POSIXct and in UTC.
time.scale	character. Scale for conversion of POSIX time to numeric for modeling. Defaults to "hours" and most users will not need to change this.
theta	starting values for parameter optimization.
fixPar	Values of parameters which are held fixed to the given value.
method	Optimization method that is passed to optim.
control	Control list which is passed to optim.
constr	Named list with elements lower and upper that are vectors the same length as theta giving the box constraints for the parameters
prior	A function returning the log-density function of the parameter prior distribution. THIS MUST BE A FUNCTION OF ONLY THE FREE PARAMETERS. Any fixed parameters should not be included.
need.hess	A logical value which decides whether or not to evaluate the Hessian for parameter standard errors
initialSANN	Control list for optim when simulated annealing is used for obtaining start values. See details
attempts	The number of times likelihood optimization will be attempted in cases where the fit does not converge or is otherwise non-valid
retrySD	optional user-provided standard deviation for adjusting starting values when attempts > 1. Default value is 1.
skip_check	Skip the likelihood optimization check and return the fitted values. Can be useful for debugging problem fits.

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:

par	Parameter maximum likelihood estimates (including fixed parameters)
estPar	MLE without fixed parameters
se	Standard error of MLE
ci	95% confidence intervals for parameters
Cmat	Parameter covariance matrix
loglik	Maximized log-likelihood value
aic	Model AIC value
coord	Coordinate names provided for fitting
fixPar	Fixed parameter values provided
convergence	Indicator of convergence (0 = converged)
message	Messages given by optim during parameter optimization
activity	Model provided for stopping variable
drift	Logical value indicating random drift model
mov.model	Model description for movement component
err.model	Model description for location error component
n.par	number of parameters
nms	parameter names
n.mov	number of movement parameters
n.errX	number or location error parameters for “longitude” error model
n.errY	number or location error parameters for “latitude” error model
stop.mf	covariate for stop indication in stopping models
polar.coord	Logical indicating coordinates are polar latitude and longitude
init	Initial values for parameter optimization
data	Original data.frame used to fit the model
lower	The lower parameter bounds
upper	The upper parameter bounds
need.hess	Logical value
runTime	Time used to fit model

Author(s)

Devin S. Johnson, Josh M. London

NMML/crawl documentation built on Oct. 9, 2024, 11:56 a.m.