sleap-io v0.6.4

sleap-io v0.6.4 Release Notes

Summary

This release adds a sio export command for analysis-ready data export, fixes an out-of-memory crash in video rendering, and adds support for newer DeepLabCut file formats.

• Analysis Export: New sio export command for exporting pose data to CSV and HDF5 with frame padding, range selection, and multi-video batch export
• Memory-Efficient Rendering: sio render now streams frames to disk instead of accumulating them in memory, preventing OOM crashes on long videos
• DLC v2 Support: Automatically loads CSV files from newer DeepLabCut versions that use multi-column image paths
• Pandas 3.0 Compatibility: Internal test fix for compatibility with Pandas 3.0's new StringDtype

Installation / Upgrade

# One-off CLI usage (no installation needed)
uvx sleap-io@0.6.4 show labels.slp

# Install as CLI tool (new install)
uv tool install "sleap-io[all]"

# Upgrade existing CLI tool installation
uv tool upgrade sleap-io

# Add to project (new dependency)
uv add "sleap-io[all]"

# Upgrade existing project dependency
uv lock --upgrade-package sleap-io && uv sync

See installation docs for more options.

---

New Features

sio export Command for Analysis-Ready Data Export (#347)

A new dedicated CLI command for exporting pose tracking data to analysis-friendly formats. Unlike sio convert (which converts between pose tracking formats), sio export is optimized for downstream analysis workflows with options for frame padding, range selection, and batch export.

Basic Usage

# Export to CSV (default: frames-wide format with NaN padding for missing frames)
sio export labels.slp -o tracks.csv

# Export to HDF5 analysis format
sio export labels.slp -o analysis.h5

# Export a specific frame range
sio export labels.slp -o tracks.csv --start 100 --end 500

# Export all videos in a multi-video file
sio export labels.slp -o tracks.csv -v all
# Creates: tracks.video0.csv, tracks.video1.csv, ...

CSV Format Options

Five CSV layout formats are available via --csv-format:

Format	Description
frames (default)	One row per frame, columns for all coordinates
instances	One row per instance per frame
points	One row per keypoint per instance per frame
sleap	SLEAP-native column naming
dlc	DeepLabCut-compatible multi-header format

# Export in DLC-compatible format
sio export labels.slp -o tracks.csv --csv-format dlc --scorer MyModel

# Export point-level data with scores
sio export labels.slp -o tracks.csv --csv-format points --include-scores

Frame Padding

By default, sio export pads missing frames with NaN values for continuous time-series output. This ensures every frame in the range has a row, which is important for analysis tools that expect uniform sampling.

# Disable padding (only export frames with instances)
sio export labels.slp -o tracks.csv --no-empty-frames

Memory-Efficient Chunked Writing

For large datasets, use chunked CSV writing to limit memory usage:

sio export labels.slp -o tracks.csv --chunk-size 5000

Python API

import sleap_io as sio

# Save with frame padding and range selection
sio.save_csv(
    "tracks.csv",
    labels,
    include_empty=True,     # Pad missing frames with NaN
    start_frame=100,
    end_frame=500,
    chunk_size=5000,        # Memory-efficient chunked writing
)

Analysis HDF5 via sio convert

HDF5 analysis export is now also available through sio convert:

sio convert labels.slp -o analysis.h5
sio convert labels.slp -o analysis.h5 --h5-dim-order standard

---

Bug Fixes

Out-of-Memory Crash in Video Rendering (#348)

Fixed: render_video() and sio render would crash with an out-of-memory error on long or high-resolution videos.

Root Cause: All rendered frames were accumulated in a Python list before being written to disk. For a 1080p 10-minute video at 30fps (~18,000 frames at ~6 MB each), this required ~36 GB of memory.

Fix: Frames are now streamed directly to the VideoWriter as they are rendered. Peak memory is now constant (~5 MB) regardless of video length -- a 91% reduction in memory usage.

Scenario	Before	After
50 frames at 640x480	60.7 MB	5.3 MB
1080p, 10 min @ 30fps	~36 GB (OOM)	~12 MB

No changes to the API or CLI -- sio render and render_video() work exactly as before, just without crashing.

---

Newer DeepLabCut File Format Support (#343)

Fixed: Loading CSV files produced by newer versions of DeepLabCut returned 0 labeled frames.

Root Cause: Newer DLC versions (DeepLabCut PR #1584) changed how image paths are stored in CSV files. Instead of a single column with the full path (labeled-data/video/img000.png), the path is split across three columns as a pandas MultiIndex.

Fix: The DLC loader now auto-detects the newer format and handles it transparently. All three DLC variants (single-animal, multi-animal, multi-animal with unique tracking) are supported in both old and new formats.

# Works automatically with both old and new DLC files
labels = sio.load_file("dlc_project/CollectedData.csv")

---

Pandas 3.0 Test Compatibility (#344)

Fixed: The test_polars_pandas_equivalence test failed on Pandas 3.0 due to the new StringDtype not being compatible with np.issubdtype(). The comparison logic was simplified to use pd.testing.assert_frame_equal. This is an internal test-only fix with no impact on user-facing behavior.

---

API Changes

New Symbols

Type	Name	Location	Description
Function	export()	sleap_io.io.cli	CLI command for analysis-ready data export

New Parameters

Function	New Parameters
save_csv()	include_empty, start_frame, end_frame, chunk_size, video_id
to_dataframe()	all_frames, start_frame, end_frame

Modified Behavior

Symbol	Change
sio convert	Now supports analysis_h5 output format (.h5/.hdf5 extensions)
sio convert	New --h5-dim-order and --min-occupancy options for HDF5 output
save_csv(include_empty=...)	Previously accepted but ignored; now properly wired through to pad missing frames

CLI Changes

Command	Change
sio export	New command for analysis-ready CSV and HDF5 export
sio convert	Added analysis_h5 output support with --h5-dim-order and --min-occupancy options

---

Coordination Notes

For CSV Import/Export

• sleap-io now loads CSV files from both older and newer DLC versions automatically
• Export to DLC-compatible format: sio export labels.slp -o tracks.csv --csv-format dlc

For Analysis Pipelines

• The new sio export command is designed for feeding pose data into downstream analysis (e.g., behavior classification, kinematic analysis)
• Frame padding (--empty-frames) ensures continuous time series suitable for tools expecting uniform sampling
• Chunked writing (--chunk-size) enables export of very large datasets without memory issues

---

Changelog

• #343: fix(io): Add support for loading newer DLC files (@lochhh)
• #344: fix(tests): Simplify equivalence check between Polars and Pandas DataFrames (@lochhh)
• #347: feat(cli): Add sio export command for analysis-ready data export (@talmo)
• #348: fix(rendering): Stream frames to VideoWriter to prevent OOM (@talmo)

Full Changelog: v0.6.3...v0.6.4