crawlWrap: Fit and predict tracks for using crawl

In bmcclintock/momentuHMM: Maximum Likelihood Analysis of Animal Movement Behavior Using Multivariate Hidden Markov Models

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 = 1,
  retryFits = 0,
  retrySD = 1,
  retryParallel = FALSE,
  mov.model = ~1,
  err.model = NULL,
  activity = NULL,
  drift = NULL,
  coord = c("x", "y"),
  proj = NULL,
  Time.name = "time",
  time.scale = "hours",
  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,
  coordLevel = NULL,
  ...
)

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 or sf object 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. Default: 1 (no parallel processing).
retryFits	Number of times to attempt to achieve convergence and valid (i.e., not NaN) variance estimates after the initial model fit.
retrySD	An optional list of scalars or vectors for each individual indicating the standard deviation to use for normal perturbations of theta when retryFits>0 (or attempts>1). Instead of a list object, retrySD can also be a scalar or a vector, in which case the same values are used for each each individual. If a scalar is provided, then the same value is used for each parameter. If a vector is provided, it must be of length length(theta) for the corresponding individual(s). Default: 1, i.e., a standard deviation of 1 is used for all parameters of all individuals. Ignored unless retryFits>0 (or attempts>1).
retryParallel	Logical indicating whether or not to perform retryFits attempts for each individual in parallel. Default: FALSE. Ignored unless retryFits>0 and ncores>1. Note that when attempts are done in parallel (i.e. retryParallel=TRUE), the current value for the log-likelihood of each individual and warnings about convergence are not printed to the console.
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.
proj	A list of valid epsg integer codes or proj4string for obsData that does not inherit either 'sf' or 'sp'. A valid 'crs' list is also accepted. Otherwise, ignored. If only one proj is provided, then the same projection is used for each individual.
Time.name	Character indicating name of the location time column. See crwMLE.
time.scale	character. Scale for conversion of POSIX time to numeric for modeling. Defaults to "hours".
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. If theta is not specified, then crwMLE default values are used (i.e. each parameter is started at zero).
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. If fixPar is not specified, then no parameters are fixed.
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 in cases where the fit does not converge or is otherwise non-valid. Note this is not the same as retryFits because attempts only applies when the current fit clearly does not appear to have converged; retryFits will proceed with additional model fitting attempts regardless of the model output.
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.
coordLevel	Character string indicating the level of the hierarchy for the location data. Ignored unless obsData includes a 'level' field.
...	Additional arguments that are ignored.

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, 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.

Value

A crwData or crwHierData 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.

See Also

MIfitHMM, simData

Examples

## Not run: 
# extract simulated obsData from example data
obsData <- miExample$obsData

# error ellipse model
err.model <- list(x= ~ ln.sd.x - 1, y =  ~ ln.sd.y - 1, rho =  ~ error.corr)

# Fit crwMLE models to obsData and predict locations 
# at default intervals for both individuals
crwOut1 <- crawlWrap(obsData=obsData,
         theta=c(4,0),fixPar=c(1,1,NA,NA),
         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,
         theta=list(c(4,0),c(4,0)), fixPar=list(c(1,1,NA,NA),c(1,1,NA,NA)),
         err.model=list(err.model,err.model),
         predTime=list('1'=seq(1,633),'2'=seq(1,686)))

## End(Not run)

bmcclintock/momentuHMM documentation built on Oct. 26, 2022, 1 a.m.