LabelConverter

class ethograph.labels.converters.LabelConverter

Bases: object

Base class for converting external label sources to ethograph intervals.

Subclasses override extract() to pull intervals from their source (NWB, pynapple, crowsetta, …). The shared resolve_labels() method centralises the “TSV on disk → extract from source → empty” fallback chain used by every LoadResult-producing function in data_loader.

Methods

extract([trials_df])	Return an all-labels DataFrame (with trial column).
resolve_labels(source_path, trial_ids[, ...])	Load labels with fallback: existing TSV → extract from source → empty.

extract(trials_df=None)

Return an all-labels DataFrame (with trial column).

Parameters:

trials_df (DataFrame | None) – Must contain trial, start_time, stop_time columns. Required for sources with global timestamps (NWB, pynapple).

Return type:

DataFrame

resolve_labels(source_path, trial_ids, trials_df=None, labels_path=None)

Load labels with fallback: existing TSV → extract from source → empty.

Parameters:

• source_path (str | Path) – Primary data file; used to derive the default TSV path.

• trial_ids (list) – Trial identifiers (for the empty-labels fallback).

• trials_df (DataFrame | None) – Passed to extract() for global→trial conversion.

• labels_path (Path | None) – Override the TSV path (e.g. for NWB project directories).

Return type:

DataFrame