to_nwb_file#

movement.io.save_poses.to_nwb_file(ds, config=None)[source]#

Save a movement dataset to one or more NWBFile objects.

The data will be written to pynwb.file.NWBFile object(s) in the “behavior” processing module, formatted according to the ndx-pose NWB extension [1]. Each individual in the dataset will be written to a separate NWBFile, as required by the NWB format. Note that the NWBFile(s) are not automatically saved to disk.

Parameters:

  • ds (xarray.Dataset) – movement poses dataset containing the data to be converted to NWBFile(s).

  • config (NWBFileSaveConfig, optional) – Configuration object containing keyword arguments to customise the pynwb.file.NWBFile (s) that will be created for each individual. If None (default), default values will be used.

Returns:

If the dataset contains only one individual, a single NWBFile object will be returned. If the dataset contains multiple individuals, a list of NWBFile objects will be returned, one for each individual.

Return type:

pynwb.file.NWBFile or list[pynwb.file.NWBFile]

References

Examples

Create pynwb.file.NWBFile objects for each individual in a movement poses dataset ds and save them to disk:

>>> from movement.sample_data import fetch_dataset
>>> from movement.io import save_poses
>>> from pynwb import NWBHDF5IO
>>> ds = fetch_dataset("DLC_two-mice.predictions.csv")
>>> nwb_files = save_poses.to_nwb_file(ds)
>>> for file in nwb_files:
...     with NWBHDF5IO(f"{file.identifier}.nwb", "w") as io:
...         io.write(file)

Create NWBFiles with custom metadata shared across individuals. Specifically, we add metadata for pynwb.file.NWBFile, pynwb.base.ProcessingModule, and pynwb.file.Subject via the NWBFileSaveConfig object.

>>> from movement.io.nwb import NWBFileSaveConfig
>>> config = NWBFileSaveConfig(
...     nwbfile_kwargs={"session_description": "test session"},
...     processing_module_kwargs={"description": "processed behav data"},
...     subject_kwargs={"age": "P90D", "species": "Mus musculus"},
... )
>>> nwb_files = save_poses.to_nwb_file(ds, config)

Create NWBFiles with different pynwb.file.NWBFile and pynwb.file.Subject metadata for each individual (e.g. individual1, individual2) in the dataset:

>>> config = NWBFileSaveConfig(
...     nwbfile_kwargs={
...         "individual1": {
...             "experimenter": "experimenter1",
...             "session_description": "subj1 session",
...         },
...         "individual2": {
...             "experimenter": "experimenter2",
...             "session_description": "subj2 session",
...         },
...     },
...     subject_kwargs={
...         "individual1": {"age": "P90D", "sex": "M"},
...         "individual2": {"age": "P91D", "sex": "F"},
...     },
... )
>>> nwb_files = save_poses.to_nwb_file(ds, config)

Create NWBFiles with different ndx_pose.PoseEstimationSeries metadata for different keypoints (e.g. leftear, rightear):

>>> config = NWBFileSaveConfig(
...     pose_estimation_series_kwargs={
...         "leftear": {
...             "description": "left ear",
...         },
...         "rightear": {
...             "description": "right ear",
...         },
...     },
... )
>>> nwb_files = save_poses.to_nwb_file(ds, config)

See also

movement.io.nwb.NWBFileSaveConfig

For further details on the configuration object and its parameters.

On this page

This Page