moveHMM (version 1.0)

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, beta0 = NULL, delta0 = NULL,
  formula = ~1, stepDist = c("gamma", "weibull", "lnorm", "exp"),
  angleDist = c("vm", "wrpcauchy", "none"), angleMean = NULL,
  stationary = FALSE, 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 ther

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 par

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 matri

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.

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 de

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

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
• stepDist
  The step length distribution name
• angleDist
  The turning angle distribution name
• mod
  The object returned by the numerical optimizer nlm
• conditions
  A few conditions used to fit the model (zeroInflation, estAngleMean, stationary, and formula)
• rawCovs
  Raw covariate values, as found in the data (if any). Used in plot.moveHMM.

Details

• The matrixbetaof 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 matrixbetahas 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),betahas 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

### 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,verbose=2)