LabelConverter#

class ethograph.labels.converters.LabelConverter[source]#

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)[source]#

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

Parameters:

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

Return type:

pd.DataFrame

resolve_labels(source_path, trial_ids, trials_df=None, labels_path=None)[source]#

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 (pd.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:

pd.DataFrame