Metadata-Version: 2.4
Name: calibrain
Version: 1.0.2
Summary: Python framework for uncertainty estimation and calibration in EEG/MEG inverse source imaging
Author-email: Mohammad Orabe <orabe.mhd@gmail.com>, Ismail Huseynov <ismailhuseynov6666@gmail.com>, Srikantan Nagarajan <Srikantan.Nagarajan@ucsf.edu>, Stefan Haufe <haufe@tu-berlin.de>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/braindatalab/CaliBrain
Project-URL: Repository, https://github.com/braindatalab/CaliBrain
Project-URL: Documentation, https://calibrain.readthedocs.io/
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: mne
Requires-Dist: POT
Requires-Dist: nibabel
Requires-Dist: pyyaml
Requires-Dist: pyvistaqt
Requires-Dist: ipywidgets
Requires-Dist: PyQt5
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: matplotlib
Requires-Dist: joblib
Requires-Dist: myst-parser
Provides-Extra: dev
Requires-Dist: pytest==6.2.4; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<8.0.0,>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.1; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.13.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.0; extra == "docs"
Requires-Dist: sphinx-gallery>=0.19.0; extra == "docs"
Dynamic: license-file

CaliBrain
=========

.. image:: https://img.shields.io/pypi/v/calibrain.svg
   :target: https://pypi.org/project/calibrain/
   :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/calibrain.svg
   :target: https://pypi.org/project/calibrain/
   :alt: Supported Python versions

.. .. image:: https://static.pepy.tech/badge/calibrain
..    :target: https://pepy.tech/projects/calibrain
..    :alt: Total downloads
.. 
.. .. image:: https://readthedocs.org/projects/calibrain/badge/?version=latest
..    :target: https://calibrain.readthedocs.io/en/latest/
..    :alt: Documentation status

.. image:: https://img.shields.io/github/license/braindatalab/CaliBrain
   :target: https://github.com/braindatalab/CaliBrain/blob/main/LICENSE
   :alt: License

.. image:: https://img.shields.io/github/v/release/braindatalab/CaliBrain
   :target: https://github.com/braindatalab/CaliBrain/releases
   :alt: Latest GitHub release

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.20703249.svg
   :target: https://doi.org/10.5281/zenodo.20703249
   :alt: DOI

A Python framework for uncertainty estimation and calibration in EEG/MEG inverse source imaging.
Overview
--------

CaliBrain addresses a specific reliability problem in EEG/MEG inverse source
imaging: a posterior estimate is only useful if its uncertainty is
well-calibrated. The package provides a simulation-based workflow for
generating source activity, propagating it through forward models, reconstructing
posterior source estimates, quantifying empirical coverage, and learning
recalibration maps from controlled experiments.

Documentation
-------------

The documentation is hosted on Read the Docs:
https://calibrain.readthedocs.io/

For runnable end-to-end examples, see the tutorials and workflow
documentation on Read the Docs.

Citation
--------

If you use CaliBrain in academic work, please cite the software archive:

``Orabe, Mohammad, Huseynov, Ismail T., Nagarajan, Srikantan, & Haufe, Stefan. (2026). CaliBrain: Python framework for uncertainty estimation and calibration in EEG/MEG inverse source imaging (v1.0.2). Zenodo. https://doi.org/10.5281/zenodo.20703249``

Workflow
--------

The package follows this workflow:

1. generate source-level ground truth under controlled sparsity and amplitude assumptions;
2. project sources to sensors through a leadfield and add noise at defined SNR;
3. reconstruct posterior means and uncertainty summaries with inverse solvers;
4. convert uncertainty summaries into intervals, ellipses, or ellipsoids;
5. compare empirical against nominal coverage;
6. fit isotonic recalibration functions on training splits and evaluate them on held-out splits.

CaliBrain currently supports fixed and free-orientation source models for inverse source imaging methods:
* ``gamma_map_sflex`` for Gamma-MAP reconstruction with sparse basis field expansions;
* ``gamma_lambda_map_sflex`` for the S-FLEX Gamma-MAP variant with joint sparsity and lambda regularization;
* ``BMN`` as a Bayesian minimum norm baseline;
* ``BMN_joint`` as a Bayesian minimum norm variant with joint gamma/lambda learning.

Installation
------------

From PyPI:

.. code-block:: bash

   python -m pip install calibrain

From a local checkout:

.. code-block:: bash

   git clone https://github.com/braindatalab/CaliBrain.git
   cd CaliBrain
   python -m pip install -e .

License
-------

CaliBrain is distributed under the BSD 3-Clause License. See ``LICENSE``.
