Metadata-Version: 2.4
Name: meganorm
Version: 0.2.2
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
Project-URL: Documentation, https://meganorm.readthedocs.io/
Project-URL: Source, https://github.com/ML4PNP/MEGaNorm
Project-URL: Software DOI, https://doi.org/10.5281/zenodo.15441319
Project-URL: Scientific paper, https://doi.org/10.1038/s42003-026-09825-2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
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,<3.13
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: nilearn==0.13.1
Requires-Dist: mne_bids==0.18.0
Requires-Dist: mne_icalabel==0.7.0
Requires-Dist: specparam==2.0.0rc7
Requires-Dist: arviz<2.0,>=0.21
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: autoreject==0.4.3
Requires-Dist: pingouin==0.6.1
Requires-Dist: scikit-image==0.26.0
Requires-Dist: onnxruntime
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MEGaNorm

<!-- BEGIN MEGANORM METADATA: badges -->
[![PyPI](https://img.shields.io/pypi/v/meganorm?logo=pypi\&logoColor=white\&color=3775A9)](https://pypi.org/project/meganorm/)
[![Python](https://img.shields.io/pypi/pyversions/meganorm?logo=python\&logoColor=white\&color=3776AB)](https://pypi.org/project/meganorm/)
[![Tests](https://github.com/ML4PNP/MEGaNorm/actions/workflows/tests.yml/badge.svg)](https://github.com/ML4PNP/MEGaNorm/actions/workflows/tests.yml)
[![Documentation](https://readthedocs.org/projects/meganorm/badge/?version=latest)](https://meganorm.readthedocs.io/en/latest/)
[![Docker Pulls](https://img.shields.io/docker/pulls/smkia/meganorm?logo=docker\&logoColor=white\&color=2496ED)](https://hub.docker.com/r/smkia/meganorm)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ML4PNP/MEGaNorm/main?filepath=notebooks%2F)
[![License](https://img.shields.io/github/license/ML4PNP/MEGaNorm?color=blue)](https://github.com/ML4PNP/MEGaNorm/blob/main/LICENSE)
[![Software DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15441319.svg)](https://doi.org/10.5281/zenodo.15441319)
[![Paper DOI](https://img.shields.io/badge/DOI-10.1038%2Fs42003--026--09825--2-B31B1B?logo=doi\&logoColor=white)](https://doi.org/10.1038/s42003-026-09825-2)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14128/badge)](https://www.bestpractices.dev/projects/14128)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/meganorm?period=month\&units=international_system\&left_text=downloads/month\&left_color=grey\&right_color=brightgreen)](https://pypi.org/project/meganorm/)
[![Last Commit](https://img.shields.io/github/last-commit/ML4PNP/MEGaNorm?logo=github\&color=informational)](https://github.com/ML4PNP/MEGaNorm/commits/main)
<!-- END MEGANORM METADATA: badges -->

<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 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](https://github.com/mne-tools/mne-python), [PCNToolkit](https://github.com/amarquand/PCNtoolkit), and [SpecParam](https://github.com/fooof-tools/fooof) 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.

![Overview of the MEGaNorm pipeline](docs/images/pipeline_overview.png)

---

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

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

<!-- BEGIN MEGANORM METADATA: source-install -->
```bash
# 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 .
```
<!-- END MEGANORM METADATA: source-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

```bash
make build
make run
```

#### Pull from Docker Hub

```bash
make pull
make run
```

Alternatively:

```bash
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](https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall). A FreeSurfer license is also required.

After installation, cortical reconstruction of the anatomical MRI can be performed using `recon-all`, for example:

```bash
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](https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all) for further information.

---

## Getting started

<!-- BEGIN MEGANORM METADATA: documentation -->
The full MEGaNorm documentation, including usage instructions and examples, is available at [meganorm.readthedocs.io](https://meganorm.readthedocs.io/).
<!-- END MEGANORM METADATA: documentation -->

After installation, verify that MEGaNorm can be imported:

```python
import meganorm
```

The local scientific API is available from `meganorm.API` and follows
`Dataset → Config → Pipeline → FeatureDataset → NormativeModel → NormativeResults`.
The [Getting Started guide](docs/source/getting_started.rst) covers the complete
workflow, processing several datasets, participant failure reports, and reruns.
The [configuration guide](docs/source/configuration.rst) explains processing
settings, JSON files, and updates to older configuration names. See
[changes in v0.2.2](docs/source/whats_new.rst) 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/`](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
<!-- BEGIN MEGANORM METADATA: ci-link -->
[GitHub Actions](https://github.com/ML4PNP/MEGaNorm/actions/workflows/tests.yml)
<!-- END MEGANORM METADATA: ci-link -->
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:

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
```

Please report unexpected behavior or reproducibility issues through the
<!-- BEGIN MEGANORM METADATA: issues -->
[GitHub issue tracker](https://github.com/ML4PNP/MEGaNorm/issues).
<!-- END MEGANORM METADATA: issues -->

---

## 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`](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.
<!-- BEGIN MEGANORM METADATA: software-doi -->
https://doi.org/10.5281/zenodo.15441319
<!-- END MEGANORM METADATA: software-doi -->

### 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*.
<!-- BEGIN MEGANORM METADATA: paper-doi -->
https://doi.org/10.1038/s42003-026-09825-2
<!-- END MEGANORM METADATA: paper-doi -->

---

## Contributing

Contributions, bug reports, and feature requests are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution guidelines.

---

## License

MEGaNorm is distributed under the **GNU General Public License v3.0**. See [`LICENSE`](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).

<p align="center">
  <a href="https://www.tilburguniversity.edu/">
    <img src="docs/source/_static/tilburg-university-logo.png"
         alt="Tilburg University"
         height="65">
  </a>
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  <a href="https://www.nwo.nl/projecten/vqlab92202">
    <img src="docs/source/_static/nwo-logo.jpg"
         alt="Dutch Research Council (NWO)"
         height="65">
  </a>
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  <a href="https://www.surf.nl/en">
    <img src="docs/source/_static/surf-logo.png"
         alt="SURF"
         height="65">
  </a>
</p>

---
