lisbet.io.annotation_formats#

Annotation-format loaders for LISBET supervised fine-tuning.

This module loads annotations from different external formats and converts them to the internal LISBET annotation representation:

xarray.Dataset

dims: time, behaviors, annotators data variable: target_cls(time, behaviors, annotators)

Supported formats#

movement

Current/default LISBET annotation format. Loads NetCDF files such as annotations.nc or manual_scoring.nc.

csv-events

Generic interval-based CSV event annotation format with at least: behavior,start_time,end_time

boris

BORIS tabular CSV export with START/STOP rows. The converter pairs START and STOP rows and creates one behavioral interval per bout.

Notes

The csv-events and boris loaders expect annotation times in seconds and convert them to frame indices using the provided fps value, the BORIS FPS column, or a default value.

Functions

boris_events_to_intervals(boris_events)

Convert BORIS START/STOP rows to an interval annotation table.

intervals_to_lisbet_xarray(intervals_df[, ...])

Convert interval annotations to the internal LISBET xarray format.

load_annotations(seq_path[, annot_format, ...])

Load annotations from a sequence directory using the requested format.

load_boris_annotations(seq_path[, n_frames, fps])

Load BORIS tabular CSV annotations and convert them to LISBET format.

load_csv_event_annotations(seq_path[, ...])

Load a generic interval-based CSV annotation format.

load_movement_annotations(seq_path)

Load the current/default LISBET movement annotation format.

read_boris_csv(boris_file)

Read a BORIS CSV export and return the clean event table.
lisbet.io.annotation_formats.intervals_to_lisbet_xarray(intervals_df, fps=30, n_frames=None, annotator='annotator0', behavior_col='behavior', start_col='start_time', end_col='end_time', other_label='other', add_other=True, source_software='CSV')[source]#

Convert interval annotations to the internal LISBET xarray format.

Parameters:

  • intervals_df (DataFrame) – Interval annotation table. Required columns are behavior, start_time, and end_time. Times are expected in seconds.

  • fps (float) – Frames per second used to convert seconds to frame indices.

  • n_frames (Optional[int]) – Number of frames in the corresponding tracking sequence. If None, it is inferred from the maximum end time.

  • annotator (str) – Name assigned to the annotator coordinate.

  • behavior_col (str) – Column names in the interval table.

  • start_col (str) – Column names in the interval table.

  • end_col (str) – Column names in the interval table.

  • other_label (str) – Label assigned to frames without any annotated behavior.

  • add_other (bool) – Whether to add an “other” behavior for unannotated frames.

  • source_software (str) – Stored in the output xarray Dataset attributes.

Returns:

LISBET-compatible annotation dataset.

Return type:

Dataset

lisbet.io.annotation_formats.load_movement_annotations(seq_path)[source]#

Load the current/default LISBET movement annotation format.

This preserves the existing LISBET behavior: annotations are read from NetCDF files whose names contain “manual_scoring” or “annotations”.

Return type:

Optional[Dataset]

lisbet.io.annotation_formats.load_csv_event_annotations(seq_path, n_frames=None, fps=None)[source]#

Load a generic interval-based CSV annotation format.

Return type:

Optional[Dataset]

Expected CSV columns#

behavior,start_time,end_time

Optional columns#

annotator,subject,video_id,media_file

Times are expected in seconds.

lisbet.io.annotation_formats.read_boris_csv(boris_file)[source]#

Read a BORIS CSV export and return the clean event table.

BORIS CSV exports may contain metadata rows before the actual event table. This function detects the event-table header and reads from that point.

If the file is already a clean BORIS event table, it is read directly.

Return type:

DataFrame

lisbet.io.annotation_formats.boris_events_to_intervals(boris_events)[source]#

Convert BORIS START/STOP rows to an interval annotation table.

Return type:

DataFrame

lisbet.io.annotation_formats.load_boris_annotations(seq_path, n_frames=None, fps=None)[source]#

Load BORIS tabular CSV annotations and convert them to LISBET format.

Return type:

Optional[Dataset]

lisbet.io.annotation_formats.load_annotations(seq_path, annot_format='movement', n_frames=None, fps=None)[source]#

Load annotations from a sequence directory using the requested format.

Parameters:

  • seq_path (Path) – Sequence directory.

  • annot_format (str) – Annotation format to load. Supported values are: “movement”, “csv-events”, and “boris”.

  • n_frames (Optional[int]) – Number of frames in the corresponding pose-tracking sequence.

  • fps (Optional[float]) – Frames per second used to convert interval times to frame indices. If missing, BORIS FPS metadata or a default value may be used.

Returns:

LISBET-compatible annotation dataset, or None if no annotation file is found for the requested format.

Return type:

Optional[Dataset]