CUBE user guide

CUBE finds and measures behaviour in video of animals. It combines DeepLabCut (DLC) pose estimation with unsupervised machine learning: it tracks body points, groups similar movements into clusters, lets you name the clusters by watching example clips, and then compares behaviour between animals or groups.

The method builds on B-SOiD (Hsu & Yttri 2021, Nat. Commun. 12:5188) and adds:

• multi-scale movement features (100 ms and 200 ms windows) and body-size-independent geometry;
• automatic selection of the clustering settings, with split and merge refinement of the clusters;
• stability checks across random seeds;
• hidden Markov model (HMM) smoothing of the labels over time;
• interactive annotation and optional guided labelling with your own labels;
• group statistics, a Group Predictor with permutation testing, and paradigm-specific reports.

What CUBE does not require: manual behaviour labels, predefined behaviour categories, or frame-by-frame annotation. You can add labels later (see Guided labelling) when you want clusters to follow behaviours you define.

What you provide: video recordings of your animals. CUBE can run the DLC SuperAnimal quadruped model for you, or you can bring your own DLC output files (H5 or CSV).

How CUBE relates to other tools#

CUBE builds on B-SOiD and sits alongside other well-validated tools such as VAME and keypoint-MoSeq. These tools were designed for different needs, and none is best in every setting. The points below describe where CUBE's design differs. They reflect design choices rather than measured differences in performance. CUBE is under active development, and suggestions are very welcome.

Where CUBE's design differs

1. A single application from recording to figures. Video alignment, pose estimation, pre-processing, clustering, annotation and statistics are run from one point-and-click interface, so a complete analysis does not require programming or moving files between separate programs. Every stage of a run is saved to one folder.
2. Temporally aware, animal-centred clustering with a reproducibility check. Features describe posture and movement in animal-centred (egocentric) coordinates together with the order of movements. Clustering is repeated across random seeds and the agreement between runs is reported. When agreement is low, CUBE builds a representative (medoid) or consensus partition, so that the result depends less on a single seed.
3. Researcher-guided refinement and correction. Clusters are named by watching example clips, and can be merged, split or recombined by hand, with a dendrogram view to support the decision. Optional guided labelling lets you supply your own labelled examples, so manual input remains possible at each stage rather than only at the end.
4. Built-in analysis and figures. The analyser produces ethograms, bout statistics, bar charts, transition analyses and group comparisons that highlight clusters whose usage changes between conditions, including behaviours that were not defined in advance. A Group Predictor, based on regularised logistic regression (a generalised linear model) with permutation testing, asks whether behavioural profiles distinguish the groups.
5. Arena-aware clustering. Optionally, clustering can take the position of the animal in traced regions of the arena into account, such as the open arms of an elevated plus maze, so that spatial context can help separate behaviours without letting position replace movement as the classification signal.

Related tools

• B-SOiD (Hsu and Yttri 2021) introduced the pose-feature, UMAP, HDBSCAN and fast-classifier approach that CUBE follows. CUBE keeps its speed and its lack of GPU training.
• VAME (Luxem et al. 2022) learns a temporal embedding with a neural network. CUBE does not adopt that architecture or its training cost, and uses temporally aware features and smoothing to address a related question by simpler means.
• keypoint-MoSeq (Weinreb et al. 2024) models keypoint uncertainty explicitly. CUBE uses a simpler analogue, in which low per-body-part confidence is used as a feature so that unreliable frames can be separated from behaviour clusters.

The five steps at a glance

The pipeline at a glance

Start

The pipeline

Analyse

Reference

Help