Understanding the output files

You will find: one folder per run, with everything from Steps 0 to 5 inside it.

Every run writes into a single timestamped folder, CUBE results <date>_<time>, which CUBE creates inside the folder you processed (or inside the global output folder, if you set one):

CUBE results <date>_<time>/
  CUBE 0 - Corrected 3D vids/          (Step 0, multi-camera recordings only)
  CUBE 1a - 2D DLC/                    (Step 1a: tracking output per video)
  CUBE 1b - 3D DLC/<session>/          (Step 1b: 3D output per session)
  CUBE 2 - Preclustering files/        (Step 2: cleaned keypoint files per folder)
  CUBE 3 - Clusters/                   (Step 3: everything described below)
  CUBE 5 - Final Data/                 (Step 5: exported comparison figures)

Older results that use the previous folder layout are still found automatically.

Inside CUBE 3 - Clusters/:

bout_lengths/
  <stem>_bout_lengths.csv                 raw classifier bouts
  <stem>_bout_lengths_hmm.csv             HMM-smoothed bouts (the Analyser prefers these)
  <stem>_bout_lengths_hmm_enriched.csv    only if kinematic directedness and/or
                                          environmental context are switched on
  <stem>_approach_events.csv              only if both of those are on and an
                                          approach/avoid event was found
  <stem>_frame_labels.csv                 per frame: frame, time_s, label
  <stem>_frame_labels_hmm.csv             the same, HMM-smoothed
  <stem>_epochs.csv, <stem>_epochs_hmm.csv   epoch-level summaries
model/
  bsoid_model.pkl                         the trained model and settings
  hmm_model.pkl                           the HMM
  umap_embedding.npy                      the embedding of every bin
  session_bin_ranges.json                 which bins belong to which session
  cluster_feature_centroids.npz           cluster centres, used by the Analyser's hierarchy views
  split_merge_log.json                    every accepted split and its fate
  session_env_context.json                only if environmental context is on
plots/                                    the plots listed under Step 3
cluster_kinematics.csv                    movement signature of each cluster
cluster_confidence.csv                    low-confidence flag of each cluster
videos/
  example_clips/<cluster_id>/             short clips for annotation
  labeled_videos/                         full videos with the cluster label on every frame
  umap_evolution/                         optional
guided/                                   only if you used guided labelling

The bout table#

The bout CSV is the main input of the Analyser:

HMM files take priority. The Analyser loads the _hmm files when they exist and falls back to the raw files otherwise. To analyse the raw classifier labels, rename or delete the _hmm files.

Frame label files. In *_frame_labels[_hmm].csv, the label column is the final label (after Turned Away marking and bout bridging), and raw_label is the unmodified prediction for that frame.