fitHMM: Fit an HMM to the data

In moveHMM: Animal Movement Modelling using Hidden Markov Models

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)

moveHMM documentation built on May 31, 2023, 6:13 p.m.