add_interval#

ethograph.labels.intervals.add_interval(df, onset_s, offset_s, labels, individual, protected_label_ids=None, individual_rec='', confidence=1.0, labeling_method='manual')[source]#

Add an interval, resolving overlaps for the same subject.

If the new interval overlaps existing intervals for the same (actor, recipient) pair, the existing intervals are trimmed or split — unless their label ID is in protected_label_ids, in which case they are kept untouched. Another pair’s intervals are never touched: the same animal mounting bird A and preening bird B are two independent tracks.

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 performing the behaviour (actor).

  • 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.

  • individual_rec (str) – Recipient of the behaviour; NO_RECIPIENT for a solo one.

  • confidence (float) – How sure this label is; HUMAN_CONFIDENCE for a hand-placed one.

  • labeling_method (str) – Who vouches for it; LABELING_MANUAL for a hand-placed one. A remnant trimmed off an existing interval keeps that interval’s method — nobody re-judged it.

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