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.683692v1

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.

Example Scripts

The data preparation (including preprocessing, source reconstruction and parcellation) needs to be (roughly) matched to the training data for the canonical HMM. The examples scripts 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.

Canonical HMMs are available for the following parcellations:

Name	parcellation_file
38ROI_Giles	fmri_d100_parcellation_with_PCC_reduced_2mm_ss5mm_ds8mm.nii.gz
52ROI_Glasser	Glasser52_binary_space-MNI152NLin6_res-8x8x8.nii.gz

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.

Elekta MEG

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

• See elekta_meg_sensor.ipynb for an example of how to apply the canonical HMM to sensor-level data.

CTF MEG

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

OPM

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

EEG

• See eeg.ipynb for a start-to-end example script for 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.

Contributions

Contributions are welcome, e.g. if you develop a useful preprocessing function. Please open an issue or pull request.

Getting help

Please open an issue on this repository if you run into errors, need help or spot any typos. Alternatively, you can email [email protected].