Metadata-Version: 2.4
Name: ecogpy
Version: 0.2.0
Summary: Atomic, composable primitives for ECoG / iEEG signal processing
Author-email: Arash Shahidi <A.Shahidi@campus.lmu.de>
License: MIT
Project-URL: Repository, https://github.com/arashshahidi1997/cogpy
Project-URL: Documentation, https://arashshahidi1997.github.io/cogpy/
Keywords: ecog,ieeg,electrophysiology,signal-processing,neuroscience
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: lazy_loader
Requires-Dist: xarray
Requires-Dist: tqdm
Requires-Dist: dill
Requires-Dist: kneed
Requires-Dist: statsmodels
Requires-Dist: tabulate
Requires-Dist: pyyaml
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Requires-Dist: plotly; extra == "viz"
Requires-Dist: holoviews; extra == "viz"
Requires-Dist: panel; extra == "viz"
Requires-Dist: param; extra == "viz"
Requires-Dist: bokeh; extra == "viz"
Requires-Dist: datashader; extra == "viz"
Requires-Dist: tsdownsample; extra == "viz"
Provides-Extra: notebook
Requires-Dist: ipykernel; extra == "notebook"
Requires-Dist: ipywidgets; extra == "notebook"
Requires-Dist: ipython; extra == "notebook"
Provides-Extra: io
Requires-Dist: h5py; extra == "io"
Requires-Dist: zarr; extra == "io"
Requires-Dist: xmltodict; extra == "io"
Provides-Extra: interop-mne
Requires-Dist: mne; extra == "interop-mne"
Provides-Extra: interop-nap
Requires-Dist: pynapple; extra == "interop-nap"
Provides-Extra: perf
Requires-Dist: dask[distributed]; extra == "perf"
Requires-Dist: pyfftw; extra == "perf"
Provides-Extra: signal
Requires-Dist: ghostipy; extra == "signal"
Requires-Dist: scikit-image; extra == "signal"
Requires-Dist: emd; extra == "signal"
Requires-Dist: specparam; extra == "signal"
Provides-Extra: all
Requires-Dist: ecogpy[viz]; extra == "all"
Requires-Dist: ecogpy[notebook]; extra == "all"
Requires-Dist: ecogpy[io]; extra == "all"
Requires-Dist: ecogpy[perf]; extra == "all"
Requires-Dist: ecogpy[signal]; extra == "all"
Dynamic: license-file

# cogpy

Atomic, composable primitives for ECoG / iEEG signal processing.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**[Documentation](https://arashshahidi1997.github.io/cogpy/)** · **[Repository](https://github.com/arashshahidi1997/cogpy)**

## 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

| Area | Key functions |
|------|--------------|
| **Event detection** | `ThresholdDetector`, `BurstDetector`, `score_to_bouts` |
| **Event matching** | `match_nearest`, `estimate_lag`, `estimate_drift` |
| **Triggered analysis** | `perievent_epochs`, `triggered_average`, `estimate_template`, `subtract_template` |
| **Regression** | `lagged_design_matrix`, `ols_fit`, `ols_residual` |
| **Spectral** | `psd_multitaper`, `spectrogramx`, `band_power`, `ftest_line_scan` |
| **Spatial measures** | `moran_i`, `gradient_anisotropy`, `csd_power` |
| **Filtering** | `bandpassx`, `cmrx`, `gaussian_spatialx`, `zscorex` |
| **Validation** | `snr_improvement`, `bandpower_change`, `residual_energy_ratio` |

## Install

```bash
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

```python
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

```bash
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](https://arashshahidi1997.github.io/cogpy/explanation/primitives.html) — all operators with imports and signatures
- [Package map](https://arashshahidi1997.github.io/cogpy/explanation/package-map.html) — module tree overview
- [Composition patterns](https://arashshahidi1997.github.io/cogpy/howto/compose-artifact-analysis.html) — how to assemble primitives

## License

MIT — see [LICENSE](LICENSE).
