📖 API Reference

This section provides a categorized reference of SimBA’s modules and methods, grouped by their functionality such as feature extraction, plotting, transformation, and modeling.

📑 Find anything fast

Browse the Module Index — an alphabetical list of every SimBA module, and the quickest way to find where a class or function lives.

Or jump to the General Index (every class, function and term, A–Z), or use full-text search.

🔍 Blob tracking tools

Track animals in videos using background subtraction and blob detection — an alternative to pose-estimation that needs no trained keypoint model. Detected blob contours are converted into geometric features such as the animal’s center, nose, tail, and left/right flank points, so downstream movement, ROI, and geometry analyses work from the silhouette alone. Well suited to single-animal, high-contrast recordings where a full pose model is unnecessary.

SimBA Blob Tracking Methods

📦 Bounding-box tools

Build bounding boxes and anchored polygons around animals from pose-estimation data, then quantify how they overlap through time. Useful for detecting proximity-based social interactions — one animal entering another’s space, or body parts coming into contact — without training a dedicated classifier. Overlap statistics can be aggregated per-animal and per-frame for downstream analysis.

See tutorial: Anchored ROI (bounding box) tutorial

🔁 Circular transformations

Statistical operations for circular data such as head direction and heading angle, where values wrap around 360°. Wraparound-aware and multi-animal capable, these methods derive base angles from body-part triplets and compute quantities like mean resultant vector length, angular difference, directional dispersion, and the Rayleigh test — in both sliding-window and whole-session forms. GPU-accelerated variants are available for large datasets.

Circular transformations
- Circular statistics mixin
- Circular GPU methods

🔧 Config reader

Parse SimBA project configuration (project_config.ini) and expose project metadata — file paths, animal and body-part definitions, video parameters, and classifier settings. Most SimBA classes inherit from this reader so they can locate data and resolve project-wide options consistently, rather than re-parsing the config themselves.

Config reader
- Config reader

💡 Cue-light tools

Link animal behavior to the on/off state of cue lights in the arena. Detect illumination changes from ROI pixel intensity, then summarize movement and classified behavior in the periods before, during, and after each light event — for analyses of conditioned or stimulus-driven responses.

See tutorial: Cue-light tutorial

Cue-light tools

🔧 Data processing tools

Transform classification, tracking, and image data after feature extraction or model inference. Includes interpolation and smoothing of pose data, aggregation of classifier results, and specialized calculators such as Kleinberg burst detection, the forward spike-time tiling coefficient (FSTTC), and movement and severity scoring.

Data processing tools

📏 Feature extraction mixins

Core low-level feature methods — distances, angles, velocities, areas, and body-part relationships — that the default extraction pipelines assemble into full feature sets. Use these directly to compose custom features from raw tracking coordinates when the out-of-the-box extractors don’t fit your schema.

Feature extraction mixins
- Feature extraction methods
- Supplementary feature extraction methods

📝 Feature extraction wrappers

Pre-configured “out-of-the-box” feature extraction modules for common pose-estimation schemas, spanning a range of single- and multi-animal body-part layouts. Each wrapper turns raw tracking coordinates into the tabular feature set that SimBA classifiers are trained and run on, so most users never have to write feature code by hand.

Feature extraction wrappers

📐 Geometry transformations

Transform pose-estimated body-part coordinates into geometric shapes — bounding boxes, polygons, circles, and lines — and compute spatial relationships between them. Supports buffering, unions and intersections, point-in-shape tests, inter-shape distances, overlap, and directionality. Built on Shapely, with GPU-accelerated variants for many of the heavier operations.

Geometry transformations
- Geometry mixin
- Geometry GPU methods

⚙️ Global configuration

Global SimBA settings and environment variables — GPU toggles, default paths, and feature flags — that tune runtime behaviour across the package. Set these once to change how modules execute (for example, enabling numba eager compilation or GPU code paths) without editing individual scripts.

Global Configuration Options

⚡ GPU acceleration

CUDA/CuPy-accelerated versions of SimBA’s compute-heavy routines — geometry, image, background subtraction, statistics, circular statistics, time-series, and SHAP — consolidated in one place. On a supported NVIDIA GPU they produce the same results as their CPU counterparts but run orders of magnitude faster on large datasets, with per-function expected-runtime tables to help you gauge the speed-up.

GPU acceleration

🖼️ Image transformations

Manipulate video frames and extract visual information from tracking data — crop, slice, rotate, and greyscale frames, isolate regions around body parts, and compute pixel-based features. Includes methods for comparing image features across time (e.g. frame-to-frame change), with both CPU and GPU implementations.

Image transformations
- Image mixin
- Image GPU methods

🏷️ Labeling tools

Interactive tools for annotating behavioral events frame by frame. Create and edit the ground-truth labels used to train classifiers, review and correct model predictions directly on the video, and manage annotations across a project’s videos.

Labeling tools

🧩 Mixins (overview)

Entry point to SimBA’s mixin classes — the reusable method libraries (feature, geometry, statistics, plotting, image, network, timeseries, model) that the other topical sections draw on. Grouping shared functionality here keeps it consistent and testable across the package; most user-facing tools are thin wrappers that combine these mixins.

Mixins (overview)

🤖 Model tools

Create, train, evaluate, and apply SimBA’s behavior classifiers (random-forest based). Configure hyperparameters, run cross-validation, generate evaluation metrics and plots such as feature importances and learning curves, and batch-apply trained models to new videos to produce per-frame behavior probabilities.

Model tools

🔗 Network transformations

Build and analyze graphs derived from pose-estimation time-series — for example, interaction networks between animals or connectivity between body parts. Compute node and edge metrics and visualize how the network’s structure changes over time.

Network transformations
- Network (Graph) methods

⚠️ Outlier correction

Heuristic filtering of implausible body-part tracking. Location- and movement-based criteria — scaled by a reference inter-body-part distance — flag and correct jitter and sudden, physically impossible jumps before feature extraction, improving the quality of downstream features and classification.

Outlier correction

🎨 Plotting and visualization tools

Visualize behavioral data and pose-tracking outputs — Gantt plots, path, distance and velocity plots, heatmaps, classification-probability charts, and data overlays rendered onto the original video. Produces both static figures and frame-by-frame videos, with multiprocessing support for large batches.

Plotting and visualization tools

📦 Pose-estimation import tools

Parse, load, and standardize pose-estimation output from common trackers (e.g. DeepLabCut, SLEAP, DeepPoseKit, MARS) across H5, CSV, and JSON formats. Handles single- and multi-animal data and can interpolate and smooth tracking on import, producing the consistent internal format the rest of SimBA expects.

Pose-estimation import tools

🗺️ ROI tools

Define regions-of-interest — rectangles, circles, and polygons — and analyze tracking in relation to them. Compute zone entries and exits, time and distance spent in each region, distance to ROI boundaries, and whether animals are oriented toward a region, with visualization tools for the results.

📊 Statistics transformations

Compute statistical features from tracking and classification data — descriptive statistics, distribution comparisons, distance metrics, and drift/change detection — over sliding or static time windows. Underpins much of SimBA’s feature extraction, and many methods have GPU-accelerated counterparts for large datasets.

Statistics transformations
- Statistics mixin
- Statistics GPU methods

📥 Third-party label appenders

Import behavioral annotations produced by external tools (e.g. BORIS, Ethovision, Observer, DeepEthogram, SOLOMON) and align them, frame by frame, to SimBA’s pose-estimation and feature data. Lets you reuse existing human or third-party labels as classifier training targets without re-annotating.

Third-party label appenders

🕐 Time-series transformations

Analyze the temporal structure of tracking and feature signals using sliding-window methods — complexity and entropy measures, autocorrelation, and windowed descriptive statistics — to capture how behavior evolves over time. GPU-accelerated variants are available for the heavier computations.

Time-series transformations

🔮 Unsupervised learning

Discover behavioral structure without labels. Combines dimensionality reduction (e.g. UMAP, PCA) with clustering (e.g. HDBSCAN, K-means), plus tools to embed, visualize, and quantify the resulting clusters — a workflow for surfacing candidate behavioral motifs from feature data.

Unsupervised learning

🖥️ User Interface (UI) tools

SimBA’s graphical interface components — the Tkinter windows, pop-ups, and menus that drive project creation, configuration, and each step of the analysis workflow. The entry point for users who prefer clicking through SimBA rather than scripting it.

User Interface (UI) tools

⚙️ Utilities

Helper methods used throughout the package — logging, CLI execution, input and argument validation, warnings, timing, and reading/writing project files. The shared plumbing that keeps SimBA’s error messages, checks, and file handling consistent across every module.

📹 Video processing tools

Video processing tools built on OpenCV and FFmpeg — clip, crop, concatenate, downsample, re-encode, rotate, and greyscale videos, and compute average/background frames. Covers the common pre-processing steps needed to get raw recordings ready for tracking and analysis, with multiprocessing support for batch jobs.

Video processing tools

👁️ YOLO Methods

Methods for training YOLO models, creating training and validation datasets, and converting behavioral neuroscience-specific datasets to YOLO datasets.

Uses the Ultralytics package.

YOLO methods