NWB Export

The jabs-cli convert-to-nwb command converts a JABS pose estimation HDF5 file to NWB (Neurodata Without Borders) format using the ndx-pose extension.

pip install "jabs-behavior-classifier[nwb]"

The extra adds pynwb and ndx-pose as dependencies.

Two output modes are available. Choose the mode based on how the files will be used:

Command usage

jabs-cli convert-to-nwb INPUT_PATH OUTPUT [OPTIONS]

Examples

# Single combined file — all identities in one NWB file
jabs-cli convert-to-nwb session_pose_est_v6.h5 session.nwb

# One NWB file per identity (recommended for DANDI upload)
jabs-cli convert-to-nwb session_pose_est_v6.h5 session.nwb --per-identity

# Include per-animal metadata
jabs-cli convert-to-nwb session_pose_est_v6.h5 session.nwb --subjects subjects.json

# Specify session start time and experimenter
jabs-cli convert-to-nwb session_pose_est_v6.h5 session.nwb --session-metadata session.json

Subjects JSON format

Pass a JSON file to --subjects to attach per-animal biological metadata to the NWB output. Keys are identity names: use external IDs from the pose file when present (e.g. "mouse_a"), or subject_1, subject_2, … when the pose file has no external IDs.

DANDI requires species, sex, and either age or date_of_birth on every subject. All other fields are optional.

{
  "subject_1": {
    "subject_id": "M123",
    "sex": "M",
    "species": "Mus musculus",
    "age": "P70D",
    "genotype": "WT",
    "strain": "C57BL/6J"
  },
  "subject_2": {
    "subject_id": "M124",
    "sex": "F",
    "species": "Mus musculus",
    "age": "P72D",
    "genotype": "Shank3+/-",
    "strain": "C57BL/6J"
  }
}

In per-identity mode, subject metadata is written to both the standard NWBFile.subject field and the jabs_metadata scratch field. If no --subjects file is provided, a minimal subject with subject_id set to the identity name is written automatically. In combined mode, subject metadata is written only to jabs_metadata (see below).

Session metadata JSON format

Pass a JSON file to --session-metadata to set NWB session-level fields. This is the primary way to specify session_start_time, which is not currently stored in JABS pose files and otherwise defaults to the time the export was run.

{
  "session_start_time": "2024-03-15T10:30:00-05:00",
  "experimenter": ["Jane Smith", "John Doe"],
  "lab": "Kumar Lab",
  "institution": "The Jackson Laboratory",
  "experiment_description": "Open field test",
  "session_id": "session_001"
}

All fields are optional. Unknown keys are ignored with a warning.

Output modes

Combined file (default)

All identities from the recording session are written into a single NWB file.

session.nwb
  └── all identities, all objects

This is a non-standard NWB usage. Standard NWB (NWBFile.subject) only supports one subject per file, so combined files cannot populate that field. Instead, all per-animal metadata is stored in the jabs_metadata scratch field (a JSON string). Tools that do not know about jabs_metadata will not see subject metadata at all.

DANDI upload: Combined files will fail DANDI validation because NWBFile.subject is not set. Use per-identity mode for DANDI.

Per-identity (--per-identity)

One NWB file is written per animal. The OUTPUT path is used as a naming template; files are written as {output_stem}_{identity_name}.nwb in the same directory.

session_subject_1.nwb   ← identity 0 + all objects
session_subject_2.nwb   ← identity 1 + all objects
session_subject_3.nwb   ← identity 2 + all objects

This is the more standard output. Each file contains exactly one animal, so NWBFile.subject is populated with that animal's biological metadata (when provided via --subjects). Any standard NWB tool — including the DANDI archive — can read the subject field directly without knowing anything about JABS.

Identity names in the filenames come from external_ids in the pose file (sanitized for filesystem compatibility), or fall back to subject_1, subject_2, … when no external IDs are present. Static and dynamic objects are written to every per-identity file identically, since they are session-level data.

Reading per-identity files

The JABS reader re-assembles per-identity files transparently. Point it at any one sibling file; it detects the per_identity_files flag in jabs_metadata, finds all siblings, and merges them into a single result with all identities in their original order.

Subject metadata and NWBFile.subject

jabs_metadata.subjects always carries the full dict for all identities, even in per-identity files. This makes each file self-contained: the JABS reader can recover complete subject metadata from any sibling without loading the others.

NWB file structure

For the full format specification — including all field definitions, jabs_metadata keys, and worked examples for static and dynamic objects — see File Formats — NWB Pose File.

The layout below shows a combined file with two animal identities, two static objects (corners, lixit), and one dynamic object (fecal_boli).

NWBFile
├── subject/                               [Subject] per-identity mode only
├── processing/
│   └── behavior/                          [ProcessingModule]
│       ├── Skeletons/                     [Skeletons container]
│       │   ├── subject/                   Skeleton — animal keypoints + edges
│       │   ├── corners/                   Skeleton — static object (4 nodes)
│       │   ├── lixit/                     Skeleton — static object (1 or 3 nodes)
│       │   └── fecal_boli/                Skeleton — dynamic object (max_count nodes)
│       │
│       ├── subject_1/                     [PoseEstimation] animal identity 0
│       │   ├── nose/                      [PoseEstimationSeries] num_frames timestamps
│       │   ├── left_ear/
│       │   └── ...
│       │
│       ├── subject_2/                     [PoseEstimation] animal identity 1
│       │   ├── nose/
│       │   └── ...
│       │
│       ├── corners/                       [PoseEstimation] static object
│       │   ├── corners_0/                 [PoseEstimationSeries] 1 timestamp
│       │   ├── corners_1/
│       │   ├── corners_2/
│       │   └── corners_3/
│       │
│       ├── lixit/                         [PoseEstimation] static object
│       │   └── lixit_0/                   [PoseEstimationSeries] 1 timestamp
│       │
│       ├── fecal_boli/                    [PoseEstimation] dynamic object
│       │   ├── fecal_boli_0/              [PoseEstimationSeries] n_predictions timestamps
│       │   ├── fecal_boli_1/
│       │   └── ...
│       │
│       ├── jabs_identity_mask             [TimeSeries] uint8 identity presence mask
│       ├── jabs_bounding_boxes_subject_1  [TimeSeries] optional, one per identity
│       └── jabs_bounding_boxes_subject_2  [TimeSeries] optional, one per identity
│
└── scratch/
    └── jabs_metadata/                     [ScratchData] JSON string (see below)

In a per-identity file the layout is identical, except: - NWBFile.subject is populated (when subject metadata is provided) - Only one animal identity container is present - jabs_identity_mask / jabs_bounding_boxes_<identity> cover that identity only

Animal pose

Each animal identity is a PoseEstimation container in processing/behavior. The container name is the sanitized external ID from the pose file, or subject_1, subject_2, … (1-based) when no external IDs are available.

A single Skeleton named subject is shared by all animal identities and stored in the Skeletons container.

PoseEstimationSeries fields (per keypoint)

Identity mask

jabs_identity_mask is a TimeSeries that records whether each identity is present in each frame.

Bounding boxes (optional)

When the pose file contains bounding box data, one TimeSeries per identity is written with the name jabs_bounding_boxes_{identity_name}.

Format: [[upper_left_x, upper_left_y], [lower_right_x, lower_right_y]] in pixels.

Static objects

Static objects are fixed-position spatial landmarks that do not move during a session. They are read from static_objects/ in JABS pose HDF5 files (pose format v5+).

Common static objects:

Each static object is a PoseEstimation container with a single timestamp (t = 0.0 s), one PoseEstimationSeries per keypoint, and a dedicated Skeleton. Nodes are named {object_name}_{i} (zero-indexed).

Each PoseEstimationSeries for a static object has data shape (1, 2) — one row for the single timestamp and two columns for (x, y). Because the time dimension (1) is shorter than the spatial dimension (2), the DANDI validator will emit a NWBI.check_data_orientation warning for each static keypoint:

[NWBI.check_data_orientation] — Data may be in the wrong orientation. Time should be
in the first dimension, and is usually the longest dimension. Here, another dimension
is longer.

These warnings are expected and can be ignored. The check is a heuristic designed to catch transposed animal pose arrays; it fires a false positive for static objects, which legitimately have only one timestamp by definition.

Dynamic objects

Dynamic objects are objects whose position or count may change over time. Unlike animal pose, predictions are made only for a sparse subset of frames. Dynamic objects are available from JABS pose format v7+.

Each dynamic object is a PoseEstimation container with n_predictions irregular timestamps. One PoseEstimationSeries is written per instance slot × keypoint combination.

Instance slot occupancy is encoded in the confidence field:

• confidence = 1.0 — slot is occupied at this prediction
• confidence = 0.0 — slot is unoccupied; coordinate values are padding and must be ignored

Node naming:

jabs_metadata scratch field

Every JABS NWB file contains a ScratchData object named jabs_metadata in the NWB scratch space. Its data field is a JSON string carrying JABS-specific metadata needed for a lossless round-trip. Standard NWB fields alone are insufficient because pynwb returns PoseEstimationSeries in alphabetical order from HDF5, which would otherwise scramble the keypoint ordering.

Tools that do not use the JABS reader can parse this JSON directly to recover ordered keypoint names, identity ordering, subject metadata, and object classification.

Keys

Example — combined file

{
  "format_version": 1,
  "identity_names": ["subject_1", "subject_2"],
  "num_identities": 2,
  "body_parts": ["nose", "left_ear", "right_ear", "base_neck", "left_front_paw",
                 "right_front_paw", "center_spine", "left_rear_paw", "right_rear_paw",
                 "base_tail", "mid_tail", "tip_tail"],
  "cm_per_pixel": 0.043,
  "external_ids": null,
  "subjects": {
    "subject_1": {
      "subject_id": "M123",
      "sex": "M",
      "species": "Mus musculus",
      "age": "P70D",
      "genotype": "WT",
      "strain": "C57BL/6J",
      "weight": null,
      "description": null
    },
    "subject_2": {
      "subject_id": "M124",
      "sex": "F",
      "species": "Mus musculus",
      "age": "P72D",
      "genotype": "Shank3+/-",
      "strain": "C57BL/6J",
      "weight": null,
      "description": null
    }
  },
  "metadata": {
    "source_file": "/data/session_pose_est_v7.h5",
    "pose_format_version": 7,
    "source_file_hash": "a3f1c8..."
  },
  "static_object_names": ["corners", "lixit"],
  "dynamic_object_names": ["fecal_boli"],
  "dynamic_object_shapes": {
    "fecal_boli": [3, 1]
  }
}

Coordinate system

All coordinates in JABS NWB files use the following convention:

This applies to animal keypoints, static object points, and dynamic object points. NWB files always store coordinates in (x, y) order.

Data not exported

Pose files v6 and later may contain instance segmentation data. This data is not included in the NWB output. See File Formats — Data not exported to NWB for the full list of omitted fields. If you need segmentation data, read it directly from the source JABS pose HDF5 file.