to_via_tracks_file#

movement.io.save_bboxes.to_via_tracks_file(ds, file_path, track_ids_from_trailing_numbers=True, frame_n_digits=None, image_file_prefix=None, image_file_suffix='.png')[source]#

Save a movement bounding boxes dataset to a VIA tracks .csv file.

Parameters:

  • ds (xarray.Dataset) – The movement bounding boxes dataset to export.

  • file_path (str or pathlib.Path) – Path where the VIA tracks .csv file [1] will be saved.

  • track_ids_from_trailing_numbers (bool, optional) – If True, extract track IDs from the numbers at the end of the individuals’ names (e.g. mouse_1 -> track ID 1). If False, the track IDs will be assigned sequentially (0, 1, 2, …) based on the alphabetically sorted list of individuals’ names. Default is True.

  • frame_n_digits (int, optional) – The number of digits to use to represent frame numbers in the image filenames (including leading zeros). If None, the number of digits is automatically determined from the largest frame number in the dataset, plus one (to have at least one leading zero). Default is None.

  • image_file_prefix (str, optional) – Prefix to apply to every image filename. It is prepended to the frame number which is padded with leading zeros. If None or an empty string, nothing will be prepended to the padded frame number. Default is None.

  • image_file_suffix (str, optional) – Suffix to add to every image filename holding the file extension. Strings with or without the dot are accepted. Default is ‘.png’.

Returns:

Path to the saved file.

Return type:

pathlib.Path

Notes

The input arguments that define how the image filenames are formatted (frame_n_digits, image_file_prefix, and image_file_suffix) are useful to ensure the exported VIA tracks .csv file can be loaded in the VIA software alongside the image files the tracks refer to.

References

Examples

Export a movement bounding boxes dataset as a VIA tracks .csv file, deriving the track IDs from the numbers at the end of the individuals’ names and assuming the image files are PNG files. The frame numbers in the image filenames are padded with at least one leading zero by default:

>>> from movement.io import save_boxes
>>> save_boxes.to_via_tracks_file(ds, "/path/to/output.csv")

Export a movement bounding boxes dataset as a VIA tracks .csv file, assigning the track IDs sequentially based on the alphabetically sorted list of individuals’ names, and assuming the image files are PNG files:

>>> from movement.io import save_boxes
>>> save_boxes.to_via_tracks_file(
...     ds,
...     "/path/to/output.csv",
...     track_ids_from_trailing_numbers=False,
... )

Export a movement bounding boxes dataset as a VIA tracks .csv file, deriving the track IDs from the numbers at the end of the individuals’ names, and assuming the image files are JPG files:

>>> from movement.io import save_boxes
>>> save_boxes.to_via_tracks_file(
...     ds,
...     "/path/to/output.csv",
...     image_file_suffix=".jpg",
... )

Export a movement bounding boxes dataset as a VIA tracks .csv file, deriving the track IDs from the numbers at the end of the individuals’ names and with image filenames following the format frame-<frame_number>.jpg:

>>> from movement.io import save_boxes
>>> save_boxes.to_via_tracks_file(
...     ds,
...     "/path/to/output.csv",
...     image_file_prefix="frame-",
...     image_file_suffix=".jpg",
... )

Export a movement bounding boxes dataset as a VIA tracks .csv file, deriving the track IDs from the numbers at the end of the individuals’ names, and with frame numbers in the image filenames represented using 4 digits (i.e., image filenames would be 0000.png, 0001.png, etc.):

>>> from movement.io import save_boxes
>>> save_boxes.to_via_tracks_file(
...     ds,
...     "/path/to/output.csv",
...     frame_n_digits=4,
... )

Examples using to_via_tracks_file#

Load and upsample bounding box tracks

Load and upsample bounding box tracks