An open-source platform for standardized mouse behavioral phenotyping.
Documentation · User Guide · Sample Data · Contact Us
- 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
# Using pipx (recommended)
pipx install jabs-behavior-classifier
# OR using uv
uv tool install jabs-behavior-classifieruvx --from jabs-behavior-classifier jabsjabs # Launch the GUI
jabs-init --help # View project initialization optionsNote: The first launch may take a few minutes to initialize. Subsequent launches will be much faster.
Install from PyPI
pip install jabs-behavior-classifierInstall 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-classifiermacOS: Enable XGBoost
XGBoost requires the OpenMP library, which doesn't ship with macOS:
brew install libomp| 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.
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
We provide tested Singularity definition files for Linux environments:
| Container | Use Case |
|---|---|
| headless.def | Command-line use on compute clusters |
| gui.def | Interactive GUI in a portable environment |
Please inspect the definition files for related Linux packages required to run the software.
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 | 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.
- ReadTheDocs Tutorial — Complete user guide and tutorials
- User Guide — Markdown documentation
- Sample Data — Test datasets for demonstration
Interested in contributing? Check out our:
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
Copyright 2023 The Jackson Laboratory — All rights reserved.
JABS is licensed under a non-commercial use license. See LICENSE for details.
For commercial licensing inquiries, contact us.
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