fitHMM {moveHMM}

Fit an HMM to the data

Description

Fit an hidden Markov model to the data provided, using numerical optimization of the log-likelihood function.

Usage

fitHMM(
  data,
  nbStates,
  stepPar0,
  anglePar0 = NULL,
  beta0 = NULL,
  delta0 = NULL,
  formula = ~1,
  stepDist = c("gamma", "weibull", "lnorm", "exp"),
  angleDist = c("vm", "wrpcauchy", "none"),
  angleMean = NULL,
  stationary = FALSE,
  knownStates = NULL,
  verbose = 0,
  nlmPar = NULL,
  fit = TRUE
)

Arguments

data

An object moveData.

nbStates

Number of states of the HMM.

stepPar0

Vector of initial state-dependent step length distribution parameters. The parameters should be in the order expected by the pdf of stepDist, and the zero-mass parameter should be the last. Note that zero-mass parameters are mandatory if there are steps of length zero in the data. For example, for a 2-state model using the gamma distribution and including zero-inflation, the vector of initial parameters would be something like: c(mu1,mu2,sigma1,sigma2,zeromass1,zeromass2).

anglePar0

Vector of initial state-dependent turning angle distribution parameters. The parameters should be in the order expected by the pdf of angleDist. For example, for a 2-state model using the Von Mises (vm) distribution, the vector of initial parameters would be something like: c(mu1,mu2,kappa1,kappa2).

beta0

Initial matrix of regression coefficients for the transition probabilities (more information in "Details"). Default: NULL. If not specified, beta0 is initialized such that the diagonal elements of the transition probability matrix are dominant.

delta0

Initial value for the initial distribution of the HMM. Default: rep(1/nbStates,nbStates).

formula

Regression formula for the covariates. Default: ~1 (no covariate effect).

stepDist

Name of the distribution of the step lengths (as a character string). Supported distributions are: gamma, weibull, lnorm, exp. Default: gamma.

angleDist

Name of the distribution of the turning angles (as a character string). Supported distributions are: vm, wrpcauchy. Set to "none" if the angle distribution should not be estimated. Default: vm.

angleMean

Vector of means of turning angles if not estimated (one for each state). Default: NULL (the angle mean is estimated).

stationary

FALSE if there are covariates. If TRUE, the initial distribution is considered equal to the stationary distribution. Default: FALSE.

knownStates

Vector of values of the state process which are known prior to fitting the model (if any). Default: NULL (states are not known). This should be a vector with length the number of rows of 'data'; each element should either be an integer (the value of the known states) or NA if the state is not known.

verbose

Determines the print level of the optimizer. The default value of 0 means that no printing occurs, a value of 1 means that the first and last iterations of the optimization are detailed, and a value of 2 means that each iteration of the optimization is detailed.

nlmPar

List of parameters to pass to the optimization function nlm (which should be either 'gradtol', 'stepmax', 'steptol', or 'iterlim' – see nlm's documentation for more detail)

fit

TRUE if an HMM should be fitted to the data, FALSE otherwise. If fit=FALSE, a model is returned with the MLE replaced by the initial parameters given in input. This option can be used to assess the initial parameters. Default: TRUE.

Details

• The matrix beta of regression coefficients for the transition probabilities has one row for the intercept, plus one row for each covariate, and one column for each non-diagonal element of the transition probability matrix. For example, in a 3-state HMM with 2 covariates, the matrix beta has three rows (intercept + two covariates) and six columns (six non-diagonal elements in the 3x3 transition probability matrix - filled in row-wise). In a covariate-free model (default), beta has one row, for the intercept.

• The choice of initial parameters is crucial to fit a model. The algorithm might not find the global optimum of the likelihood function if the initial parameters are poorly chosen.

Value

A moveHMM object, i.e. a list of:

mle

The maximum likelihood estimates of the parameters of the model (if the numerical algorithm has indeed identified the global maximum of the likelihood function), which is a list of: stepPar (step distribution parameters), anglePar (angle distribution parameters), beta (transition probabilities regression coefficients - more information in "Details"), and delta (initial distribution).

data

The movement data

mod

The object returned by the numerical optimizer nlm

conditions

A few conditions used to fit the model (stepDist, angleDist, zeroInflation, estAngleMean, stationary, and formula)

rawCovs

Raw covariate values, as found in the data (if any). Used in plot.moveHMM.

knownStates

Vector of states known a priori, as provided in input (if any, NULL otherwise). Used in viterbi,logAlpha, and logBeta

nlmTime

Computing time for optimisation, obtained with system.time

References

Patterson T.A., Basson M., Bravington M.V., Gunn J.S. 2009. Classifying movement behaviour in relation to environmental conditions using hidden Markov models. Journal of Animal Ecology, 78 (6), 1113-1123.

Langrock R., King R., Matthiopoulos J., Thomas L., Fortin D., Morales J.M. 2012. Flexible and practical modeling of animal telemetry data: hidden Markov models and extensions. Ecology, 93 (11), 2336-2342.

Examples

### 1. simulate data
# define all the arguments of simData
nbAnimals <- 2
nbStates <- 2
nbCovs <- 2
mu<-c(15,50)
sigma<-c(10,20)
angleMean <- c(pi,0)
kappa <- c(0.7,1.5)
stepPar <- c(mu,sigma)
anglePar <- c(angleMean,kappa)
stepDist <- "gamma"
angleDist <- "vm"
zeroInflation <- FALSE
obsPerAnimal <- c(50,100)

data <- simData(nbAnimals=nbAnimals,nbStates=nbStates,stepDist=stepDist,angleDist=angleDist,
                 stepPar=stepPar,anglePar=anglePar,nbCovs=nbCovs,zeroInflation=zeroInflation,
                 obsPerAnimal=obsPerAnimal)

### 2. fit the model to the simulated data
# define initial values for the parameters
mu0 <- c(20,70)
sigma0 <- c(10,30)
kappa0 <- c(1,1)
stepPar0 <- c(mu0,sigma0) # no zero-inflation, so no zero-mass included
anglePar0 <- kappa0 # the angle mean is not estimated, so only the concentration parameter is needed
formula <- ~cov1+cos(cov2)

m <- fitHMM(data=data,nbStates=nbStates,stepPar0=stepPar0,anglePar0=anglePar0,formula=formula,
              stepDist=stepDist,angleDist=angleDist,angleMean=angleMean)

print(m)