v1.0.3

CaliBrain v1.0.3

This release focuses on documentation hardening and metadata cleanup.

Highlights

• Strengthened the tutorial sequence and Sphinx-Gallery structure.
• Added post_fixed calibration examples for fixed-split recalibration workflows.
• Unified data generation tutorials around DataGenerator.
• Removed deprecated solver components from the active pipeline.
• Added a compact README example that shows calibration before and after isotonic recalibration.
• Updated documentation home pages, gallery ordering, and release-facing metadata.

Notes

A new Zenodo DOI has not yet been minted. The repository currently still references the existing archive DOI until the release archive is created.

v1.0.2

v1.0.2 focuses on documentation and release packaging hardening.

Highlights

• Reworked the installation documentation into separate beginner-oriented guides for PyPI, pip, and conda.
• Simplified documentation navigation by removing redundant topic listings and relying on direct links plus sidebar hierarchy.
• Refined the documentation structure around the current workflow, conceptual overview, glossary, datasets, and runnable tutorial gallery.
• Added Examples using calibrain.XXX sections to API reference pages so core classes and workflow entry points link directly to relevant tutorials.
• Bumped package metadata and citation files to v1.0.2.

Notes

• This release is documentation- and packaging-focused; it does not introduce new calibration algorithms.
• For full details, see the changelog in docs/source/development/changelog.rst.

v1.0.1

• Raised the supported Python version floor to >=3.10 and aligned package metadata, documentation builds, and contributor setup instructions.
• Completed package dependency declarations for wheel-based installation and clean-environment imports.
• Reworked documentation CI so GitHub Actions validates documentation builds while Read the Docs remains the canonical published documentation host.
• Fixed the documentation version switcher to use explicit Read the Docs latest, stable, and tagged release targets.
• Added a PyPI publishing workflow based on published GitHub releases, with manual dispatch retained as a fallback.
• Added Zenodo DOI citation metadata and a root CITATION.cff file with full author metadata and ORCID identifiers.
• Standardized software citation text across the README, documentation landing page, and citation page using full author names and DOI-based software references.
• Added and refined README / documentation landing page badges for PyPI, docs, downloads, license, release, workflow status, and DOI.
• Consolidated the root project README around README.rst and synchronized the documentation landing page with the current package scope and workflow summary.

Documentation and citation

• Documentation: https://calibrain.readthedocs.io/
• DOI: https://doi.org/10.5281/zenodo.20703249
• PyPI: https://pypi.org/project/calibrain/

Citation

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.1). Zenodo. https://doi.org/10.5281/zenodo.20703249

v1.0.0

CaliBrain v1.0.0

Overview

CaliBrain v1.0.0 marks a major consolidation of the package around a stable end-to-end workflow for uncertainty estimation and calibration in EEG/MEG inverse source imaging.

This release promotes the current development pipeline to the supported baseline and formalizes the workflow for data generation, aggregation, calibration, and calibration-figure generation.

Highlights

• Consolidated the supported inverse-solver stack around gamma_map_sflex, gamma_lambda_map_sflex, BMN, and BMN_joint
• Replaced the legacy benchmarking workflow with DataGenerator
• Added explicit workflow modules for:
  • data generation
  • aggregation
  • calibration
• Reworked calibration from within-subject, across-source fitting to pooled source datasets across subjects
• Changed isotonic regression fitting to operate on subject-level splits rather than one subject at a time
• Added support for uncertainty modes pointwise and aggregated
• Added support for free-orientation interval types full_cov and marginal
• Added support for calibration modes precal, post_oracle, post_pooled, post_pooled_mismatch, and post_fixed
• Expanded metric evaluation support for mse, mae, rmse, rmae, mean_posterior_std, emd, mean_signed_deviation, mean_absolute_deviation, max_underconfidence_deviation, and max_overconfidence_deviation
• Standardized manifest-based discovery and downstream aggregated dataset writing for calibration workflows
• Updated the documentation and changelog to reflect the supported workflow and version baseline

Breaking changes

• Removed the legacy benchmarking-based workflow in favor of DataGenerator
• Changed calibration fitting from single-subject source-wise calibration to pooled cross-subject calibration with subject-split isotonic regression
• Standardized the active pipeline around manifest-driven aggregation and calibration outputs
• Removed or deprecated older unsupported solver and method branches from the supported workflow

Workflow summary

calibrain/workflows/data_generation.py

• Runs end-to-end synthetic experiment generation from configuration files
• Resolves solver grids and writes posterior summaries plus manifest entries

calibrain/workflows/aggregation.py

• Reads posterior summaries from the manifest
• Filters runs and writes compact calibration-ready datasets

calibrain/workflows/calibration.py

• Loads aggregated train/eval datasets
• Fits and evaluates calibration mappings and writes calibration summaries

calibrain/workflows/plot_paper_calibration_figures.py

• Collects calibration outputs
• Builds paper-style fixed/free calibration comparison figures

Supported calibration modes

• precal
• post_oracle
• post_pooled
• post_pooled_mismatch
• post_fixed

Supported uncertainty settings

Modes

• pointwise
• aggregated

Free-orientation interval types

• full_cov
• marginal

Notes

• This release establishes the 1.0.0 workflow baseline on main
• Documentation and CI now target Python >=3.10

v0.1.2

CaliBrain v0.1.2 – Major Refactor, Unit Consistency, new Inverse Solver and Evaluation Metrics

This release introduces a complete codebase refactor, improved physical unit handling, and an expanded evaluation framework. This version simplifies the API, improves simulation realism, and adds extensive tools for uncertainty and accuracy analysis.

---

Highlights

New Features

• Modular class-based architecture:
  • SourceSimulator, SensorSimulator, MetricEvaluator, Visualizer
• Added new evaluation metrics:
  • Uncertainty: mean_posterior_std
  • Calibration: mean_calibration_error, max_underconfidence_deviation, max_overconfidence_deviation, mean_absolute_deviation, mean_signed_deviation
  • Spatial Accuracy: emd, jaccard_error, mse
  • Detection Performance: euclidean_distance, f1, accuracy
• Integrated eLORETA as a distributed inverse solution
• Unit-aware plotting with auto-scaled labels for EEG, MEG, and source signals
• Comprehensive tutorials and example notebooks
• Fully restructured and expanded documentation

Improvements

• Refactored simulation pipeline for clarity and modularity
• Improved ERP waveform generation and parameter handling
• Leadfield projection now supports channel filtering and orientation types

Bug Fixes

• Resolved inconsistent unit usage across simulation pipeline (#18):
  • Converted source dipole values from nAm to Am
  • Standardized EEG/MEG output to SI units (V, T)
  • Visualizations now infer appropriate scale (e.g., microvolts, femtotesla)

What's Changed

• Feat: Integrate Real Subject Leadfields by @orabe in #9
• Enhance UncertaintyEstimator class by @orabe in #11
• Spatial cv by @AliHashemi-ai in #14
• All Metrics by @IsmailHuseynov in #13
• Implement Calibration and Uncertainty Metrics for Inverse Solver by @orabe in #15
• Implement Multiple Top-Level Seeds for Benchmark Generalization by @orabe in #16
• Add Alpha-SNR-Based Noise Model for Sensor Signal Simulation by @orabe in #17
• Major Refactor and Feature Expansion of CaliBrain Framework by @orabe in #19

Full Changelog: v0.1.1...v0.1.2

v0.1.1

ERP-like EEG Data Simulation & Enhancements

This release introduces enhancement to the data simulation for a more realistic ERP-like EEG signals. It also includes improvements to noise handling and refactoring of the data simulation pipeline by @orabe (see PR #7).

Key Enhancements:

• ERP-like EEG Data Simulation (Closes #6):
  • Source-Level ERP Generation: Implemented a pipeline to generate plausible ERP signals at selected sources. This involves:
    • Generating band-limited, temporally windowed white noise.
    • Applying Butterworth bandpass filtering.
    • Windowing with a Hanning window (now supporting random length and duration) for smooth onsets/offsets.
    • Normalization and amplitude scaling.
  • Sensor-Level Projection: Projecting simulated source activity to the sensor level using the leadfield matrix.
  • Noise Modeling: Added Gaussian noise to achieve specified Signal-to-Noise Ratios (SNR).
  • Multi-Trial Simulation: Refactored DataSimulator to support multi-trial simulations.
• Improved Noise Handling: Enhanced noise handling in both data simulation and source estimation processes.
• Refactoring:
  • Refactored the ERP signal generation within DataSimulator.
  • Refactored the data parameter grid for more flexible experiment configuration.

Affected Files:

• calibrain/data_simulation.py
• calibrain/benchmark.py
• examples/run_experiments.py

---

Full Changelog: v0.1.0...v0.1.1

v0.1.0 - Initial Release

Initial public release of CaliBrain (v0.1.0)!

This version establishes the core foundation of CaliBrain, a Python package designed for simulating EEG/MEG data and benchmarking Brain Source Imaging (BSI) methods, with a focus on uncertainty estimation.

Core Components:

• LeadfieldSimulator: For simulating leadfield matrices (developed by @orabe).
• DataSimulator: For generating synthetic EEG/MEG data (developed by @orabe).
• SourceEstimator: For estimating source activity, with initial support for the Gamma-MAP method (developed by @orabe).
• UncertaintyEstimator: For estimating uncertainty in source activity (developed by @orabe).
• Benchmark: A class for systematically benchmarking source estimation methods (developed by @orabe).
• utils: A collection of utility functions (developed by @orabe).
• vbfa.py: Implementing Variational Bayes Factor Analysis for noise learning (#2 by @AliHashemi-ai).
• eLORETA_caliBrain.py: eLORETA implementation with posterior covariance matrix estimation (#3 by @IsmailHuseynov).

Contributors:

• @orabe
• @AliHashemi-ai
• @IsmailHuseynov

Full Changelog: https://github.com/braindatalab/CaliBrain/commits/v0.1.0