Cere-MEG-Bellum (CMB)

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 changes are possible. Please report any issues or feature requests on the GitHub issue tracker.

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

Documentation

The full documentation, including the API reference, is available at ceremegbellum.readthedocs.io.

Requirements

• Python >= 3.11
• nnU-Net (v1) (installed automatically as a dependency)
• FreeSurfer (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 (recommended!), venv or conda. uv and conda are good options because they can also manage the Python version without depending on system Python.

   # 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. Here is an example command for NVIDIA GPUs with CUDA 12.6 support.

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

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

   This installs the core package plus PyVista 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 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 for a complete end-to-end example using the MNE sample dataset. It is also rendered on the Examples page of the documentation.

The example works with both current MNE-Python releases and the upcoming release that adds mne.setup_subcortical_source_space, and picks the source space layout from the installed version:

• Current MNE-Python: cmb.setup_full_source_space gives [cortex, cerebellum].
• Upcoming MNE-Python: mne.setup_source_space(...) + mne.setup_subcortical_source_space(...) gives a mixed source space [lh, rh, cerebellum].

Both give the same forward solution. In either layout the cerebellum is the last source space, fwd["src"][-1]. To plot the cortex of a mixed source space with the CMB plotting functions, join the hemispheres with cmb.join_cortical_source_spaces(fwd["src"][:2]).

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:

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

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

-e flag stands for editable mode (changes to source code will be reflected immediately). The dev extra has the test, lint and type-checking tools, and docs has the tools for building the documentation.

Running tests

# 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 and hosted on Read the Docs. The front page is generated from this README, and the API reference from the NumPy-style docstrings.

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

# Type checking
pyright

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

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

License

CMB is licensed under the MIT License.

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