register_writer#

movement.io.save.register_writer(target_software, *, ds_type=None, suffixes=None)[source]#

Register a writer function for a given target software.

The decorator also handles dataset and file path validation: the dataset is checked against its expected type (ds_type, or if unset, the type inferred from ds.attrs["ds_type"]), and the file path is checked for write permission and optional suffixes, before the writer function is called.

Parameters:

  • target_software (Literal['movement', 'DeepLabCut', 'SLEAP', 'LightningPose', 'NWB', 'VIA-tracks']) – The name of the target software to save to.

  • ds_type (Literal['poses', 'bboxes'] | None) – The movement dataset type the writer is restricted to. If None (default), the writer (e.g., movement’s native netCDF format) accepts either type, and the expected type is instead inferred from the dataset’s ds_type attribute at save time.

  • suffixes (set[str] | None) – The set of valid file suffixes (e.g. {".h5", ".csv"}) for this writer. If None (default), the file path is still validated for write permission, but its suffix is not checked.

Returns:

A decorator that registers the writer function.

Return type:

Callable[[Callable[[Concatenate[Dataset, str | Path, ParamSpec(P)]], None]], Callable[[Concatenate[Dataset, str | Path, ParamSpec(P)]], None]]

Notes

The file argument passed to the decorated writer function will be a validated pathlib.Path object, instead of the original file path.

Examples

>>> from movement.io.save import register_writer
>>> @register_writer("SLEAP", ds_type="poses", suffixes={".h5"})
... def to_sleap_analysis_file(ds: xr.Dataset, file: str | Path):
...     pass