Loading and saving keypoint annotation- SLEAP Integration.

[HarshdipSaha]

Add keypoint annotations support

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

This PR addresses #112 by adding support for loading and saving keypoint annotations datasets. Currently, ethology only supports bounding box annotations, but many pose estimation workflows (e.g., using SLEAP) work with keypoint data. This feature extends ethology's capabilities to handle keypoint annotations while maintaining consistency with the existing bounding box implementation.

What does this PR do?

This PR implements keypoint annotations support following the same architectural patterns as bounding boxes:

1. Validator: Adds ValidKeypointsAnnotationsDataset class in ethology/validators/annotations.py that validates datasets with required dimensions (image_id, space, keypoint, id) and required data variable position.

2. Loader: Adds ethology/io/annotations/load_keypoints.py with from_files() function that:

   • Uses sleap-io to load SLEAP .slp files
   • Transforms SLEAP Labels objects into ethology's 4D xarray format
   • Handles missing keypoints (represented as NaN) and multiple instances per frame
   • Preserves metadata (keypoint names, video/frame mappings)

3. Saver: Adds ethology/io/annotations/save_keypoints.py with to_file() function that:

   • Converts ethology keypoint datasets back to SLEAP Labels objects
   • Uses sleap-io to save to .slp format
   • Handles optional confidence and visibility arrays

4. Integration: Updates ethology/io/annotations/__init__.py to export the new modules.

5. Dependencies: Adds sleap-io as an optional dependency (required only for keypoints IO).

6. Tests: Adds comprehensive validator tests in tests/test_unit/test_validators/test_annotations.py and test fixtures in tests/fixtures/annotations.py.

The implementation follows ethology's design principles:

• No identity consistency across frames (annotations with same id in different images don't refer to the same individual)
• id dimension ranges from 0 to maximum number of instances per image
• Missing keypoints are represented as NaN values
• Follows the same validation and error handling patterns as bounding boxes

References

Closes #112

How has this PR been tested?

• Unit tests: Added 6 test cases for ValidKeypointsAnnotationsDataset validator covering valid datasets, invalid datasets (missing dimensions/variables), and edge cases. All tests pass.

• Integration tests: Created synthetic SLEAP files and verified:

  • Loading SLEAP files produces correct 4D xarray structure (image_id, space, keypoint, id)
  • Missing keypoints are correctly represented as NaN
  • Multiple instances per frame are handled correctly
  • Metadata (keypoint names, image mappings) is preserved

• Manual testing: Tested with synthetic data showing:

• Correct handling of empty first frames (fixed bug where code would crash if frame 0 had no instances)

• Proper NaN handling for occluded keypoints

• Visualization of 4D hypercube structure

• Existing tests: All existing bounding box tests continue to pass, confirming no regressions.

Is this a breaking change?

No..

Does this PR require an update to the documentation?

Yes, documentation can be updated to:

1. Document the new load_keypoints and save_keypoints modules in the API reference
2. Add an example in the gallery showing keypoint annotations workflow (loading, validation, basic analysis)
3. Update installation instructions to mention sleap-io as an optional dependency for keypoints support

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 (pending - can be done in follow-up PR)
• The code has been formatted with pre-commit

Additional Notes

• The validator is located in ethology/validators/annotations.py (not ethology/io/annotations/validate.py) to match the existing codebase structure where all validators are in the validators module.

• The implementation includes defensive code to handle variations in sleap-io API (different attribute names, optional parameters) to ensure compatibility across sleap-io versions.

[codecov]

Codecov Report

❌ Patch coverage is 99.14040% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.33%. Comparing base (33adaa5) to head (f102395).

Files with missing lines	Patch %	Lines
ethology/io/annotations/load_keypoints.py	98.64%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #135      +/-   ##
==========================================
- Coverage   99.45%   99.33%   -0.13%     
==========================================
  Files           8       11       +3     
  Lines         554      903     +349     
==========================================
+ Hits          551      897     +346     
- Misses          3        6       +3     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sfmig]

Hi @HarshdipSaha, would you mind having a look at the CI checks and solving the relevant issues? Thanks!

[HarshdipSaha]

Hi @sfmig , I have added the relevant tests for load and save key points