Description Usage Arguments Details Value Note Author(s) References See Also Examples

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

1 2 3 4 5 6 7 8 | ```
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=0.99,IC="AICc",MSPE="position",trace=FALSE,...)
``` |

`tau` |
Array of autocorrelation timescales (explained below). |

`omega` |
Frequency (2π/period) of oscillatory range crossings. |

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

`error` |
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 |

`axes` |
Spatial dimensions of the movement model. |

`data` |
Timeseries data represented as a |

`CTMM` |
A |

`REML` |
Use residual maximum likelihood if |

`profile` |
Analytically solve for as many covariance parameters as possible. |

`zero` |
Calculates |

`verbose` |
Return additional information. See "Value" below. |

`method` |
Fitting method to use: |

`COV` |
Estimate the autocorrelation parameter covariance matrix. |

`control` |
An optional argument list with standardized numerical arguments. |

`trace` |
Report progress updates. Can be among |

`level` |
Attempt to simplify a model if a feature's non-existence falls within this level of confidence interval. |

`IC` |
Information criteria used for selection. Can be |

`MSPE` |
Reject non-stationary features that increase the mean square predictive error of |

`...` |
Further arguments passed to |

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`

(τ) 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 (2018). 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/2`

Fraction 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.max`

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

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`

.

`AICc`

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

`loglike`

The log-likelihood.

`sigma`

The maximum likelihood variance/covariance estimate (possibly debiased). For the endlessly diffusing BM and IOU processes, this is instead the diffusion rate estimate.

`mu`

The maximum likelihood stationary mean vector estimate.

`COV.mu`

The covariance matrix of the

`mu`

estimate, assuming that the covariance estimate is correct.`DOF.mu`

The 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.`COV`

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

Fitting without telemetry errors involves fewer parameters and is much faster than fitting with telemetry errors, as the variance/covariance can be profiled analytically without numerical optimization.
Therefore, fitting without telemetry errors, if possible, can provide improved initial estimates of `tau`

and `sigma`

for later fitting with telemetry errors.

The default `optim`

method here is `"Nelder-Mead"`

with the largest allowable number of maximum iterations. Annecdotally, the faster `"BFGS"`

and `"L-BFGS-B"`

methods often perform poorly on these types of problems.
However, Nelder Mead is not ideal and you may want to attempt a second fit, using the first fit as its initial guess.

The AICs/BICs of endlessly diffusing models like BM and IOU cannot be easily compared to the AICs/BICs of range resident models like bivariate Gaussian, OU, and OUF, as their joint likelihood functions are infinitely different. Endlessly diffusing models have to be conditioned off of an initial state, which we derive in `ctmm`

by taking the large range limit of a range-restricted process. I.e., BM is the limit OU(`Inf`

) and IOU(`tau`

) is the limit OUF(`Inf`

,`tau`

). Using comparable likelihood functions gives up statistical efficiency and the objective prior. Moreover, comparing conditional likelihoods—with the objective prior taken from the joint likelihood—does not appear to select the true model with a likelihood ratio test. Therefore, there does not appear to be a simple approach for selecting between range resident and endlessly diffusing movement models.

Prior to v0.3.6, the univariate AICc formula was (mis)used, with the full parameter count treated as degrees of freedom in the mean. As of v.0.3.6, the mean and autocovariance parameters are treated separately in the approximate multivariate AICc formula (Burnham & Anderson, Eq. 7.91). Still, this improved formula is only exact for IID data.

Prior to v0.3.2, `ctmm.select`

would consider every possible model.
This is no longer feasible with current versions of `ctmm`

, as the number of possible models has grown too large.

C. H. Fleming and G. Péron.

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álmán filters for continuous-time movement models. Ecological Informatics, 40, 8-21 (2017).

`ctmm.boot`

, `ctmm.guess`

, `optim`

, `summary.ctmm`

, `variogram.fit`

.

1 2 3 4 5 6 7 8 9 10 | ```
# 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)
``` |

ctmm-initiative/ctmm documentation built on Nov. 4, 2018, 2:55 a.m.

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.