ethograph.labels.intervals

Interval-based label representation and core primitives for EthoGraph.

Labels are stored as a pandas DataFrame with columns:

onset_s (float64) - start time in seconds offset_s (float64) - end time in seconds (NaN for point events) labels (int32) - label class ID (nonzero) individual (str) - individual identifier event_type (str) - “state” (interval) or “point” (instantaneous)

Use split_by_kind(df) at the top of every interval operation so points pass through untouched. states_only(df) / points_only(df) are for read-only consumers (dense conversion, plot rendering).

Functions

empty_intervals	Create an empty intervals DataFrame with the correct columns and dtypes.
load_mapping	Load a class-name ↔ index mapping file.
load_label_mapping	Load a label mapping with colors for visualization.
save_label_mapping	Write a label mapping back to disk, preserving branch and event_type.
add_interval	Add an interval, resolving overlaps for the same individual.
delete_interval	Drop interval by DataFrame index.
find_interval_at	Return DataFrame index of state interval containing time_s for individual.
get_interval_bounds	Return (onset_s, offset_s, labels) for interval at idx.
purge_short_intervals	Drop intervals shorter than a threshold.
stitch_intervals	Merge adjacent same-label intervals where gap <= max_gap_s.
snap_boundaries	Snap interval onset/offset to nearest changepoint times.