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
cogpy.events.cluster_spatiotemporal(events_df, *, tolerance_s=0.2, spatial_dims=('iAP', 'iML'), time_col='time', amp_col='amp', min_participation=1, n_valid_channels=None, min_participation_fraction=None, extra_agg=None)

Cluster per-channel events into spatial events by temporal proximity.

A single-link clusterer over the time axis. Two events join the same cluster iff their time_col values are within tolerance_s of each other on the consecutively-sorted event train. Spatial coordinates are used for participation accounting only — they do not gate clustering.

Parameters:

  • events_df (pandas.DataFrame) – Per-channel event table. Must contain time_col and every entry of spatial_dims. Other columns are pass-through (see extra_agg).

  • tolerance_s (float, default 0.2) – Maximum gap (seconds) between consecutive events on the global time axis for them to join the same cluster.

  • spatial_dims (sequence of str, default ("iAP", "iML")) – Column names that identify a unique recording site. Use positional indices (iAP / iML) when grid coordinates are floating-point physical positions, since exact equality is required for participation counting.

  • time_col (str, default "time") – Column name carrying the event timestamp (seconds).

  • amp_col (str or None, default "amp") – Column name carrying a signed event amplitude. Aggregated as mean / max / min per cluster if present. Pass None to skip amplitude aggregation.

  • min_participation (int, default 1) – Reject clusters with fewer than this many participating spatial_dims tuples.

  • n_valid_channels (int or None) – Total number of valid channels for the recording (used together with min_participation_fraction to gate clusters by their participation fraction). If None, the participation-fraction gate is disabled.

  • min_participation_fraction (float or None) – Reject clusters with n_participating / n_valid_channels below this fraction. Requires n_valid_channels to be set.

  • extra_agg (dict or None) – Additional pandas aggregation map for pass-through columns (e.g. {"gamma_z": "median", "polarity_consistent": "mean"}).

Returns:

  • pandas.DataFrame with one row per surviving cluster. Columns

    • spatial_cycle_id (int) — running cluster identifier, 0-indexed.

    • t_med (float) — median event time within the cluster.

    • t_first (float) — earliest event time (cluster start / wave origin).

    • t_last (float) — latest event time (cluster end).

    • n_participating (int) — number of distinct spatial_dims tuples.

    • participating_<dim> (object) — list of unique values per spatial dim.

    • participation_fraction (float) — only when n_valid_channels – is set; otherwise NaN.

    • amp_mean, amp_max, amp_min (float) — when amp_col is set.

    • Extra columns from extra_agg.

Return type:

DataFrame

Notes

For an LFP joint-extrema detector with grid spacing of a few hundred μm and a slow-oscillation rate around 1 Hz, tolerance_s ≈ 0.2 (i.e. one quarter of an SO half-period) is a reasonable default. Spectral burst detectors at higher rates (spindle 10–16 Hz, ripple ~150 Hz) should use shorter tolerances scaled to their event durations.