Neuronal Avalanche Detection and Criticality Analysis for Resting-State fMRI
A reference-quality Python library implementing the complete pipeline for detecting neuronal avalanches and assessing brain criticality from resting-state fMRI data. The core methodological innovation is defining avalanches as connected components in a spatiotemporal graph where spatial adjacency is informed by individual structural connectivity — replacing the standard temporal-only approach that conflates spatially disconnected activations.
# Core installation (numpy, scipy, matplotlib only)
pip install graphavalanche
# Full installation with neuroimaging integration
pip install "graphavalanche[full]"
# Development installation (editable)
git clone https://github.com/YOUR_USERNAME/graphavalanche.git
cd graphavalanche
pip install -e ".[full,dev]"import numpy as np
from graphavalanche import detect_avalanches, adjacency_from_sc, analyze_criticality
from graphavalanche.clinical import subject_criticality_profile
# Load your data
ts = np.load('timeseries_schaefer100.npy') # (100, 300) — parcellated rs-fMRI
sc = np.load('sc_schaefer100_sift2.npy') # (100, 100) — SIFT2-filtered SC
# Build spatial adjacency from structural connectivity
adj = adjacency_from_sc(sc)
# Full per-subject criticality profile
profile = subject_criticality_profile(ts, adj, subject_id='sub-01')
# Group comparison (e.g., controls vs COVID-ICU survivors)
from graphavalanche.clinical import group_comparison
results = group_comparison(ctrl_profiles, patient_profiles,
group_names=('Controls', 'COVID-ICU'))graphavalanche/
├── __init__.py # Clean public API
├── detection.py # Spatiotemporal graph construction + connected components
├── powerlaw.py # Discrete MLE + doubly-truncated (Deluca & Corral 2013)
├── criticality.py # Branching ratio (conventional + MR estimator)
├── shape_collapse.py # Automated γ optimization for shape collapse
├── surrogates.py # 4 surrogate types (phase, multivariate, IAAFT, circular)
├── atm.py # Avalanche Transition Matrices (Sorrentino et al. 2021)
├── sensitivity.py # Threshold parameter sweep
├── clinical.py # Per-subject profiles + group comparison
└── viz.py # Publication-quality visualization
Avalanches are defined as connected components in a spatiotemporal graph G(V, E) where vertices are suprathreshold (node, time) pairs and edges connect spatially adjacent, temporally contiguous pairs. This correctly separates simultaneous but spatially disconnected activations that the classic temporal-only method (Shriki et al. 2013) merges into single "mega-avalanches."
Four spatial adjacency definitions are supported: structural connectivity (SIFT2 tractography), coordinate distance (k-d tree), parcellation topology (shared voxel boundaries), and full connectivity (which recovers the classic method as a special case).
Three event definitions following Xu et al. (2022): above-threshold, threshold crossing, and local peak.
Discrete MLE via Hurwitz zeta function following Clauset, Shalizi & Newman (2009), with doubly-truncated fitting (Deluca & Corral 2013, p ≥ 0.20) to handle the finite-size effects inherent to parcellation-based fMRI. Bootstrap goodness-of-fit testing with ≥2,500 samples for ε = 0.01 precision. Full comparison suite against truncated power-law, lognormal, exponential, stretched exponential (Weibull), and gamma distributions via Vuong's likelihood ratio test. Automated x_min sensitivity analysis.
Branching ratio estimation via both the conventional method and the MR estimator (Wilting & Priesemann 2018), which is subsampling-robust and thus strongly preferred for fMRI. Size-duration scaling ⟨S⟩ ~ D^γ, crackling noise exponent relation γ = (α-1)/(τ-1) (Sethna et al. 2001), DCC κ, automated shape collapse with γ optimization producing three independent γ estimates (γ_pred, γ_fit, γ_collapse), and functional E/I ratio proxy.
Four surrogate types targeting distinct null hypotheses: phase-shuffled (H₀: linear autocorrelation), multivariate phase (H₀: linear multivariate dynamics), IAAFT (H₀: linear Gaussian + static nonlinearity), and circular time-shift (H₀: no inter-regional synchrony). Integrated pipeline generates surrogates, detects avalanches, computes all metrics, and reports p-values and z-scores.
Per-subject criticality profiles mapping each subject onto the subcritical–critical–supercritical spectrum. Group comparison with Mann-Whitney U, Welch's t-test, Cohen's d, and rank-biserial correlation. Avalanche Transition Matrices with structural connectivity correlation.
Core (required): numpy ≥ 1.22, scipy ≥ 1.9, matplotlib ≥ 3.5
Full (optional): nilearn, mrestimator, powerlaw, networkx
- Tagliazucchi et al. (2012) Front Physiol 3:15
- Shriki et al. (2013) J Neurosci 33:7079–7090
- Clauset, Shalizi & Newman (2009) SIAM Rev 51:661–703
- Wilting & Priesemann (2018) Nat Commun 9:2325
- Sorrentino et al. (2021) eLife 10:e67400
- Xu, Feng & Yu (2022) Hum Brain Mapp 43:2534–2553
- Friedman et al. (2012) Phys Rev Lett 108:208102
- Deluca & Corral (2013) Acta Geophys 61:1351–1394
- Fontenele et al. (2019) Phys Rev Lett 122:208101
- Marshall et al. (2016) Front Physiol 7:250
MIT