SimBA (Simple Behavioral Analysis)
We are are no longer supporting the legacy SimBAxTF branch, which required TensorFlow. To receive support, you must download the most up-to-date SimBA version (pip install simba-uw-tf-dev). If you are using the legacy SimBAxTF branch, please transition to the currently supported branch. If you require access to download the legacy branch, please contact us on Gitter for access.
Apr-04-2023: SimBA version 1.55 release
Although core methods remain, the SimBA code and documentation has sprawled significantly. If you are curious about the methods in the GUI, try clicking the header icons which should take you to the relevant documentation.
As always, reach out to us on Gitter chat or open an issue if you have questions, bug reports of feature requests!
Oct-07-2021: SimBA version 1.31 release
We have released a significantly improved GUI for region-of-interest segmentation and analysis. Click here to go to the new ROI documentation page.
Regions of Interest (ROIs) in SimBA
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.
Feb-08-2021: SimBA version 1.3 release
It has been nearly a year since the first public iteration of SimBA was released! We would like to thank the open-source community who have supported us and provided invaluable feedback and motivation to continue developing and supporting SimBA to where it is now. We have recently passed well over 150,000 downloads via pip install across all branches, and average between ~5000 to 10,000 weekly downloads alongside a gitter community of >100 users. We have just passed 15 citations for the SimBA preprint, which was released ~8 months ago. This would not be possible without your support. Thank you.
The newest release of SimBA, v1.3, provides a significant jump in features, quality of life improvements, and bug fixes. Several are highlighted below.
Please update using pip install simba-uw-tf==1.3.7, this version has native deeplabcut and deepposekit GUI support disabled. Hence, tensorflow is not needed. Pose-estimation developers have created excellent GUIs for their pipelines, and we do a disservice to you by not supporting the most updated versions. SimBA now supports pose-estimation dataframe imports from Deeplabcut, DeepPoseKit, SLEAP, MARS and others. If you are developing a new pose-estimation method and would like it directly supported in SimBA, please let us know!
Selected New Features
- Easy install of SimBA via
pip- Documentation - Install simba using anaconda - Documentation
- Introduction of SHAP for behavioral neuroscience classifier explainability and standarization- Documentation
- Plotly integration for immediate data visualization - Documentation
- Labelling/annotating behaviors with many third-party apps - Documentation
- Kleinberg Filter for smoothing - Documentation
- ROI Visualization update - Documentation
- User define features extraction - Documentation
- Quick line plot - Allow user to make line plots with selected bodypart and tracking data (located under Tools)
- Many, many, many, many bug-fixes
June-12-2020: SimBA version 1.2 release
New Features
- Multi-animal DLC support - Documentation
- Multi-animal SLEAP support - Documentation
- SimBA 'pseudo-labelling' module - Documentation
- Easy install of SimBA via
pip- Documentation - Plenty of new quality-of-life features (e.g., time-bin analyzes / improved visualizations options) - Documentation
- Many, many, many, many bug-fixes
Please join our Gitter chat if you have any questions, or even if you would simply like to discuss potential applications for SimBA in your work. Please come by, stay inside, wash your hands, and check on your lab mates reguarly!
April-25-2020: SimBA pre-print manuscript release
A pre-print SimBA manuscript on bioRxiv! The manuscript details the use of SimBA for generation of social predictive classifiers in rat and mouse resident-intruder protocols - please check it out using the link above. All data, pose-estimation models, and the final classifiers generated in the manuscript, can be accessed through our OSF repository and through the Resource menu further down this page.
March-05-2020: SimBA version 1.1 release
New Features
- Region of Interest support (ROI Module) - Documentation
- DeepPoseKit support (DPK Module) - Documentation
- SimBA accepts user-defined pose-configurations (Flexible Annotation Module) - Documentation
- Interactive classifer discrimination thresholding - Documentation
- Individual discrimination thresholds for classifiers - Documentation
- Heatmap visualizations -Documentation
- Multi-crop tool - Documentation
- Post-classification validation method for false-positives - Documentation
- Many, many, many bug-fixes
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
- 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.
Installation note: SimBA can be installed either with TensorFlow compatability (for generating DeepLabCut, DeepPoseKit and SLEAP pose-estimation models), or without TensorFlow (for stand-alone use with classifiers and other functions). Please choose the appropriate branch for your needs, using pip install. More details are found in the Installation Documentation.
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 ๐ท
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 generic tutorial on building classifiers in SimBA.
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
Installation โ๏ธ
Tutorial ๐
- API
๐ - Process video using SimBA tools
๐จ - Batch pre-process video using SimBA
๐ญ - Using DeepPoseKit in SimBA
๐ - Using DeepLabCut through SimBA
๐ - SimBA generic tutorial
๐ - SimBA friendly asked questions (FAQ)
๐ - SimBA behavioral annotation interface ๐ท๏ธ
- SimBA Advanced behavioral annotation interface ๐ท๏ธ
- Using third-party annotation tools in SimBA ๐ท๏ธ
- Using user-defined ROIs in SimBA
๐บ๏ธ - Using multi-animal pose (maDLC/SLEAP/APT) in SimBA
๐ญ ๐ญ - Using the SimBA data analysis and export dashboard
๐ - Explainable machine classifications in SimBA (SHAP)
๐งฎ - Kleinberg markov chain classification smoothing in SimBA
๐ - Cue-light analyses in SimBA
๐ก ๐ก - Bounding boxes in SimBA๐ฆ
- Reversing the directionality of classifiers in SimBA
โช - Spike-time correlation coefficients in SimBA
๐ - Analysing animal directions in SimBA ๐งญ
- Recommended hardware
๐ฅ๏ธ - Downloading compressed data from the SimBA OSF repository ๐พ
Resource ๐พ
All data (classifiers etc.) is available on our Open Science Framework repository. For a schematic overview of the data respository folder structure (as of March-20-2020), click HERE.
API reference
Models
Below is a link to download trained behavior classification models to apply it on your dataset
- Random forest models
๐ฒ
Docker images
SimBA visualization examples
- YouTube playlist ๐บ
Labelled images
Tracking weights
- DeepLabCut tracking weights
๐๏ธ
Golden Lab webpage
- Sam Golden Lab UW
๐งช ๐งซ ๐
License ๐
This project is licensed under the GPLv3. Note that the software is provided 'as is', without warranty of any kind, express or implied.
If you use any part of the code or data, please cite us! Thank you ๐!
@article{Nilsson2020.04.19.049452,
author = {Nilsson, Simon RO and Goodwin, Nastacia L. and Choong, Jia Jie and Hwang, Sophia and Wright, Hayden R and Norville, Zane C and Tong, Xiaoyu and Lin, Dayu and Bentzley, Brandon S. and Eshel, Neir and McLaughlin, Ryan J and Golden, Sam A.},
title = {Simple Behavioral Analysis (SimBA) {\textendash} an open source toolkit for computer classification of complex social behaviors in experimental animals},
elocation-id = {2020.04.19.049452},
year = {2020},
doi = {10.1101/2020.04.19.049452},
publisher = {Cold Spring Harbor Laboratory},
URL = {https://www.biorxiv.org/content/early/2020/04/21/2020.04.19.049452},
eprint = {https://www.biorxiv.org/content/early/2020/04/21/2020.04.19.049452.full.pdf},
journal = {bioRxiv}
}
References ๐
