MEGaNorm

MEGaNorm

Normative modeling of EEG/MEG brain dynamics across populations and timescales.

MEGaNorm is a Python package that wraps MNE-Python and PCNToolkit functionalities for extracting functional imaging-derived phenotypes (f-IDPs) from large-scale EEG and MEG datasets, and then deriving their normative ranges. It allows researchers to analyze large MEG and EEG dataset using high-performance computing facilities, and then build, visualize, and analyze normative models of brain dynamics across individuals.

---

🚀 Features

• Compatibility with MNE-Python, PCNToolkit, SpecParam libraries
• Normative modeling of oscillatory brain activity
• Using high performance capabilities on SLURM clusters
• EEG and MEG support with BIDS integration
• Ready for reproducible deployment with Docker

---

📦 Installation

Option 1: From PyPI (recommended)

This is the easiest way to get started if you just want to use the toolbox.

conda create --channel=conda-forge --strict-channel-priority --name meganorm python=3.12

conda activate meganorm

pip install meganorm

---

Option 2: Installl from the source files

# 1. Create and activate environment
conda create --channel=conda-forge --strict-channel-priority --name meganorm python=3.12

conda activate meganorm

# 2. Clone and install MEGaNorm
git clone https://github.com/ML4PNP/MEGaNorm.git
cd MEGaNorm/
pip install .

---

Option 3: Using Docker

We provide a pre-configured Docker environment with Jupyter Lab. You can either build the image locally or pull the latest version from Docker Hub.

Option A: Build the image locally

make build
make run

Option B: Pull the latest image from Docker Hub

make pull # or docker pull smkia/meganorm:latest
make run

This mounts:

• notebooks/ → for saving Jupyter notebooks
• results/ → for analysis outputs
• data/ → for raw/processed EEG/MEG data

Jupyter will open in your browser on http://localhost:8888

---

FreeSurfer installation (necessary for source localization)

If you plan to use the MEGaNorm package for source localization, you must first download and install FreeSurfer from https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall. You will also need to obtain a FreeSurfer license key and provide it to the MEGaNorm package.

After installing FreeSurfer, you need to run the FreeSurfer cortical reconstruction pipeline on your MRI data using the following commands:

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

For more details on the recon-all pipeline, please refer to the FreeSurfer recon-all documentation: https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all

---

Getting Started (under construction)

👉 documentation Early helpers are available at: https://meganorm.readthedocs.io. We are working hard to add more thorough documentations and tutorials and they will be available soon.

import meganorm

Explore examples in the notebooks/ folder.

---

Testing (under construction)

Run unit tests using:

pytest tests/

---

Citing MEGaNorm

• Citing the package (DOI: 10.5281/zenodo.15441320): You can download BibTeX and other citation formats directly from the Zenodo page: Zamanzadeh, M., Verduyn, Y., & Kia, S. M. (2025). MEGaNorm: a Python package for normative modeling on MEG and EEG data (v0.1.0). Zenodo.

• Citing the paper (nature communication biology): Zamanzadeh, Mohammad, Ymke Verduyn, Augustijn de Boer, Tomas Ros, Thomas Wolfers, Richard Dinga, Marie Šafář Postma, Andre F. Marquand, Marijn van Wingerden, and Seyed Mostafa Kia. "Normative modeling of MEG brain oscillations across the human lifespan." Communications biology (2026).

---

🤝 Contributing

Contributions, issues and feature requests are welcome!

See CONTRIBUTING.md for more info.

---

📜 License

This project is licensed under the terms of the GNU General Public License v3.0 – see the LICENSE file for details.