Reorder dimensions

[lochhh]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
This PR closes #236.

What does this PR do?
This PR

• reorders the dimensions of movement poses and bboxes datasets as follows:
  • poses: ("time", "individuals", "keypoints", "space") → ("time", "space", "keypoints", "individuals")
  • bboxes: ("time", "individuals", "space") → ("time", "space", "individuals")
• updates the docs (by first checking changed files, and then searching for the keyword "shape" in the entire directory)
• removes the duplicated assert_dataset in test_load_poses and test_load_bboxes by introducing a new helper class MovementDatasetAsserts in conftest.py that provides a common valid_dataset function to assert poses and bboxes dataset validity in tests
• replaces if-else-blocks with a ternary operator
• fixes broken examples (in docstrings and in .md)
• fixes broken references to external packages

Strategy:

• Directly transpose after datasets are loaded as xarray.Datasets (i.e. validators are still using the old "dims order")
• Make tests pass (by transposing fixtures) for both poses and bboxes
• Change the order in Validators (at the root) so that we don't need to transpose the dataset after loading them into movement
• Drop transpose in test fixtures and make tests pass by creating fixtures with the new "dims order"
• Refactor tests (e.g. duplicated code )
• Update documentation/docstrings

References

#236

How has this PR been tested?

Tests pass locally and on CI.

Does this PR require an update to the documentation?

Done.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.78%. Comparing base (f7539b9) to head (06a0d9d).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #351   +/-   ##
=======================================
  Coverage   99.78%   99.78%           
=======================================
  Files          14       14           
  Lines         927      932    +5     
=======================================
+ Hits          925      930    +5     
  Misses          2        2           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[niksirbi]

Thanks for undertaking this tricky surgery @lochhh, a PR that touches almost all files!

I couldn't find a fault with it and I'd say this is good to go, after resolving merge conflicts.

There is one thing I'm puzzled about, which you perhaps can help with.
In compute_norm(), we have:

if "space" in data.dims:
        validate_dims_coords(data, {"space": ["x", "y"]})
        return xr.apply_ufunc(
            np.linalg.norm,
            data,
            input_core_dims=[["space"]],
            kwargs={"axis": -1},
        )

kwargs={"axis": -1} is passed onto linalg.norm and I understood it as meaning the "norm along the space axis". You haven't updated this, so by my logic this should be broken now, but the passing tests indicate that it works as expected. What gives?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[lochhh]

Thanks! Rebase is done now.

There is one thing I'm puzzled about, which you perhaps can help with. In compute_norm(), we have:

if "space" in data.dims:
        validate_dims_coords(data, {"space": ["x", "y"]})
        return xr.apply_ufunc(
            np.linalg.norm,
            data,
            input_core_dims=[["space"]],
            kwargs={"axis": -1},
        )

kwargs={"axis": -1} is passed onto linalg.norm and I understood it as meaning the "norm along the space axis". You haven't updated this, so by my logic this should be broken now, but the passing tests indicate that it works as expected. What gives?

From xarray's apply_ufunc tutorial:

With apply_ufunc, core dimensions are recognized by name, and then moved to the last dimension of any input arguments before applying the given function. This means that for functions that accept an axis argument, you usually need to set axis=-1

[niksirbi]

With apply_ufunc, core dimensions are recognized by name, and then moved to the last dimension of any input arguments before applying the given function. This means that for functions that accept an axis argument, you usually need to set axis=-1

That's cool, thanks for clarifying! LGTM 🎉