Additional Detectors Specification v2.6.4

Version

  • Version: 2.6.4

  • Date: 2026-03-05

  • Depends on: v2.6.1 (cogpy.detect.EventDetector), v2.6.0 (cogpy.events.EventCatalog)

Overview

v2.6.4 expands the detector library beyond BurstDetector by adding:

  • ThresholdDetector: generic threshold-crossing detector (interval events)

  • RippleDetector: bandpass + Hilbert envelope + z-score + dual threshold (interval events)

  • SpindleDetector (optional): spindle-band wrapper with longer duration constraints

All detectors return EventCatalog and are compatible with visualization frontends via the event stream export API.

Components

Detection utilities

File: cogpy/core/detect/utils.py

Shared helpers for:

  • bandpass filter (bandpassx)

  • Hilbert envelope (SciPy)

  • safe z-scoring

  • run/interval finding and merging

  • dual-threshold interval event extraction

ThresholdDetector

File: cogpy/core/detect/threshold.py

Produces interval events by finding contiguous runs above a threshold:

  • direction="positive": x >= abs(threshold)

  • direction="negative": x <= -abs(threshold) (or <= threshold if threshold is already negative)

  • direction="both": abs(x) >= abs(threshold)

Supports:

  • optional bandpass filtering

  • optional Hilbert envelope

  • optional merging by merge_gap

  • filtering by min_duration

RippleDetector

File: cogpy/core/detect/ripple.py

Pipeline:

  1. bandpass filter (freq_range)

  2. Hilbert envelope

  3. z-score

  4. dual threshold (threshold_low, threshold_high)

  5. duration constraints (min_duration, max_duration)

SpindleDetector (optional)

Implemented as a wrapper over RippleDetector with default spindle-band parameters (11–16 Hz) and longer duration constraints (0.5–3.0 s).

Success Criteria

  • Detectors are importable from cogpy.detect.

  • Each detector returns a valid EventCatalog (with intervals for ripple/spindle).

  • Unit tests cover basic detection + serialization.

  • Example script demonstrates running multiple detectors.