CaliBrain: A Python toolbox for uncertainty estimation, calibration, and benchmarking in Bayesian EEG/MEG inverse source imaging

Le résumé fourni par la source

Overview Inverse source imaging is an ill-posed problem: different source configurations can explain the same sensor data. CaliBrain addresses a central question in Bayesian source imaging: are posterior uncertainty estimates empirically reliable? The toolbox provides simulation-based workflows for generating source activity, propagating it through forward models, reconstructing posterior source estimates, quantifying empirical coverage, and evaluating recalibration maps under controlled experimental conditions. 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. Example The example below simulates one inverse problem, reconstructs sources, and plots empirical coverage before and after isotonic recalibration. import matplotlib.pyplot as plt import numpy as np from calibrain import ( BMN, LeadfieldBuilder, SensorSimulator, SourceEstimator, SourceSimulator, UncertaintyCalibrator, UncertaintyEstimator, ) # Simulate a small fixed-orientation inverse problem. x_true, _ = SourceSimulator().simulate(n_sources=64, nnz=4, seed=0) # Build a random leadfield, simulate sensor data, and reconstruct sources. L = LeadfieldBuilder(leadfield_dir="unused").get_leadfield( retrieve_mode="random", orientation_type="fixed", n_sensors=20, n_sources=x_true.shape[0], ) _, y_noisy, noise, _ = SensorSimulator().simulate(x_true, L, seed=0) result = SourceEstimator(solver=BMN, noise_var=float(np.var(noise))).fit(L, y_noisy).predict() # Compute calibration curves before and after isotonic recalibration. nominal_coverages = np.linspace(0.0, 1.0, 11) uncertainty = UncertaintyEstimator(nominal_coverages=nominal_coverages) calibrator = UncertaintyCalibrator(nominal_coverages=nominal_coverages) posterior_var = uncertainty.posterior_variance_from_cov(result["posterior_cov"]) pre_curve = uncertainty.calibration_curve_intervals_aggregated( x_true=x_true, x_hat=result["posterior_mean"], posterior_var=posterior_var, ) mapping = calibrator.fit_mapping( x_true=x_true, x_hat=result["posterior_mean"], posterior_var=posterior_var, ) post_curve = calibrator.evaluate_with_mapping( x_true=x_true, x_hat=result["posterior_mean"], posterior_var=posterior_var, mapping=mapping, ) # Plot nominal vs empirical coverage. plt.plot([0, 1], [0, 1], "--", color="0.5", label="perfect calibration") plt.plot(pre_curve["nominal_coverages"], pre_curve["empirical_coverages"], "o-", label="before calibration") plt.plot(post_curve["nominal_coverages"], post_curve["empirical_coverages"], "o-", label="after calibration") plt.xlabel("Nominal coverage") plt.ylabel("Empirical coverage") plt.legend() plt.tight_layout() plt.show() Contributing Contribution guidelines are available in `CONTRIBUTING.md`. The full development guide is also available in the documentation. ## Citation If you use CaliBrain in academic work, please cite the software archive: Orabe, Mohammad, Huseynov, Ismail T., Nagarajan, Srikantan, & Haufe, Stefan. (2026). CaliBrain: A Python toolbox for uncertainty estimation and calibration in EEG/MEG inverse source imaging (v1.0.2). Zenodo. https://doi.org/10.5281/zenodo.20721580 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. Relationship to related software CaliBrain complements broader neurophysiology analysis libraries, general uncertainty-calibration toolkits, and standard inverse-solver workflows rather than replacing them. Its scope is narrower and more specific: CaliBrain focuses on simulation-based uncertainty estimation and calibration for EEG/MEG inverse source imaging, including source-level intervals, local covariance-based ellipsoids, empirical coverage analysis, and recalibration across controlled evaluation conditions. Installation From PyPI: python -m pip install calibrain From a local checkout: 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`.

Ce résumé expose les affirmations des auteurs. BNTIC ne l’interprète pas comme une validation indépendante des résultats.