Tutorial#

GLHMM is a Python toolbox with a focus on neuroscience applications but broadly applicable to other domains as well. It implements a generalisation of various types of Hidden Markov Model (HMM). The toolbox can be applied on multiple data modalities, including fMRI, EEG, MEG, and ECoG, and offers a comprehensive set of HMMs tailored for different data types and analysis goals. The most important configurable aspect is the state distribution, which is parameterized using a regression model. A non-exhaustive list of possible state distributions are:

  • Gaussian: used in fMRI and other neuroimaging modalities.

  • Wishart: employed in fMRI to specifically focus on changes in connectivity (covariance).

  • Time-delay embedded: applied to whole-brain electrophysiological data (MEG or EEG), to capture spectral modulations in the data.

  • Autoregressive: provides a more detailed spectral description for electrophysiological data with a limited number of channels.

  • Regression-based decoding: describes the dynamic relationship between brain activity and ongoing stimuli.

  • Regression-based encoding: emphasizes the spatial interpretation of brain activity in relation to stimuli.

Installation#

If you have not done so, install the repo using:

[1]:

pip install glhmm

Requirement already satisfied: glhmm in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (0.2.3)
Requirement already satisfied: scipy in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (1.12.0)
Requirement already satisfied: numpy in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (1.26.4)
Requirement already satisfied: scikit-learn in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (1.4.1.post1)
Requirement already satisfied: matplotlib in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (3.8.3)
Requirement already satisfied: numba in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (0.59.1)
Requirement already satisfied: seaborn in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (0.13.2)
Requirement already satisfied: pandas in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (2.2.1)
Requirement already satisfied: igraph in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (0.11.4)
Requirement already satisfied: tqdm in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (4.66.2)
Requirement already satisfied: scikit-image in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (0.22.0)
Requirement already satisfied: statsmodels in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from glhmm) (0.14.1)

Requirement already satisfied: texttable>=1.6.2 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from igraph->glhmm) (1.7.0)
Requirement already satisfied: contourpy>=1.0.1 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (1.2.0)
Requirement already satisfied: cycler>=0.10 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (0.12.1)
Requirement already satisfied: fonttools>=4.22.0 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (4.50.0)
Requirement already satisfied: kiwisolver>=1.3.1 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (1.4.5)
Requirement already satisfied: packaging>=20.0 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (24.0)
Requirement already satisfied: pillow>=8 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (10.2.0)
Requirement already satisfied: pyparsing>=2.3.1 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (3.1.2)
Requirement already satisfied: python-dateutil>=2.7 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from matplotlib->glhmm) (2.9.0.post0)
Requirement already satisfied: llvmlite<0.43,>=0.42.0dev0 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from numba->glhmm) (0.42.0)

Requirement already satisfied: pytz>=2020.1 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from pandas->glhmm) (2024.1)
Requirement already satisfied: tzdata>=2022.7 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from pandas->glhmm) (2024.1)

Requirement already satisfied: networkx>=2.8 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-image->glhmm) (3.2.1)
Requirement already satisfied: imageio>=2.27 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-image->glhmm) (2.34.0)
Requirement already satisfied: tifffile>=2022.8.12 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-image->glhmm) (2024.2.12)
Requirement already satisfied: lazy_loader>=0.3 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-image->glhmm) (0.3)

Requirement already satisfied: joblib>=1.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-learn->glhmm) (1.3.2)
Requirement already satisfied: threadpoolctl>=2.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from scikit-learn->glhmm) (3.4.0)

Requirement already satisfied: patsy>=0.5.4 in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from statsmodels->glhmm) (0.5.6)

Requirement already satisfied: six in /home/docs/checkouts/readthedocs.org/user_builds/glhmm2/envs/latest/lib/python3.10/site-packages (from patsy>=0.5.4->statsmodels->glhmm) (1.16.0)

Note: you may need to restart the kernel to use updated packages.

Examples#

Example data is provided in the example_data folder.

For an example of running a standard HMM using only one set of time series, see Example standard Gaussian HMM.

For an example of running a GLHMM using two sets of time series, see Example GLHMM.

Relations to behaviour#

After estimating an HMM, we can explore its connections with an external variable not initially considered in the model. This could involve tasks like predicting age from subject-specific HMMs based on neuroimaging data or examining correlations with physiological factors. Our toolbox supports these types of analyses in the module called Prediction and Statistics

Prediction#

This module enables the utilization of individual brain activity patterns for various applications, including predictions (such as cognitive abilities) and classifications (of subjects or clinical groups, for example). For a tutorial, see here

Statistics#

This module provides powerful permutation testing analysis, which allows for statistical significance assessment without data distribution assumptions. It supports various test types, such as between- and within-session/subject tests. Users can choose between permutation testing with regression or correlation for a wide range of research questions. For a tutorial demonstrating the application of testing see here

These are examples of permutation tests: - Testing across subjects . - Testing across sessions . - Testing across trials . - Testing across visits .