SimBA (Simple Behavioral Analysis)

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.

!Docs

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

Quickstart

pip install simba-uw-tf-dev   # Python 3.6 or 3.10
simba                         # launch the GUI

See Scenario 1 for a worked example that takes raw tracking data through to a validated classifier.

Installation ⚙️

Installation guide on Read the Docs 📘

Install SimBA

Install SimBA using Anaconda

Scope & inputs

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. See related software for the full list.
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.

Documentation: Scenario tutorials

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

Scenario 3: Updating a classifier with further annotated data

Scenario 4: Analyzing and adding new Experimental data to a previously started project

Tutorial 📚

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 👁️

Legacy documentation: General methods

Step 1: Pre-process videos

Step 2: Create tracking model and generate pose-estimation data

Step 3: Building classfier(s)

Step 4: Analysis/Visualization

Click here for the full legacy generic tutorial on building classifiers in SimBA.

Apr-03-2025: Blob (contour) tracking in SimBA

For documentation, see THIS tutorial on GitHub or THIS tutorial in the documentation.

Demo GIF

Feb-11-2025: SimBA ROI interface update

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.

What is SimBA?

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
SimBA is used in a growing list of published studies
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.

Mouse

Rat

SimBA GUI workflow

Pipeline 👷

Resources 💾

Data, pose models & classifiers — OSF repository 💾
Example datasets — Ready-to-use datasets 🗂️
Trained classifiers — Random forest models 🌲
Install / package — PyPI 📦
API reference — SimBA on ReadTheDocs 📘
Glossary — SimBA terms explained 📖
Example notebooks — Run SimBA from code 📓
Docker images — Docker Hub 🐳
Visualization examples — YouTube playlist 📺
Visualization gallery — All SimBA plot and video types 🖼️
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 📊

Developer & contact 👨‍💻

SimBA is developed and maintained by Simon Nilsson (homepage). For questions, bug reports, or feature requests, reach out via GitHub or open an issue. See also getting help.

License 📃

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. See also the license and third-party notices pages.

If you find any part of the code or data useful for your own work, please cite us. Thank you 🙏!

Goodwin, N. L., Choong, J. J., Hwang, S., Pitts, K., Bloom, L., Islam, A., Zhang, Y. Y., Szelenyi, E. R., Tong, X., Newman, E. L., Miczek, K., Wright, H. R., McLaughlin, R. J., Norville, Z. C., Eshel, N., Heshmati, M., Nilsson, S. R. O., & Golden, S. A. (2024). Simple Behavioral Analysis (SimBA) as a platform for explainable machine learning in behavioral neuroscience. Nature Neuroscience, 27(7), 1411–1424. https://doi.org/10.1038/s41593-024-01649-9

@article{Goodwin_2024,
  title     = {Simple Behavioral Analysis (SimBA) as a platform for explainable machine learning in behavioral neuroscience},
  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.},
  journal   = {Nature Neuroscience},
  volume    = {27},
  number    = {7},
  pages     = {1411--1424},
  year      = {2024},
  doi       = {10.1038/s41593-024-01649-9},
  url       = {https://doi.org/10.1038/s41593-024-01649-9},
  publisher = {Springer Science and Business Media LLC}
}

You can also use the Cite this repository button at the top right of this page. Other formats (APA, MLA, Chicago, Harvard, Vancouver, RIS) and one-click .bib/.ris downloads: How to cite SimBA.

References 📜

Contributors 🤼

See the credits page for everyone who has contributed to SimBA.

sgoldenlab/simba: SimBA (Simple Behavioral Analysis), a pipeline and GUI for developing supervised behavioral classifiers