Learn R Programming
crawl (version 1.5)

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

Description

The function uses the Kalman filter to estimate movement paramters 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(mov.model = ~1, err.model = NULL, stop.model = NULL,
  drift.model = FALSE, data, coord = c("x", "y"), polar.coord, Time.name,
  initial.state, theta, fixPar, method = "L-BFGS-B", control = NULL,
  constr = list(lower = -Inf, upper = Inf), prior = NULL,
  need.hess = TRUE, initialSANN = NULL, attempts = 1)

Arguments

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.
stop.model
formula object giving the covariate for the stopping portion of the model.
drift.model
logical indicating whether or not to include a random drift component.
data
data.frame object containg telemetry and covariate data. A 'SpatialPointsDataFrame' object from the package 'sp' or an 'STIDF' from the package 'spacetime' will also be accepted. In which case the polar.coord and coord (and
coord
A 2-vector of character values giving the names of the "X" and "Y" coordinates in data.
polar.coord
logical indicating location are in degrees latitude and longitude.
Time.name
character indicating name of the location time column
initial.state
list object containg the inital state of the Kalman filter.
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 specification
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

Value

  • A list with the following elements:
  • parParameter maximum likelihood estimates (including fixed parameters)
  • estParMLE without fixed parameters
  • seStandard error of MLE
  • ci95% confidance intervals for parameters
  • CmatParameter covariance matrix
  • loglikMaximized log-likelihood value
  • aicModel AIC value
  • initial.stateIntial state provided to crwMLE for model fitting
  • coordCoordinate names provided for fitting
  • fixParFixed parameter values provided
  • convergenceIndicator of convergence (0 = converged)
  • messageMeesages given by optim during parameter optimization
  • stop.modelModel provided for stopping variable
  • random.driftLogical value indicating random drift model
  • mov.modelModel description for movement component
  • err.modelModel description for location error component
  • n.parnumber of parameters
  • nmsparameter names
  • n.movnumber of movement parameters
  • n.errXnumber or location error parameters for "longitude" error model
  • n.errYnumber or location error parameters for "latitude" error model
  • stop.mfcovariate for stop indication in stopping models
  • polar.coordLogical indicating coordinates are polar latitude and longitude
  • initInitial values for parameter optimization
  • dataOriginal data.frame used to fit the model
  • lowerThe lower parameter bounds
  • upperThe upper parameter bounds
  • need.hessLogical value
  • runTimeTime used to fit model

Details

A full model specification involves 4 components: a movement model, a stopping 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 longitude and one for 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. If polar.coord=TRUE then the ad-hoc logitude correction factor described by Johnson et al. (2008) (Ecology 89:1208-1215) is used to adjust the variance scale for the longitude mdoel.

The inital.state is a list with the following elemets (with the exact names):

a1.y A vector with initial state values for the latitude coordinate. It have 2 elemets (location at time 1, velocity at time 1) for non-drift models and 3 elemets for drift models (location at time 1, velocity at time 1, drift velocity at time 1) for driftmodels,

P1.y Covarince matrix for the state at time 1 (measure of uncertainty for your inital state) a1.y,

a1.x Same as a1.y, but in the longitude coordinate,

P1.x Same as P1.y, but in the longitude coordinate.

theta and fixPar are vectors with the appropriate number or parameters. theta contains only those paraemters 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. If a POSIXct column is used it is internally converted to a numeric vector with units of hours. The spacetime package supports an STIDF object that contains slots for both spatial and time series data types. If data is of class STIDF then the spatial and temporal information are automatically extracted and polar.coord, Time.name and coord are not required. If your data are not compatible with these data structures, it is better to convert it yourself prior to analysis with crawl. Also, for stopping models, the stopping covariate must be between 0 and 1 inclusive, with 1 representing complete stop of the animal (no true movement, however, location error can still occur) and 0 represent unhindered movement. The coordinate location should have NA where no location is recorded, but there is a change in the movment 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 optimaization 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.