SimBA is a toolkit for creating supervised machine-learning classifiers of animal social and non-social behavior from pose-estimation data, without requiring a programming background.
-blue.svg){kind=icon}
Manuscript: Simple Behavioral Analysis (SimBA) as a platform for explainable machine learning in behavioral neuroscience Pre-print: Simple Behavioral Analysis (SimBA) – an open source toolkit for computer classification of complex social behaviors in experimental animals
pip install simba-uw-tf-dev # Python 3.6 or 3.10
simba # launch the GUISee Scenario 1 for a worked example that takes raw tracking data through to a validated classifier.
- Input: pose-estimation from DeepLabCut (incl. multi-animal), SLEAP, DeepPoseKit, DANNCE (3D), MARS, FaceMap, APT, SuperAnimal-TopView, YOLO, or blob tracking; user-defined pose schemes supported.
- Output: per-frame behavior classifiers with standard evaluation (precision/recall, learning curves, permutation importance) and SHAP-based explainability.
- Validation: classifier libraries validated in mice and rats; all data, models, and annotations available on OSF.
- Analyses — all produce descriptive statistics, export to CSV, and can be split into time-bins:
- Behavior: bout counts, durations, latency to first event, event frequency, severity scoring.
- Movement: velocity, distance travelled, path/trajectory metrics.
- Space (ROIs/zones): time-in-zone, entries, distance moved per zone, behavior × zone; supports animal-anchored zones.
- Social & directional: which animal — or body part, or ROI — each animal is oriented toward.
- Temporal structure: behavior-sequence coupling (FSTTC), burst detection & smoothing (Kleinberg).
- Turn-key assays: spontaneous alternation, pup retrieval, cue-light, light/dark box, freezing, circling, etc.
- Unsupervised: dimensionality reduction and clustering of behavior.
- Visualizations — static plots or overlays burned onto the video, mergeable into one multi-panel video (see Visualizations):
- Tracking overlays: pose keypoints, skeletons, animal-anchored bounding boxes, blob contours.
- Spatial: path/trajectory plots, ROI/zone overlays, location heatmaps.
- Classifier: annotated prediction videos, Gantt charts, classifier heatmaps, probability plots (incl. interactive grapher), SHAP summary plots.
- Movement & directionality: distance plots, velocity/data line plots, directionality overlays (animal→animal, →body-part, →ROI).
- Assay-specific: cue-light, light/dark box, spontaneous-alternation, circular/polar plots.
To faciliate the initial use of SimBA, we provide several use scenarios. We have created these scenarios around a hypothetical experiment that take a user from initial use (completely new start) all the way through analyzing a complete experiment and then adding additional experimental datasets to an initial project.
Scenario 1: Building classifiers from scratch
Scenario 2: Using a classifier on new experimental data
- Analysing animal directions in SimBA 🧭
- API 📘
- Batch pre-process video using SimBA 🏭
- Blob (contour) tracking in SimBA 🟣
- Bounding boxes in SimBA📦
- Compute feature subsets in SimBA 📕
- Cue-light analyses in SimBA💡💡
- Downloading compressed data from the SimBA OSF repository 💾
- Explainable machine classifications in SimBA (SHAP) 🧮
- Kleinberg markov chain classification smoothing in SimBA 🔗
- Mutual exclusivity using heuristic rules in SimBA 📗
- Process video using SimBA tools 🔨
- Recommended hardware 🖥️
- Reversing the directionality of classifiers in SimBA ⏪
- SimBA Advanced behavioral annotation interface 🏷️
- SimBA behavioral annotation interface 🏷️
- SimBA friendly asked questions (FAQ) 📕
- SimBA generic tutorial 📘
- Spike-time correlation coefficients in SimBA 📔
- Spontaneous alternation in SimBA🌽
- Using DeepLabCut through SimBA 📗
- Using DeepPoseKit in SimBA 📙
- Using multi-animal pose (maDLC/SLEAP/APT) in SimBA 🐭🐭
- Using the SimBA data analysis and export dashboard 📊
- Using third-party annotation tools in SimBA 🏷️
- Using user-defined ROIs in SimBA 🗺️
- Visualization tools 👁️
Step 1: Pre-process videos
Step 3: Building classfier(s)
Step 4: Analysis/Visualization
For documentation, see THIS tutorial on GitHub or THIS tutorial in the documentation.
We have improved the GUI for region-of-interest segmentation and analysis, which includes new interactive controls for drawing shapes. Click here to go to the new ROI documentation page.
The updates primarily serves to improve stability, but includes new methods for drawing circles, interactive ROI resizing, interactive ROI moving and aesthetics.
The SimBA region of interest (ROI) interface allows users to define and draw ROIs on videos. ROI data can be used to calculate basic descriptive statistics based on animals movements and locations such as:
- How much time the animals have spent in different ROIs.
- How many times the animals have entered different ROIs.
- The distance animals have moved in the different ROIs.
- Calculate how animals have engaged in different classified behaviors in each ROI.
- etc....
Furthermore, the ROI data can be used to build potentially valuable, additional, features for random forest predictive classifiers. Such features can be used to generate a machine model that classify behaviors that depend on the spatial location of body parts in relation to the ROIs. CAUTION: If spatial locations are irrelevant for the behaviour being classified, then such features should not be included in the machine model generation as they just only introduce noise.
Several excellent computational frameworks exist that enable high-throughput and consistent tracking of freely moving unmarked animals. Here we introduce and distribute a pipeline that enabled users to use these pose-estimation approaches in combination with behavioral annotation and generation of supervised machine-learning behavioral predictive classifiers. We have developed this pipeline for the analysis of complex social behaviors, but have included the flexibility for users to generate predictive classifiers across other behavioral modalities with minimal effort and no specialized computational background.
SimBA does not require computer science and programing experience, and SimBA is optimized for wide-ranging video acquisition parameters and quality. We may be able to provide support and advice for specific use instances, especially if it benefits multiple users and advances the scope of SimBA. Feel free to post issues and bugs here or contact us directly and we'll work on squashing them as they appear. We hope that users will contribute to the community!
- The SimBA pipeline requires no programing knowledge
- Specialized commercial or custom-made equipment is not required
- Extensive annotations are not required
- The pipeline is flexible and can be used to create and validate classifiers for different behaviors and environments
- Currently included behavioral classifiers have been validated in mice and rats
- SimBA is written on Windows/MacOS and compatible with Linux
SimBA provides several validated classifer libraries using videos filmed from above at 90° angle with pose-estimation data from 8 body parts per animal; please see our OSF repository for access to all files. SimBA now accepts any user-defined pose-estimation annotation schemes with the inclusion of the Flexible Annotation Module in v1.1. SimBA now supports maDLC and SLEAP for similar looking animals with the release of maDLC/SLEAP module in v1.2.
Listserv for release information: If you would like to receive notification for new releases of SimBA, please fill out this form and you will be added to the listserv.
- Data, pose models & classifiers — OSF repository 💾
- Trained classifiers — Random forest models 🌲
- Install / package — PyPI 📦
- API reference — SimBA on ReadTheDocs 📘
- Example notebooks — Run SimBA from code 📓
- Docker images — Docker Hub 🐳
- Visualization examples — YouTube playlist 📺
- Labelled images & tracking weights — DeepLabCut annotations/weights (OSF) 📷
- Community & support — Gitter chat 💬
- Bug reports & feature requests — GitHub Issues 🐛
- Golden Lab — Sam Golden Lab, UW 🧪
- Download statistics — Live dashboard 📊
SimBA is developed and maintained by Simon Nilsson (homepage). For questions, bug reports, or feature requests, reach out via GitHub or open an issue.
This project is licensed under the BSD 3-Clause License, modified for academic and research use only (see LICENSE). Note that the software is provided 'as is', without warranty of any kind, express or implied.
If you find any part of the code or data useful for your own work, please cite us. You can view and download the citation file by clicking the Cite this repository button at the top right of this page. Thank you 🙏!
@article{Goodwin2024,
author = {Goodwin, Nastacia L. and Choong, Jia J. and Hwang, Sophia and Pitts, Kayla and Bloom, Liana and Islam, Aasiya and Zhang, Yizhe Y. and Szelenyi, Eric R. and Tong, Xiaoyu and Newman, Emily L. and Miczek, Klaus and Wright, Hayden R. and McLaughlin, Ryan J. and Norville, Zane C. and Eshel, Neir and Heshmati, Mitra and Nilsson, Simon R. O. and Golden, Sam A.},
title = {Simple Behavioral Analysis (SimBA) as a platform for explainable machine learning in behavioral neuroscience},
journal = {Nature Neuroscience},
volume = {27},
pages = {1411--1424},
year = {2024},
doi = {10.1038/s41593-024-01649-9},
publisher = {Nature Publishing Group},
URL = {https://simba-uw-tf-dev.readthedocs.io/},
repository = {https://github.com/sgoldenlab/simba},
license = {BSD-3-Clause (Academic/Research Use Only)}
}
See the full credits page for everyone who has contributed to SimBA.