This R package implements flexible hidden Markov models, based on Template Model Builder (TMB): flexible state-dependent distributions, transition probability structures, random effects, and smoothing splines.
The statistical background, as well as details about the implementation of the package, and several example analyses, are presented in the following paper.
The package is available on CRAN, and the stable version can therefore be installed using
install.packages("hmmTMB")The development version of the package can be installed from Github using devtools,
devtools::install_github("TheoMichelot/hmmTMB")To find help files for the methods implemented in the package, search for help using the name of the corresponding class, e.g.,
?MarkovChain
?Observation
?HMMWe describe functionalities of the package in several vignettes, which are listed below.
‘Bayesian inference in hmmTMB’: Description of workflow for Bayesian analysis in hmmTMB, including specifying priors, and extracting posterior samples.
‘Advanced features of hmmTMB’: Description of some other useful functionalities, including (semi-)supervised learning, parameter constraints, selection of initial parameter values, etc.
‘General dependence structures in hmmTMB’: Implementation details for hidden Markov models (HMMs) with non-standard dependence structures, including hidden semi-Markov models, higher-order HMMs, autoregressive HMMs, and coupled HMMs.
‘(Semi-)supervised learning in hmmTMB’: Illustration of semi-supervised learning to pass information about state process to model.
‘Flexible animal movement modelling using hmmTMB’: Description of wild haggis movement analysis, illustrating how non-parametric covariate effects can be included. This includes two different types of movement models: (1) correlated random walks based on step lengths and turning angles, and (2) correlated random walks based on locations directly.
‘Occupancy modelling using hmmTMB’: Analysis of occupancy data set of crossbill from Kéry et al. (2013), “Analysing and mapping species range dynamics using occupancy models, Journal of Biogeography, 40(8), 1463-1474.
‘The categorical distribution in hmmTMB’: The categorical distribution is slightly different from others, in that the number of parameters depends on the data (specifically, on the number of categories in the data). This vignette shows an example analysis for a data set on patient-therapist interactions from the mHMMbayes package.
‘The multivariate normal distribution in hmmTMB’: We illustrate the state-dependent multivariate normal distribution for modelling correlated variables, using time series of log-returns. The vignette describes the formulation in terms of standard deviations and correlation parameters, and compares this approach to using multiple univariate normal distributions.
‘Forecasting
with hmmTMB: an example using Old Faithful data’ and ‘Forecasting
with hmmTMB: energy prices’: We illustrate the use of the
Forecast class to forecast the state process and
observation distribution of a fitted hidden Markov model. The two
vignettes use different data sets, and illustrate different ways to
visualise the forecast outputs.
‘SPDE
smooths in hmmTMB’: This analysis showcases the 'spde'
smooth basis, which is based on the stochastic partial differential
equation (SPDE) approach to smoothing. In the vignette, transition
probabilities are estimated as spatially-varying with an SPDE smooth, to
estimate areas where different transitions are more likely to
occur.
‘(Semi-)supervised learning in hmmTMB’: When the state process is partially known, this information can be passed to the model in a semi-supervised approach.
‘List of distributions in hmmTMB’: List of observation distributions currently available in hmmTMB.
‘Adding new distributions in hmmTMB’: Technical vignette about adding new observation distributions to hmmTMB, with detailed instructions to add the required R and C++ code.
‘Syntax of model formulas in hmmTMB’: Flexible covariate dependence can be specified using the syntax of mgcv formulas, and this vignette describes a few special cases, including random effects (intercepts or slopes), smooth non-linear relationships, factor-smooth interactions, multidimensional smooths, varying-coefficient models, cyclical effects, etc.
‘HMM package comparison’: Comparison of syntax between several R packages (hmmTMB, momentuHMM, depmixS4, LMest) and a Python package (hmmlearn) for a simple 2-state Gaussian HMM.