Skip to content

BehaviorScope-X Documentation#

BehaviorScope-X is a desktop application and script bundle for building animal behavior classifiers from video. The central workflow is simple: annotate behavior bouts, choose a supported pose-model workflow, build full-video sequence caches, extract pose-derived and pose-backbone visual features, train temporal classifiers, and inspect frame-level and bout-level outputs.

The GUI is the shared validated workflow surface. It follows a pose-model-flexible design: YOLO-pose, MobileNetV3, and DeepLabCut-HRNet each provide an independent route to compatible sequence caches, feature caches, classifier training, evaluation, ethogram/bout summaries, and output inspection.

The GUI is organized around model families:

  • Annotate + Clip imports videos, assigns splits, labels bouts, tracks quality-control state, and exports full-video annotation manifests.
  • YOLO-pose supports full-video cache construction, feature-cache generation, classifier training, single-video inference, folder-level batch inference, ethogram/bout summaries, and output inspection.
  • MobileNetV3 supports native full-video cache construction, MobileNetV3 feature-cache generation, cached-feature classifier training, staged held-out evaluation, ethogram/bout summaries, and output inspection.
  • DeepLabCut-HRNet exposes staged workflows for DLC SuperAnimal fine-tuning, top-down sequence-cache generation, HRNet feature extraction, classifier training, held-out evaluation, ethogram/bout summaries, and output inspection.

Use the GUI when you want a guided desktop workflow. Use the analysis runners when you want scripted, reproducible long-running jobs.

  1. Installation
  2. GUI Overview
  3. Annotation Workflow
  4. One model-family workflow:
  5. YOLO-pose Workflow
  6. MobileNetV3 Workflow
  7. DeepLabCut-HRNet Workflow
  8. Feature Taps
  9. Outputs and Provenance
  10. Troubleshooting

Start the GUI#

python behaviorscope_x_qt.py

Start the Documentation Server#

mkdocs serve

Then open the local URL printed by MkDocs.