crawlWrap: Fit and predict tracks for using crawl

Description

Wrapper function for fitting crawl::crwMLE models and predicting locations with crawl::crwPredict for multiple individuals.

Usage

crawlWrap(obsData, timeStep = 1, ncores, retryFits = 0, mov.model = ~1,
  err.model = NULL, activity = NULL, drift = NULL, coord = c("x", "y"),
  Time.name = "time", initial.state, theta, fixPar, method = "L-BFGS-B",
  control = NULL, constr = NULL, prior = NULL, need.hess = TRUE,
  initialSANN = list(maxit = 200), attempts = 1, predTime = NULL,
  fillCols = FALSE)

Arguments

obsData

data.frame object containing fields for animal ID ('ID'), time of observation (identified by Time.name, must be numeric or POSIXct), and observed locations (x- and y- coordinates identified by coord), such as that returned by simData when temporally-irregular observed locations or measurement error are included. Alternatively, a 'SpatialPointsDataFrame' object from the package 'sp' will also be accepted, in which case the coord values will be taken from the spatial data set and ignored in the arguments. Note that crwMLE requires that longitude/latitude coordinates be projected to UTM (i.e., easting/northing). For further details see crwMLE.

timeStep

Length of the time step at which to predict regular locations from the fitted model. Unless predTime is specified, the sequence of times is seq(a_i,b_i,timeStep) where a_i and b_i are the times of the first and last observations for individual i. timeStep can be numeric (regardless of whether obsData[[Time.name]] is numeric or POSIXct) or a character string (if obsData[[Time.name]] is of class POSIXct) containing one of "sec", "min", "hour", "day", "DSTday", "week", "month", "quarter" or "year". This can optionally be preceded by a positive integer and a space, or followed by "s" (e.g., ``2 hours''; see seq.POSIXt). timeStep is not used for individuals for which predTime is specified.

ncores

Number of cores to use for parallel processing.

retryFits

Number of times to attempt to achieve convergence and valid (i.e., not NaN) variance estimates after the initial model fit. retryFits differs from attempts because retryFits iteratively uses random perturbations of the current parameter estimates as the initial values for likelihood optimization, while attempts uses the same initial values (theta) for each attempt.

mov.model

List of mov.model objects (see crwMLE) containing an element for each individual. If only one movement model is provided, then the same movement model is used for each individual.

err.model

List of err.model objects (see crwMLE) containing an element for each individual. If only one error model is provided, then the same error model is used for each individual (in which case the names of the err.model components corresponding to easting/longitudinal and northing/latitudinal location error must match coord).

activity

List of activity objects (see crwMLE) containing an element for each individual. If only one activity covariate is provided, then the same activity covariate is used for each individual.

drift

List of drift objects (see crwMLE) containing an element for each individual. If only one drift component is provided, then the same drift component is used for each individual.

coord

A 2-vector of character values giving the names of the "x" and "y" coordinates in data. See crwMLE.

Time.name

Character indicating name of the location time column. See crwMLE.

initial.state

List of initial.state objects (see crwMLE) containing an element for each individual. If only one initial state is provided, then the same initial states are used for each individual.

theta

List of theta objects (see crwMLE) containing an element for each individual. If only one theta is provided, then the same starting values are used for each individual.

fixPar

List of fixPar objects (see crwMLE) containing an element for each individual. If only one fixPar is provided, then the same parameters are held fixed to the given value for each individual.

method

Optimization method that is passed to optim.

control

Control list which is passed to optim.

constr

List of constr objects (see crwMLE) containing an element for each individual. If only one constr is provided, then the same box constraints for the parameters are used for each individual.

prior

List of prior objects (see crwMLE) containing an element for each individual. If only one prior is provided, then the same prior is used for each individual.

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 using theta as the starting values. Note this is not the same as retryFits.

predTime

List of predTime objects (see crwPredict) containing an element for each individual. predTime can be specified as an alternative to the automatic sequences generated according to timeStep. If only one predTime object is provided, then the same prediction times are used for each individual.

fillCols

Logical indicating whether or not to use the crawl::fillCols function for filling in missing values in obsData for which there is a single unique value. Default: FALSE. If the output from crawlWrap is intended for analyses using fitHMM or MIfitHMM, setting fillCols=TRUE should typically be avoided.

Value

A crwData object, i.e. a list of:

crwFits

A list of crwFit objects returned by crawl::crwMLE. See crwMLE

crwPredict

A crwPredict data frame with obsData merged with the predicted locations. See crwPredict.

The crwData object is used in MIfitHMM analyses that account for temporal irregularity or location measurement error.

Details

Consult crwMLE and crwPredict for futher details about model fitting and prediction.
Note that the names of the list elements corresponding to each individual in mov.model, err.model, activity, drift, initial.state, theta, fixPar, constr, prior, and predTime must match the individual IDs in obsData. If only one element is provided for any of these arguments, then the same element will be applied to all individuals.

Examples

Run this code

# NOT RUN {
# extract simulated obsData from example data
obsData <- miExample$obsData

# extract crwMLE inputs from example data
inits <- miExample$inits # initial state
err.model <- miExample$err.model # error ellipse model

# Fit crwMLE models to obsData and predict locations 
# at default intervals for both individuals
crwOut1 <- crawlWrap(obsData=obsData,ncores=1,
         theta=c(4,0),fixPar=c(1,1,NA,NA),
         initial.state=inits,
         err.model=err.model,attempts=100)

# Fit the same crwMLE models and predict locations 
# at same intervals but specify for each individual using lists
crwOut2 <- crawlWrap(obsData=obsData,ncores=1,
         theta=list(c(4,0),c(4,0)), fixPar=list(c(1,1,NA,NA),c(1,1,NA,NA)),
         initial.state=list(inits,inits),
         err.model=list(err.model,err.model),
         predTime=list('1'=seq(1,633),'2'=seq(1,686)))
# }
# NOT RUN {
# }