🧠 neuroscience

CROCOpy - A Python toolbox for the analysis of CRitical Oscillations and COnnectivity

CROCOpy is a lightweight, device-agnostic Python toolbox designed to simplify the analysis of continuous electrophysiological recordings by providing comprehensive methods for computing neuronal oscillations, functional connectivity metrics, and critical dynamics on both CPU and GPU platforms.

Original authors: Myrov, V., Siebenhuhner, F., Wang, S. H., Arnulfo, G., Juvonen, J. J., Roascio, M., Burlando, G., Suleimanova, A., Repo, J., Liu, W., Palva, S., Palva, J. M.

Published 2026-02-18

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Myrov, V., Siebenhuhner, F., Wang, S. H., Arnulfo, G., Juvonen, J. J., Roascio, M., Burlando, G., Suleimanova, A., Repo, J., Liu, W., Palva, S., Palva, J. M.

Original paper licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). ⚕️ This is an AI-generated explanation of a preprint that has not been peer-reviewed. It is not medical advice. Do not make health decisions based on this content. Read full disclaimer

Imagine your brain isn't just a static computer, but a bustling, chaotic city. Sometimes the traffic flows smoothly (order), sometimes it's gridlocked (disorder), and most of the time, it's dancing right on the edge between the two. This "edge" is where the magic happens, and scientists call it Criticality.

The paper you shared introduces CROCOpy, a new digital Swiss Army knife designed to help scientists understand how this brain-city works. Here is a simple breakdown of what it does, using everyday analogies.

1. What is CROCOpy?

Think of CROCOpy as a super-powered microscope and translator for brain waves.

The Problem: Brain data is messy. It's like trying to listen to a thousand people talking at a wedding while standing in the middle of the room. Scientists need tools to separate the whispers from the shouting and figure out who is talking to whom.
The Solution: CROCOpy is a free, open-source software tool (a "toolbox") that helps researchers do exactly that. It's built to be fast (using powerful computer chips called GPUs, like a sports car engine) and works with any type of brain recording device.

2. What does it actually measure?

The toolbox looks at three main things, which the authors call "Observables." Here is how they work:

A. The Rhythm (Oscillations)

Imagine a crowd doing "The Wave" in a stadium.

The Metric: CROCOpy checks how well the wave is synchronized. Are people standing up and sitting down at the exact same time?
The Tool: It measures Phase Autocorrelation. Think of this as checking if the wave has a steady beat or if it's just random noise.

B. The "Critical" State (Criticality)

This is the most exciting part. The authors believe the brain works best when it's balanced on a knife-edge between chaos and order. CROCOpy checks if the brain is in this sweet spot using three tests:

Avalanches: Imagine a snowstorm. Sometimes a tiny snowflake falls, and nothing happens. Other times, a small slide triggers a massive avalanche. CROCOpy counts these "brain avalanches" (bursts of activity). If the brain is "critical," the size of these bursts follows a perfect mathematical pattern (like a pyramid).
Long-Range Temporal Correlations (LRTCs): This is like checking if the weather today predicts the weather next week. If the brain is healthy, its activity today is subtly connected to its activity far in the future. CROCOpy measures this "memory" of the brain.
Bistability: Imagine a light switch that gets stuck halfway between "On" and "Off," flickering back and forth. CROCOpy checks if the brain's energy levels are flickering between two distinct states, which is a sign of a healthy, critical system.
The E/I Ratio: Think of the brain as a seesaw with Excitation (gas pedal) on one side and Inhibition (brakes) on the other. CROCOpy calculates if the brain is pressing the gas too hard (supercritical) or the brakes too hard (subcritical), or if it's perfectly balanced.

C. The Connections (Connectivity)

How do different parts of the brain-city talk to each other?

Phase Synchrony: Are two distant groups of neurons dancing to the same beat? CROCOpy checks if they are "in sync." It has special filters to ignore fake connections caused by signals bleeding over from one sensor to another (like ignoring the echo in a canyon).
Amplitude Coupling: If one group of neurons gets louder, does another group get louder too? This measures if they are sharing the same "volume knob."
Cross-Frequency Coupling: This is like a conductor mixing a slow drum beat with a fast violin melody. CROCOpy checks if the slow rhythm is controlling the volume of the fast rhythm.

3. Why is this important? (The Real-World Test)

The authors didn't just build the tool; they used it to study sleeping children.

The Discovery: They found that as children grow up, their brain's "dance" changes.
- Babies (< 1 year): Their brain waves are a bit chaotic and less organized.
- Older Kids (> 5 years): Their brain waves become more synchronized and mature, looking more like an adult's.
The Analogy: It's like watching a toddler learn to dance. At first, they just flail around. As they get older, they learn the steps, the rhythm, and how to dance with others. CROCOpy helped the scientists see this "learning to dance" process happen in real-time.

4. The Bottom Line

CROCOpy is a gift to the scientific community. Before this, researchers had to build their own tools from scratch, which was slow and prone to errors. Now, they have a single, fast, and easy-to-use toolbox that can:

Measure how organized the brain is.
Check if the brain is in a healthy "critical" state.
See how different brain areas talk to each other.

It's like giving every neuroscientist a high-tech dashboard that tells them exactly how the brain's engine is running, helping them understand everything from normal development to diseases like epilepsy.

1. Problem Statement

The brain operates as a complex dynamical system where neuronal interactions give rise to oscillations, functional connectivity, and scale-invariant dynamics (criticality). While existing literature suggests a close relationship between functional connectivity and critical dynamics (e.g., neuronal avalanches, long-range temporal correlations), current analytical tools are fragmented.

Fragmentation: Existing toolboxes typically focus on either criticality metrics (e.g., DFA exponents) or connectivity metrics (e.g., phase locking), rarely integrating both.
Performance Limitations: Most existing software is not optimized for speed and lacks GPU acceleration, making them unsuitable for analyzing large-scale electrophysiological datasets (e.g., high-density MEG/EEG or multi-day ECoG).
Accessibility: There is a need for a unified, open-source, and device-agnostic framework that simplifies the analysis of continuous electrophysiological recordings while providing rigorous statistical methods and tutorials.

2. Methodology and Software Design

CROCOpy is a lightweight, open-source Python toolbox designed to analyze neuronal oscillations, functional connectivity, and critical dynamics.

Architecture:
- Device-Agnostic: Supports both CPU and GPU computations, utilizing numpy or cupy under the hood for seamless hardware switching.
- Data Structure: Operates on basic N-dimensional arrays, ensuring flexibility.
- Preprocessing: Includes built-in routines for narrow-band filtering and statistical testing.
- Documentation: Provides detailed tutorials on GitHub for usage and interpretation.
Core Metrics Implemented:
The toolbox categorizes observables into three main domains:

A. Oscillations & Criticality:
- Phase Autocorrelation (pAC): Quantifies rhythmicity via phase self-similarity, calculating pAC values and lifetimes.
- Neuronal Avalanches: Detects suprathreshold peaks, discretizes time series into bins, and fits power-law distributions to avalanche sizes and durations.
- Long-Range Temporal Correlations (LRTCs): Implements Detrended Fluctuation Analysis (DFA) to calculate scaling exponents. It offers both a standard time-domain approach (with artifact rejection) and a faster spectral-domain approach.
- Bistability: Analyzes power fluctuations to determine if a system alternates between "up" and "down" states using Bayesian Information Criterion (BIC) to fit single vs. bi-exponential distributions.
- Functional Excitation-Inhibition (fE/I) Ratio: Infers local E/I balance by correlating the mean envelope of a window with its fluctuation standard deviation. Values $>1$ suggest excitation-dominated dynamics; $<1$ suggests inhibition-dominated.
B. Functional Connectivity (FC):
- Phase Synchrony: Calculates Phase Locking Value (PLV), imaginary PLV (iPLV), and Weighted Phase Lag Index (wPLI) to mitigate spurious zero-lag interactions caused by volume conduction.
- Amplitude Coupling: Computes Pearson correlation and orthogonalized correlation (oCC) to measure inter-areal coupling of amplitude envelopes while correcting for linear mixing.
C. Cross-Frequency Coupling (CFC):
- Phase-Phase Coupling (CFS): Extends PLV to oscillations with integer frequency ratios ( $n:m$ ).
- Phase-Amplitude Coupling (PAC): Estimates the modulation of high-frequency amplitude envelopes by low-frequency phases using a PLV-based approach.

3. Key Contributions

Unified Framework: CROCOpy is the first toolbox to integrate metrics for critical dynamics (avalanches, LRTCs, bistability, fE/I) and functional connectivity (phase, amplitude, and cross-frequency coupling) into a single package.
High-Performance Computing: Unlike previous tools, it leverages GPU acceleration, enabling the efficient processing of massive datasets.
Robustness to Artifacts: Implements specific corrections for common electrophysiological issues, such as volume conduction (via iPLV/wPLI and oCC) and linear mixing.
Open Science: The code is openly available on GitHub, accompanied by tutorials, fostering reproducibility and community contribution.

4. Results (Validation Case Study)

The authors validated the toolbox by analyzing a pediatric sleep EEG dataset across three age cohorts (<1 year, 1–5 years, >5 years). Key findings included:

Bistability: The bistability index was lowest in infants (<1 year) and highest in children (>5 years), peaking in the beta frequency range (15–30 Hz).
LRTCs (DFA): The youngest cohort exhibited lower DFA exponents and lacked the characteristic peak in the lower alpha band (6–10 Hz) seen in older groups.
Connectivity (wPLI): Connectivity profiles in infants showed two distinct peaks (around 4 Hz and 15 Hz). With age, these peaks converged and shifted toward canonical alpha and beta bands, indicating a maturation of network organization during sleep.

5. Significance

Holistic Analysis: By combining criticality and connectivity metrics, CROCOpy allows researchers to study the brain as a unified dynamical system, potentially revealing how scale-free dynamics support functional communication.
Clinical Biomarkers: The metrics provided (e.g., fE/I, DFA, bistability) are proposed as potential biomarkers for neurological disorders, having already been applied in studies involving epilepsy, resting-state iSEEG, and sleep dynamics.
Scalability: The GPU optimization makes the analysis of large-scale neurophysiological datasets feasible, addressing a major bottleneck in modern neuroscience.
Community Growth: The active development model and invitation for community contributions ensure the toolbox will evolve to include new criticality-inspired biomarkers and mechanistic insights.