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) - the individual performing the behaviour (actor) individual_rec (str) - the recipient of a dyadic behaviour, “” if none event_type (str) - “state” (interval) or “point” (instantaneous) confidence (float64) - how sure the label is: 1.0 for a human label,

the model’s own score for a predicted one

labeling_method (str) - who vouches for the label: “manual” (placed or

edited by hand), “automated” (a model’s output nobody has looked at) or “curated” (automated, then approved by a human) — the vocabulary of ndx-ethogram

individual and individual_rec together are the subject of a label: each (actor, recipient) pair is its own independent track, exactly as each individual was on its own before recipients existed. NO_RECIPIENT (“”) means a solo behaviour — the default, and what every pre-recipient file reads back as.

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 subject.
delete_interval	Drop interval by DataFrame index.
find_interval_at	Return DataFrame index of state interval containing time_s for one subject.
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.