Importing labels#

Open File → Import labels… to bring up the import panel. The Labels format dropdown offers:

Option	Source	Converter
`.tsv`	Ethograph TSV (backup, colleague’s labels, manual edit)	(native)
`pynapple (.npz)`	Pynapple file with `IntervalSet` objects	`PynappleLabelConverter`
`pynapple (.nwb)`	NWB file loaded via `IntervalSet` objects	`PynappleLabelConverter`
Crowsetta formats (aud-seq, simple-seq, textgrid, notmat, timit, yarden, …)	crowsetta-supported annotation tools (Audacity, Praat, Raven, …)	`CrowsettaLabelConverter`

A BORIS project is not a label file for an open session: it holds the media and the trials too, so it is imported as whole sessions from the start page — see Migrating from BORIS.

Comparing predictions#

File → Import predictions… loads a model’s prediction file (a run folder or a plain .tsv). With Load as: overlay, each file opens in its own Predictions — <file>.tsv panel: a thin strip above the time-series panels, below the video. Import several files to stack them and compare models against each other and against your labels. Every run folder writes the same <stem>_predictions.tsv, so a run’s panel is named with its folder in front (predictions_mstcn_20260101/<stem>_predictions.tsv); a plain .tsv keeps its own name.

The Predictions group lists every set currently loaded. Select one to make it current — the Curation section’s Confidence curves… falls back to it when the labels carry no run of their own; Remove unloads it and closes its panel. A run folder’s frame-by-frame confidence curve is drawn dashed inside that run’s own panel, on its 0–1 axis, and nowhere else — the Confidence checkbox shows or hides it on every panel at once. A plain .tsv has no curve.

The Moll et al. 2025 template ships several such runs to try this on: they download with the dataset into its labels/predictions_<model>/ folders (one per model, e.g. predictions_mlp, predictions_c2f-tcn, predictions_feral-cp), each ready for Import predictions → From folder.

Each file gets at most one panel. Closed one? Add it back from the ➕ Add panel popup, which lists every loaded file. Click a prediction on its panel to select it and press V to play it back. Predictions are read-only. If you want to load predictions and accept/curate them, use File → Import predictions → Import as Labels…

Pynapple / NWB IntervalSets#

Selecting pynapple (.npz) or pynapple (.nwb) loads the file with pynapple.load_file() and extracts every IntervalSet in the data dict except the one used as the trial boundaries: trials if present, otherwise epochs, then intervals, then the first set with trial in its name. Every other set, epochs included when trials exists, is imported as labels. Each IntervalSet name becomes a label class.

Label names already in the active mapping.txt keep their IDs; new names are appended to it (see Importing labels from other formats). The labels are written to the canonical labels.tsv in the session folder.

Global-time intervals are split across trials using the trials / epochs IntervalSet (or the session’s trial table). See PynappleLabelConverter for the conversion logic.

Crowsetta interop#

Ethograph registers an ethograph-seq crowsetta format for sharing labels with string names (resolved via mapping.txt):

from ethograph.labels.crowsetta_format import EthographSeq

# Export: int labels -> string labels via mapping
ethoseq = EthographSeq.from_intervals_df(df, id_to_name={1: "Head bob", 2: "Song"})
ethoseq.to_file("labels_for_sharing.tsv")

# Import via crowsetta
import crowsetta

scribe = crowsetta.Transcriber(format="ethograph-seq")
annot = scribe.from_file("labels_for_sharing.tsv").to_annot()

On import, label names already in the active mapping.txt keep their IDs and new names are appended to it (see Importing labels from other formats); background and sil count as background.

Programmatic usage#

All converters expose the same resolve_labels(...) contract, which falls back through existing TSV → extract from source → empty:

from pathlib import Path
from ethograph.labels.converters import PynappleLabelConverter
import pynapple as nap

data = nap.load_file("session.nwb")
trials_ep = data["trials"] if "trials" in data.keys() else None

converter = PynappleLabelConverter(data, trials_ep=trials_ep)
df = converter.resolve_labels(
    source_path=Path("session.nwb"),
    trial_ids=[1, 2, 3],
)

See Exporting labels for the full TSV column reference.