save_dataset#

movement.io.save.save_dataset(ds, file, target_software='movement', **kwargs)[source]#

Save a movement dataset to a file in any supported format.

Parameters:

  • ds (Dataset) – The movement dataset to save.

  • file (str | Path) – Path to the file to save the dataset to. The required file extension depends on the target format.

  • target_software (Literal['movement', 'DeepLabCut', 'SLEAP', 'LightningPose', 'NWB', 'VIA-tracks']) – The format to save the dataset in. Defaults to "movement", which saves the dataset in movement’s native netCDF format (.nc). Otherwise, one of the supported third-party formats.

  • **kwargs – Additional keyword arguments passed to the format-specific writer (e.g. split_individuals for DeepLabCut, config for NWB, or any xarray.Dataset.to_netcdf() argument for movement-netCDF).

Return type:

None

Raises:

  • TypeError – If ds is not an xarray.Dataset.

  • ValueError – If target_software is not a supported format, or if it is incompatible with the dataset’s ds_type (e.g. saving a bounding boxes dataset to a poses-only format).

See also

movement.io.save_poses, movement.io.save_bboxes

Notes

For NWB, each individual is written to a separate file (as required by the NWB format). For a single-individual dataset, the dataset is written to file. For a multi-individual dataset, each NWBFile’s identifier (by default the individual’s name, but configurable via NWBFileSaveConfig) is appended to the file path, just before the extension, e.g. "/path/to/file_id_0.nwb".

Examples

Save a dataset to movement’s native netCDF format:

>>> from movement.io import save_dataset
>>> save_dataset(ds, "/path/to/file.nc")

Save a poses dataset to a DeepLabCut .h5 file:

>>> save_dataset(ds, "/path/to/file.h5", target_software="DeepLabCut")

Save a bounding boxes dataset to a VIA-tracks .csv file:

>>> save_dataset(ds, "/path/to/file.csv", target_software="VIA-tracks")

Save a poses dataset to NWB file(s), with custom metadata:

>>> from movement.io.nwb import NWBFileSaveConfig
>>> config = NWBFileSaveConfig(
...     nwbfile_kwargs={"session_description": "foraging session"}
... )
>>> save_dataset(
...     ds, "/path/to/file.nwb", target_software="NWB", config=config
... )