lisbet.io.core#

IO utilities for LISBET.

Functions

dump_annotations(results, output_path)

Save LISBET behavior predictions to CSV files.

dump_embeddings(results, output_path)

Save LISBET embeddings to CSV files.

dump_evaluation_results(report, output_path, ...)

Save evaluation report to a YAML file in a standardized location.

dump_model_config(output_path, run_id, ...)

Save model configuration to YAML file.

dump_profiling_results(output_path, run_id, prof)

Internal helper.

dump_records(data_path, records)

Dump a list of records to a file.

dump_weights(model, output_path, run_id, ...)

Internal helper.

export_embedder(model_path, weights_path[, ...])

load_model(config_path, weights_path)

Load a pretrained LISBET model from a configuration file.

load_multi_records(data_config)

Internal helper.

load_records(data_format, data_path[, ...])

Load pose-tracking records from a directory, with optional filtering, coordinate selection, coordinate renaming, and annotation-format selection.

Classes

Record(id, posetracks[, annotations])

Data structure representing a single pose-tracking record.
class lisbet.io.core.Record(id, posetracks, annotations=None)[source]#

Data structure representing a single pose-tracking record.

Parameters:

  • id (str) – Unique identifier for the record, typically derived from the relative path.

  • posetracks (Dataset) – Pose-tracking data for the record.

  • annotations (Dataset | None) – Annotations associated with the record, if available.

id: str#
posetracks: Dataset#
annotations: Dataset | None = None#
__init__(id, posetracks, annotations=None)#
lisbet.io.core.load_records(data_format, data_path, data_scale=None, data_filter=None, select_coords=None, rename_coords=None, annot_format='movement')[source]#

Load pose-tracking records from a directory, with optional filtering, coordinate selection, coordinate renaming, and annotation-format selection.

Parameters:

  • data_format ({'movement', 'DLC', 'SLEAP'}) – Pose-tracking dataset format to load.

  • data_path (str or Path) – Root directory containing the sequence sub-directories.

  • data_scale (str, optional) – If supplied as WIDTHxHEIGHT or WIDTHxHEIGHTxDEPTH, every input coordinate is assumed to be in data units and is divided by the given scale to obtain normalized coordinates in the range [0, 1]. Otherwise, the algorithm infers the active extent directly from the data.

  • data_filter (str, optional) – Comma-separated substrings used to filter records. A record is kept if any substring occurs in its relative path. By default, all records are kept.

  • select_coords (str or None, optional) –

    Optional subset string in the format ‘INDIVIDUALS;AXES;KEYPOINTS’, where each field is a comma-separated list or ‘*’ for all. If None, all data is loaded.

    Example:

    ’mouse1,mouse2;x,y;nose,tail’

  • rename_coords (str or None, optional) –

    Optional coordinate-name remapping in the format ‘INDIVIDUALS;AXES;KEYPOINTS’, where each field is a comma-separated list of maps ‘old_id:new_id’ or ‘*’ for no remapping at that level. If None, original dataset names are used.

    Example:

    ’mouse1:resident,mouse2:intruder;*;nose:snout,tail:tailbase’

  • annot_format ({'movement', 'csv-events', 'boris'}, optional) –

    Annotation format to load. The default is ‘movement’, which preserves the current LISBET behavior and loads NetCDF annotation files such as annotations.nc or manual_scoring.nc.

    Supported values are:

    • ’movement’:

      Current/default LISBET annotation format based on NetCDF files.

    • ’csv-events’:

      Generic interval-based CSV annotation format with columns such as behavior, start_time, and end_time.

    • ’boris’:

      BORIS tabular CSV export format, where state behaviors are represented by paired START and STOP rows.

    All supported annotation formats are converted internally to the LISBET annotation representation:

    xarray.Dataset with dimensions:

    time, behaviors, annotators

    and data variable:

    target_cls(time, behaviors, annotators)

Returns:

A list of Record objects. Each Record contains:

  • idstr

    Record identifier relative to data_path.

  • posetracksxarray.Dataset

    Loaded and preprocessed pose-tracking data.

  • annotationsxarray.Dataset or None

    Loaded annotations in the internal LISBET format, or None if no annotation file is found for the requested annotation format.

Return type:

list[Record]

Raises:

  • ValueError – If data_format is unsupported, if annot_format is unsupported, if select_coords or rename_coords are invalid, or if no valid records are found in the specified directory.

  • NotImplementedError – For recognized but unimplemented pose-tracking formats.

Examples

Load records using the default LISBET/movement annotation format:

>>> records = load_records(
...     data_format="movement",
...     data_path="~/datasets/mice",
...     select_coords="mouse1,mouse2;x,y;nose,tail",
...     rename_coords="mouse1:resident,mouse2:intruder;*;nose:snout,tail:tailbase",
...     annot_format="movement",
... )

Load records with BORIS CSV annotations:

>>> records = load_records(
...     data_format="movement",
...     data_path="~/datasets/mice",
...     annot_format="boris",
... )

Inspect the first loaded record:

>>> print(len(records))
42
>>> print(records[0].id)
'session1/seq001'
>>> print(records[0].posetracks)
<xarray.Dataset ...>
>>> print(records[0].annotations)
<xarray.Dataset ...> or None
lisbet.io.core.load_multi_records(data_config)[source]#

Internal helper. Loads and splits records for all tasks.

lisbet.io.core.load_model(config_path, weights_path)[source]#

Load a pretrained LISBET model from a configuration file.

This function supports loading models from YAML configuration files (as used in LISBET). It uses the model factory to instantiate the model and loads weights from the specified file.

Parameters:

  • config_path (str or Path or dataclass) – Path to the model configuration YAML file.

  • weights_path (str or Path) – Path to the model weights file.

Returns:

The loaded LISBET model.

Return type:

torch.nn.Module

lisbet.io.core.export_embedder(model_path, weights_path, output_path=PosixPath('.'))[source]#
lisbet.io.core.dump_records(data_path, records)[source]#

Dump a list of records to a file.

Pose tracks and annotations are saved in a NetCDF format.

Parameters:

  • data_path (str or Path) – Directory where the records will be saved.

  • records (list of Record) – List of Record objects to be saved.

lisbet.io.core.dump_annotations(results, output_path)[source]#

Save LISBET behavior predictions to CSV files.

Parameters:

  • results (list of (record_id, np.ndarray)) – Output from annotate_behavior.

  • output_path (str or Path) – Root directory to save CSVs. Each record will be saved under output_path/annotations/<record_id>/machineAnnotation_lisbet.csv

lisbet.io.core.dump_embeddings(results, output_path)[source]#

Save LISBET embeddings to CSV files.

Parameters:

  • results (list of (record_id, np.ndarray)) – Output from compute_embeddings.

  • output_path (str or Path) – Root directory to save CSVs. Each record will be saved under output_path/embeddings/<record_id>/features_lisbet_embedding.csv

lisbet.io.core.dump_evaluation_results(report, output_path, model_path)[source]#

Save evaluation report to a YAML file in a standardized location.

Parameters:

  • report (dict) – The evaluation report.

  • output_path (str) – Directory to save the report.

  • model_path (str) – Path to the model config (used to extract model_id).

lisbet.io.core.dump_weights(model, output_path, run_id, filename)[source]#

Internal helper. Saves model weights.

lisbet.io.core.dump_model_config(output_path, run_id, model_config)[source]#

Save model configuration to YAML file.

lisbet.io.core.dump_profiling_results(output_path, run_id, prof)[source]#

Internal helper. Saves profiling results.