`cogpy.detect`

Event detection framework: detectors, transforms, and pipelines.

Detectors wrap existing detection functions behind a unified interface that returns EventCatalog. Pre-built pipelines chain transforms (spectrogram, filtering, envelope) with a detector for reproducible, serializable workflows.

Guide: How to detect events | Tutorial: Detection and Events | Design: Detection Framework

Submodules

`cogpy.detect.base`	Base class for event detectors (v2.6.1).
`cogpy.detect.burst`	BurstDetector (v2.6.1).
`cogpy.detect.threshold`	Threshold-based event detection (v2.6.4).
`cogpy.detect.ripple`	Ripple detection (v2.6.4): bandpass + envelope + dual threshold.
`cogpy.detect.pipeline`	DetectionPipeline: compose transforms + detector (v2.6.5).
`cogpy.detect.pipelines`	Pre-built detection pipelines (v2.6.5).
`cogpy.detect.transforms`	Detection transforms for DetectionPipeline (v2.6.5).

Event detection framework.

Provides a unified EventDetector interface and composable DetectionPipeline that return cogpy.events.EventCatalog.

Detectors: BurstDetector, RippleDetector, SpindleDetector, SlowWaveDetector, ThresholdDetector. Built-in pipelines: BURST_PIPELINE, RIPPLE_PIPELINE, FAST_RIPPLE_PIPELINE, GAMMA_BURST_PIPELINE.

class cogpy.detect.BurstDetector(*, h_quantile=0.9, h=None, nperseg=256, noverlap=128, bandwidth=4.0, footprint=None)

Bases: EventDetector

Detect burst peaks using an h-maxima transform.

Accepts: - Spectrogram-like inputs (must include a ‘freq’ dimension) -> explicit mode - Raw time-series inputs (has ‘time’ but no ‘freq’ dimension) -> implicit mode (computes spectrogram)

See also

ThresholdDetector: Simple threshold crossing detector.
cogpy.detect.utils.score_to_bouts: Convert continuous scores to event bouts.

Examples

>>> import cogpy
>>> sigx = cogpy.datasets.load_sample()
>>> det = BurstDetector(h_quantile=0.9, nperseg=256)
>>> catalog = det.detect(sigx.isel(AP=0, ML=0))
>>> type(catalog).__name__
'EventCatalog'

Parameters:

h_quantile (float)
h (float | None)
nperseg (int)
noverlap (int | None)
bandwidth (float)

can_accept(data)

Parameters:: data (DataArray)
Return type:: bool

detect(data, **kwargs)

Run detection and return an EventCatalog.

Parameters:

data (DataArray)
kwargs (Any)

Return type:

EventCatalog

get_event_dims()

Return the dimensions events are defined over.

Return type:: list[str]

get_transform_info()

Return type:: dict[str, Any]

needs_transform(data)

Parameters:: data (DataArray)
Return type:: bool

class cogpy.detect.DetectionPipeline(*, transforms=None, detector=None, name=None)

Bases: object

Chain transforms and an EventDetector into a reproducible workflow.

Parameters:

transforms (list[Any] | None)
detector (Any | None)
name (str | None)

classmethod from_dict(config)

Parameters:: config (dict[str, Any])
Return type:: DetectionPipeline

run(data)

Run transforms then detector. Returns EventCatalog (if detector set) else transformed data.

Parameters:: data (DataArray)

to_dict()

Return type:: dict[str, Any]

class cogpy.detect.EventDetector(name=None)

Bases: ABC

Base class for event detectors.

Parameters:: name (str | None)

can_accept(data)

Parameters:: data (DataArray)
Return type:: bool

abstractmethod detect(data, **kwargs)

Run detection and return an EventCatalog.

Parameters:: data (DataArray)
Return type:: Any

classmethod from_dict(config)

Parameters:: config (dict[str, Any])

abstractmethod get_event_dims()

Return the dimensions events are defined over.

Return type:: list[str]

get_transform_info()

Return type:: dict[str, Any]

needs_transform(data)

Parameters:: data (DataArray)
Return type:: bool

to_dict()

Return type:: dict[str, Any]

class cogpy.detect.RippleDetector(*, freq_range=(100.0, 250.0), threshold_low=2.0, threshold_high=3.0, min_duration=0.02, max_duration=0.2, filter_order=4, direction='positive')

Bases: EventDetector

Ripple detector using bandpass → Hilbert envelope → z-score → dual threshold.

Produces interval events with (t0, t, t1, duration, value).

Parameters:

freq_range (tuple[float, float])
threshold_low (float)
threshold_high (float)
min_duration (float)
max_duration (float)
filter_order (int)
direction (str)

can_accept(data)

Parameters:: data (DataArray)
Return type:: bool

detect(data, **_kwargs)

Run detection and return an EventCatalog.

Parameters:

data (DataArray)
_kwargs (Any)

get_event_dims()

Return the dimensions events are defined over.

Return type:: list[str]

get_transform_info()

Return type:: dict

class cogpy.detect.SlowWaveDetector(*, freq_range=(0.5, 4.0), dur_neg=(0.08, 1.0), dur_cycle=(0.3, 1.5), amp_ptp_percentile=25.0, filter_order=4)

Bases: EventDetector

Slow-wave detector: bandpass → zero-crossing trough detection → gating.

Produces interval events with columns: (t0, t, t1, trough_time, midcrossing_time, peak_time,

duration, duration_neg, amplitude, val_trough, val_peak, frequency, state)

Parameters:

freq_range (tuple[float, float]) – Bandpass frequency range in Hz. Default (0.5, 4.0) for delta band. Use (0.5, 2.0) for strict slow oscillation.
dur_neg (tuple[float, float]) – Min/max duration of negative half-wave in seconds. Default (0.08, 1.0) — DOWN >80 ms per Swanson et al.
dur_cycle (tuple[float, float]) – Min/max duration of full cycle in seconds. Default (0.3, 1.5).
amp_ptp_percentile (float) – Only keep events with peak-to-trough amplitude above this percentile of all candidate amplitudes. Default 25.0 (per Swanson et al.).
filter_order (int) – Butterworth filter order. Default 4.

can_accept(data)

Parameters:: data (DataArray)
Return type:: bool

detect(data, **_kwargs)

Run detection and return an EventCatalog.

Parameters:

data (DataArray)
_kwargs (Any)

get_event_dims()

Return the dimensions events are defined over.

Return type:: list[str]

get_transform_info()

Return type:: dict

class cogpy.detect.SpindleDetector(*, freq_range=(11.0, 16.0), threshold_low=2.0, threshold_high=3.0, min_duration=0.5, max_duration=3.0, filter_order=4, direction='positive', compute_frequency=False, compute_rel_power=False, rel_power_broadband=(1.0, 40.0), rel_power_min=None, compute_symmetry=False, min_isolation=None)

Bases: RippleDetector

Spindle detector with optional yasa-style enrichment features.

Extends RippleDetector (bandpass → envelope → z-score → dual threshold) with per-event metrics:

frequency: peak oscillation frequency via zero-crossing count
rel_power: sigma-band power / broadband power within each event
symmetry: position of peak amplitude (0–1; 0.5 = symmetric)
isolation: reject events closer than min_isolation seconds

All enrichment features are off by default to keep the detector lightweight.

Typical spindle band: 11–16 Hz with duration 0.5–3.0 s.

Parameters:

freq_range (tuple[float, float])
threshold_low (float)
threshold_high (float)
min_duration (float)
max_duration (float)
filter_order (int)
direction (str)
compute_frequency (bool)
compute_rel_power (bool)
rel_power_broadband (tuple[float, float])
rel_power_min (float | None)
compute_symmetry (bool)
min_isolation (float | None)

detect(data, **kwargs)

Run detection and return an EventCatalog.

Parameters:

data (DataArray)
kwargs (Any)

class cogpy.detect.ThresholdDetector(threshold, *, direction='both', bandpass=None, use_envelope=False, min_duration=0.0, merge_gap=0.0, filter_order=4)

Bases: EventDetector

Generic threshold crossing detector producing interval events.

Supports: - positive threshold: x >= threshold - negative threshold: x <= -abs(threshold) (or <= threshold if threshold is negative) - both: abs(x) >= abs(threshold)

Parameters:

threshold (float) – Threshold in data units.
direction (str) – ‘positive’, ‘negative’, or ‘both’.
bandpass (tuple[float, float] | None) – Optional (low, high) bandpass in Hz.
use_envelope (bool) – If True, compute Hilbert envelope before thresholding.
min_duration (float) – Minimum event duration in seconds.
merge_gap (float) – Merge events separated by <= merge_gap seconds.
filter_order (int) – Bandpass filter order (only used if bandpass is set).

cogpy.detect

Submodules

`cogpy.detect`