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, ndx-multisubjects, ndx-jabs) |
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
Release files for jabs-behavior-classifier 0.48.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| jabs_behavior_classifier-0.48.0.tar.gz | 8.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jabs_behavior_classifier-0.48.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 17.6 MB
Release files / jabs_behavior_classifier-0.48.0.tar.gz
| Download URL | jabs_behavior_classifier-0.48.0.tar.gz |
|---|---|
| Size | 8.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e8f6c5dc6fc308dc0ed3c614b4648420ad5ed55d8a72579d7e49f6d83b37a26
|
|
BLAKE2b-256 checksum How to use checksums |
a5e718a6c68c63f559fbc6a2a6acaa2cd0b9e38f39b0fc3ad98d4246af3dd1f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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}
|
Release files / jabs_behavior_classifier-0.48.0-py3-none-any.whl
| Download URL | jabs_behavior_classifier-0.48.0-py3-none-any.whl |
|---|---|
| Size | 8.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4759f04e94f5490a5c16b7d8e776c86766857018fda596fa42dc55938c26c37b
|
|
BLAKE2b-256 checksum How to use checksums |
435f259b01c71ce7211be7dcc81e978209193afde72966ac37f3ba21d1c85ddd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","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}
|
