pyAvalanches: A Python Package for Analyzing Spatiotemporal Propagation in Neuronal Avalanches

arXiv:2609.11530 · q-bio.NC · Submitted 2026-09-10 · Read on arXiv

Listen

Transcript

Introduction to the show: ident: Genomics Radio. Generated commentary on the latest computational biology and genomics papers.

Ines: We're looking at the paper: "pyAvalanches: A Python Package for Analyzing Spatiotemporal Propagation in Neuronal Avalanches".

Marcus: Here's the gist of the paper. The paper introduces pyAvalanches, an open-source Python package designed to provide an end-to-end pipeline for detecting, characterizing, and analyzing neuronal avalanches from electrophysiological recordings like EEG.

Ines: This tool addresses the reproducibility issues in existing research by standardizing the analysis workflow and incorporating the computation of Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns.

Marcus: Core Objectives and Innovation The primary aim of pyAvalanches is to characterize the spatiotemporal organization of activity propagation during avalanches.

Ines: The core innovation of pyAvalanche is the computation of Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns.

Title and authors: Ines: We're looking at this paper, "pyAvalanches: A Python Package for Analyzing Spatiotemporal Propagation in Neuronal Avalanches," and the authors are Marzullia, Angiolellib, Manninoa, Demurub, Sorrentino, and Corsia.

Marcus: They’ve built this open-source Python package to give researchers a standardized way to do the avalanche analysis from electrophysiological data like EEG.

Ines: The title highlights that the main goal is characterizing spatiotemporal propagation, which means tracking how activity moves across different parts of the brain and over time.

Yuki: That suggests they are moving beyond just counting events to understanding the actual pattern of propagation in these cascades.

Marcus: Exactly, it’s about mapping out that sequence and location aspect rather than just getting basic statistics like size or duration distributions.

The paper's summary: Ines: Basically, the paper introduces pyAvalanches as an end-to-end pipeline so researchers don't have to build their analysis scripts from scratch every time.

Marcus: It starts with detecting these avalanches from recordings, then it computes what they call Avalanche Transition Matrices or ATMs to map out those propagation patterns.

Ines: These ATMs are key because they let them derive network-based metrics that link the physical topology of brain regions to the dynamics of the avalanche.

Yuki: So it bridges the gap between studying how neurons fire and understanding how brain networks organize themselves during these events, which is a big connection.

Marcus: The whole architecture is modular, so you can just plug in what you need, from detection to metrics extraction using scikit-learn compatible transformers.

The paper's improvements: Ines: One of the main things they improved is making it standardized and end-to-end, which fixes a lot of the fragmentation issues that have been slowing down research.

Marcus: They specifically introduced the computation of ATMs using two methods: the standard conditional probability model and a weighted-stochastic formulation.

Yuki: That means they’re not just looking at one way to model propagation, but checking if different mathematical approaches give you different pictures of where the activity is going.

Ines: And beyond the matrices, they use graph-theoretic metrics from those ATMs, like node centrality and strength to find functional hubs within the dynamic network.

Marcus: That allows you to quantify specific topological properties of how activity propagates through a system, which is useful for predicting what kind of network structure might support certain behaviors.

Conclusion: Ines: So, the paper wraps up by showing how this package can be used for group-level analysis on public datasets, generating a group-averaged ATM heatmap to compare propagation patterns across different conditions.

Marcus: The implication here is that you can get a clear visual comparison of large-scale spatiotemporal patterns between different clinical populations just by looking at these matrices.

Yuki: For the wider context, this tool helps us see if the underlying dynamics of neuronal avalanches are consistent across different groups, which supports theories about brain organization in health versus disease.

Ines: And for future work, they plan to add more metrics for both avalanche properties and network topology, and they also want to integrate information from neuroimaging data.

Marcus: It’s a solid step forward by providing this standardized framework; it makes the complex analysis of these cascades much more accessible to a broader community.

Sorbonne University Brain Institute ICM Inria Inserm AP-HP Hôpital de la Pitiére Salpˆetriž Paris France Department of Medical Motor and Wellness Sciences University of Naples Parthenope Institute of Systems Neuroscience Aix-Marseille University INSERM UMR1106

q-bio.NC

Submitted: 2026-09-10

Updated: 2026-10-29

License: http://creativecommons.org/licenses/by/4.0/

Importance score: 92/100

The gist: The paper introduces pyAvalanches, an open-source Python package designed to provide an end-to-end pipeline for detecting, characterizing, and analyzing neuronal avalanches from electrophysiological

Key concepts

Neuronal Avalanches: These are sudden bursts of neuronal activity that propagate through a neural circuit like a chain reaction. They are studied to understand how information moves through the brain, often relating to critical dynamics and system organization in neural networks.
Avalanche Transition Matrices (ATMs): ATMs are matrices computed from avalanche data that map the spatiotemporal propagation patterns of activity. They show which regions tend to excite or be excited by other regions during an avalanche, revealing the underlying connectivity and organization of neural interactions.
Network-based Metrics: These are statistical measures derived directly from the ATMs using graph theory. By analyzing these metrics, researchers can quantify the topology of dynamic networks—identifying functional hubs and understanding how activity propagates through specific structural connections in the brain.

Terminology

Neuronal Avalanches — 26× in this paper · explained in 2 episodes
Core — 13× in this paper · explained in 2 episodes
Avalanche Transition Matrix — 5× in this paper
Brain-Computer Interfaces — 3× in this paper
Transformer — 3× in this paper · explained in 2 episodes
Transformers — 3× in this paper · explained in 2 episodes
Italian National Recovery and Resilience Plan — 2× in this paper
Benchmarking — 1× in this paper · explained in 4 episodes
Composition — 1× in this paper · explained in 2 episodes
Homogeneity — 1× in this paper · explained in 2 episodes
Unified Framework — 1× in this paper · explained in 6 episodes

Summary

The paper introduces pyAvalanches, an open-source Python package designed to provide an end-to-end pipeline for detecting, characterizing, and analyzing neuronal avalanches from electrophysiological recordings like EEG. This tool addresses the reproducibility issues in existing research by standardizing the analysis workflow and incorporating the computation of Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns.

Core Objectives and Innovation

The primary aim of pyAvalanches is to characterize the spatiotemporal organization of activity propagation during avalanches. The core innovation of pyAvalanche is the computation of Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns. Building on this, the package derives network-based metrics from the ATMs, bridging the study of the topology and organization of underlying dynamical interactions with network neuroscience adopting the framework of neuronal avalanches. The entire workflow is encapsulated in a modular and scikit-learn compatible architecture.

Analysis Pipeline Functionalities

pyAvalanches is built around four main core functionalities. These include:

Avalanche detection, which identifies neuronal avalanches from multi-channel time-series data (e.g., EEG, MEG, ECoG) with configurable parameters for event thresholding and temporal binning.
Avalanches Transition Matrices computation, which characterizes the propagation of activity during avalanches using two distinct methods: the standard conditional probability model and the weighted-stochastic formulation.
Network analysis, which computes graph-theoretic metrics directly from the generated ATMs using specialized libraries like Brain Connectivity Toolbox and NetworkX.
Results management and reporting, which provides dedicated data containers to systematically organize results and includes a function for the automated generation of comprehensive HTML reports.

Software Architecture and Compatibility

pyAvalanches is implemented with a modular, sequential pipeline architecture where each stage is encapsulated in its own pipeline object. The core workflow divides into distinct stages for each functionality described above (avalanche detection, ATM computation, and metrics extraction) each with a consistent.process method. The software is built upon the standard Python scientific computing stack, with key dependencies including NumPy, SciPy, and matplotlib. Furthermore, the ATM pipeline includes scikit-learn compatible transformers, allowing the resulting matrices to be directly extracted and vectorized as features that can be fed into machine learning classifiers. The package supports both continuous (resting-state) and epoched (taskrelated) data, which can be provided as NumPy arrays or as MNE-Python objects.

Application and Impact

The utility of pyAvalanches is demonstrated through an illustrative group-level analysis on a public resting-state EEG dataset comparing propagation patterns across different clinical populations. The package facilitates reproducible research, enables the development of novel avalanche-based biomarkers, and makes complex avalanche analysis accessible to a broader scientific community. By providing a user-friendly, tested, and extensible tool, pyAvalanches facilitates reproducible research. The package is fully documented and distributed via the Python Package Index (PyPI). Future development will focus on adding new metrics, for both avalanche properties and network topology, including integrating information from neuroimaging data. The package creates a new bridge between the study of neuronal avalanches and network neuroscience through the integrated computation of ATMs and the subsequent application of graph-theoretic metrics. The package’s integration with scikit-learn allows for the use of new ATM derived features in predictive models for tasks such as classifying clinical populations, tracking disease progression, or decoding cognitive states.

Illustrative Workflow Example

To demonstrate a typical end-to-end workflow, the analysis follows a three-stage process: per-subject processing, group-level aggregation, and result visualization. The core code iterates through each subject’s data using MNE-Python and applies a sequence of pyAvalanches pipelines to detect avalanches (AvalanchePipeline), compute the related ATMs (ATMPipeline), and extract network metrics (NetworkMetricsPipeline). The results from all stages are encapsulated within a Subject object. Once all individuals are processed, the list of Subject objects is aggregated into a single GroupResults container, which serves as the entry point for all subsequent group-level analyses. This container is then used to generate key summary outputs, such as plotting distributions and visualizing the mean Avalanche Transition Matrix (ATM) for each condition. The primary output is the group-averaged ATM for each condition, visualized as a heatmap allowing for direct comparison of large-scale spatiotemporal propagation patterns.

Acknowledgments

This work was supported by the French National Research Agency (MANET project, ANR-25-CE33-7747-01), the IRIN (Italian Research Infrastructure for Neuroscience, Project “EBRAINS-Italy”, Next GenerationEU/Italian National Recovery and Resilience Plan (NRRP), M4C2 (Project code IR0000011, CUP B51E22000150006) and Governo Italiano Ministero per lo sviluppo Economico (ACCORDI PER INNOVAZIONE. Approccio User-friendly integrato per Diagnosi, Assistenza e Cura Efficaci—AUDACE grant number B69J23006050007). The funders had no role in study design, data collection and analysis, decision to publish, or preparation of the manuscript.

References

[1] J. M. Beggs and D. Plenz, “Neuronal Avalanches in Neocortical Circuits”, en, The Journal of Neuroscience, vol. 23, no. 35, pp. 11 167–11 177, Dec. 2003.

[2] J. M. Beggs, “The Criticality Hypothesis: How Local Cortical Networks Might Optimize Information Processing”, Philosophical Transactions: Mathematical, Physical and Engineering Sciences, vol. 366, no. 1864, pp. 329–343.

[3] L. Cocchi, L. L. Gollo, A. Zalesky, and M. Breakspear, “Criticality in the brain: A synthesis of neurobiology, models and cognition”, en, Progress in Neurobiology, vol. 158, pp. 132–152.

[4] P. Sorrentino et al., “The structural connectome constrains fast brain dynamics”, en, eLife, vol. 10, e67400.

[5] M.-C. Corsi et al., “Measuring neuronal avalanches to inform brain-computer interfaces”, en, iScience, vol. 27, no. 1, p. 108 734.

[6] C. Mannino, P. Sorrentino, M. Chavez, and M.-C Corsi, Neuronal avalanches as a predictive biomarker for guiding tailored BCI training programs, en, Jun. 2025.

[7] A Romano et al., “Topological changes of fast large-scale brain dynamics in mild cognitive impairment predict early memory impairment: A resting-state, source reconstructed, magnetoencephalography study”, Neurobiology of Aging, vol.

Improvements for AI systems

Improve AI systems to include an end-to-end pipeline for neuronal avalanche analysis from electrophysiological recordings like EEG, MEG, and ECoG. This allows AI models to directly ingest raw neurophysiological data and extract core statistical characterization like size and duration distributions automatically.
Develop AI systems capable of computing Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns between brain regions. This enables the creation of network-based metrics from ATMs, bridging the study of the topology and organization of the underlying dynamical interactions with network neuroscience.
Create AI systems that utilize graph-theoretic metrics derived from ATMs, such as node centrality and strength. This allows for quantifying functional hubs and topological properties of the dynamic networks through which activity propagates, which can then be used in predictive models.
Enhance AI systems by integrating ATM features with scikit-learn compatible transformers. This enables the direct use of ATM features in classification and other predictive models for tasks like classifying clinical populations, tracking disease progression, or decoding cognitive states.
Implement a modular software architecture where distinct stages—avalanche detection, ATM computation, and network metrics extraction—are encapsulated in separate pipeline objects. This modularity allows users to execute only required portions of the analysis for specific research needs.

Abstract

The analysis of neuronal avalanches offers insights into brain dynamics utilizing the framework of criticality, but the reproducibility and comparability of studies are limited by the use of fragmented, lab-specific scripts. To address this issue, we introduce pyAvalanches, an open-source Python package providing a standardized, end-to-end pipeline for avalanche analysis from electrophysiological recordings (e.g., electroencephalography-EEG). Starting from the detection of neuronal avalanches the package provides their core statistical characterization, including size and duration distributions. Beyond this, the main aim of pyAvalanches is to characterize the spatiotemporal organization of activity propagation during avalanches. To this end, the core innovation of pyAvalanches is the compuation of Avalanche Transition Matrices (ATMs) to map spatiotemporal propagation patterns. Building on this, the package derives network-based metrics from the ATMs, bridging the study of the topology and organization of the underlying dynamical interactions with network neuroscience adopting the framework of neuronal avalanches. The entire workflow is encapsulated in a modular and scikit-learn compatible architecture. We demonstrate the utility of pyAvalanches through an illustrative group-level analysis on a public resting-state EEG dataset, comparing propagation patterns across different clinical populations. By providing a user-friendly, tested, and extensible tool, pyAvalanches facilitates reproducible research, enables the development of novel avalanche-based biomarkers, and makes complex avalanche analysis accessible to a broader scientific community. The package is fully documented and distributed via the Python Package Index (PyPI).