Add LEAP .mat format reader

[talmo]

Summary

This PR adds support for reading LEAP (LEAP Estimates Animal Pose) MATLAB .mat files. LEAP is a deep learning framework for animal pose estimation that exports tracking data in MATLAB format. This implementation provides a read-only interface to import LEAP tracking data into the SLEAP ecosystem.

Key Changes

Core Implementation

• New I/O Module: Added sleap_io/io/leap.py with read_labels() function for parsing LEAP .mat files
• Format Integration: Added load_leap() wrapper function and automatic .mat file format detection in load_file()
• Package Exports: Updated sleap_io/__init__.py to expose load_leap function
• Dependencies: Added pymatreader as an optional dependency in the [mat] extra group

Data Parsing Features

• Skeleton Parsing: Extracts node names from nodes or joints fields, builds edge connections
• Position Data: Handles multiple array shapes (2D/3D), supports alternative field names (positions, pose, posedata)
• Video Path Resolution: Automatically infers video path from .mat file path when boxPath field is missing
• Index Conversion: Properly converts MATLAB 1-based indexing to Python 0-based indexing
• Custom Skeleton Support: Allows users to override the skeleton structure when loading

Example Usage

import sleap_io as sio

# Basic loading
labels = sio.load_leap("path/to/leap_data.mat")

# Auto-detection via load_file
labels = sio.load_file("path/to/leap_data.mat")

# Custom skeleton override
custom_skeleton = sio.Skeleton(
    nodes=["head", "tail"], 
    edges=[("head", "tail")]
)
labels = sio.load_leap("path/to/leap_data.mat", skeleton=custom_skeleton)

# Access the loaded data
print(f"Loaded {len(labels.labeled_frames)} frames")
print(f"Skeleton has {len(labels.skeleton.nodes)} nodes")
for frame in labels.labeled_frames:
    for instance in frame.instances:
        print(f"Frame {frame.frame_idx}: {len(instance.points)} points")

Installation

To use the LEAP reader, install sleap-io with the mat extra:

# Using pip
pip install sleap-io[mat]

# Using uv
uv pip install sleap-io[mat]

# From source with all extras
uv sync --all-extras

API Changes

New Public Functions

• sleap_io.load_leap(filename: str, skeleton: Optional[Skeleton] = None) -> Labels
• sleap_io.io.leap.read_labels(labels_path: str, skeleton: Optional[Skeleton] = None) -> Labels

Updated Functions

• load_file() now automatically detects .mat files and routes them to the LEAP loader
• Supported formats list updated to include "leap"

Testing

Comprehensive test coverage (94.0%) with 11 test cases covering:

• Loading via multiple API entry points
• Custom skeleton support
• Missing dependency handling
• Various position data formats (2D/3D arrays)
• Alternative field names
• Edge cases in skeleton parsing
• Video path inference

# Run tests
uv run pytest tests/io/test_leap.py -v
# 11 passed

# Coverage report
uv run pytest tests/io/test_leap.py --cov=sleap_io.io.leap --cov-report=term
# Coverage: 94.0%

Design Decisions

1. Read-only Implementation: LEAP files are typically generated by the LEAP software itself, so writing support was not implemented. Users should export from LEAP and import into SLEAP.

2. Video Path Inference: When boxPath is missing from the .mat file, we infer the video path by replacing the .mat extension with .mp4 (most common video format).

3. Flexible Field Names: LEAP exports may use different field names (positions, pose, posedata) depending on the version. The reader tries multiple alternatives.

4. Array Shape Handling: LEAP may store positions as either (nodes, 2, frames) or (frames, nodes, 2). The reader automatically detects and transposes as needed.

5. Optional Dependency: pymatreader is only required when using LEAP functionality, keeping the base installation lightweight.

File Format Notes

LEAP .mat files typically contain:

• skeleton: Dictionary with nodes/joints (node names) and edges (connections)
• positions/pose/posedata: Array of shape (nodes, 2, frames) or (frames, nodes, 2)
• boxPath: Optional path to the associated video file
• Additional metadata fields that are currently ignored

Future Considerations

• Could add support for LEAP's confidence scores if they become available in the format
• Might extend to handle multiple animals/tracks if LEAP adds multi-animal support
• Could implement a writer if there's demand for round-trip conversion

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.29630% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.19%. Comparing base (1513e82) to head (f5af8b4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
sleap_io/io/leap.py	95.89%	0 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #224      +/-   ##
==========================================
+ Coverage   93.14%   93.19%   +0.04%     
==========================================
  Files          24       25       +1     
  Lines        5119     5199      +80     
  Branches     1378     1403      +25     
==========================================
+ Hits         4768     4845      +77     
  Misses        156      156              
- Partials      195      198       +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.