Loading poses from LightningPose

[niksirbi]

Background

movement can currently load pose estimation results from DeepLabCut and SLEAP, but the overall aim is to support all popular animal pose estimaiton libraries.

LightningPose (LP) is a newer tool, but it's gaining in popularity. For example, it's being used within the Allen Institute for Neural Dynamics. Researchers in that institute were kind enough to share some sample output data with us (model predictions).

Based on that sample data, and on the relevant LP code for saving predictions, it seems that LP stores predictions in a pandas.DataFrame formatted in DeepLabCut (single-animal) format. The dataframe is then exported as a .csv file.

Plan

Since movement already supports loading data from csv files in DeepLabCut format, we can basically already load LP data via the load_poses.from_dlc_file() function. We would just need to change the ds.attrs["source_software"] = "DeepLabCut" line to ds.attrs["source_software"] = "LightningPose".

The easiest way to accomplish that would be to write a new user-facing load_poses.from_lp_file() function, that calls load_poses.from_dlc_file() under the hood, and then overwrites the "source_software" attribute.

As an alternative, we could refactor the separate loading functions into a single load_poses.from_file() function, and supply a "source_software" argument, which would then be passed to the synonymous attribute.

In any case, we would need to add some LP output files to our test data and add the relevant test cases.

Context

This wasn't originally planned for v0.1, but given that it's a low hanging fruit, we might as well implement it now.

[adamltyson]

In case any of these packages change their output formats, what about something like the following (with better function names)?

def load_dlc(path):
    return load_single_animal_df(path, source="dlc")

def load_lp(path):
    return load_single_animal_df(path, source="lp")

def load_single_animal_df(path, source="default"):
    ....

As an aside, I (as a user) much prefer load_dlc(), load_sleap() etc than load_data(source="dlc").

[niksirbi]

Actually, a version of what @adamltyson proposes can be easily done with the existing structure in io.load_poses.py. The relevant functionality that parses DLC-style .csv files into a pandas dataframe is already a separate utility function - _parse_dlc_csv_to_df.

So we could have something like:

def from_lp_file(file_path, fps):
"""Load pose tracking data from Lightning pose output .csv file
...
"""
    file = ValidFile(
        file_path,
        expected_permission="r",
        expected_suffix=[".csv"],
    )

    df = _parse_dlc_csv_to_df(file.path)
    ds = from_dlc_df(df=df, fps=fps)

    # Add metadata as attrs
    ds.attrs["source_software"] = "LightningPose"
    ds.attrs["source_file"] = file.path.as_posix()
    
    return ds

I've skipped over logging and other niceties in the above example, but I think that's all it would take.
Basically, once I add some test files to our GIN repository, this feature can be added immediately after.