# justinshenk/simba architecture

> Architecture diagram of the GitHub repository justinshenk/simba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justinshenk/simba
- Repository: https://github.com/justinshenk/simba

## Overview

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.

Main entry points: [`simba/SimBA.py`](https://github.com/justinshenk/simba/blob/master/simba/SimBA.py) (SimBA GUI), [`simba/train_multiple_models_from_meta.py`](https://github.com/justinshenk/simba/blob/master/simba/train_multiple_models_from_meta.py) (Model train), [`simba/run_RF_model.py`](https://github.com/justinshenk/simba/blob/master/simba/run_RF_model.py) (Model apply), [`simba/dpk_script/train_model.py`](https://github.com/justinshenk/simba/blob/master/simba/dpk_script/train_model.py) (DPK flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_py["App.py<br/>launcher<br/>[App.py]"]
  node_simba_gui["SimBA GUI<br/>desktop app<br/>[SimBA.py]"]
  node_dash_launcher["Dash launch<br/>launcher"]
  node_setup_pkg["Packaging<br/>build/package<br/>[setup.py]"]
end

subgraph group_ingest["Ingest"]
  node_project_setup["Project setup<br/>config/bootstrap"]
  node_video_prep["Video prep<br/>preprocess"]
  node_pose_import["Pose import<br/>interop"]
  node_pose_configs["Pose configs<br/>config data"]
end

subgraph group_core["Core pipeline"]
  node_feature_engine["Feature engine<br/>feature extraction"]
  node_outlier_cleanup["Outlier cleanup<br/>correction"]
  node_model_train["Model train<br/>classifier training"]
  node_model_apply["Model apply<br/>inference<br/>[run_RF_model.py]"]
  node_model_validate["Validate<br/>validation"]
  node_annotation_tools["Annotations<br/>labeling<br/>[pseudoLabel.py]"]
  node_behavior_analytics["Behavior analytics<br/>analysis"]
  node_roi_system["ROI system<br/>spatial analysis<br/>[ROI_analysis.py]"]
end

subgraph group_viz["Reporting"]
  node_plots_reports["Plots & reports<br/>visualization"]
  node_dash_ui["Dash UI<br/>dashboard<br/>[SimBA_dash_app.py]"]
  node_shap_insights["SHAP<br/>explainability<br/>[shap_visualize.py]"]
end

subgraph group_dpk["DeepPoseKit"]
  node_dpk_flow["DPK flow<br/>integration<br/>[train_model.py]"]
end

node_app_py -->|"starts"| node_simba_gui
node_dash_launcher -->|"opens"| node_dash_ui
node_setup_pkg -.->|"installs"| node_simba_gui
node_simba_gui -->|"configures"| node_project_setup
node_simba_gui -->|"orchestrates"| node_video_prep
node_simba_gui -->|"imports"| node_pose_import
node_project_setup -->|"uses"| node_pose_configs
node_pose_import -->|"feeds"| node_feature_engine
node_pose_configs -->|"parameterizes"| node_feature_engine
node_feature_engine -->|"prepares"| node_outlier_cleanup
node_outlier_cleanup -->|"cleans inputs"| node_model_train
node_outlier_cleanup -->|"cleans inputs"| node_model_apply
node_annotation_tools -->|"labels"| node_model_train
node_model_train -->|"evaluates"| node_model_validate
node_model_train -->|"publishes"| node_model_apply
node_model_apply -->|"outputs"| node_behavior_analytics
node_model_apply -->|"supports"| node_roi_system
node_behavior_analytics -->|"visualizes"| node_plots_reports
node_roi_system -->|"visualizes"| node_plots_reports
node_model_validate -->|"explains"| node_shap_insights
node_behavior_analytics -->|"explores"| node_dash_ui
node_dpk_flow -.->|"integrates"| node_pose_import
node_dpk_flow -.->|"trains"| node_model_train
node_dpk_flow -.->|"predicts"| node_model_apply

click node_app_py "https://github.com/justinshenk/simba/blob/master/App.py"
click node_simba_gui "https://github.com/justinshenk/simba/blob/master/simba/SimBA.py"
click node_dash_launcher "https://github.com/justinshenk/simba/blob/master/simba/run_dash_tkinter.py"
click node_setup_pkg "https://github.com/justinshenk/simba/blob/master/setup.py"
click node_project_setup "https://github.com/justinshenk/simba/blob/master/simba/create_project_ini.py"
click node_video_prep "https://github.com/justinshenk/simba/blob/master/simba/process_videos_automation.py"
click node_pose_import "https://github.com/justinshenk/simba/blob/master/simba/read_DLCmulti_h5_function.py"
click node_pose_configs "https://github.com/justinshenk/simba/blob/master/simba/pose_configurations/configuration_names/pose_config_names.csv"
click node_feature_engine "https://github.com/justinshenk/simba/blob/master/simba/features_scripts/extract_features_16bp.py"
click node_outlier_cleanup "https://github.com/justinshenk/simba/blob/master/simba/outlier_scripts/movement/correct_devs_mov_16bp.py"
click node_model_train "https://github.com/justinshenk/simba/blob/master/simba/train_multiple_models_from_meta.py"
click node_model_apply "https://github.com/justinshenk/simba/blob/master/simba/run_RF_model.py"
click node_model_validate "https://github.com/justinshenk/simba/blob/master/simba/validate_model_on_single_video.py"
click node_annotation_tools "https://github.com/justinshenk/simba/blob/master/simba/pseudoLabel.py"
click node_behavior_analytics "https://github.com/justinshenk/simba/blob/master/simba/process_movement.py"
click node_roi_system "https://github.com/justinshenk/simba/blob/master/simba/ROI_analysis.py"
click node_plots_reports "https://github.com/justinshenk/simba/blob/master/simba/plot_sklearn_results.py"
click node_dash_ui "https://github.com/justinshenk/simba/blob/master/simba/SimBA_dash_app.py"
click node_shap_insights "https://github.com/justinshenk/simba/blob/master/simba/shap_visualize.py"
click node_dpk_flow "https://github.com/justinshenk/simba/blob/master/simba/dpk_script/train_model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py,node_simba_gui,node_dash_launcher,node_setup_pkg toneBlue
class node_project_setup,node_video_prep,node_pose_import,node_pose_configs toneAmber
class node_feature_engine,node_outlier_cleanup,node_model_train,node_model_apply,node_model_validate,node_annotation_tools,node_behavior_analytics,node_roi_system toneMint
class node_plots_reports,node_dash_ui,node_shap_insights toneRose
class node_dpk_flow toneIndigo
```

## Components

### Runtime

User-facing launchers and packaging entry points

- [App.py](https://github.com/justinshenk/simba/blob/master/App.py): launcher · Top-level desktop entry point · `App.py`
- [SimBA GUI](https://github.com/justinshenk/simba/blob/master/simba/SimBA.py): desktop app · Main application shell for interactive workflows · `simba/SimBA.py`
- [Dash launch](https://github.com/justinshenk/simba/blob/master/simba/run_dash_tkinter.py): launcher · Tkinter and Dash startup scripts · `simba/run_dash_tkinter.py`
- [Packaging](https://github.com/justinshenk/simba/blob/master/setup.py): build/package · Install and dependency metadata · `setup.py`

### Ingest

Project setup, preprocessing, and external pose import

- [Project setup](https://github.com/justinshenk/simba/blob/master/simba/create_project_ini.py): config/bootstrap · Create and reset project and pose configuration · `simba/create_project_ini.py`
- [Video prep](https://github.com/justinshenk/simba/blob/master/simba/process_videos_automation.py): preprocess · Crop, extract frames, merge, and batch process videos · `simba/process_videos_automation.py`
- [Pose import](https://github.com/justinshenk/simba/blob/master/simba/read_DLCmulti_h5_function.py): interop · Convert external pose-estimation outputs into SimBA format · `simba/read_DLCmulti_h5_function.py`
- [Pose configs](https://github.com/justinshenk/simba/blob/master/simba/pose_configurations/configuration_names/pose_config_names.csv): config data · Body-part and skeleton configuration definitions · `simba/pose_configurations/configuration_names/pose_config_names.csv`

### Core pipeline

Feature extraction, cleanup, model lifecycle, and analysis

- [Feature engine](https://github.com/justinshenk/simba/blob/master/simba/features_scripts/extract_features_16bp.py): feature extraction · Pose-layout-specific feature extraction subsystem · `simba/features_scripts/extract_features_16bp.py`
- [Outlier cleanup](https://github.com/justinshenk/simba/blob/master/simba/outlier_scripts/movement/correct_devs_mov_16bp.py): correction · Movement and location correction for noisy tracking · `simba/outlier_scripts/movement/correct_devs_mov_16bp.py`
- [Model train](https://github.com/justinshenk/simba/blob/master/simba/train_multiple_models_from_meta.py): classifier training · Random-forest training and multi-model lifecycle · `simba/train_multiple_models_from_meta.py`
- [Model apply](https://github.com/justinshenk/simba/blob/master/simba/run_RF_model.py): inference · Run trained classifiers on new videos · `simba/run_RF_model.py`
- [Validate](https://github.com/justinshenk/simba/blob/master/simba/validate_model_on_single_video.py): validation · Held-out video validation and classifier scoring · `simba/validate_model_on_single_video.py`
- [Annotations](https://github.com/justinshenk/simba/blob/master/simba/pseudoLabel.py): labeling · Manual labels, pseudo-labeling, and annotation reversal tools · `simba/pseudoLabel.py`
- [Behavior analytics](https://github.com/justinshenk/simba/blob/master/simba/process_movement.py): analysis · Temporal summaries, severity, bursts, and movement metrics · `simba/process_movement.py`
- [ROI system](https://github.com/justinshenk/simba/blob/master/simba/ROI_analysis.py): spatial analysis · Region drawing, ROI movement, directionality, and ROI features · `simba/ROI_analysis.py`

### Reporting

Plots, dashboards, and result visualization

- [Plots & reports](https://github.com/justinshenk/simba/blob/master/simba/plot_sklearn_results.py): visualization · Static plots, Gantt views, thresholds, and summary charts · `simba/plot_sklearn_results.py`
- [Dash UI](https://github.com/justinshenk/simba/blob/master/simba/SimBA_dash_app.py): dashboard · Interactive analytics and dashboard presentation layer · `simba/SimBA_dash_app.py`
- [SHAP](https://github.com/justinshenk/simba/blob/master/simba/shap_visualize.py): explainability · Model interpretation and feature contribution visuals · `simba/shap_visualize.py`

### DeepPoseKit

Dedicated DeepPoseKit integration workflow

- [DPK flow](https://github.com/justinshenk/simba/blob/master/simba/dpk_script/train_model.py): integration · DeepPoseKit-specific annotation, training, prediction, and outlier handling · `simba/dpk_script/train_model.py`

## Connections

- App.py → SimBA GUI: starts · Main desktop entry starts the SimBA application
- Dash launch → Dash UI: opens · Launches the interactive dashboard layer
- Packaging → SimBA GUI: installs · Packages the application and runtime dependencies
- SimBA GUI → Project setup: configures · Creates and loads project metadata and pose configs
- SimBA GUI → Video prep: orchestrates · Drives preprocessing of videos and frames
- SimBA GUI → Pose import: imports · Brings external pose outputs into the pipeline
- Project setup → Pose configs: uses · Project creation depends on pose schema definitions
- Pose import → Feature engine: feeds · Imported coordinates become inputs to feature extraction
- Pose configs → Feature engine: parameterizes · Feature logic depends on body-part layout
- Feature engine → Outlier cleanup: prepares · Extracted coordinates are cleaned before downstream analysis
- Outlier cleanup → Model train: cleans inputs · Corrected tracking data supports training set construction
- Outlier cleanup → Model apply: cleans inputs · Model inference runs on corrected pose data
- Annotations → Model train: labels · Manual and pseudo labels seed classifier training
- Model train → Validate: evaluates · Trained classifiers are validated on held-out video
- Model train → Model apply: publishes · Trained models are applied to new datasets
- Model apply → Behavior analytics: outputs · Predictions become behavioral time series and summaries
- Model apply → ROI system: supports · Predictions and coordinates feed spatial ROI analysis
- Behavior analytics → Plots & reports: visualizes · Computed summaries are rendered as plots and tables
- ROI system → Plots & reports: visualizes · ROI metrics are rendered in static reports and figures
- Validate → SHAP: explains · Validation outputs drive interpretability plots
- Behavior analytics → Dash UI: explores · Analytics are also exposed through interactive dashboards
- DPK flow → Pose import: integrates · DeepPoseKit workflow plugs into the broader pose-import boundary
- DPK flow → Model train: trains · DeepPoseKit includes its own model training path
- DPK flow → Model apply: predicts · DeepPoseKit path includes video prediction and output visualization