What it is for: HDBSCAN often splits one real behaviour into two or three clusters because of small pose differences. Recombination takes the N raw clusters down to a smaller set that matches distinguishable behaviours. The Unbiased Analytics tab offers three ways to do this. They answer different questions.
The three methods#
| Method | View | What decides a merge | Stops at | Best for |
|---|---|---|---|---|
| Manual k-sweep | Recombination | You pick the number of groups, k | Exactly k groups | Seeing what forcing 3, 5 or 8 groups looks like, side by side |
| Recombination with pose-distance cap | Recombination | The same, but a proposed group is rejected (split back into its raw clusters) if any pair inside it is too far apart in pose space | k groups, minus any rejected merges | Checking that a chosen k merges clusters that look alike, not just clusters whose usage changes together |
| Guided Merge | Guided Merge | The algorithm merges the closest pair by usage pattern, but only if the pair is also close in pose space and clearly better than the next-best rejected option | Automatically, when no further merge is justified | Not having to choose k, and having a reproducible, defensible starting point for merging |
All three start from the same distance between clusters: 70% correlation of each cluster's usage pattern across your experimental groups plus 30% cosine similarity of the clusters' outgoing transition profiles. What differs is whether a second, independent signal, pose similarity, can veto a merge.
Why a pose-distance cap exists#
The blended distance only looks at how a cluster's usage changes between groups and how it transitions to other clusters. Two clusters can match on both for reasons unrelated to being the same behaviour, such as a shared arousal state or a coincidence in a small dataset. The pose-distance cap adds an independent check: it measures how different the clusters' movement and posture really are, using the same features UMAP and HDBSCAN were trained on, and only lets a merge through when the clusters are close on both criteria.
Requirement. The cap, Guided Merge and the Cluster Hierarchy view need model/cluster_feature_centroids.npz, which Step 3 saves automatically. Runs from before this file existed do not have it; rerun Step 3 to create it (Steps 4 and 5 do not need to be redone). Until then the cap control is greyed out and the views explain why.
Backfill pose data (approximate). A faster alternative for old runs: it builds pseudo-centroids from the saved embedding instead of true feature-space centroids, so it needs no raw keypoint files and runs instantly. It is a lower-fidelity approximation, because distances between clusters in a UMAP embedding are only locally meaningful. Everything built from it is marked APPROXIMATE, and the button never overwrites a real cluster_feature_centroids.npz. Use it for a quick look and rerun Step 3 for results you will publish.
Parameters#
| Parameter | Where | Default | What it does | What changing it means |
|---|---|---|---|---|
| k to save / compare k values | Recombination | 5 / 3,5,8 | How many merged groups the manual sweep makes | Lower k lumps more and is easier to read but may merge distinct behaviours; higher k stays closer to the raw clustering |
| Pose-distance cap (percentile) | Recombination | 100 (off) | Only clusters within this percentile of the closest pose distances may merge | Lower is stricter. Values under about 10 can reject almost everything, which suggests k should be lower before you merge |
| Guided Merge cap % | Guided Merge | 50 (median) | The ceiling of pose distance Guided Merge may consider at all | Lower is more conservative. Values well above 50 to 60 remove the pose constraint |
| Guided Merge min gap | Guided Merge | 0.15 | The best remaining merge must be at least this much closer (as a fraction of its own distance) than the closest pair that pose distance already ruled out | Lower accepts more borderline merges (fewer, larger groups); higher stops earlier |
| Save source | Save Reclustered Groups | Manual (k-sweep) | Whether Save as Preset and Push to Group Editor export the k-sweep groups or the Guided Merge groups | Defaults to the view you are looking at |
Reading the outputs#
- Recombination title. When the cap is active it reports how many proposed merges were rejected at each k (for example "2 of 5 proposed merges rejected"). If many are rejected, your k probably lumps clusters that do not look alike: try a lower k, or keep the smaller groups.
- Guided Merge labels. Each merged group (
RG-1,RG-2, ...) is labelled with the raw cluster ids inside it. - Guided Merge table. One row per accepted merge, with the pair, their blended distance, pose distance and percentile, usage correlation and transition similarity. A merge with a high pose-distance percentile and only a moderate correlation deserves a second look before you rely on it.
- Cophenetic correlation (bottom of the table) is a number between -1 and 1 that says how faithfully the dendrogram represents the distances. Below roughly 0.7 to 0.8, be sceptical of any cut of the tree.
Which method to use#
- A quick summary plot: manual k-sweep with the cap off. Pick a k that gives a readable number of groups (5 to 8 is usually legible).
- A write-up that has to justify the merges: Guided Merge with the defaults, and cite the table's pose-distance percentile and correlation for each merge.
- Someone doubts a merge you made by hand: open Recombination at your k, set a strict cap (20 to 30) and see whether the merge survives. Compare with the Cluster Hierarchy view: clusters on clearly distant branches are a real reason to reconsider.
- Guided Merge merges nothing, or everything into two groups: if nothing merges, raise the cap % first, then lower the min gap. If it merges too much, lower the cap % first, then raise the min gap.
- Controls are greyed out: the run predates
cluster_feature_centroids.npz; rerun Step 3.