Home - OHBA-analysis/HMM-MAR GitHub Wiki

UPDATING TO THE LATEST VERSION IS STRONGLY RECOMMENDED, DUE TO AN ERROR THAT WAS RECENTLY FOUND ON THE STOCHASTIC INFERENCE UPDATES.

Introduction

HMM-MAR (Hidden Markov Model - Multivariate Autoregressive) is a toolbox to segment multivariate time series into states that are characterised by their unique quasi-stationary spectral properties. In the context of neuroscience applications, it can be used on both resting and task data, and on different data modalities (EEG, MEG, LFP, fMRI, etc). Although when it started it had just the MAR and Gaussian model, it has nowadays grown to allow for other non-MAR state definitions (and it is too late to change the name now). Those include the Gaussian distribution, a (Wishart) distribution where the states describe time-delayed cross-correlation patterns (a sort of truncated Gaussian Process), a distribution representing decoding models (or GLM), etc (see references below).

The toolbox comprises a number of additional features:

  • Estimation of the spectral properties for each state, using either a parametric (MAR) or a non-parametric approach (statewise multitaper).
  • Some preprocessing utilities, including correction for volume conduction.
  • Utilities to interrogate the results
  • Built-in permutation testing analysis to check the relation of the HMM results with different data conditions
  • Semi-supervised prediction of events.
  • Extension to the classical inference to work with very big data sets.
  • Routines for cross-validation and model selection.
  • Simulation of data.
  • Sign disambiguation for source reconstructed M/EEG data.

HMM-MAR is experimental software. It is IMPORTANT to use the latest version, as we do continuous maintenance of the code. The toolbox has no dependencies and only requires Matlab, unless:

  • The inputs are specified as SPM files, in which case it will require SPM.
  • Correction for volume conduction (aka signal leakage) is performed, in which case it requires the package MEG-ROI-nets.

Apart from this Wiki, a quick way to understand the usage of the toolbox is to look at the example scripts (under directory 'examples'), which contain some typical instances of usage of the HMM.

Please cite the references below if this toolbox turns out to be useful. If there is something in this documentation that is not clear enough or does not make sense, please get in touch! We would be grateful if bugs are reported to diego dot vidaurre at ohba dot ox dot ac dot uk.

Some additional examples can be found here. If you have issues of questions, it is possible to email us, but please better use the Issues tab on github, so that others can see the response as well.

Documentation index

  1. Introduction
  2. Theory
  3. User Guide
  4. FAQ
  5. Examples

References

If this toolbox turns out to be useful, we'd grateful if you cite the main references for the HMM-MAR:

Diego Vidaurre, Andrew J. Quinn, Adam P. Baker, David Dupret, Alvaro Tejero-Cantero and Mark W. Woolrich (2016) Spectrally resolved fast transient brain states in electrophysiological data. NeuroImage. Volume 126, Pages 81–95.

and, describing an efficient inference (stochastic) method for big amounts of data,

Diego Vidaurre, R. Abeysuriya, R. Becker, Andrew J. Quinn, F. Alfaro-Almagro, S.M. Smith and Mark W. Woolrich (2017) Discovering dynamic brain networks from Big Data in rest and task. NeuroImage.

An example of application on fMRI is shown in

Diego Vidaurre, S.M. Smith and Mark W. Woolrich (2017). Brain network dynamics are hierarchically organized in time. Proceedings of the National Academy of Sciences of the USA

A version adequate for modelling whole-brain M/EEG data (not MAR-based, but using lagged cross-correlations) is proposed in

Diego Vidaurre, Lawrence T. Hunt, Andrew J. Quinn, Benjamin A.E. Hunt, Matthew J. Brookes, Anna C. Nobre and Mark W. Woolrich (2017). Spontaneous cortical activity transiently organises into frequency specific phase-coupling networks. Nature Communications.

A step-by-step paper detailing the use of the HMM for MEG alongside comprehensive details of MEG preprocessing in

Andrew J. Quinn, Diego Vidaurre, Romesh Abeysuriya, Robert Becker, Anna C Nobre, Mark W Woolrich (2018). Task-Evoked Dynamic Network Analysis Through Hidden Markov Modeling. Frontiers in Neuroscience.

A version designed to model coherence in fMRI is presented in

Joana Cabral, Diego Vidaurre, Paulo Marques, Ricardo Magalhaes, Pedro Silva Moreira, Jose Miguel Soares, Gustavo Deco, Nino Sousa and Morten L. Kringelbach (2017). Cognitive performance in healthy older adults relates to spontaneous switching between states of functional connectivity during rest. Scientific Reports.

An HMM-based model to find dynamic decoding models, where the states define how, when and where the stimulus is encoded in the brain

Diego Vidaurre, Nicholas Myers, Mark Stokes, Anna C Nobre and Mark W. Woolrich (2018). Temporally unconstrained decoding reveals consistent but time-varying stages of stimulus processing. Cerebral Cortex.

And an extension of this which provides interpretable spatial and temporal maps of activity on single trials, whilst also supporting temporally unconstrained decoding:

Cameron Higgins, Diego Vidaurre, Nils Kolling, Yunzhe Liu, Tim Behrens and Mark Woolrich (2022). Spatiotemporally resolved multivariate pattern analysis for M/EEG. *Human Brain Mapping