Label branches#

Within a single branch, each timepoint can only belong to one label. When you place a new label that overlaps an existing one in the same branch, the existing label is trimmed or split automatically. This is by design: downstream action-segmentation models require a single class per frame, and the plot overlays assume non-overlapping intervals.

Sometimes, however, you need overlapping annotations at different timescales — for example, brief transient events like syllables or movements (song, peck, jump) on one tier, and longer behavioural states like arousal or passivity (active, resting, sleep) on another. A bird can be active and producing a song at the same time, and those annotations need to coexist. Label branches solve this.

How branches work#

Each label in mapping.txt belongs to a branch (default 0). Labels in different branches are independent: they can overlap freely without trimming each other. Labels in the same branch remain mutually exclusive.

Exactly one branch is the Main labels branch (the editing branch). When a branch is the Main slot:

  • Keyboard shortcuts and click-to-label only create intervals for labels in that branch.

  • Existing labels in other branches are protected — they are never trimmed or overwritten.

  • Up to two additional branches (or the imported predictions) can be shown alongside the Main labels as thin top strips — see Choosing what to display: Main / Top 1 / Top 2 below for how to configure them.

Assigning branches in mapping.txt#

Add a third column to any line in mapping.txt:

0 background
1 song 0
2 peck 0
3 jump 0
4 active 1
5 resting 1
6 sleep 1

Labels without an explicit branch number default to branch 0. In this example, transient events (song / peck / jump) live on branch 0 and behavioural states (active / resting / sleep) on branch 1 — a song interval and an active interval can overlap because they belong to different branches.

See Label mapping (mapping.txt) for the full mapping file format.

Switching branches in the GUI#

Each branch appears as a section in the Labels panel. The branch shown in the Main slot of the Overlays row (see below) is the editing branch. Press Shift+B to toggle the Main slot between the current and the previously-selected branch.

You can also drag labels between branches: grab a label row from one branch table and drop it onto another. The mapping file is updated automatically.

Choosing what to display: Main / Top 1 / Top 2#

The Overlays row in the Data panel has three dropdowns that decide which annotations are drawn on the plots:

Slot

Where it draws

Allowed values

Main

Full plot height (or a single bottom strip on spectrogram-style plots)

Any branch, or (none)

Top 1

Thin strip at the top of the plot

Any branch, the imported Predictions, or (none)

Top 2

Thin strip just below Top 1

Same options as Top 1

Defaults and auto-fill behaviour:

  • On startup, Main is set to Branch 0 and both top slots are empty.

  • When you import predictions, they are placed into Top 1 if it is empty, otherwise into Top 2. If both are taken, the slots are left unchanged — pick a slot manually.

  • When you add a new branch with the + button, it is placed into Top 1 if it is empty, otherwise into Top 2. Same fallback as above.

  • Press Ctrl+Y to toggle Predictions in or out of the top slots.

Changing a dropdown immediately redraws every plot.

Adding and removing branches#

  • Click the + button below the branch tables to add a new empty branch. The new branch is auto-assigned to the first free top slot.

  • Click the x button on a branch header to delete it. A branch can only be deleted when it contains no labels — move all labels out first. Slots that referenced the deleted branch are reset to (none).