Metadata-Version: 2.4
Name: meganorm
Version: 0.2.0
Summary: A Python package for normative modeling on large-scale EEG and MEG data.
Home-page: https://github.com/ML4PNP/MEGaNorm
Author: Seyed Mostafa Kia, Mohammad Zamanzadeh, Ymke Verduyn
License: GNU GPLv3
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.2
Requires-Dist: pandas>=2.3.3
Requires-Dist: scipy>=1.17.1
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: seaborn>=0.13.2
Requires-Dist: plotly>=5.24.1
Requires-Dist: scikit_learn>=1.8.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: mne>=1.12.1
Requires-Dist: mne_bids>=0.18.0
Requires-Dist: mne_icalabel>=0.7.0
Requires-Dist: fooof>=1.1.0
Requires-Dist: pcntoolkit>=1.3.0
Requires-Dist: pyrasa>=1.1.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: kneed>=0.8.6
Requires-Dist: gedai>=0.1.0
Requires-Dist: autoreject>=0.4.3
Requires-Dist: onnxruntime
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MEGaNorm

[![Paper DOI](https://img.shields.io/badge/DOI-10.1038%2Fs41598--024--12345--6-blue)](https://doi.org/10.1038/s42003-026-09825-2)
[![Made with Python](https://img.shields.io/badge/Made%20with-Python-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![Documentation Status](https://readthedocs.org/projects/meganorm/badge/?version=latest)](https://meganorm.readthedocs.io/en/latest/?badge=latest)
![Last Commit](https://img.shields.io/github/last-commit/ML4PNP/MEGaNorm.svg)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ML4PNP/MEGaNorm/main?filepath=notebooks%2F)
[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15441320.svg)](https://doi.org/10.5281/zenodo.15441320)


<p align="center">
  <img src="docs/images/logo.png" alt="MEGaNorm Logo" width="180"/>
</p>

<h1 align="center">MEGaNorm</h1>

<p align="center">
  Normative modeling of EEG/MEG brain dynamics across populations and timescales.
</p>


**MEGaNorm** is a Python package that wraps [MNE-Python](https://github.com/mne-tools/mne-python) and [PCNToolkit](https://github.com/amarquand/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.

![Overview](docs/images/pipeline_overview.png)

&#x20;

---

## 🚀 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.

```bash
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

```bash
# 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

```bash
make build
make run
```

#### Option B: Pull the latest image from Docker Hub

```bash
make pull
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](http://localhost:8888)

---

## 📒 Getting Started (under construction)

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

```python 
import meganorm
```

Explore examples in the [`notebooks/`](notebooks/) folder.

---

## 🧚‍♂️ Testing (under construction)

Run unit tests using:

```bash
pytest tests/
```

---

## 🧠 Citing MEGaNorm

* Citing the package (**DOI**: [10.5281/zenodo.15441320](https://doi.org/10.5281/zenodo.15441320)): You can download BibTeX and other citation formats directly from the [Zenodo page](https://doi.org/10.5281/zenodo.15441320): 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](https://doi.org/10.1038/s42003-026-09825-2)): 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](CONTRIBUTING.md) for more info.

---

## 📜 License

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