Importing labels#

Open File → Import labels… to bring up the import panel. The Labels format combo 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`
BORIS (`.boris`)	BORIS project files	`BorisLabelConverter` (via the BORIS import wizard)
Crowsetta formats (aud-seq, simple-seq, textgrid, notmat, timit, yarden, …)	crowsetta-supported annotation tools (Audacity, Praat, Raven, …)	`CrowsettaLabelConverter`

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.

Each file gets at most one panel. Closed one? Add it back from the ➕ Add panel popup, which lists every imported 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 alongside the .nc.

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

BORIS#

BORIS observations bind one or more media files (concatenated in Player 1) to a list of events coded in observation-global time. The wizard splits events across media boundaries, treating one media file as one trial.

The importer preserves BORIS’s two event kinds (see State vs point events):

State events become intervals (onset_s → offset_s). Events that span a file boundary are clipped at the boundary with a warning.
Point events become rows with event_type = "point" and offset_s = NaN.

The per-behavior type field from BORIS is written into the generated mapping.txt so the kind is preserved on round-trip and the labelling shortcut behaves correctly. The BORIS Image index column is ignored, as ethograph stores label times in time (seconds), and does not round to nearest frame. This becomes import when labelling multimodal & multi sampling rate data (video, audio, accelerometer, …).

The .boris JSON is parsed via load_boris_project(); the import wizard lives at ethograph.gui.wizard_boris.

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.