MEGaNorm

MEGaNorm

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.

---

Features

• 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

---

Installation

MEGaNorm currently supports Python 3.12.

From PyPI (recommended)

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 meganorm

From source

To 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 .

Using Docker

A pre-configured Docker environment with JupyterLab is available. You can either build the image locally or pull the latest image from Docker Hub.

Build locally

make build
make run

Pull from Docker Hub

make pull
make run

Alternatively:

docker pull smkia/meganorm:latest

The Docker environment mounts:

• notebooks/ for Jupyter notebooks
• results/ for analysis outputs
• data/ 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

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 -all

See the FreeSurfer recon-all documentation for further information.

---

Getting started

The full MEGaNorm documentation, including usage instructions and examples, is available at meganorm.readthedocs.io.

After installation, verify that MEGaNorm can be imported:

import meganorm

The 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.

---

Testing

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

GitHub Actions

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 -q

Please report unexpected behavior or reproducibility issues through the

GitHub issue tracker.

---

Citation

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.

Software

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

Scientific publication

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

---

Contributing

Contributions, bug reports, and feature requests are welcome. See CONTRIBUTING.md for contribution guidelines.

---

License

MEGaNorm is distributed under the GNU General Public License v3.0. See LICENSE for details.

Acknowledgements

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).

             

---