# EventCatalog Specification v2.6.0

## Version
- Version: 2.6.0
- Date: 2026-03-05
- Status: Implementation
- Depends on: `cogpy.datasets.schemas` (`Events`, `Intervals`)

## Overview

`EventCatalog` provides a unified, lightweight event representation that bridges:

- **Analysis workflows:** typed containers (`Events`, `Intervals`) for integration with pynapple/MNE-style pipelines.
- **Visualization workflows:** event export for frontends like TensorScope (tables, navigation, overlays).

It is a wrapper around a pandas DataFrame with:
- a **minimal required schema** (`event_id`, `t`)
- optional standardized columns (intervals/spatial/spectral/metadata/provenance)
- conversion and factory helpers for common detector outputs

This is intentionally **non-breaking and additive**. It does not replace the existing
strict detector contract `cogpy.datasets.schemas.EventCatalog` (which assumes interval
fields are present); instead it provides a more general “bridge” catalog suitable for
point events and interval events.

## Schema

### Required Columns
- `event_id` : `str | int` — unique identifier
- `t` : `float` — event time in seconds (peak/center)

### Optional Interval Columns
- `t0` : `float` — start time (seconds)
- `t1` : `float` — end time (seconds)
- `duration` : `float` — computed as `t1 - t0` when missing (requires `t0`, `t1`)

### Optional Spatial Columns
- `channel` : `int | str`
- `AP` : `float`
- `ML` : `float`

### Optional Spectral Columns
- `freq` : `float`
- `f0`, `f1` : `float`
- `bandwidth` : `float` (computed as `f1 - f0` when missing)

### Optional Metadata / Provenance Columns
- `label` : `str`
- `score` : `float`
- `value` : `float`
- `family` : `str`
- `detector` : `str`
- `source_signal` : `str`
- `pipeline` : `str`

## Core API

Converters:
- `to_events()` → `Events`
- `to_intervals()` → `Intervals` (requires `t0`, `t1`)
- `to_point_intervals(half_window)` → `Intervals`
- `to_event_stream(style=...)` → serializable event stream for frontends

Factories:
- `from_hmaxima(...)`
- `from_blob_candidates(...)`
- `from_burst_dict(...)`
- `from_spwr_mat(...)`

Queries:
- `filter_by_time(t_min, t_max)`
- `filter_by_channel(channels)`
- `filter_by_spatial(AP, ML, radius)`

## Success Criteria

- `EventCatalog` implemented in `cogpy.events`
- Factories cover common existing detector outputs
- Converters to `Events`, `Intervals`, and serializable event streams work
- Validation and basic filters are tested
- Example demonstrates end-to-end usage