Canonical HMM Networks for Studying M/EEG

This repository contains canonical Hidden Markov Models (HMMs) that were pre-trained on the Cam-CAN dataset (using the time-delay embedding approach).

Preprint

https://www.biorxiv.org/content/10.1101/2025.10.21.683692v2

Installation

To run these scripts you need to install FSL and osl-dynamics. Note, osl-dynamics will install MNE-Python automatically.

Once you have installed the osld environment, a couple extra Python packages are needed. These can be installed via a terminal:

conda activate osld
pip install fslpy ipyevents

We recommend running the Jupyter Notebook scripts using VSCode. Use the osld kernel (conda environment) when running the scripts.

Tutorials

The data preparation (including preprocessing, source reconstruction and parcellation) needs to be (roughly) matched to the training data for the canonical HMM. The tutorials illustrate how to perform these steps on new data. MNE-Python is used to do the data processing. The most important thing to match is the sampling frequency (250 Hz) and parcellation.

Elekta MEG

• See elekta_meg_parcel.ipynb for a start-to-end tutorial on applying the canonical HMM to parcellated Elekta MEG data.

• See elekta_meg_sensor.ipynb for a tutorial on applying the canonical HMM to sensor-level data.

CTF MEG

• See ctf_meg.ipynb for a start-to-end tutorial on applying the canonical HMM to parcellated CTF MEG data.

OPM

• See opm.ipynb for a start-to-end tutorial on applying the canonical HMM to parcellated OPM data.

EEG

• See eeg.ipynb for a start-to-end tutorial on applying the canonical HMM to parcellated EEG data. Note, to source reconstruct/parcellate EEG data we need medium/high-density EEG, e.g. ~64+ channels.

Also see the /contributions directory for further example scripts and tutorials.

Models / Parcellations

Canonical HMMs are available for the following parcellations:

Name	parcellation_file
Giles38	atlas-Giles_nparc-38_space-MNI_res-8x8x8.nii.gz
Glasser52	atlas-Glasser_nparc-52_space-MNI_res-8x8x8.nii.gz
DK54	atlas-DK_nparc-54_space-MNI_res-8x8x8.nii.gz

For more information regarding the parcellations, see here.

There is also a sensor-level canonical HMM available for Elekta MEG. New parcellations could be made available on request, however, the rank of the Cam-CAN data limits us to ~50 parcels.

Citation

If you find this resource useful, please cite the repository:

Gohil, C., & Woolrich, M. W. (2025). Canonical HMM Networks (Version 0.4.1) [Computer software]. https://doi.org/10.5281/zenodo.17583973.

And following papers:

Gohil, C., Huang, R., Higgins, C., van Es, M. W., Quinn, A. J., Vidaurre, D., & Woolrich, M. W. (2025). Canonical Hidden Markov Model Networks for Studying M/EEG. bioRxiv, 2025-10.

Gohil, C., Huang, R., Roberts, E., van Es, M. W., Quinn, A. J., Vidaurre, D., & Woolrich, M. W. (2024). osl-dynamics, a toolbox for modeling fast dynamic brain activity. Elife, 12, RP91949.

Getting help

Please open an issue on this repository if you run into errors, need help or spot any typos. Alternatively, you can email chetan.gohil@psych.ox.ac.uk.