fitHMM: 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
)

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

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.

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

Run this code

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

Run the code above in your browser using DataLab