Advanced settings

Selection modes. occurrence_persistence_ranged (default) ranks candidates by how well their clusters survive a test against real behaviour bouts, while respecting the preferred range (a hard floor at the low end, a soft penalty above the high end). occurrence_persistence uses the same ranking but ignores the range and can settle on very few clusters. floor_soft_cap ranks by DBCV or silhouette, avoids the low bound and lightly penalises overshoot. legacy is an earlier rule that can collapse to very few clusters.

After the first clustering, clusters that are mixed are split and clusters that are barely separated are merged, up to a few rounds. In order:

1. Split. A cluster whose mean silhouette is below the split threshold is re-embedded and re-clustered locally. A split is accepted only if the local result is a stable sub-partition, so noise alone does not cause a split.
2. Merge. Sibling clusters that separated at low persistence in the HDBSCAN condensed tree, and that are also close in the embedding, are merged.
3. Prune. Rare clusters are removed.
4. Steps 1 to 3 repeat up to the iteration limit and stop early when a round changes nothing.

Every decision is written to the run log, and every accepted split to model/split_merge_log.json. Clusters with low silhouette bars in cluster_validity.png are the split candidates, and split_merge_refinement.png shows the effect.

If merging looks too aggressive, lower the merge threshold. If splitting is creating small, low-confidence fragments, raise the split threshold or reduce the iterations. To switch refinement off completely, set the split threshold and the merge threshold both to 0.

Related settings: after refinement, clusters below the minimum cluster frequency are removed again, so a small split-off cluster may disappear; lower the frequency if you want such clusters to survive.

These add extra ways to decide which clusters are tested for a split. They apply to 2D and 3D data and to both remedy methods.

These features use the order of movements, not just their amount. They are on by default; the section can be used to switch them off and reproduce an earlier baseline.

Consensus clustering (engine settings, no separate controls): UMAP and HDBSCAN are run with consensus_n_seeds seeds (default 8), a co-association matrix records how often each pair of bins shares a cluster, and Ward linkage clusters that matrix. Ward is the default because average and complete linkage chained everything into one giant cluster. It costs roughly the number of seeds times the runtime of the first clustering. A memory guard (consensus_max_memory_gb, default 4) stops oversized datasets before the work starts, and the usual split and merge refinement is replaced by a consensus-specific version (consensus_refine_enabled, on).

UMAP itself always runs single-threaded, so embeddings are reproducible.

These can be set in the saved session's engine configuration (the .pipeline_session.json file) for headless runs.

• bout_gap_bridging_enabled (on) and bout_gap_bridging_max_gap_s (0.3). Some behaviours are bursty: licking is a series of brief on-off events, each shorter than the 0.3 s bout minimum. Before the duration filter runs, CUBE merges runs of the same label that are separated by a short interruption of any other label (up to the gap tolerance) and fills the gap with the surrounding label. Bridging happens after turned-away exclusion, so a very short turned-away blip inside a bout is folded back into it. In the frame label files label shows the bridged result and raw_label the unmodified prediction. Turning it off drops every sub-minimum blip and changes bout counts for bursty behaviours.
• min_epoch_dur_s (0.3) and max_epoch_dur_s (10): the bout duration filter, also set in the main window.
• max_interp_gap_sec (0.5): the longest gap that is filled from neighbouring frames.
• dlc_smart_adapt_pool_max (6): the most same-camera videos Smart Adapt pools for its pseudo-labels. dlc_temporal_gate, dlc_bbox_gate and dlc_fill_conf_cap (all on) switch the per-video tracking corrections described in Section 4a on or off; these are in the advanced DLC configuration of the session file.

Switch it on in the Environments, Objects, Paradigms... window. CUBE then writes an extra table per session, <stem>_bout_lengths_hmm_enriched.csv, next to the normal bout table (which is never changed). It repeats the basic columns and adds, for each bout: net_displacement_px (straight-line distance from the first to the last frame), path_length_px (summed frame-to-frame travel), straightness_ratio (net divided by path: 1 is perfectly straight, near 0 is meandering), mean_speed_px_s, and heading_consistency (1 means every step points the same way, near 0 means random). Bouts shorter than 5 frames get no straightness or heading value. With the setting off, no such file is written. Each cluster's movement signature (cluster_kinematics.csv) is always available in the Analyser's Metric selector.

Use it when you traced an arena (elevated plus maze, Y-maze, open field, three-chamber and similar) and suspect that a cluster mixes two behavioural contexts that look alike kinematically, for example grooming near the wall versus in the open. This option lets that split appear as two clusters. B-SOiD, VAME and keypoint-MoSeq do not use arena or region information in their clustering step; see CUBE_ANALYSIS_METHODOLOGY.md Section 7 for the comparison. Region information never enters UMAP or HDBSCAN itself: it only selects which clusters are tested for a split, and the test is the usual HDBSCAN and DBCV one. The option is in the Environments, Objects, Paradigms window and needs a traced arena with regions, but not environmental context to be switched on.

The [region-split] cluster-count trace line of the run log shows the count before and after refinement and after pruning. A merge that would recreate a region-mixed cluster is refused, and one more region-only screening pass runs after refinement, so a region-pure split is not silently undone. validation_report.json gains a region_split block when the option is on, and the hierarchy plot shows each cluster's region composition and marks clusters produced by a region split.

The split side of refinement tests every candidate cluster, which becomes slow when a partition has many candidates. Four engine settings bound this: hdbscan_split_max_candidates (10, worst first), hdbscan_split_candidate_cutoff (0, meaning automatic: a stricter silhouette bar of half the split threshold is applied before the limit), hdbscan_split_sweep_n_steps (12 steps for each local sweep, against 40 for the main sweep) and hdbscan_split_n_jobs (-1, automatic). The parallel work uses worker threads.