JAX Animal Behavior System (JABS)
JABS Behavior Classifier
An open-source platform for standardized mouse behavioral phenotyping.
Documentation · User Guide · Sample Data · Contact Us
Features
- Interactive GUI for behavior annotation and classifier training
- Machine learning-powered automatic behavior classification
- XGBoost support for high-performance classification
- Command-line tools for batch processing and HPC integration
- Singularity containers for reproducible deployments
Quick Start
Installation (Recommended)
# Using pipx (recommended)
pipx install jabs-behavior-classifier
# OR using uv
uv tool install jabs-behavior-classifier
Run Without Installing
uvx --from jabs-behavior-classifier jabs
Launch JABS
jabs # Launch the GUI
jabs-init --help # View project initialization options
Note: The first launch may take a few minutes to initialize. Subsequent launches will be much faster.
Installation Options
Install from PyPI
pip install jabs-behavior-classifier
To include optional extras, use bracket notation. For example, to install with NWB export support:
pip install "jabs-behavior-classifier[nwb]"
Available extras:
| Extra | Description |
|---|---|
nwb |
NWB export support (pynwb, ndx-pose) |
Install from Source
# From GitHub
pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git
# Specific branch or commit
pip install git+https://github.com/KumarLabJax/JABS-behavior-classifier.git@branch-name
# From local clone
git clone https://github.com/KumarLabJax/JABS-behavior-classifier.git
cd JABS-behavior-classifier
pip install .
Virtual Environment Setup
python -m venv jabs.venv
# Linux/macOS
source jabs.venv/bin/activate
# Windows
jabs.venv\Scripts\activate.bat
pip install jabs-behavior-classifier
macOS: Enable XGBoost
XGBoost requires the OpenMP library, which doesn't ship with macOS:
brew install libomp
Command Line Tools
| Command | Description |
|---|---|
jabs |
Launch the JABS GUI |
jabs-init |
Initialize a new project or recompute features |
jabs-classify |
Run a trained classifier |
jabs-export-training |
Export training data from a project |
jabs-cli |
Collection of utility commands |
Run <command> --help for detailed usage information.
Prerequisites
JABS requires pose files generated from the Kumar Lab's mouse pose estimation neural networks:
- Single mouse: deep-hrnet-mouse
- Multi-mouse: Under development — contact us for more information
Singularity/Apptainer (Linux)
We provide Singularity/Apptainer definition files and SLURM batch scripts for running JABS on Linux compute clusters. See vm/README.md for build instructions and usage details.
Project Portability
JABS uses four version numbers to track compatibility:
| Version | Description |
|---|---|
| Package version | Bumped every release |
| Feature version | Bumped when feature values or storage format changes |
| Classifier version | Bumped when classifier characteristics change |
| Prediction version | Bumped when prediction storage format changes |
Artifact Compatibility
| Artifact | Portability | Best For |
|---|---|---|
| Project folders | Cross-version compatible | Long-term storage, upgrades |
| Exported training data | Same JABS version | Sharing, archiving, HPC workflows |
| Classifier pickle files | Same machine only | Large-scale pipeline predictions |
Detailed Portability Information
Project folders are the most compatible for upgrades. The vast majority of JABS upgrades allow transparent upgrades (e.g., re-generation of features) within the project folder without user interaction. We will provide instructions for changes that are not automatically compatible. Project folders are large but are almost always compatible across JABS versions.
Exported training data is compatible across computers but should generally not be considered compatible across JABS package versions. Once we add the appropriate version checks, error messages should be clearer about when and why these aren't compatible across versions. A common use case is to export training data from a project folder, transfer it to an HPC cluster, and then train and run a classifier using the jabs-classify command from the same version of JABS that was used to export the training file.
Classifier pickle files are the serialized trained classifiers. They load very fast and are tiny and efficient, but are only compatible within a specific install of the package (e.g., macOS will not be compatible with Windows). These should not be considered portable beyond the computer and specific JABS install that created them. We use these for large-scale predictions in pipelines—for example, using exported training data to train a classifier saved as a .pickle file, which can then be used to classify many videos as part of a pipeline.
Documentation
- ReadTheDocs Tutorial — Complete user guide and tutorials
- User Guide — Markdown documentation
- Sample Data — Test datasets for demonstration
Contributing
Interested in contributing? Check out our:
Citation
If you use JABS in your research, please cite:
Choudhary, A., Geuther, B. Q., Sproule, T. J., Beane, G., Kohar, V., Trapszo, J., & Kumar, V. (2025). JAX Animal Behavior System (JABS): A genetics informed, end-to-end advanced behavioral phenotyping platform for the laboratory mouse. eLife, 14:RP107259. https://doi.org/10.7554/eLife.107259.2
License
Copyright (c) 2023-2026 The Jackson Laboratory.
The JABS Behavior Classifier is released under the MIT License.
Acknowledgements
JABS was influenced by JAABA (Janelia Automatic Animal Behavior Annotator) developed by the Branson lab at Janelia Research Campus of the Howard Hughes Medical Institute. We are grateful for their pioneering work in automated behavior classification.
Kabra, M., Robie, A., Rivera-Alba, M. et al. JAABA: interactive machine learning for automatic annotation of animal behavior. Nature Methods 10, 64–67 (2013). https://doi.org/10.1038/nmeth.2281
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file jabs_behavior_classifier-0.46.2.tar.gz.
File metadata
- Download URL: jabs_behavior_classifier-0.46.2.tar.gz
- Upload date:
- Size: 8.6 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ea0b9aecfc1277d74c581b5d0b71a0274cc05ae6d4d60002616c01c4f2c7fad4
|
|
| MD5 |
b91be944cc34bd933f73f2a6779e859d
|
|
| BLAKE2b-256 |
f995359213d13d24f28f8949a37fc0bce45b8da6ebe1970a555efa9223f329b1
|
File details
Details for the file jabs_behavior_classifier-0.46.2-py3-none-any.whl.
File metadata
- Download URL: jabs_behavior_classifier-0.46.2-py3-none-any.whl
- Upload date:
- Size: 8.7 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
501ce6798493008fe953efddf8f059b27cf486fb3c774117d7dcd5de7df522de
|
|
| MD5 |
96867799091f683adcb2f977566a762c
|
|
| BLAKE2b-256 |
621c7f586345200a04238cdd35f6b96d9d2f17e3bd8b9e0dc85be63c5f21bc0a
|
