NOTE: This is an early release; the neuromodes API is subject to breaking changes prior to a stable release.

Eigenmode-based brain mapping and modelling toolbox developed by the Neural Systems and Behaviour Lab. Documentation can be found here, and source code can be found here.

Features

Asterisk (*) indicates features under development that are not yet available.

• eigen: Compute geometric eigenmodes from cortical surface meshes, optionally incorporating spatial heterogeneity
• basis: Decompose and reconstruct cortical maps using the geometric eigenmodes, or another basis set
• nulls: Generate null models of cortical maps that preserve spatial autocorrelation, using the Eigenstrapping method from Koussis et al. (2025)
• waves: Simulate neural activity and BOLD signals using the wave model from Pang et al. (2023)
• network: Generate models of structural connectomes using the Geometric Eigenmode Model from Normand et al. (2025)
• io: Access triangular surface meshes for human, macaque, and marmoset cortices
• morphometry (coming soon): Quantify multiscale anatomical differences using Mode-Based Morphometry from Cao et al. (2024)
• parcellation (coming soon): Create parcellations with any number of regions using the hierarchical bipartitioning method from Pang et al. (2025)

Installation

neuromodes works with Python 3.10+, and can be installed via:

pip install neuromodes

To try out any newer features under development, clone from our dev branch instead via:

pip install git+https://github.com/NSBLab/neuromodes.git@dev

If you wish to run the tutorials, please instead install our extra tutorials dependencies via:

pip install "neuromodes[tutorials] @ git+https://github.com/NSBLab/neuromodes.git"

If you encounter any problems, please consider opening an issue. Meanwhile, try switching to the exact environment used for development via the modern project and package manager UV:

git clone https://github.com/NSBLab/neuromodes
cd neuromodes
uv venv --python 3.14.3
uv sync --frozen

Tests can be run with pytest from the repository root:

cd neuromodes
pip install pytest  # or `uv sync --extra testing`
pytest tests

Citing

If you use neuromodes in your work, please cite the following three papers:

J.C. Pang, K.M. Aquino, M. Oldehinkel, P.A. Robinson, B.D. Fulcher, M. Breakspear, A. Fornito, Geometric constraints on human brain function, Nature, 618, 566–574 (2023) (DOI: 10.1038/s41586-023-06098-1)

M. Reuter, F-E. Wolter, N. Peinecke, Laplace-Beltrami spectra as 'Shape-DNA' of surfaces and solids, Computer-Aided Design, 38(4), 342-366 (2006). (DOI: 10.1016/j.cad.2005.10.011)

C. Wachinger, P. Golland, W. Kremen, B. Fischl, M. Reuter, BrainPrint: a discriminative characterization of brain morphology, Neuroimage, 109, 232-248 (2015). (DOI: 10.1016/j.neuroimage.2015.01.032)

If you use the hetero parameter in EigenSolver, please also cite:

V. Barnes, J. Cruddas, T. Cao, I.Z. Pope, T. Xu, T. Funck, N. Palomero-Gallagher, J.C. Pang, A. Fornito, Regional heterogeneity shapes macroscopic wave dynamics of the human and non-human primate cortex, BioRxiv (2026) (DOI: 10.64898/2026.01.22.701178)

If you use the compute_gem function, please also cite:

F. Normand, M. Gajwani, T. Cao, J. Cruddas, A. Sangchooli, S. Oldham, A. Holmes, P.A. Robinson, J.C. Pang, A. Fornito, Geometric constraints on the architecture of mammalian cortical connectomes, BioRxiv (2025) (DOI: 10.1101/2025.09.17.676944)

If you use the eigenstrap function, please also cite:

N.C. Koussis, J.C. Pang, R. Phogat, J. Jeganathan, B. Paton, A. Fornito, P.A. Robinson, B. Misic, M. Breakspear, Generation of surrogate brain maps preserving spatial autocorrelation through random rotation of geometric eigenmodes, Imaging neuroscience (2025) (DOI: 10.1162/IMAG.a.71)

Citations for cortical surface meshes and maps can be found in neuromodes/data/included_data.csv

License information

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (cc-by-nc-sa). See the LICENSE file for details.