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 and renaming.

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

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

Parameters:

data_format ({'movement', 'DLC', 'SLEAP'}) – 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; a record is kept if any substring occurs in its relative path. By default, all records are kept.
select_coords (str or None) – 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 coordinate names 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’.

Returns:

A list of Record objects, each containing id, posetracks, and optionally annotations.

Return type:

list[Record]

Raises:

ValueError – If data_format is unsupported, or if select_coords/rename_coords are invalid.
NotImplementedError – For recognized but unimplemented formats.

Examples

>>> 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",
... )
>>> 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.