OHBA Software Library: Dynamics Toolbox
osl-dynamics is a Python toolbox for studying brain dynamics using neuroimaging data: MEG, EEG and fMRI. It provides generative models that decompose data into brain networks (often called brain states or modes), including the Hidden Markov Model (HMM) and Dynamic Network Modes (DyNeMo), along with everything needed for a complete analysis: data loading and preparation, spectral estimation, network visualisation and statistical significance testing.
You can use osl-dynamics to:
- Infer dynamic functional networks from resting-state or task M/EEG and fMRI data using the HMM, DyNeMo and related models (M-DyNeMo, HIVE, DIVE, DyNeSTE and more).
- Characterise brain states/modes with summary statistics (fractional occupancy, lifetimes, intervals, switching rates), state-specific power maps, and functional connectivity.
- Estimate spectra using multitaper and regression-based methods, or wavelet transforms.
- Detect oscillatory bursts.
- Test for statistical significance using GLM permutation testing.
- Preprocess and source reconstruct M/EEG data: preprocessing, coregistration, beamforming and parcellation.
- Simulate time series data from HMMs, sinusoidal oscillators and autoregressive models.
osl-dynamics works with MNE-Python: a typical M/EEG workflow preprocesses, source reconstructs and parcellates data first, then models the dynamics of the parcel time courses. Data can be loaded from NumPy (.npy), MATLAB (.mat), text (.txt) or MNE (.fif) files.
For a full description of the toolbox, see the documentation.
Quick example
Train a Time-Delay Embedded Hidden Markov Model (TDE-HMM) on parcellated MEG data to infer dynamic functional brain networks:
from osl_dynamics.data import Data
from osl_dynamics.models.hmm import Config, Model
# Load data, e.g. parcel time courses
data = Data("training_data")
# Prepare the data: time-delay embedding + PCA captures spectral structure
data.prepare({
"tde_pca": {"n_embeddings": 15, "n_pca_components": 80},
"standardize": {},
})
# Train an HMM
config = Config(
n_states=8,
n_channels=data.n_channels,
sequence_length=200,
learn_means=False,
learn_covariances=True,
batch_size=256,
learning_rate=0.01,
n_epochs=20,
)
model = Model(config)
model.random_state_time_course_initialization(data, n_init=3, n_epochs=1)
model.fit(data)
# Get inferred state probabilities
alpha = model.get_alpha(data)
See the tutorials for complete walkthroughs and the examples directory for full analysis pipelines.
Installation
The recommended installation for osl-dynamics is:
conda create -n osld -c conda-forge osl-dynamics
conda activate osld
See the installation page for more information.
Documentation
The read the docs page should be automatically updated whenever there's a new commit on the main branch.
The documentation is included as docstrings in the source code. The API reference documentation will only be automatically generated if the docstrings are written correctly. The documentation directory /doc also contains .rst files that provide additional info regarding installation, development, the models, etc.
To compile the documentation locally you need to install the required packages (sphinx, etc) in your conda environment:
cd osl-dynamics
conda activate osld
pip install -r doc/requirements.txt
To compile the documentation locally use:
sphinx-build -b html doc build
The local build of the documentation webpage can be found in build/sphinx/html/index.html.
To skip building the tutorials, comment out "sphinx_gallery.gen_gallery" here.
Releases
To release a new version:
-
Check the latest commit on
mainhas compiled successfully on readthedocs. -
Create a new release using the 'Create a new release' link on the right of the GitHub repo webpage:
- Set the tag to the new version number with a
vprefix (e.g.v3.3.0). - Write the release notes.
- Select 'Latest' for the release label and click 'Publish release'.
- Set the tag to the new version number with a
-
Publishing the release triggers a GitHub Actions workflow (
.github/workflows/release.yml) that builds the package and uploads it to PyPI. Check the workflow succeeded under the Actions tab of the GitHub repo.
Citation
If you find this toolbox useful, please cite the paper:
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.
Release files for osl-dynamics 3.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| osl_dynamics-3.6.1.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| osl_dynamics-3.6.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.9 MB
Release files / osl_dynamics-3.6.1.tar.gz
| Download URL | osl_dynamics-3.6.1.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48bbcff3fe3401dbec160a8ef3f8ecaae9544277c598360f2bec1bb03e4f8b2f
|
|
BLAKE2b-256 checksum How to use checksums |
476f8180b3cbfde4dce05bf2fd7cdce3946680b82f492dda9c4e11b099f00a81
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / osl_dynamics-3.6.1-py3-none-any.whl
| Download URL | osl_dynamics-3.6.1-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f3814b941976af3fe451f63d01e3eecc47560419002159108883ea3de0f6e76e
|
|
BLAKE2b-256 checksum How to use checksums |
1ef4d9ce075901e0be56e83552f88e6b4044369d7616271c3fe3fef0ca945619
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
