add_interval#

ethograph.labels.intervals.add_interval(df, onset_s, offset_s, labels, individual, protected_label_ids=None)[source]#

Add an interval, resolving overlaps for the same individual.

If the new interval overlaps existing intervals for the same individual, the existing intervals are trimmed or split — unless their label ID is in protected_label_ids, in which case they are kept untouched.

Parameters:

  • df (pd.DataFrame) – Current intervals DataFrame.

  • onset_s (float) – Start and end times in seconds.

  • offset_s (float) – Start and end times in seconds.

  • labels (int) – Label class ID.

  • individual (str) – Individual identifier.

  • protected_label_ids (set[int] | None) – Label IDs that must not be trimmed or split (e.g. labels belonging to inactive branches). None means no protection.

Returns:

Updated intervals DataFrame sorted by onset_s.

Return type:

pd.DataFrame

Examples

>>> df = empty_intervals()
>>> df = add_interval(df, 0.0, 1.0, 1, "crow_A")
>>> df = add_interval(df, 0.5, 1.5, 2, "crow_A")
>>> len(df)
2
>>> float(df.iloc[0]["offset_s"])  # first interval trimmed
0.499