ctmm (version 0.3.1)

ctmm: Specify, fit, and select continuous-time movement models

Description

These functions allow one to propose hypothethical movement models (with initial estimates), fit those models to the data, and select among those models via an information criteria. The fitting functions wrap around optim and ctmm.loglike to maximize the likelihood function of continuous-time movement models described in Fleming et al (2014) and Fleming et al (2015), given 2D animal tracking data.

Usage

ctmm(tau=NULL,isotropic=FALSE,range=TRUE,circle=FALSE,CPF=FALSE,error=FALSE,...)

ctmm.fit(data,CTMM=ctmm(),debias=TRUE,control=list(maxit=.Machine$integer.max),...)

ctmm.select(data,CTMM,verbose=FALSE,IC="AICc",...)

Arguments

tau

Array of autocorrelation timescales explained below.

isotropic

A Boolean denoting whether or not the animal's covariance is circular or elliptical.

range

A Boolean denoting whether or not the movement model has a finite range.

circle

The period it takes the animal to stochastically circle its mean location.

CPF

A Boolean denoting whether to consider an oscillatory CPF model.

error

A Boolean denoting whether or not to use annotated telemetry error estimates or an estimate of the error's variance if the data are not annotated with error estimates.

data

The 2D timeseries data represented as a telemetry object.

CTMM

A ctmm movement-model object containing the initial parameter guesses conforming to the basic structure of the model hypothesis. ctmm.select can accept a list of such objects.

debias

A Boolean denoting whether or not to remove the lowest-order bias from the covariance sigma estimate.

control

An optional argument to be passed to optim, but with parscale overwritten with reasonable defaults.

...

Further arguments passed to optim.

verbose

Return every fit candidate model if TRUE, else return only the selected model.

IC

Information criteria used. Only "AICc" is currently supported.

Value

• ctmm.fit returns the maximum likelihood ctmm movement-model object with all of the components of CTMM plust the following: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

encoding

UTF-8

Details

The initial ctmm parameter guess can be the output of ctmm.guess, variogram.fit or the function ctmm(...) with the argument tau explained below and additonal model options described in vignette("ctmm"). By default, tau is an ordered array of autocorrelation timescales. If length(tau)==0, then an IID bi-variate Gaussian model is fit to the data. If length(tau)==1, then an Ornstein-Uhlenbeck (OU) model (Brownian motion restricted to a finite home range) is fit the data, where tau is the position autocorrelation timescale. tau=Inf then yields Brownian motion (BM). If length(tau)==2, then the OUF model (continuous-velocity motion restricted to a finite home range) is fit to the data, where tau[1] is again the position autocorrelation timescale and tau[2] is the velocity autocorrelation timescale. tau[1]=Inf then yields integrated Ornstein-Uhlenbeck (IOU) motion, which is a spatially unrestricted continuous-velocity process. If CPF=TRUE, then an oscillatory central place foraging model is assumed. In this case tau must be an length-2 array containaing the foraging period in tau[1] (e.g., 1 day 24*60^2 seconds) and the characteristic timescale overwhich similarity between foraging excursions persists in tau[2]. debias=TRUE causes the maximum likelihood estimate (MLE) of the covariance sigma to be corrected by a prefactor of n/(n-k), where n is the number of data points and k is the number of mean parameters. If error=FALSE and other autocorrelation parameters such as tau are exact, then this correction is exact. If error=FALSE and and the other autocorrelation parameters are simply their MLE values, then this correction removes the lowest-order bias in sigma. If error=TRUE, then this is an undercorrection that is better than doing nothing. Residual maximum likelihood estimation (REML) could be more exact for error=TRUE, buth there is a potential tradeoff between bias and variablity.

References

C. H. Fleming, J. M. Calabrese, T. Mueller, K.A. Olson, P. Leimgruber, and W. F. Fagan. (2014). From fine-scale foraging to home ranges: A semi-variance approach to identifying movement modes across spatiotemporal scales. http://www.jstor.org/discover/10.1086/675504{The American Naturalist, 183(5), E154-E167.} C. H. Fleming and Y. Subasi and J. M. Calabrese. (2015). A maximum-entropy description of animal movement. http://journals.aps.org/pre/abstract/10.1103/PhysRevE.91.032107{Physical Review E, 91, 032107.}

See Also

ctmm.loglike, ctmm.guess, optim, summary.ctmm, variogram.fit.

Examples

# Load package and data
library(ctmm)
data(buffalo)
cilla <- buffalo[[1]]

# Fit a continuous-velocity model with tau ~ c(10 days,1 hour)
# also see help(variogram.fit)
GUESS <- ctmm(tau=c(10*24*60^2,60^2))
FIT <- ctmm.fit(cilla,GUESS)

# some human-readable information
summary(FIT)