cogpy

Atomic, composable primitives for ECoG / iEEG signal processing.

Documentation · Repository

What it is

cogpy provides small, pure, domain-agnostic operators for electrophysiology signal processing. It is not a pipeline framework — high-level orchestration belongs in Snakemake pipelines, notebooks, or project repos.

Capability areas

Install

pip install ecogpy               # core dependencies only
pip install ecogpy[viz]          # + matplotlib, holoviews, panel
pip install ecogpy[all]          # all optional dependencies
pip install -e .                # editable dev install

Note: The PyPI package is ecogpy (because cogpy was taken), but the import name is cogpy: import cogpy.

Quick start

from cogpy.detect import ThresholdDetector
from cogpy.brainstates.intervals import perievent_epochs
from cogpy.triggered import estimate_template, subtract_template
from cogpy.spectral.psd import psd_multitaper
from cogpy.measures.comparison import bandpower_change

# Detect events
detector = ThresholdDetector(threshold=3.0, direction="positive")
catalog = detector.detect(signal)

# Extract epochs and estimate template
epochs = perievent_epochs(signal, catalog.df["t"].values, fs, pre=0.01, post=0.01)
template = estimate_template(epochs, method="median")

# Subtract and validate
cleaned = subtract_template(signal, event_samples, template.values)
psd_before, freqs = psd_multitaper(signal.values, fs)
psd_after, _ = psd_multitaper(cleaned.values, fs)
delta = bandpower_change(psd_before, psd_after, freqs, band=(100, 140))

Package structure

All subpackages live directly under cogpy/ — no indirection layers.

cogpy/
├── detect/          Event detection (threshold, burst, ripple)
├── events/          EventCatalog, matching, lag estimation
├── triggered/       Epoch extraction, triggered stats, template subtraction
├── regression/      Design matrices, OLS fit/predict/residual
├── spectral/        PSD, spectrogram, coherence, multitaper, features
├── measures/        Spatial, temporal, and comparison metrics
├── preprocess/      Filtering, bad channel detection, interpolation
├── decomposition/   PCA, varimax rotation
├── brainstates/     Perievent epochs, interval operations
├── plot/            Static (matplotlib) and interactive (HoloViews) viz
├── io/              File I/O for ECoG/iEEG formats
├── datasets/        Sample data loaders
├── cli/             CLI entry points
└── workflows/       Snakemake preprocessing pipelines

Development

make check          # format + lint + typecheck + tests
make format         # black .
make lint           # ruff check . --fix
make tests          # pytest
make docs           # build Sphinx docs
make build          # build sdist + wheel

Documentation

• Primitive catalog — all operators with imports and signatures
• Package map — module tree overview
• Composition patterns — how to assemble primitives

License

MIT — see LICENSE.