Detector Architecture Specification v2.6.1

Version

  • Version: 2.6.1

  • Date: 2026-03-05

  • Status: Implementation

  • Depends on: v2.6.0 (cogpy.events.EventCatalog)

Overview

This specification defines a unified detector interface for event detection in CogPy. Detectors wrap existing, battle-tested detection functions (e.g., detect_hmaxima) behind a standardized interface that returns cogpy.events.EventCatalog.

Key goals:

  • Wrap existing detectors instead of reimplementing them.

  • Standardize outputs as EventCatalog.

  • Support “smart transforms”: accept either precomputed transforms (explicit) or raw signals (implicit transform computed internally).

  • Provide serializable, declarative configuration (to_dict / from_dict).

Design Principles

Wrap, Don’t Reimplement

Existing detection code already exists across:

  • cogpy.burst.blob_detection (detect_hmaxima, detect_blobs, …)

  • cogpy.spectral.spectrogram_burst (blob candidates + aggregation)

Detectors provide:

  • detect(data) -> EventCatalog

  • optional transform handling

  • metadata/provenance fields

Smart Transform Handling

Some detectors need transforms (e.g., spectrogram) before detection:

Raw LFP -> Spectrogram -> Detect peaks

Detectors should support:

  • Explicit mode: user provides precomputed spectrogram (no recomputation).

  • Implicit mode: user provides raw signal; detector computes the needed transform internally.

Declarative Configuration

Detectors must be serializable:

cfg = detector.to_dict()
det2 = BurstDetector.from_dict(cfg)

EventDetector Base Class

Required:

  • detect(data: xr.DataArray, **kwargs) -> EventCatalog

  • get_event_dims() -> list[str]

Optional:

  • can_accept(data) -> bool

  • needs_transform(data) -> bool

  • get_transform_info() -> dict

BurstDetector

BurstDetector is the first concrete detector.

Wraps:

  • cogpy.burst.blob_detection.detect_hmaxima

Accepts:

  • spectrogram-like input ("freq" in data.dims) — explicit mode

  • raw time-series input ("time" in data.dims and "freq" not in dims) — implicit mode

Implicit transform:

  • uses cogpy.spectral.specx.spectrogramx with detector parameters

Returns:

  • cogpy.events.EventCatalog (point events) via EventCatalog.from_hmaxima(...)

Success Criteria

  • cogpy.detect.EventDetector base implemented

  • cogpy.detect.BurstDetector implemented with explicit + implicit modes

  • tests pass for base + burst detector

  • demo example shows both modes