cogpy.events

Event data structures and catalog management. EventCatalog is the unified container for point and interval events returned by all detectors. It wraps a pandas DataFrame with standardized columns and provides converters, factories, and query helpers.

Guide: How to detect events | Tutorial: Detection and Events | Spec: EventCatalog Specification v2.6.0

Submodules

cogpy.events.catalog

EventCatalog: Unified event data structure (v2.6).

cogpy.events.match

Event matching and lag estimation primitives.

cogpy.events.overlap

Overlap detection utilities for interval EventCatalogs.

Event catalog infrastructure (v2.6).

Provides EventCatalog, a lightweight bridge between: - analysis containers (cogpy.datasets.schemas.Events / Intervals) - visualization (cogpy.events.EventStream)

class cogpy.events.EventCatalog(df, name='events', metadata=<factory>)

Bases: object

Unified event catalog with a standardized table schema.

Required columns:

  • event_id : str | int

  • t : float (seconds)

Optional interval columns:

  • t0, t1, duration

Parameters:

  • df (DataFrame)

  • name (str)

  • metadata (dict[str, Any])

df: DataFrame
filter_by_channel(channels)
Parameters:

channels (int | Iterable[int])

Return type:

EventCatalog

filter_by_spatial(*, AP=None, ML=None, radius=None)
Parameters:

  • AP (float | None)

  • ML (float | None)

  • radius (float | None)

Return type:

EventCatalog

filter_by_time(t_min, t_max)
Parameters:

  • t_min (float)

  • t_max (float)

Return type:

EventCatalog

classmethod from_blob_candidates(blob_dict, *, label='burst_candidate', id_prefix='blob', **metadata)
Parameters:

  • blob_dict (dict[str, Any])

  • label (str)

  • id_prefix (str)

  • metadata (Any)

Return type:

EventCatalog

classmethod from_burst_dict(burst_list, *, label='burst', **metadata)
Parameters:

  • burst_list (list[dict[str, Any]])

  • label (str)

  • metadata (Any)

Return type:

EventCatalog

classmethod from_hmaxima(peaks_df, *, time_col=None, label='peak', id_prefix='peak', value_col=None, **metadata)

Create a point-event catalog from an h-maxima peak table.

Supports both: - detect_hmaxima-style columns (time, freq, ap, ml, amp, …) - orthoslicer-friendly columns (t, z, x, y, value)

Parameters:

  • peaks_df (DataFrame)

  • time_col (str | None)

  • label (str)

  • id_prefix (str)

  • value_col (str | None)

  • metadata (Any)

Return type:

EventCatalog

classmethod from_spwr_mat(mat_data, *, label='ripple', id_prefix='ripple', **metadata)
Parameters:

  • mat_data (dict[str, Any])

  • label (str)

  • id_prefix (str)

  • metadata (Any)

Return type:

EventCatalog

property is_interval_events: bool
property is_point_events: bool
metadata: dict[str, Any]
name: str = 'events'
to_event_stream(style=None)

Convert to EventStream.

Parameters:

style (Any | None)

to_events()

Convert to cogpy.datasets.schemas.Events (always possible).

to_intervals()

Convert to cogpy.datasets.schemas.Intervals (requires t0/t1).

to_point_intervals(half_window)

Convert point events to symmetric windows around t.

Parameters:

half_window (float)

class cogpy.events.EventRegistry

Bases: object

Registry for event streams.

Manages multiple EventStream instances (bursts, ripples, etc.).

classmethod from_dict(dct)

Restore an EventRegistry from serialized metadata.

Parameters:

dct (dict)

Return type:

EventRegistry

get(name)
Parameters:

name (str)

Return type:

EventStream | None

list()
Return type:

list[str]

register(stream)
Parameters:

stream (EventStream)

Return type:

None

remove(name)
Parameters:

name (str)

Return type:

None

to_dict()
Return type:

dict

class cogpy.events.EventStream(name, df, *, time_col='t', id_col='event_id', style=None)

Bases: object

Container for event data.

Events are stored in a pandas DataFrame with required and optional columns.

Required columns: - event_id (int or str): Unique identifier - t (float): Event time in seconds

Optional columns: - channel (int): Flat channel index - AP (int): Grid row - ML (int): Grid column - label (str): Event type/category - value (float): Amplitude/score - duration (float): Duration in seconds - … (any other metadata)

Parameters:

  • name (str)

  • df (pd.DataFrame)

  • time_col (str)

  • id_col (str)

  • style (EventStyle | None)

classmethod from_dict(dct)

Restore an EventStream from serialized metadata.

If records are present, they are used to reconstruct the full table. Otherwise, an empty table is created with the required columns.

Parameters:

dct (dict)

Return type:

EventStream

get_event_by_id(event_id)
Return type:

Series | None

get_events_in_window(t0, t1)
Parameters:

  • t0 (float)

  • t1 (float)

Return type:

DataFrame

get_next_event(current_time)
Parameters:

current_time (float)

Return type:

Series | None

get_prev_event(current_time)
Parameters:

current_time (float)

Return type:

Series | None

to_dict()
Return type:

dict

class cogpy.events.EventStyle(color='#ff0000', marker='circle', line_width=2.0, alpha=0.8)

Bases: object

Visual style for event display.

Parameters:

  • color (str)

  • marker (str)

  • line_width (float)

  • alpha (float)

color

Marker/line color (hex or named).

Type:

str

marker

Marker shape (‘circle’, ‘square’, ‘triangle’).

Type:

str

line_width

Line width for markers.

Type:

float

alpha

Transparency (0-1).

Type:

float

alpha: float
color: str
line_width: float
marker: str