Troubleshooting

Installation and start-up problems#

Always begin with Help → System check (or python cube.py --check). It names what is missing and the fix.

"No clusters found" after Step 3#

1. Read the log: HDBSCAN may have labelled every point as noise. Try a larger n_neighbors or a smaller minimum cluster size.
2. Check the tracking quality: open a few keypoint files and confirm that likelihood values are mostly above 0.6.
3. If too many frames are being interpolated (see the "% interpolated" line of the log), lower the likelihood threshold.

Low classifier cross-validation accuracy#

1. Check that Min cluster frequency is not too low; tiny clusters are hard to classify.
2. Keep the class weight on balanced, which handles unequal cluster sizes.
3. Look at umap_3d.html. If all points are in one clump, try a larger n_neighbors or a smaller min_dist.

HMM smoothing gives implausibly long bouts#

1. Open hmm_transition_matrix.png. The diagonal should be high (about 0.95 to 0.99) but not 1.0.
2. Try fewer Baum-Welch iterations, which leave the matrix closer to its prior.
3. Compare *_bout_lengths.csv and *_bout_lengths_hmm.csv. To analyse the raw labels, delete or rename the _hmm files.

The number of clusters looks wrong#

1. Read the split and merge lines of the run log. Every accepted split or merge is logged, so you can trace which clusters changed and why. A merge refused by the region-aware guard is logged as REFUSED: region-aware merge guard.
2. Open plots/cluster_validity.png (or the Analyser's Cluster Validity mode) to see the values the decisions were based on, and model/split_merge_log.json for the fate of every split.
3. If merging looks too aggressive, lower the merge threshold. If splitting creates tiny, low-confidence fragments, raise the split threshold or reduce the iterations.
4. To switch refinement off, set the split threshold and the merge threshold to 0 and rerun.
5. With region-aware splitting on, check the [region-split] lines of the log. Lower the impurity threshold or the minority floor if it looks too conservative, or raise them if it over-splits.

The partition changes a lot between runs#

Look at cluster_stability.png. A low agreement means the embedding itself is seed-sensitive for your data. CUBE then builds a more robust partition automatically (see Reproducibility and Methodology); the log line [CONSENSUS-AUTO] says when it did so and why.

DLC inference fails in Step 1#

1. Check the CUDA drivers if you use a GPU, and confirm that DLC works on its own outside CUBE.
2. Try with Pooled labels off, then with Smart Adapt off. Adaptation can fail when the videos do not contain enough varied frames. If the log says Pooled adaptation unavailable, CUBE has already fallen back to the standard single-video adaptation on its own.
3. Check that OpenCV can read your video files: open one in a video player and try cv2.VideoCapture(path).isOpened() in Python.

The Analyser shows no animals or empty tables#

1. Confirm that the folder you chose contains a bout_lengths folder.
2. Confirm that it holds *_bout_lengths_hmm.csv or *_bout_lengths.csv files.
3. File names must end in _bout_lengths.csv or _bout_lengths_hmm.csv.

Group Predictor shows near-chance accuracy for every model#

Common causes: the groups really are behaviourally similar in this recording context; there are too few animals (fewer than 6 per group is very hard); the group assignments are wrong; or the wrong feature source is selected, in which case try Custom mode with a targeted set of clusters. See GROUP_PREDICTOR_REFERENCE.md for more.

"invalid command name" messages when closing#

These tkinter messages are harmless. A few scheduled screen updates run after their windows were closed. They do not affect results or saved files.