Normative modeling of EEG/MEG brain dynamics across populations and timescales.
MEGaNorm is a Python package for extracting functional imaging-derived phenotypes (f-IDPs) from large-scale EEG and MEG datasets and deriving their normative ranges. It integrates functionality from MNE-Python, PCNToolkit, and SpecParam into workflows for large-scale analysis of electrophysiological data.
MEGaNorm supports processing on high-performance computing (HPC) infrastructure and provides tools for building, visualizing, and analyzing normative models of brain dynamics across individuals and populations.
- Extraction of electrophysiological functional imaging-derived phenotypes (f-IDPs)
- Normative modeling of oscillatory brain activity
- Integration with MNE-Python, PCNToolkit, and SpecParam
- EEG and MEG support with BIDS integration
- A local Python API for cohort feature extraction and normative modeling
- High-performance computing workflows for SLURM clusters
- Reproducible deployment using Docker
MEGaNorm currently supports Python 3.12.
For most users, installation from PyPI is the recommended option.
conda create --channel=conda-forge --strict-channel-priority --name meganorm python=3.12
conda activate meganorm
pip install meganormTo install from the repository:
# Create and activate the environment
conda create --channel=conda-forge --strict-channel-priority --name meganorm python=3.12
conda activate meganorm
# Clone and install MEGaNorm
git clone https://github.com/ML4PNP/MEGaNorm.git
cd MEGaNorm
pip install .A pre-configured Docker environment with JupyterLab is available. You can either build the image locally or pull the latest image from Docker Hub.
make build
make runmake pull
make runAlternatively:
docker pull smkia/meganorm:latestThe Docker environment mounts:
notebooks/for Jupyter notebooksresults/for analysis outputsdata/for EEG/MEG data
Open the JupyterLab URL printed in the terminal at http://localhost:8888;
it includes the login token. The Makefile exposes the port on localhost.
To select a published version, pass the same TAG to both make pull and
make run.
FreeSurfer is required only when using MEGaNorm workflows that involve source localization.
Download and installation instructions are available in the FreeSurfer documentation. A FreeSurfer license is also required.
After installation, cortical reconstruction of the anatomical MRI can be performed using recon-all, for example:
export FREESURFER_HOME=/usr/local/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=/path/to/your/subjects
recon-all -s sub-01 -i /path/to/sub-01_T1w.nii.gz -allSee the FreeSurfer recon-all documentation for further information.
The full MEGaNorm documentation, including usage instructions and examples, is available at meganorm.readthedocs.io.
After installation, verify that MEGaNorm can be imported:
import meganormThe local scientific API is available from meganorm.API and follows
Dataset → Config → Pipeline → FeatureDataset → NormativeModel → NormativeResults.
The Getting Started guide covers the complete
workflow, processing several datasets, participant failure reports, and reruns.
The configuration guide explains processing
settings, JSON files, and updates to older configuration names. See
changes in v0.2.2 before updating an existing analysis.
Existing low-level functions, command-line tools, and SLURM workflows remain
available.
Example workflows are also available in the notebooks/ directory.
MEGaNorm includes an automated test suite covering its core processing, feature-extraction, normative-modeling, source-localization, IO, layout, plotting, and utility functionality. The suite runs automatically through
on pushes and pull requests, excluding tests marked slow. Run the Tests
workflow manually to include the HBR workflow and IRASA decomposition checks.
To run the tests locally from a development checkout:
python -m pip install -e ".[dev]"
python -m pytest -qPlease report unexpected behavior or reproducibility issues through the
If you use MEGaNorm in your research, please cite the software. Depending on your use of the package, you may also cite the associated scientific publication describing the MEGaNorm framework and its application to lifespan MEG normative modeling.
The citation metadata for MEGaNorm is provided in CITATION.cff and is also available through the Cite this repository option on GitHub.
The software is archived on Zenodo:
Zamanzadeh, M., Verduyn, Y., & Kia, S. M. MEGaNorm: A Python package for normative modeling of MEG and EEG data. Zenodo.
https://doi.org/10.5281/zenodo.15441319
For the scientific framework and its application to normative modeling of brain oscillations across the human lifespan, please cite:
Zamanzadeh, M., Verduyn, Y., de Boer, A., Ros, T., Wolfers, T., Dinga, R., Šafář Postma, M., Marquand, A. F., van Wingerden, M., & Kia, S. M. (2026). Normative modeling of MEG brain oscillations across the human lifespan. Communications Biology.
https://doi.org/10.1038/s42003-026-09825-2
Contributions, bug reports, and feature requests are welcome. See CONTRIBUTING.md for contribution guidelines.
MEGaNorm is distributed under the GNU General Public License v3.0. See LICENSE for details.
We gratefully acknowledge the starter grant for the MEGaNorm project, funded by the Dutch Ministry of Education, Culture and Science under the National Sector Plan. We further acknowledge support from the NWA Innovative Projects within the Routes grant (NWA.1418.24.006) from the Dutch Research Council (NWO). This work also used the Dutch national e-infrastructure with the support of the SURF Cooperative (EINF-8659, EINF-13793, and EINF-18102).
