Ability to save multi-animal pose tracks to single-animal files

[niksirbi]

This is especially relevant for DeepLabCut. Its pose estimation data used to be stored in a DataFrame with the following column levels: "scorer", "bodyparts" and "coords". After the introduction of multi-animal DeepLabCut, they've added an extra "individuals" level between "scorer" and "bodyparts".

PR #33 introduced the save_poses.to_dlc_file() which exports pose data in DeepLabCut format, using the more general 4 levels (including "individuals"). So both single- and multi- animal data is saved in the multi-animal format.

Some downstream tools (e.g. for action segmentation), may only accept single-animal DeepLabCut files. Therefore it would be useful to add a split=True argument to save_poses.to_dlc_file(), which will split multi-animal pose data into single-animal files.

[niksirbi]

Rough plan on how this could be done

The current to_dlc_file() function:

def to_dlc_file(ds: xr.Dataset, file_path: Union[str, Path]) -> None:
    """Save the xarray dataset containing pose tracks to a
    DeepLabCut-style ".h5" or ".csv" file.

    Parameters
    ----------
    ds : xarray Dataset
        Dataset containing pose tracks, confidence scores, and metadata.
    file_path : pathlib Path or str
        Path to the file to save the DLC poses to. The file extension
        must be either ".h5" (recommended) or ".csv".

    See Also
    --------
    to_dlc_df : Convert an xarray dataset containing pose tracks into a
        DeepLabCut-style pandas DataFrame with multi-index columns.
    """

could be changed to something like:

def to_dlc_file(
        ds: xr.Dataset,
        file_path: Union[str, Path],
        format: Literal["auto", "multi", "single"] = "auto",
) -> None:
    """Save the xarray dataset containing pose tracks to a
    DeepLabCut-style ".h5" or ".csv" file.

    Parameters
    ----------
    ds : xarray Dataset
        Dataset containing pose tracks, confidence scores, and metadata.
    file_path : pathlib Path or str
        Path to the file to save the DLC poses to. The file extension
        must be either ".h5" (recommended) or ".csv".
    format : {"multi", "single"}, optional
        Format of the DeepLabcut output file.
        - If "multi", the file will be formatted as in a multi-animal 
        DeepLabCut project: the columns will include the 
        "individuals" level and all individuals will be saved to the same file. 
        - If "single", the file will be formatted as in a single-animal 
        DeepLabCut project: no "individuals" level, and each individual will be
        saved in a separate file. The individual's name will be appended to the
        file path, just before the file extension, i.e. 
        "/path/to/filename_individual1.h5".
        - If "auto" the format will be determined based on the number of
        individuals in the dataset: "multi" if there are more than one, and
        "single" if there is only one. This is the default.
    
    See Also
    --------
    to_dlc_df : Convert an xarray dataset containing pose tracks into a
        DeepLabCut-style pandas DataFrame with multi-index columns.

    Examples
    --------
    >>> from movement.io import save_poses, load_poses
    >>> ds = load_poses.from_sleap("/path/to/file_sleap.analysis.h5")
    >>> save_poses.to_dlc_file(ds, "/path/to/file_dlc.h5")
    """

The save_poses.to_dlc_df() would have to be modified accordingly as well. It's not the most elegant way, since I don't like how the filename is being handled (not sure it will be intuitive for the users), so open to other suggestions as well.

For reference, this how DeepLabCut itself converts between the two formats.