BayBrainGrads

Bayesian multimodal brain-gradient analysis for clinical neuroimaging.
Cortical + hippocampal gradients · Full uncertainty quantification · Normative modelling · SC-FC coupling

---

Overview

BayBrainGrads is a Python library for computing, aligning, and statistically analysing brain gradients — the low-dimensional axes of macroscale cortical and hippocampal organisation emerging from resting-state fMRI and diffusion MRI data. It is designed from the ground up for small-sample clinical cohort studies (n ≈ 10–30) where frequentist group comparisons are underpowered and where principled uncertainty quantification is non-negotiable.

The library orchestrates a complete nine-pillar pipeline:

Pillar	Module	Key contribution
1	gradients	BrainSpace diffusion-map embedding with Procrustes alignment to the HCP S1200 template
2	null_models	Spin permutations · MSR · BrainSMASH variogram surrogates · eigenstrapping
3	scfc	Per-region SC–FC Spearman coupling + multilinear gradient model (Vázquez-Rodríguez et al., 2019)
4	bayesian	PyMC v5 hierarchical models with Yeo-network hyperpriors, partial pooling, empirical-Bayes HCP priors, 89 % HDI
5	normative	Z-score deviation maps against HCP S1200 · PCNtoolkit interface · ComBat harmonisation
6	hippocampal	First formal integration of BrainSpace cortical gradients with HippUnfold/HippoMaps hippocampal surface gradients
7	graph	BCTpy wrappers: participation coefficient · module degree z-score · global/local efficiency · modularity Q
8	ml	Nested stratified CV · elastic-net/SVM · SHAP · UMAP; validated for n = 23
9	viz	Publication-quality figures via surfplot, nilearn, seaborn, pyvista

Scientific novelty

BayBrainGrads addresses five open gaps in the gradient neuroimaging literature simultaneously:

1. No prior Bayesian analysis of cortical gradient data in any population.
2. No gradient analysis of ICU or critical-illness populations.
3. No SC–FC gradient coupling measurement in SARS-CoV-2.
4. No formal integration of BrainSpace cortical gradients with HippUnfold/HippoMaps hippocampal surface gradients in a joint framework.
5. No gradient-based neuroimaging study of the COVID-19 ICU cohort.

---

Installation

# Core only (NumPy, SciPy, pandas, matplotlib)
pip install baybraingrads

# Full install — all optional extras except CUDA backend
pip install "baybraingrads[all]"

# Specific extras
pip install "baybraingrads[gradients,bayesian,normative]"
pip install "baybraingrads[hippocampal,viz]"

Optional dependencies that require manual installation

Some packages are not yet available on PyPI and must be installed separately:

# HippoMaps (hippocampal atlas and template data)
pip install git+https://github.com/MICA-MNI/hippomaps.git

# eigenstrapping (spatial null models for surface data)
pip install git+https://github.com/StuartJohnston/eigenstrapping.git

# HippUnfold (hippocampal surface reconstruction — also available as Singularity container)
pip install hippunfold

---

Quick start

import baybraingrads as bbg

# 1. Load FC and SC matrices (pre-computed from rs-fMRI / dMRI)
fc = bbg.io.load_connectivity("fc_matrix.npz", kind="FC")
sc = bbg.io.load_connectivity("sc_matrix.npz", kind="SC")

# 2. Load Schaefer-200 / Yeo-7 parcellation metadata
parc = bbg.parcellation.load_schaefer(n_parcels=200, yeo_networks=7)

# 3. Compute gradients aligned to the HCP S1200 template
result = bbg.gradients.compute_gradients(
    fc, parcellation=parc, n_components=3, align_to_hcp=True
)

# 4. Compute summary metrics per Yeo network
metrics = bbg.metrics.network_metrics(result, parcellation=parc)

# 5. Spin-test: is G1 correlated with a brain map of interest?
p_spin = bbg.null_models.spin_test(
    result.gradients[:, 0], myelin_map, parcellation=parc, n_perm=10_000
)

# 6. Bayesian normative deviation against the HCP reference
norm_result = bbg.normative.compute_z_scores(
    Y           = group_gradients[:, 0],   # shape (n_subjects, n_parcels)
    mu_ref      = hcp_mean_g1,
    sd_ref      = hcp_std_g1,
    parcellation= parc,
)
deviation_map = bbg.normative.group_deviation_map(norm_result, statistic="mean_z")

# 7. Bayesian one-sample model (normative deviation)
bayes_result = bbg.bayesian.fit_normative_deviation_model(
    Y      = group_gradients[:, 0],
    mu_ref = hcp_mean_g1,
    sd_ref = hcp_std_g1,
)

---

Documentation

Full API reference, tutorials, and example galleries are available at
📖 baybraingrads.readthedocs.io

---

Design principles

Pipeline composability. Outputs of each module are structured dataclass objects (e.g., GradientResult, SCFCCouplingResult, NormativeDeviationResult) that carry provenance metadata and serve directly as inputs to downstream modules — no intermediate format conversions needed.

Spatial autocorrelation is always respected. Every statistical comparison involving a brain map uses one of the four validated null-model families (spin permutations, MSR, BrainSMASH, eigenstrapping) by default.

Small-n first. The statistical stack is designed around n ≈ 23: Bayesian models with partial pooling and empirical-Bayes priors from HCP, normative deviation against a healthy reference rather than between-group t-tests, and LOOCV / nested CV for ML.

Lazy imports. Sub-modules are loaded only when accessed (import baybraingrads as bbg; bbg.viz), keeping startup time low when only part of the pipeline is needed.

---

Citation

If you use BayBrainGrads in your research, please cite:

@software{baybraingrads2025,
  author    = {{BayBrainGrads Contributors}},
  title     = {{BayBrainGrads: Bayesian multimodal brain-gradient analysis for clinical neuroimaging}},
  year      = {2025},
  url       = {https://github.com/your-lab/baybraingrads},
  version   = {0.1.0},
}

Please also cite the foundational works this library builds upon:

• Margulies et al. (2016) PNAS 113:12574–12579 — cortical gradient framework
• Vos de Wael et al. (2020) Commun Biol 3:103 — BrainSpace
• Vázquez-Rodríguez et al. (2019) PNAS 116:21219–21227 — SC–FC coupling
• DeKraker et al. (2022) eLife 11:e77945 — HippUnfold
• DeKraker et al. (2025) Nature Methods — HippoMaps
• Alexander-Bloch et al. (2018) NeuroImage 178:540–551 — spin permutations
• Markello & Mišić (2021) NeuroImage 236:118052 — BrainSMASH
• McElreath (2020) Statistical Rethinking, 2nd ed. — Bayesian conventions

---

Contributing

Contributions, bug reports, and feature requests are welcome.
Please read CONTRIBUTING.md before opening a pull request.

---

License

MIT — see LICENSE.