• Paper: Neuroscience article

Behavior & Pose Analytics - in one desktop application

Computational ethology has matured into a rich ecosystem - DeepLabCut and SLEAP for pose, B-SOiD and VAME for unsupervised discovery, BORIS for manual coding, and commercial suites for regulated end-to-end work. Each is excellent at what it does; the friction usually lives in the seams between them. IntegraPose addresses that gap with one desktop application for pose estimation, multi-animal tracking, ROI- and bout-level analytics, manual review, and optional sub-behavior discovery. A curated plugin ecosystem extends the workflow for specialized experiments. The aim is to give labs without dedicated engineering support a unified, reproducible path from raw video to results that can be checked, interpreted, and reported with confidence.

Quick links: Quick Start, Installation Guide, Comprehensive User Guide.

What IntegraPose Covers

Area	What you do	Typical output
Data preparation	Extract frames, crop videos optionally, organize inputs	Clean training or inference-ready media
Project setup	Define keypoints, behaviors, skeleton, and dataset paths	A reusable project and dataset.yaml
Pose training	Train YOLO pose models from the app	Model files and training measurements
Advanced model design	Adapt a YOLO pose-model .yaml for a specialized assay	A model architecture tailored to your study
Inference	Run pose or detection inference on videos or folders	YOLO labels, optional media, motion summaries
Bout analytics and review	Measure and manually check behavior bouts, ROI visits, and object interactions	Reviewed tables, agreement measures, figures, and a review history
Batch processing	Apply the same settings to many videos	Results organized by video plus combined summaries
Sub-behavior discovery	Split known YOLO classes into the sub-behaviors actually present in your data, score them, name them, optionally export classifier-ready clip folders	Per-frame sub-cluster labels, bouts CSV, candidate scores, named clip folders

Review Predictions When Needed

After Bout Analytics, open Review Behavior Bouts or Review ROI / Object Bouts from Tab 6 or the Batch Processing Wizard. The review workspace keeps the video, predicted event, and your correction together, so you can check what happened without moving between several programs. Use it when manual confirmation is part of your study design or quality-control plan.

The video-synchronized workspace lets you:

• confirm or reject a predicted event
• correct behavior classes, animal IDs, and event start or end frames
• add, split, or merge bouts
• inspect and acknowledge legitimate overlapping behaviors
• review concurrent ROI visits, exclusive ROI-X visits, and object interactions
• measure how closely predictions agree with the completed manual review
• resize, hide, restore, and retain the video, review, timeline, and table layout

Original predictions remain available. Reviewed results become the preferred results only after you finish and export the relevant part of the review.

See the Bout Review Workspace guide for the complete researcher workflow.

Plugin Ecosystem

IntegraPose includes curated plugins that extend the seven-tab workflow without crowding the main application. Plugins are optional: enable the ones you need from Plugins -> Manage Plugins... and launch them in their own windows. They cover specialized needs that sit outside the core workflow.

Plugin status - research in progress. The plugin ecosystem evolves with active research. Some plugins are stable, others are works in progress, and the set may change as research priorities shift. If an ongoing study depends on a plugin, keep and record the IntegraPose version used for that study. See the Plugin Catalog for current per-plugin guides.

Category	Plugins
Dataset creation	Assisted Pose Curation, AutoLabel Forge (GroundingDINO + SAM), Dataset Augmentor Lab
Behavior & sequence modeling	TandemYTC - Tandem YOLO + Temporal Classifier
Domain-specific analytics	Gait & Kinematic Dashboard, Fura Imaging Lab, Zone Counter
Exploration & review	EDA Tool

Full catalog with per-plugin guides: Plugin Catalog.

What You Can Do With IntegraPose

• Gait & kinematic analysis - analyze animal gaits to extract stride length, speed, limb angles, and other locomotion signatures. A standalone gait-analysis project is available at Gait_Analysis_YOLO.
• Real-time behavior application - run closed-loop experiments, biofeedback, and live monitoring systems. Build your own plugins and integrate them as you wish.
• Rodent assay workflows - analyze and manually review rodent behavior using bouts, ROI occupancy, object interactions, and inter-animal tracking, offline or real-time with a webcam.
• Sports & movement analytics - analyze athletic performance, technique, and rehabilitation using pose estimation and movement analysis.

Install

A Conda environment is recommended.

1. Install Python 3.10-3.11 (3.11 recommended).
2. Install the PyTorch build that matches your hardware (pytorch.org).
3. Download and extract IntegraPose, or clone the repository, then open a terminal in the IntegraPose project folder.

Recommended full desktop install

This profile supports all seven main tabs and installs the dependencies used by the bundled plugins. The CPU example works on any computer. If you have an NVIDIA or AMD GPU, replace the PyTorch line with the matching GPU command from the next section.

git clone https://github.com/farhanaugustine/IntegraPose.git
cd IntegraPose
conda create -n integrapose python=3.11
conda activate integrapose
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install ".[dev,plugins]"
python tools/install_albumentations_gui.py

The dot in ".[dev,plugins]" means “install the IntegraPose project in the current folder.” The command therefore must be run from the folder containing setup.cfg.

The examples use double quotes because they work in Windows PowerShell, Anaconda Prompt, macOS Terminal, and most Linux shells. On macOS or Linux, you can use single quotes instead (pip install '.[dev,plugins]') if that better matches your shell. Keep the brackets inside the quotes.

Choosing the PyTorch GPU build

IntegraPose works on CPU, NVIDIA GPUs, and AMD GPUs. GPU support comes from the PyTorch build you install before installing IntegraPose.

Use the official PyTorch install selector as the source of truth for the current command: https://pytorch.org/get-started/locally/. The examples below show the usual pattern, but PyTorch may update CUDA or ROCm version numbers over time.

If you are not sure which GPU you have, install the CPU build first. IntegraPose will still run, just slower:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

For an NVIDIA GPU, install the current NVIDIA driver, then use the official PyTorch selector and choose:

• OS: your operating system
• Package: Pip
• Language: Python
• Compute Platform: CUDA

Example command: install the PyTorch version compatible with your GPU.

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

For an AMD GPU, first check AMD's compatibility matrix. ROCm support depends on the exact GPU, operating system, driver, Python, and PyTorch combination.

For the IntegraPose desktop application, the recommended AMD path is a native Linux installation with Python 3.10 or 3.11:

1. Confirm that AMD lists your GPU and Linux version as supported.
2. Install the matching AMD driver and ROCm components by following the official ROCm Linux guide.
3. Open the PyTorch install selector and choose Stable, Linux, Pip, Python, and the ROCm version supported by your system.
4. Run the exact PyTorch command shown by the selector. Do not copy an older hard-coded ROCm wheel URL from a tutorial.
5. From the IntegraPose repository folder, run:

pip install ".[dev,plugins]"
python tools/install_albumentations_gui.py

AMD also publishes prebuilt rocm/pytorch Docker images. This is an advanced option for the desktop application because the container needs access to the host display. Choose a specific image tag containing py3.10 or py3.11; do not use rocm/pytorch:latest without first checking its Python version. Follow AMD's current PyTorch on ROCm instructions for the required /dev/kfd, /dev/dri, security, IPC, and shared-memory options.

Current AMD PyTorch-on-Windows packages may require a Python version outside IntegraPose's supported 3.10-3.11 range, and AMD's Windows support has additional training limitations. Check AMD's Windows compatibility and limitations before attempting that path. Use the CPU installation on Windows when the supported versions do not align.

Verify the install by starting Python in your Conda environment or Docker container:

python

Then copy and paste this:

import torch

print("PyTorch version:", torch.__version__)
print("GPU available:", torch.cuda.is_available())
print("CUDA build:", torch.version.cuda)
print("ROCm build:", torch.version.hip)

if torch.cuda.is_available():
    print("GPU name:", torch.cuda.get_device_name(0))
else:
    print("GPU name: CPU only")

For AMD ROCm, it is normal for PyTorch to use the torch.cuda API and device strings such as cuda:0. IntegraPose detects whether that cuda:0 backend is NVIDIA CUDA or AMD ROCm automatically.

References: PyTorch install selector, AMD ROCm Linux guide, AMD compatibility matrix, NVIDIA CUDA installation guide.

For a minimal core installation (Tabs 1-6), from the repository root:

pip install .

Tab 7 and the bundled plugins require packages from the full profile. Install the recommended user profile with:

pip install ".[dev,plugins]"

For a contributor environment with dev tools and the plugin stack:

pip install ".[dev,plugins]"

For Albumentations support, kept separate so it does not replace the GUI OpenCV build:

python tools/install_albumentations_gui.py

Launch

python -m integra_pose
# or
integrapose

Documentation

The full manual lives under docs/.

• Comprehensive User Guide - covers every tab, bout and ROI review, bundled plugins, and advanced model options.
• Quick Start - get from a fresh install to a first run in minutes.
• Installation - environment setup, minimal and full install profiles, Albumentations install path.

To build the docs locally, first install IntegraPose, then run:

pip install mkdocs-material
mkdocs serve

Then open http://127.0.0.1:8000/ in your browser.

Workflow At A Glance

Step	Place in the app
1	Data Preprocessing
2	Setup & Annotation
3	Model Training
4	Inference
5	Webcam Inference
6	Bout & ROI Analytics, followed by optional manual review
7	Behavior Clustering
Supporting tools	Log Console, Batch Processing Wizard, optional plugins

Raw videos
  -> Data Preprocessing
  -> Setup & Annotation
  -> Model Training, imported model, or custom architecture
  -> Inference or Batch Processing Wizard
  -> Bout & ROI Analytics
  -> Manual review (when required by the study)
  -> Behavior Clustering (optional)

Pick Your Starting Path

Goal	Best guide
Already have a detection model and want ROI/bout analytics	Detection-Only Workflow
Want a full pose workflow inside IntegraPose	Pose Model Workflow
Process many videos at once	Batch Processing Wizard
Validate or correct predicted events	Bout Review Workspace
Design a custom YOLO architecture for your assay	Customizing the YOLO Model
Browse optional plugins	Plugin Catalog

Showcase

Examples of IntegraPose in action - simultaneous keypoint tracking and behavior classification.

OpenField	Video Source	Behaviors
	BehaviorDEPOT	Walking, Wall-Rearing / Supported Rearing
	BehaviorDEPOT	Walking, Wall-Rearing / Supported Rearing
	BehaviorDEPOT	Walking, Grooming
	Temporal_Behavior_Analysis	Exploring/Walking, Wall-Rearing / Supported Rearing
	Temporal_Behavior_Analysis	Wall-Rearing / Supported Rearing, Jump
	BehaviorDEPOT	Ambulatory/Walking, Object Exploration, Object Mounting
	BehaviorDEPOT	Ambulatory/Walking, Object Exploration
	Self	Ambulatory/Walking, Nose-Poking, Wall-Rearing / Supported Rear
	Self	Ambulatory/Walking, Wall-Rearing / Supported Rear

Status, Stability & Roadmap

IntegraPose is active research software. The core workflow (Tabs 1-7) is stable enough for ongoing lab use; individual features and plugins evolve as research needs change. Forks may adapt the software to specific needs, but updates may introduce breaking changes. Pull requests are welcome.

More specifically:

• The set of bundled plugins may change as research priorities evolve. Keep a copy of the IntegraPose version used for an ongoing study.
• Commands, result-file formats, project bundles, and plugin connections may change while the project is evolving.
• Documentation, tutorials, and example outputs are maintained alongside the application. Use the guide under docs/ that accompanies your copy of IntegraPose.
• No warranties, express or implied, are provided. See the AGPL-3.0 license for the full liability disclaimer.

Citation

If IntegraPose contributes to your analysis pipeline, please cite:

Augustine, F., O'Sullivan, S., Murray, V., Ogura, T., Lin, W., & Singer, H. S. (2025). IntegraPose: A unified framework for simultaneous pose estimation and behavior classification. Neuroscience, 590, 1-22. https://doi.org/10.1016/j.neuroscience.2025.10.020

DOI for the software release: 10.5281/zenodo.15565090.

License

IntegraPose is provided under the GNU Affero General Public License v3.0 (AGPL-3.0).

What this means for you

• Using the app for research, analysis, and publications: Totally fine. You can run IntegraPose internally and publish results however you like; the AGPL does not limit what you learn or publish.
• Modifying or redistributing IntegraPose: If you share the altered program or host it for others, for example as a web service, you must provide your changes' source code under AGPL too.
• Integrating Ultralytics: The AGPL choice keeps the alignment with Ultralytics' AGPL license. If your group has a commercial exception from Ultralytics, you can apply that to IntegraPose as well.

Need more detail? See GNU's AGPL overview.

Acknowledgments

IntegraPose builds on the open-source ecosystem. We extend our gratitude to:

• The Ultralytics team for the YOLO training and inference backbone.
• The Roboflow Supervision team for visualization and overlay utilities.
• PyTorch, OpenCV, NumPy, SciPy, Pandas, Matplotlib, Pillow, HDBSCAN, UMAP, and the broader scientific Python community.
• Public datasets that make benchmarking possible, including BehaviorDEPOT, Temporal_Behavior_Analysis, and several MARS Caltech multi-mouse and mouse-strain datasets available through Harvard Dataverse.