sleap-io¶

PyPI - Python Version

Standalone utilities for working with animal pose tracking data.

This is intended to be a complement to the core SLEAP package that aims to provide functionality for interacting with pose tracking-related data structures and file formats with minimal dependencies. This package does not have any functionality related to labeling, training, or inference.

Installation¶

pip install sleap-io

or

conda install -c conda-forge sleap-io

For development, use one of the following syntaxes:

conda env create -f environment.yml

pip install -e .[dev]

Usage¶

Load and save in different formats¶

import sleap_io as sio

# Load from SLEAP file.
labels = sio.load_file("predictions.slp")

# Save to NWB file.
labels.save("predictions.nwb")

See also: Labels.save and Formats

Convert labels to raw arrays¶

import sleap_io as sio

labels = sio.load_slp("tests/data/slp/centered_pair_predictions.slp")

# Convert predictions to point coordinates in a single array.
trx = labels.numpy()
n_frames, n_tracks, n_nodes, xy = trx.shape
assert xy == 2

# Convert to array with confidence scores appended.
trx_with_scores = labels.numpy(return_confidence=True)
n_frames, n_tracks, n_nodes, xy_score = trx.shape 
assert xy_score == 3

See also: Labels.numpy

Read video data¶

import sleap_io as sio

video = sio.load_video("test.mp4")
n_frames, height, width, channels = video.shape

frame = video[0]
height, width, channels = frame.shape

See also: sio.load_video and Video

Create labels from raw data¶

import sleap_io as sio
import numpy as np

# Create skeleton.
skeleton = sio.Skeleton(
    nodes=["head", "thorax", "abdomen"],
    edges=[("head", "thorax"), ("thorax", "abdomen")]
)

# Create video.
video = sio.load_video("test.mp4")

# Create instance.
instance = sio.Instance.from_numpy(
    points=np.array([
        [10.2, 20.4],
        [5.8, 15.1],
        [0.3, 10.6],
    ]),
    skeleton=skeleton
)

# Create labeled frame.
lf = sio.LabeledFrame(video=video, frame_idx=0, instances=[instance])

# Create labels.
labels = sio.Labels(videos=[video], skeletons=[skeleton], labeled_frames=[lf])

# Save.
labels.save("labels.slp")

Fix video paths¶

import sleap_io as sio

# Load labels without trying to open the video files.
labels = sio.load_file("labels.v001.slp", open_videos=False)

# Fix paths using prefix replacement.
labels.replace_filenames(prefix_map={
    "D:/data/sleap_projects": "/home/user/sleap_projects",
    "C:/Users/sleaper/Desktop/test": "/home/user/sleap_projects",
})

# Save labels with updated paths.
labels.save("labels.v002.slp")

See also: Labels.replace_filenames

Save labels with embedded images¶

import sleap_io as sio

# Load source labels.
labels = sio.load_file("labels.v001.slp")

# Save with embedded images for frames with user labeled data and suggested frames.
labels.save("labels.v001.pkg.slp", embed="user+suggestions")

See also: Labels.save

Make training/validation/test splits¶

import sleap_io as sio

# Load source labels.
labels = sio.load_file("labels.v001.slp")

# Make splits and export with embedded images.
labels.make_training_splits(n_train=0.8, n_val=0.1, n_test=0.1, save_dir="split1", seed=42)

# Splits will be saved as self-contained SLP package files with images and labels.
labels_train = sio.load_file("split1/train.pkg.slp")
labels_val = sio.load_file("split1/val.pkg.slp")
labels_test = sio.load_file("split1/test.pkg.slp")

See also: Labels.make_training_splits

Support¶

For technical inquiries specific to this package, please open an Issue with a description of your problem or request.

For general SLEAP usage, see the main website.

Other questions? Reach out to talmo@salk.edu.

License¶

This package is distributed under a BSD 3-Clause License and can be used without restrictions. See LICENSE for details.