Usage#

This section explains how to use CaliBrain for simulating data, running experiments, and analyzing uncertainty calibration.

What can I do with CaliBrain?#

  1. Simulate or load a leadfield matrix.

  2. Simulate synthetic dipole activity.

  3. Simulate sensor-level measurements.

  4. Solve the inverse problem to reconstruct sources.

  5. Quantify uncertainty and visualize calibration results.

Running Experiments#

To run the entire benchmark with default settings:

python examples/run_experiments.py

Experiment Configuration Example:

data_param_grid_meg = {
    "subject": ["CC120166"], # "CC120166", "CC120264", "CC120309", "CC120313",
    "nnz": [1, 10, 100],
    "orientation_type": ["fixed"], # "fixed", "free"
    "alpha_SNR": [0.0, 0.3, 0.5, 0.7, 0.99],
}

data_param_grid_eeg = {
    "subject": ["fsaverage"], # "caliBrain_fsaverage", "fsaverage",
    "nnz": [1, 10, 100],
    "orientation_type": ["fixed"], # "fixed", "free"
    "alpha_SNR": [0.0, 0.3, 0.5, 0.7, 0.99],
}

gamma_map_params = {
    "init_gamma": [0.001], #  0.001, 1.0, or tuple for random values (0.001, 0.1)
    "noise_type": ["oracle"], # "baseline", "oracle", "joint_learning", "CV"
}

eloreta_params = {
    "noise_type": ["oracle"],
}

estimators = [
    (gamma_map, gamma_map_params, data_param_grid_meg),
    (eloreta, eloreta_params, data_param_grid_meg),
    (gamma_map, gamma_map_params, data_param_grid_eeg),
    (eloreta, eloreta_params, data_param_grid_eeg),
]

API Overview#

Core components of CaliBrain: - SourceSimulator: Simulate source activity. - SensorSimulator: Simulate sensor-level measurements. - LeadfieldBuilder: Setup and simulate leadfields. - SourceEstimator: Solve inverse problems (e.g., Gamma-MAP, eLORETA). - UncertaintyEstimator: Analyze confidence intervals and calibration. - MetricEvaluator: Compute evaluation metrics for model performance. - Visualizer: Plot calibration results, source estimates, and uncertainty. - Benchmark: Automate experiment running and results collection.

Examples#

Examples are located in the examples/ folder: - leadfield_builder_example.py: Simulate or load leadfields. - run_experiments.py: Run benchmark experiments for calibration.

Leadfield Simulation#

To simulate or load a leadfield matrix:

python examples/run_experiments.py --config configs/leadfield_sim_cfg.yml --log-level INFO

Arguments: - --config: Path to the YAML configuration file (required). - --log-level: Logging level (optional: DEBUG, INFO, WARNING, etc.).

Configuration Options (`configs/leadfield_sim_cfg.yml`): - Data paths: Set paths for data storage and subject directories. - Source Space: Define source space (default: ico4 spacing, white surface). - BEM Model: Specify three-layer head model (brain, skull, scalp). - Montage: Set EEG sensor positions (e.g., easycap-M43 or custom .fif). - Info: Define EEG/MEG measurement info (e.g., sfreq=100 Hz, EEG modality). - Forward Solution: Define dipole orientations (fixed or free). - Leadfield Matrix: Extract and save for efficient simulation.

Generated Files: - {subject}-src.fif (Source Space) - {subject}-bem.fif (BEM Model) - {subject}-montage.fif (Montage) - {subject}-info.fif (Measurement Info) - {subject}-fixed-fwd.fif or {subject}-free-fwd.fif (Forward Solution) - {subject}-leadfield-fixed.npz or {subject}-leadfield-free.npz (Leadfield Matrix)

Example: Leadfield Simulation#

from calibrain import LeadfieldBuilder
from calibrain.utils import load_config

config = load_config("configs/leadfield_sim_cfg.yml")
simulator = LeadfieldBuilder(config=config)
leadfield = simulator.simulate()