justinshenk/simba

1. What this repository is

SimBA is a Python-based behavioral analysis toolkit for experimental animals, centered on a desktop workflow rather than a server. The core product is a Windows-oriented GUI application plus a large set of batch-processing scripts for pose-based behavior classification, validation, and visualization.

2. Top-level application entry points

The main user-facing entry points appear to be App.py, simba/SimBA.py, and related launcher scripts such as run_dash_tkinter.py and simba/SimBA_dash_app.py. These connect the GUI to the processing pipeline. setup.py and simba/requirements.txt package the repo as an installable Python application.

3. Primary pipeline boundary

The architecture is organized around a clear data pipeline: video files and pose-estimation outputs come in, behavioral features are derived, classifiers are trained or applied, and results are exported as event tables and plots. The repo is not a single monolith; it is a toolkit of discrete processing stages that can be run interactively from the GUI or in batch mode from scripts.

4. Video preprocessing and project setup

Scripts such as process_videos_automation*, crop_video_tool*, extract_frames_fast.py, extract_seqframes.py, merge_movie_ffmpeg.py, and multiplecrop.py handle video preprocessing. Project/configuration creation is managed by files like create_project_ini.py, import_videos_csv_project_ini.py, define_new_pose_config.py, and reset_poseConfig.py, which indicate that SimBA relies on structured project metadata and pose configuration files to keep datasets consistent.

5. Pose-estimation import and interoperability

A major boundary in the system is the translation layer between external pose-estimation tools and SimBA’s internal data format. The repo includes import/conversion support for DeepLabCut, DeepPoseKit, SLEAP, MARS, Boris, and Solomon through scripts such as read_DLCmulti_h5_function.py, import_sleap_h5.py, import_solomon.py, append_boris.py, json2csv.py, and sleap_bottom_up_convert.py. This is a key architectural feature: SimBA does not generate pose data itself; it ingests outputs from these external systems.

6. Feature extraction and pose configuration

Behavioral modeling is driven by feature engineering over body-part coordinates. The features_scripts/ directory contains many specialized extractors for different pose layouts: 4, 7, 8, 9, 14, 16, and user-defined body-part schemes. This suggests the internal design is parameterized around pose configuration files rather than one fixed skeleton, and feature extraction is a reusable subsystem reused by training, validation, and analysis.

7. Outlier correction and movement cleanup

The outlier_scripts/ tree is a dedicated correction layer for noisy tracking data. It has separate branches for movement and location correction, plus user-defined variants and legacy versions. This subsystem sits between raw pose imports and downstream feature computation, ensuring that classifier inputs are cleaned before behavior inference. The presence of many body-part-specific files shows that outlier handling is tightly coupled to pose schema.

8. Classification and model lifecycle

Model training and inference are handled by scripts such as train_model*, train_multiple_models_from_meta*, run_RF_model.py, sklearn_DLC_RF_train_model.py, and validate_model_on_single_video.py. The README emphasizes random forest behavior classifiers, with pre-trained models also distributed via OSF. The lifecycle here is: build labeled training data, train a classifier, validate on held-out video, then apply the model to new datasets.

9. Behavior annotations and pseudo-labeling

Annotation support is split into dedicated tools like labelling_aggression.py, load_labelling_aggression.py, pseudoLabel.py, reverse_tracking_order.py, and reverse_annotations.py. This indicates an iterative human-in-the-loop workflow: manual labels seed the model, pseudo-labeling and annotation utilities expand training data, and annotation direction can be corrected when behavior definitions require it.

10. Post-classification analysis and temporal summaries

Once classifier outputs exist, several subsystems turn them into analytical summaries: process_movement.py, process_severity.py, timeBins_*, Kleinberg_burst_analysis.py, FSTCC.py, and prob_graph.py. These modules suggest SimBA is not just a classifier runner; it also computes derived temporal metrics such as burst detection, time-bin counts, severity measures, and spike-time style comparisons.

11. Spatial analysis and ROI subsystem

The ROI layer is substantial and separate from behavior classification. Files like ROI_draw_defined.py, ROI_freehand_draw_3.py, ROI_analysis*.py, ROI_process_movement*.py, ROI_plot*.py, ROI_directionality_to_other_animals.py, and ROI_add_to_features.py show a complete spatial-analysis workflow: define regions, map movement into regions, analyze directionality, and visualize ROI-based features. This is a distinct module family that feeds into the broader analysis pipeline.

12. Visualization and reporting

Visualization is handled by multiple output channels: static plots (plot_heatmap*, line_plot.py, path_plot.py, data_plot.py, gantt.py), model diagnostics (plot_sklearn_results*, shap_calcs.py, shap_visualize.py), and interactive dashboards (SimBA_dash_app.py, misc/simBA_dash_app.py, misc/dash_simba_base.css). The repo also includes Plotly/H5 tooling, which indicates an optional interactive analytics layer for exploring predictions and results.

13. DeepPoseKit-specific subpackage

simba/dpk_script/ is a focused integration area for DeepPoseKit workflows, with scripts for creating annotations, training models, predicting new videos, visualizing output, and detecting/merging outliers. This is effectively a subsystem boundary for a specific external pose-estimation stack, separate from the more general SimBA classifier pipeline.

14. Data and distribution dependencies

External data/models live outside the codebase in OSF repositories, referenced heavily in the README. The repository itself contains example CSVs, plots, docs, and legacy scripts, but the operational architecture depends on downloadable classifiers, pose weights, and tutorial datasets. That means a diagram should show SimBA as the orchestration layer sitting between raw experimental assets, third-party pose estimators, and downstream behavioral analytics.