Maximum Likelihood Analysis of Animal Movement Behavior Using Multivariate Hidden Markov Models

Extended tools for analyzing telemetry data using generalized hidden Markov models. Features of momentuHMM (pronounced ``momentum'') include data pre-processing and visualization, fitting HMMs to location and auxiliary biotelemetry or environmental data, biased and correlated random walk movement models, hierarchical HMMs, multiple imputation for incorporating location measurement error and missing data, user-specified design matrices and constraints for covariate modelling of parameters, random effects, decoding of the state process, visualization of fitted models, model checking and selection, and simulation. See McClintock and Michelot (2018) .

R package for Maximum likelihood analysis Of animal MovemENT behavior Using multivariate Hidden Markov Models

Get started with the vignette: Guide to using momentuHMM

Installation instructions

CRAN release

The package is available at . To install it:

install.packages("momentuHMM")

Install from Github

To install the latest (stable) version of the package from Github:

library(devtools)
install_github("bmcclintock/momentuHMM")

To install the latest (unstable) version of the package from Github:

library(devtools)
install_github("bmcclintock/momentuHMM", ref="develop")

References

McClintock, B.T., Michelot, T. (2018) momentuHMM: R package for generalized hidden Markov models of animal movement. Methods in Ecology and Evolution, 9(6), 1518-1530.

McClintock, B.T., King R., Thomas L., Matthiopoulos J., McConnell B.J., Morales J.M. (2012) A general discrete-time modeling framework for animal movement using multistate random walks. Ecological Monographs, 82(3), 335-349.

McClintock, B.T. (2017) Incorporating telemetry error into hidden Markov models of animal movement using multiple imputation. Journal of Agricultural, Biological, and Environmental Statistics, 22(3), 249-269.

News

momentuHMM 1.4.3 2018-11-21

NEW FEATURES

betaCons argument added to fitHMM and MIfitHMM for specifying equality constraints on transition probability matrix parameters
betaRef argument added to fitHMM and MIfitHMM for specifying the reference states for t.p.m. multinomial logit link
retryParallel argument added to crawlWrap

CHANGES

updated for compatibility with crawl (>= 2.2.1); notable changes include removal of the initial.state argument and addition of the time.scale argument in crawlWrap.
changed how fixPar and betaCons are handled when optimizing the likelihood; this should make optimization faster and more stable when these parameter constraints are used
formulaDelta=NULL now default in fitHMM, MIfitHMM, and simData
%dorng% now used instead of %dopar%, thereby allowing for reproducible foreach loops when using parallel processing
cleaned up crawlWrap printing when retryFits>0 and retryParallel=FALSE
retrySD argument in fitHMM and MIfitHMM can now be a scalar
bug fix in calculation of standard errors (and confidence intervals) for transition probability and initial distribution parameters when workBounds$beta or workBounds$delta are specified other than the default (-Inf,Inf)
bug fix in calculation of number of parameters in getAIC when formulaDelta=NULL and initial distribution is fixed using fixPar$delta
bug fix in MIpool when estimated standard errors are not finite for some imputations

momentuHMM 1.4.2 2018-06-19

NEW FEATURES

Northern fulmar example of Pirotta et al (2018) added to vignette
retrySD argument added to crawlWrap for additional flexibility when exploring the likelihood surface using retryFits
shape argument added to plotSat and plotSpatialCov functions
projargs argument added to plotSat function (for handling projected data coordinates)
stateNames argument added to plotSpatialCov function
data argument of plotSat function can now be a data frame, momentuHMMData, momentuHMM, miHMM, or miSum object
data argument of plotSpatialCov function can now be a data frame, momentuHMMData, momentuHMM, miHMM, or miSum object

CHANGES

'angleStrength' special function name changed to 'angleFormula'
strength argument in 'angleFormula' special function is now optional
when theta and/or fixPar arguments are missing in crawlWrap, crawl::crwMLE default values are now used
bug fix in crawlWrap when retryFits>0 and control argument is NULL. This bug caused additional model fitting attempts to fail
modified B-spline examples in fitHMM and simData to accommodate bug fixes in splines2 (>= 0.2.8)

momentuHMM 1.4.1 2018-05-21

NEW FEATURES

special function 'toState' can now be used in formula argument for modelling transitions to specific states
timeInStates function added for calculating activity budgets
modelName argument added to fitHMM and MIfitHMM
added setModelName and setStateNames functions
added stationary and plotStationary functions for calculating and visualizing stationary state probabilities as a function of covariates
plotStationary argument added to plot.momentuHMM, plot.miHMM, and plot.miSum
added summary.momentuHMMData function

CHANGES

bug fix when a pseudo-design matrix formula includes interactions with >1 factor variable
check and print package version upon loading
unit tests no longer included in CRAN build because they were taking too long
updated citation info

momentuHMM 1.4.0 2018-02-27

NEW FEATURES

von Mises consensus distribution of Rivest et al. (2016) can now be specified for angular data streams
angleStrength function can now be used in circular-circular regression models. This allows each angular covariate (e.g. wind direction) to be weighted by an additional positive real covariate (e.g. wind speed) as in Rivest et al. (2016).
checkPar0 function added to aid users with initial parameter (e.g. Par0, beta0, delta0) specification
centroids argument added to MIfitHMM
useInitial argument added to MIfitHMM for using parameter estimates of first model fit as initial values for all subsequent model fits
retrySD argument added to fitHMM and MIfitHMM for specifying standard deviation of random normal perturbations when using retryFits
alternative optimization methods (Nelder-Mead'' andSANN'') can now be specified in fitHMM and MIfitHMM using the optMethod and control arguments
prior argument added to fitHMM and MIfitHMM for specifying prior distributions on working parameters
AICweights function added for calculating AIC weights across a set of candidate models
sample size (n) argument added to AIC.momentuHMM for calculating small sample corrected AIC (i.e. AICc)
crawlPlot argument added to plot.crwData as a wrapper for crawl::crwPredictPlot
various graphical parameters added to plot.momentuHMM for plot customization

CHANGES

For multiple imputation analyses, pseudoRes (and plotPR) can now calculate (and plot) pseudo-residuals individually for each model fit
cons and workcons arguments are now deprecated; please use workBounds instead
verbose argument in fitHMM and MIfitHMM is now deprecated; please use nlmPar instead

momentuHMM 1.3.0 2017-12-06

NEW FEATURES

Dynamic activity centers (i.e., those with coordinates that can change over time) can now be handled via the centroids argument in prepData and simData. An example based on the group dynamic model of Langrock et al. (2014) has been added to the vignette.
initialPosition argument in simData can now be specified as a list indicating the initial position for each individual

CHANGES

multinomial logit link now used on zeroInflation and oneInflation parameters
bug fix in calculation of pseudo-residuals (pseudoRes) with zeroInflation and/or oneInflation
bug fix in CIreal when natural scale delta estimates are near boundary
bug fix in crawlWrap when predTime is of length one
bug fix in MIpool when initial distribution includes covariates
splines and splines2 package dependencies changed to Suggests in DESCRIPTION file

momentuHMM 1.2.0 2017-10-19

NEW FEATURES

Regression formulas can now be specified for the initial distributions of HMMs using the formulaDelta argument in fitHMM, MIfitHMM, and simData. These changes are backwards compatible with previous versions, but note that the number and order of arguments has been changed in fitHMM, MIfitHMM, and simData.

CHANGES

If step length is zero at time t or t+1, simData and prepData now return NA for turning angle at time step t
bug fix in pseudoRes such that pseudo-residuals now "reset" for each individual
bug fix in fitHMM when using fixPar to fix initial distribution (delta)
bug fix in fitHMM when nbStates=1 and circularAngleMean=TRUE
bug fix in fitHMM when nbStates=1 and retryFits>0

momentuHMM 1.1.1 2017-09-19

NEW FEATURES

Normal (Gaussian) and Bernoulli distributions can now be specified for data streams
Harbour seal example of McClintock et al (2013) added to vignette

Changes

added pseudoRes continuity adjustment for discrete distributions

momentuHMM 1.1.0 2017-08-15

NEW FEATURES

fixPar argument in fitHMM and MIfitHMM now specified on the same scale as the initial parameters (Par0, beta0, and delta0 arguments)
Factor-level covariates (e.g. 'sexM', `sexF') can now be included in pseudo design matrix DM arguments of fitHMM, MIfitHMM, and simData
obsPerAnimal argument in simData can now be specified as a list indicating the number of observations for each individual

CHANGES

vignette now built using knitr
bug fix in crawlWrap when predTimes argument includes times that are before the time of first observation
bug fix in plot.miSum calculation of natural scale parameters when cons and/or workcons MIfitHMM arguments are used

momentuHMM 1.0.1 2017-07-17

NEW FEATURES

Elephant seal example of Michelot et al (2017) added to vignette

CHANGES

turning angles for lat/long coordinates (type='LL') now calculated based on initial bearings using geosphere::bearing in turnAngle
bug fix when calculating activity center distances from lat/long coordinates (type='LL') in distAngle
bug fix in prepData when successive pairs of coordinates are NA