NWB Format (.nwb)¶

Neurodata Without Borders (NWB) is a standardized format for neurophysiology data. sleap-io provides comprehensive support for both reading and writing pose tracking data in NWB format.

Harmonized NWB I/O¶

The harmonized API automatically detects and routes to the appropriate NWB backend:

`sleap_io.io.main.load_nwb(filename, **kwargs)` ¶

Load an NWB dataset as a SLEAP Labels object.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to a NWB file (`.nwb`).	required
`**kwargs`		Additional loader keyword arguments forwarded by `load_file` (e.g. `open_videos`, `lazy`). They are accepted but ignored; this format does not use them.	required

Returns:

Type	Description
`Labels`	The dataset as a `Labels` object.

Source code in sleap_io/io/main.py

def load_nwb(filename: str, **kwargs) -> Labels:
    """Load an NWB dataset as a SLEAP `Labels` object.

    Args:
        filename: Path to a NWB file (`.nwb`).
        **kwargs: Additional loader keyword arguments forwarded by `load_file`
            (e.g. ``open_videos``, ``lazy``). They are accepted but ignored; this
            format does not use them.

    Returns:
        The dataset as a `Labels` object.
    """
    from sleap_io.io import nwb

    return nwb.load_nwb(filename)

`sleap_io.io.main.save_nwb(labels, filename, nwb_format='auto', append=False)` ¶

Save a SLEAP dataset to NWB format.

Parameters:

Name	Type	Description	Default
`labels`	`Labels`	A SLEAP `Labels` object (see `load_slp`).	required
`filename`	`str \| Path`	Path to NWB file to save to. Must end in `.nwb`.	required
`nwb_format`	`str`	Format to use for saving. Options are: - "auto" (default): Automatically detect based on data - "annotations": Save training annotations (PoseTraining) - "annotations_export": Export annotations with video frames - "predictions": Save predictions (PoseEstimation)	`'auto'`
`append`	`bool`	If True, append to existing NWB file. Only supported for predictions format. Defaults to False.	`False`

Raises:

Type	Description
`ValueError`	If an invalid format is specified.

Source code in sleap_io/io/main.py

def save_nwb(
    labels: Labels,
    filename: str | Path,
    nwb_format: str = "auto",
    append: bool = False,
) -> None:
    """Save a SLEAP dataset to NWB format.

    Args:
        labels: A SLEAP `Labels` object (see `load_slp`).
        filename: Path to NWB file to save to. Must end in `.nwb`.
        nwb_format: Format to use for saving. Options are:
            - "auto" (default): Automatically detect based on data
            - "annotations": Save training annotations (PoseTraining)
            - "annotations_export": Export annotations with video frames
            - "predictions": Save predictions (PoseEstimation)
        append: If True, append to existing NWB file. Only supported for
            predictions format. Defaults to False.

    Raises:
        ValueError: If an invalid format is specified.
    """
    from sleap_io.io import nwb
    from sleap_io.io.nwb import NwbFormat

    # Convert string to NwbFormat if needed
    if isinstance(nwb_format, str):
        nwb_format = NwbFormat(nwb_format)

    nwb.save_nwb(labels, filename, nwb_format, append=append)

NWB Format Types¶

sleap-io supports multiple NWB format types through the nwb_format parameter:

"auto" (default): Automatically detect based on data content
Uses "annotations" if data contains user-labeled instances
Uses "predictions" if data contains only predicted instances
"annotations": Save as PoseTraining format (ndx-pose extension)
Stores manual annotations for training data
Preserves skeleton structure and node names
Includes annotator information
"annotations_export": Export annotations with embedded video frames
Creates self-contained NWB file with video data
Generates MJPEG video with frame provenance tracking
Useful for sharing complete datasets
"predictions": Save as PoseEstimation format (ndx-pose extension)
Stores predicted pose data from inference
Includes confidence scores
Supports multiple animals/tracks

Examples¶

Basic NWB Usage¶

import sleap_io as sio

# Load any NWB file (auto-detects format)
labels = sio.load_nwb("pose_data.nwb")

# Save with auto-detection
sio.save_nwb(labels, "output.nwb")

# Save with specific format
sio.save_nwb(labels, "training.nwb", nwb_format="annotations")
sio.save_nwb(labels, "predictions.nwb", nwb_format="predictions")

Advanced Annotations API¶

For more control over NWB training data, use the annotations module directly:

from sleap_io.io.nwb_annotations import save_labels, load_labels

# Save with custom metadata
save_labels(
    labels,
    "training.nwb",
    session_description="Mouse reaching task",
    identifier="mouse_01_session_03",
    annotator="researcher_name",
    nwb_kwargs={
        "session_id": "session_003",
        "experimenter": ["John Doe", "Jane Smith"],
        "lab": "Motor Control Lab",
        "institution": "University",
        "experiment_description": "Skilled reaching behavior"
    }
)

# Load annotations
labels = load_labels("training.nwb")

Export with Video Frames¶

from sleap_io.io.nwb_annotations import export_labels, export_labeled_frames

# Export complete dataset with videos
export_labels(
    labels,
    output_dir="export/",
    nwb_filename="dataset_with_videos.nwb",
    as_training=True,  # Include manual annotations
    include_videos=True  # Embed video frames
)

# Export only labeled frames as video
export_labeled_frames(
    labels,
    output_path="labeled_frames.avi",
    labels_output_path="labels.nwb",
    fps=30.0
)

Multi-Subject Support¶

For multi-animal experiments, sleap-io supports the ndx-multisubjects NWB extension. This links each tracked animal to a proper NWB Subject entry.

from sleap_io.io.nwb_annotations import save_labels

# Basic multi-subject export (uses track names as subject IDs)
save_labels(labels, "output.nwb", use_multisubjects=True)

# With detailed subject metadata
subjects_metadata = [
    {"sex": "M", "species": "Mus musculus", "age": "P30D"},
    {"sex": "F", "species": "Mus musculus", "age": "P45D"},
]
save_labels(
    labels,
    "output.nwb",
    use_multisubjects=True,
    subjects_metadata=subjects_metadata
)

Subject metadata fields

The subjects_metadata list should have one entry per track. Each entry can include:

sex: Subject sex (defaults to "U" for unknown)
species: Species name (defaults to "unknown")
age: Age in ISO 8601 duration format (e.g., "P30D" for 30 days)
Any other fields supported by NWB Subject

Tracked instances required

Multi-subject export requires all instances to have track assignments. A warning is issued if untracked instances are present.

NWB Metadata¶

The NWB format requires certain metadata fields. sleap-io provides sensible defaults:

Required fields (auto-generated if not provided):
session_description: Defaults to "Processed SLEAP pose data"
identifier: Auto-generated UUID string
session_start_time: Current timestamp
Optional fields (via nwb_kwargs):
session_id: Unique session identifier
experimenter: List of experimenters
lab: Laboratory name
institution: Institution name
experiment_description: Detailed experiment description
Any other valid NWB file fields