Metadata-Version: 2.4
Name: cmb
Version: 0.1.1
Summary: Cere-MEG-Bellum (CMB) - Cerebellum segmentation and MNE-Python compatible source spaces for MEG/EEG
Author-email: John Gustaf Wilhelm Samuelsson <johnsam@mit.edu>, Christoph Dinh <christoph.dinh@brain-link.de>, Teemu Taivainen <ttaiv@outlook.com>
License-Expression: MIT
Project-URL: Documentation, https://ceremegbellum.readthedocs.io
Project-URL: Homepage, https://github.com/johnsam7/ceremegbellum
Project-URL: Source, https://github.com/johnsam7/ceremegbellum/
Project-URL: Tracker, https://github.com/johnsam7/ceremegbellum/issues/
Keywords: neuroscience,neuroimaging,MEG,EEG,cerebellum,brain
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.14
Requires-Dist: mne>=1.8
Requires-Dist: matplotlib>=3.9
Requires-Dist: nibabel>=5.3
Requires-Dist: pandas>=2.2
Requires-Dist: pooch>=1.8
Requires-Dist: antspyx>=0.5
Requires-Dist: torch>=2.0
Requires-Dist: nnunet>=1.7
Provides-Extra: viz
Requires-Dist: pyvista>=0.43; extra == "viz"
Provides-Extra: viz-qt
Requires-Dist: cmb[viz]; extra == "viz-qt"
Requires-Dist: pyvistaqt>=0.11; extra == "viz-qt"
Requires-Dist: PySide6; extra == "viz-qt"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: pydata-sphinx-theme; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: numpydoc; extra == "dev"
Dynamic: license-file

# Cere-MEG-Bellum (CMB)

[![Documentation Status](https://readthedocs.org/projects/ceremegbellum/badge/?version=latest)](https://ceremegbellum.readthedocs.io/en/latest/)

CMB is a Python package for fitting a high-resolution cerebellar atlas to standard MRI (ARCUS) and MEG/EEG source space computation including the cerebellum.

Currently under active development: **API may change without notice**. Please report any issues or feature requests on the [GitHub issue tracker](https://github.com/johnsam7/ceremegbellum/issues).

For more information about the method, please see:

> Samuelsson, J. G., J. D.Schmahmann, M. I.Sereno, B.Rosen, and M. S.Hämäläinen. 2026. “A Digital Anatomical Atlas of the Human Cerebellum at Subfolial Resolution.” Human Brain Mapping 47, no. 4: e70497. <https://doi.org/10.1002/hbm.70497>.

## Features

- Automatic segmentation of cerebellar lobules using a trained nnU-Net model
- Diffeomorphic registration (ANTs SyNCC) of a high-resolution cerebellar template to subject anatomy
- Construction of cerebellar cortical source spaces compatible with MNE-Python
- Visualization of cerebellar data in normal, inflated, and flatmap views

<!-- docs-skip-start -->

## Documentation

The full documentation, including the API reference, is available at
[ceremegbellum.readthedocs.io](https://ceremegbellum.readthedocs.io).

<!-- docs-skip-end -->

## Requirements

- Python >= 3.10
- [nnU-Net (v1)](https://github.com/MIC-DKFZ/nnUNet/tree/nnunetv1) (installed automatically as a dependency)
- [FreeSurfer](https://surfer.nmr.mgh.harvard.edu/) (not required to run the package, but `recon-all` outputs are required)

## Installation

1. Create a new virtual environment for Cere-MEG-Bellum and activate it.
   You can do this, for example, with [uv](https://docs.astral.sh/uv/) (recommended!),
   [venv](https://docs.python.org/3/library/venv.html) or [conda](https://github.com/conda/conda).
   `uv` and `conda` are good options because they can also manage the Python version without
   depending on system Python.

   ```bash
   # uv
   uv venv cmb-env --python 3.12 --seed
   source cmb-env/bin/activate
   # conda
   conda create -n cmb-env python=3.12 pip
   conda activate cmb-env
   # venv
   python -m venv cmb-env
   source cmb-env/bin/activate
   ```

2. Install the correct PyTorch version for your hardware. Look up the exact installation command on the
   [PyTorch website](https://pytorch.org/get-started/locally/). Here is an **example** command for
   NVIDIA GPUs with CUDA 12.6 support.

   ```bash
   # NOTE: PyTorch website may use pip3.
   # Inside virtual environment pip and pip3 are the same.
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

   # Or use uv for faster installation!
   uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126
   ```

3. Install Cere-MEG-Bellum and rest of the dependencies from PyPI.

   ```bash
   pip install "cmb[viz]"

   # Or use uv for faster installation!
   uv pip install "cmb[viz]"
   ```

   This installs the core package plus [PyVista](https://docs.pyvista.org/) for 3D visualization. If you don't need 3D views (normal/inflated) and only want flatmaps, you can use `pip install cmb` instead.

   To use the non-blocking Qt window (`backend="pyvistaqt"` in `plot_normal` / `plot_inflated`), install `pip install "cmb[viz-qt]"`, which adds [pyvistaqt](https://qtdocs.pyvista.org/) and the PySide6 Qt binding. If you prefer another Qt binding (e.g. PyQt6), install `pip install "cmb[viz]" pyvistaqt pyqt6` instead.

## Quick start

See [`examples/example_script.py`](https://github.com/johnsam7/ceremegbellum/blob/main/examples/example_script.py) for a complete end-to-end example using the MNE sample dataset.

<!-- docs-end -->

## For developers

### Installation for development

Follow steps 1 and 2 from regular installation, then install the package from source with all optional dependencies and developer tools:

```bash
git clone https://github.com/johnsam7/ceremegbellum.git
cd ceremegbellum

pip install -e ".[dev,viz-qt]"
# or
uv pip install -e ".[dev,viz-qt]"
```

`-e` flag stands for editable mode (changes to source code will be reflected immediately).

### Running tests

```bash
# Runs all the tests, including those that need data.
pytest tests/

# Runs only the tests that don't need data (and are faster).
pytest tests/ -m "not requires_data"
```

### Building the documentation

The documentation is built with [Sphinx](https://www.sphinx-doc.org/) and hosted on
[Read the Docs](https://ceremegbellum.readthedocs.io). The front page is generated from this README,
and the API reference from the NumPy-style docstrings. The documentation dependencies are included in
the `dev` extra.

```bash
cd docs
make html  # on Windows use 'make.bat html'
```

Then view the built html documentation by opening file `docs/build/html/index.html` in a web browser.

### Type checking, linting, and formatting

```bash
# Type checking
pyright

# Linting
ruff check .
# Fixing linting errors
ruff check --fix .

# Checking formatting
ruff format --check .
# Fixing formatting
ruff format .
```

<!-- docs-license -->

## License

CMB is licensed under the [MIT License](https://github.com/johnsam7/ceremegbellum/blob/main/LICENSE).

Copyright (c) 2021-2026, authors of CMB. All rights reserved.
