SimBA (Simple Behavioral Analysis)

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

<p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/landing_1.gif" /> </p>

To install SimBA via pip, use the following command (preferably using python3.6, or python 3.10 if necessary):

pip install simba-uw-tf-dev

For detailed installation instructions, click HERE

Installation ⚙️

• Install SimBA

• Install SimBA using Anaconda

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 📚

• API 📘
• Visualization tools 👁️
• 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) 🧮
• Mutual exclusivity using heuristic rules in SimBA 📗
• Compute feature subsets in SimBA 📕
• 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 📔
• Spontaneous alternation in SimBA🌽
• Analysing animal directions in SimBA 🧭
• Recommended hardware 🖥️
• Downloading compressed data from the SimBA OSF repository 💾

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.

<p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/blob_tracking_example.gif" width="650" alt="Demo GIF"> </p>

Feb-11-2025: SimBA ROI interface update

<p align="center"> <img src="https://github.com/sgoldenlab/simba/blob/master/images/roi_new_1.png" /> </p>

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.

Apr-16-2023: API Reference

See SimBA on readthedocs for API reference and example notebooks when you prefer to run methods available in SimBA through the command line over the GUI. If you find that notebook examples are lacking, please reach out to us Gitter or by opening an issue and let's chat about typing up further examples!

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.

<p align = "center"> <img src="/images/doc_inst.png" alt="" title="SimBA" /> <p/>

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.

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 invalua