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 fit continuous-time movement models to 2D animal tracking data as described in Fleming et al (2014) and Fleming et al (2015), and Fleming et al (2017).
ctmm(tau=NULL,omega=FALSE,isotropic=FALSE,range=TRUE,circle=FALSE,error=FALSE,
axes=c("x","y"),...)ctmm.loglike(data,CTMM,REML=FALSE,profile=TRUE,zero=0,verbose=FALSE)
ctmm.fit(data,CTMM=ctmm(),method="ML",COV=TRUE,control=list(),trace=FALSE)
ctmm.select(data,CTMM,verbose=FALSE,level=1,IC="AICc",MSPE="position",trace=FALSE,...)
Array of autocorrelation timescales (explained below).
Frequency (\(2\pi/period\)) of oscillatory range crossings.
A Boolean denoting whether or not the animal's covariance is circular or elliptical.
A Boolean denoting whether or not the movement model has a finite range.
The period it takes the animal to stochastically circle its mean location.
A Boolean denoting whether or not to use annotated telemetry error estimates or an estimate of the error's standard deviation if the data are not annotated with error estimates or when \(HDOP=1\).
Spatial dimensions of the movement model.
Timeseries data represented as a telemetry object.
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.
Use residual maximum likelihood if TRUE. Not recommended.
Analytically solve for as many covariance parameters as possible.
Calculates \(log(likelihood) - zero\), instead of just \(log(likelihood)\), in a way that maintains numerical precision if the constant zero is close to the log likelihood. Used internally by ctmm.fit.
Return additional information. See "Value" below.
Fitting method to use: "ML", "HREML", "pREML", "pHREML", or "REML". See "Description" below.
Estimate the autocorrelation parameter covariance matrix.
An optional argument list with standardized numerical arguments.
Report progress updates. Can be among 0:2 with increasing detail.
Attempt to simplify a model if a feature's non-existence falls within this level of confidence interval.
Information criteria used for selection. Can be "AICc", "AIC", "BIC" or none (NA). AICc is approximate.
Reject non-stationary features that increase the mean square predictive error of "position", "velocity", or not (NA).
Further arguments passed to ctmm.fit.
The function ctmm returns a prototype ctmm movement-model object.
By default, ctmm.loglike returns the log-likelihood of the model CTMM.
ctmm.fit (and ctmm.loglike with verbose=TRUE) returns the maximum likelihood ctmm movement-model object with all of the components of CTMM plus the components listed below.
ctmm.select returns the best model by default or the complete list of attempted models if verbose=TRUE.
AICcThe approximate corrected Akaike information criterion for multivariate distributions with variable numbers of unknown mean and (structured) covariance parameters (Burnham & Anderson, Eq. 7.91). This formula is only exact for IID data.
loglikeThe log-likelihood.
sigmaThe maximum likelihood variance/covariance estimate (possibly debiased). For the endlessly diffusing BM and IOU processes, this is instead the diffusion rate estimate.
muThe maximum likelihood stationary mean vector estimate.
COV.muThe covariance matrix of the mu estimate, assuming that the covariance estimate is correct.
DOF.muThe effective number of degrees of freedom in the estimate of mu, assuming that the autocorrelation model is correct. This can be much smaller than length(data$t) if the data are autocorrelated.
COVCovariance of the autocovariance parameter estimate vector c(sigma,tau,circle), as derived (asymptotically) from the hessian of the log-likelihood function, and where sigma is parameterized in terms of its standard area, eccentricity, and angle of orientation. Typically, sigma's area parameter is extremely correlated to tau[1], and sequential components of tau are slightly correlated.
Model fitting and selection first requires a prototype model with guesstimated parameters (i.e., Brownian motion with a particular diffusion rate).
The initial ctmm parameter guess can be generated by the output of ctmm.guess, variogram.fit or manually specified with the function ctmm(...), where the argument tau is explained below and additonal model options described in vignette("ctmm").
By default, tau (\(\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.
The potential fitting methods---maximum likelihood (ML), residual maximum likelihood (REML), perturbative REML (pREML), hybrid REML (HREML), and perturbative hybrid REML (pHREML)---are described in Fleming et al (2019). In general, pHREML is the best method, though when parameter estimates lie near boundaries it can fail, in which case ctmm.fit will fall back to HREML, as reported by the method slot of the resulting fit object.
The control list can take the folowing arguments, with defaults shown:
method="Nelder-Mead"optim method for multiple parameters.
precision=1/2Fraction of machine numerical precision to target in the maximized likelihood value. MLEs will necessarily have half this precision. On most computers, precision=1 is approximately 16 decimal digits of precision for the likelihood and 8 for the MLEs.
maxit=.Machine$integer.maxMaximum number of iterations allowed for optimization.
Model selection in ctmm.select proceeds by first fitting the initial model guess, and then attempting to simplify the autocorrelation model and complexify the deterministic (mean) model until the information criteria fails to improve. The intent of working in these directions is to avoid fitting trends to autocorrelation.
Note that simpler models in a nested hierarchy will only be attempted if they appear credible, which can be adjusted with the level argument. level=1 will, therefore, always attempt a simpler model.
K. P. Burnham, D. R. Anderson. Model Selection and Multimodel Inference: A Practical Information-Theoretic Approach. Springer, 2nd edition (2003).
C. H. Fleming, J. M. Calabrese, T. Mueller, K.A. Olson, P. Leimgruber, W. F. Fagan. From fine-scale foraging to home ranges: A semi-variance approach to identifying movement modes across spatiotemporal scales. The American Naturalist, 183:5, E154-E167 (2014).
C. H. Fleming, Y. Subasi, J. M. Calabrese. A maximum-entropy description of animal movement. Physical Review E, 91, 032107 (2015).
C. H. Fleming, D. Sheldon, E. Gurarie, W. F. Fagan, S. LaPoint, J. M. Calabrese. K<U+00E1>lm<U+00E1>n filters for continuous-time movement models. Ecological Informatics, 40, 8-21 (2017).
# NOT RUN {
# Load package and data
library(ctmm)
data(buffalo)
Cilla <- buffalo$Cilla
GUESS <- ctmm.guess(Cilla,interactive=FALSE)
FIT <- ctmm.fit(Cilla,GUESS)
# some human-readable information
summary(FIT)
# }
Run the code above in your browser using DataLab