Skip to content

CobraBox

Lightweight toolbox for feature extraction from EEG and fMRI time-series data

CobraBox provides a clean, immutable data model for neuroimaging time-series analysis with automatic history tracking and a flexible feature system.

Key Features

  • Immutable data containers - Data, EEG, and FMRI classes wrapping xarray.DataArray
  • Automatic history tracking - Every operation is recorded in the history attribute
  • Feature system - Dataclass-based feature classes that preserve metadata
  • Chord pipelines - Fan-out → map → fan-in for windowed analysis
  • Serialization - Save and load any pipeline to YAML or JSON with cb.save / cb.load
  • Multi-modal support - Works with EEG, fMRI, and other time-series data
  • Type-safe - Full type hints for better IDE support and error detection

Quick Example

import cobrabox as cb
import numpy as np

# Create synthetic data: [time, space]
my_array = np.random.default_rng(seed=0).normal(size=(100, 4))

# Wrap in Data container
data = cb.from_numpy(arr=my_array, dims=["time", "space"], sampling_rate=100.0, subjectID="sub-01")

# Apply features
feat = cb.LineLength().apply(data)

print(f"Shape: {feat.data.shape}")
print(f"History: {feat.history}")

Browse Features

Filter the full feature catalog by tag — click chips to narrow the table (match all or any selected tags), or type to search names, summaries and tags.

Match:
Modality
Application domain
More filtersconnectivity · output · method · signal type & more
Signal representation
Signal property
Connectivity
Research paradigm
Method
Operation
IO shape
Requirement
FeatureDomainTagsSummary
AmplitudeEntropycb.amplitude_entropy(data)cb.AmplitudeEntropy().apply(data)infometrics
Compute amplitude entropy from time-series data using histogram-based probability estimation.
AmplitudeVariationcb.amplitude_variation(data)cb.AmplitudeVariation().apply(data)signalstats
Compute amplitude variation over the time dimension.
AnalyticSignalcb.analytic_signal(data)cb.AnalyticSignal().apply(data)transforms
Extract analytic-signal representations along the time axis.
Autocorrelationcb.autocorrelation(data)cb.Autocorrelation().apply(data)signalstats
Compute normalized autocorrelation at a given lag along a required dimension.
BandpassFiltercb.bandpass_filter(data)cb.BandpassFilter().apply(data)decompositions
Filter a signal into frequency bands.
BandPowercb.band_power(data)cb.BandPower().apply(data)spectral
Compute band power for specified frequency bands using Welch's method.
Coherencecb.coherence(data)cb.Coherence().apply(data)connectivity
Compute magnitude-squared coherence for all pairwise channel combinations.
ConcatAggregatecb.ConcatAggregate()windowing
Aggregate a stream of per-window Data by stacking along a new 'window' dimension.
ContinuousWaveletTransformcb.continuous_wavelet_transform(data)cb.ContinuousWaveletTransform().apply(data)spectral
Continuous wavelet transform (CWT) scalogram.
Cordancecb.cordance(data)cb.Cordance().apply(data)spectral
Compute cordance, a qEEG measure combining absolute and relative bandpower.
Correlationcb.correlation(data)cb.Correlation().apply(data)connectivity
Compute pairwise Pearson or Spearman correlation between all channel pairs.
Covariancecb.covariance(data)cb.Covariance().apply(data)connectivity
Compute pairwise sample covariance between all channel pairs.
DirectedTransferFunctioncb.directed_transfer_function(data)cb.DirectedTransferFunction().apply(data)connectivity
Estimate the Directed Transfer Function (DTF) between channels via a VAR model.
DiscreteWaveletTransformcb.discrete_wavelet_transform(data)cb.DiscreteWaveletTransform().apply(data)spectral
Multi-level discrete wavelet decomposition (DWT).
EMDcb.emd(data)cb.EMD().apply(data)decompositions
Decompose a signal into Intrinsic Mode Functions (IMFs) using Empirical Mode Decomposition.
EnvelopeCorrelationcb.envelope_correlation(data)cb.EnvelopeCorrelation().apply(data)connectivity
Compute amplitude envelope correlation (AEC) between all channel pairs.
EpileptogenicityIndexcb.epileptogenicity_index(data)cb.EpileptogenicityIndex().apply(data)signalstats
Compute the Epileptogenicity Index (EI) per channel (Bartolomei et al., 2008).
FourierTransformcb.fourier_transform(data)cb.FourierTransform().apply(data)transforms
Real-valued FFT along the time axis.
FourierTransformSurrogatescb.fourier_transform_surrogates(data)cb.FourierTransformSurrogates().apply(data)surrogates
Generate Fourier transform surrogates (preserving autocorrelation) of SignalData.
FractalDimensioncb.fractal_dimension(data)cb.FractalDimension().apply(data)infometrics
Compute fractal dimension over the time dimension.
GrangerCausalitycb.granger_causality(data)cb.GrangerCausality().apply(data)connectivity
Compute the Granger causality matrix across channels.
InverseFourierTransformcb.inverse_fourier_transform(data)cb.InverseFourierTransform().apply(data)transforms
Inverse of :class:`~cobrabox.transforms.fourier_transform.FourierTransform`.
LempelZivcb.lempel_ziv(data)cb.LempelZiv().apply(data)infometrics
Compute Lempel-Ziv Complexity (LZC) over the time dimension.
LineLengthcb.line_length(data)cb.LineLength().apply(data)signalstats
Compute line length over the time dimension.
Maxcb.max(data)cb.Max().apply(data)signalstats
Compute the maximum value across a dimension.
Meancb.mean(data)cb.Mean().apply(data)signalstats
Compute the mean value across a dimension.
MeanAggregatecb.MeanAggregate()windowing
Aggregate a stream of per-window Data by averaging across windows.
Mincb.min(data)cb.Min().apply(data)signalstats
Compute the minimum value across a dimension.
MutualInformationcb.mutual_information(data)cb.MutualInformation().apply(data)connectivity
Compute mutual information (MI) between all pairs of series along a specified dimension (by
Nonreversibilitycb.nonreversibility(data)cb.Nonreversibility().apply(data)infometrics
Compute dc_norm: normalised deviation from causal normality (time-irreversibility).
PartialCorrelationcb.partial_correlation(data)cb.PartialCorrelation().apply(data)connectivity
Compute the partial-correlation matrix across channels.
PartialDirectedCoherencecb.partial_directed_coherence(data)cb.PartialDirectedCoherence().apply(data)connectivity
Estimate the Partial Directed Coherence (PDC) between channels via a VAR model.
PhaseLockingValuecb.phase_locking_value(data)cb.PhaseLockingValue().apply(data)connectivity
Compute the phase-locking-value (PLV) matrix across channels.
PowerSpectralDensitycb.power_spectral_density(data)cb.PowerSpectralDensity().apply(data)spectral
Power spectral density via FFT.
ReciprocalConnectivitycb.reciprocal_connectivity(data)cb.ReciprocalConnectivity().apply(data)connectivity
Compute per-channel Reciprocal Connectivity (RC) from a directed connectivity matrix.
RecurrenceMatrixcb.recurrence_matrix(data)cb.RecurrenceMatrix().apply(data)infometrics
Compute a pairwise recurrence (self-similarity) matrix from a time-series.
SampleEntropycb.sample_entropy(data)cb.SampleEntropy().apply(data)infometrics
Sample Entropy feature.
SlidingWindowcb.sliding_window(data)cb.SlidingWindow().apply(data)windowing
Yield one Data per sliding window over the time dimension.
SlidingWindowReducecb.sliding_window_reduce(data)cb.SlidingWindowReduce().apply(data)windowing
Sliding window with automatic per-window reduction.
Spectrogramcb.spectrogram(data)cb.Spectrogram().apply(data)spectral
Compute the power spectrogram for each spatial channel.
SpikeCountcb.spike_count(data)cb.SpikeCount().apply(data)signalstats
Calculate spikes in the input data using the IQR method.
SVDcb.svd(data)cb.SVD().apply(data)decompositions
Compute truncated SVD over one dimension.

Browse Datasets

CobraBox ships small synthetic datasets for testing, plus downloaders for public real EEG/iEEG datasets. See the Working with Datasets guide for loading, filtering, and subset-download examples.

Identifier Type Summary Size
dummy_chain local Synthetic chain-topology VAR time-series (3 subjects). —
dummy_noise local Synthetic uncorrelated noise time-series (10 subjects). —
dummy_random local Synthetic random-topology VAR time-series (3 subjects). —
dummy_star local Synthetic star-topology VAR time-series (3 subjects). —
realistic_swiss local Simulated realistic Swiss VAR time-series (1 subject). —
bonn_eeg remote Bonn University EEG dataset (Andrzejak et al. 2001): 5 sets of 100 single-channel recordings. Sets: Z = healthy eyes open, O = healthy eyes… ~10 MB
chb_mit remote CHB-MIT Scalp EEG Database: pediatric patients with intractable seizures (24 subjects, 256 Hz, 23 channels, ictal/interictal). Children's… ~30 GB
siena_eeg remote Siena Scalp EEG Database: adult epilepsy patients with annotated seizures (14 subjects, 512 Hz, 21+ channels, ictal/interictal). University… ~15 GB
sleep_ieeg remote Sleep iEEG Dataset: interictal iEEG during slow-wave sleep from 185 epilepsy patients (135 Detroit at 1000 Hz, 50 UCLA at 2000 Hz).… ~13 GB
swiss_eeg_long remote Long-term intracranial EEG recordings from the SWEZ dataset (ETH Zurich, 18 subjects, ictal/interictal). >1 TB (hundreds of hourly files per subject)
swiss_eeg_short remote Short-term scalp EEG recordings from the BioCAS 2018 challenge (18 subjects, ictal/interictal). ~11 GB
zurich_ieeg remote Zurich iEEG HFO Dataset: interictal ECoG during slow-wave sleep from 20 epilepsy patients (TLE and extra-temporal), with HFO event… ~60 GB
zurich_ieeg_clean remote Zurich iEEG HFO Dataset, cleaned: identical to 'zurich_ieeg' but with per-subject electrodes removed — channels lacking metadata and… ~60 GB

Why CobraBox?

Traditional neuroimaging workflows often lose track of preprocessing steps and metadata. CobraBox solves this by:

  1. Immutability - Data is never modified in-place; every operation returns a new instance
  2. Metadata preservation - Subject IDs, conditions, and sampling rates travel with your data
  3. Transparent pipelines - The history attribute shows exactly what operations were applied
  4. xarray integration - Leverage the full power of labeled multi-dimensional arrays

Installation

uv sync --group docs

See Installation for detailed setup instructions.

Next Steps