subject-subtyping

Prepare a CSV with a subject_id column and numeric imaging features, then run train_reference.py with a model such as consensus, gmm, or kmeans and a chosen cluster count. The script exports subtype assignments, embeddings, silhouette metrics, and a model checkpoint.

Seven methods are supported: K-means, Gaussian mixture models, spectral clustering, NMF, consensus clustering, PCA embedding plus K-means, and autoencoder embedding plus K-means. Consensus clustering is recommended when stability is central to the claim.

Run a prespecified range such as k=2..8, compare silhouette scores and bootstrap stability, then freeze k before any clinical endpoint testing. Outcome labels must never be used to select the cluster count.

Not directly. The training checkpoint does not bundle the fitted imputer and scaler, and spectral or consensus training defines no out-of-sample rule. A separately validated deployment pipeline preserving preprocessing and feature order is required for new-patient inference.

Stability requires completed replicate runs supplied via repeated --replicate flags to report_subtypes.py. Without them, stability is explicitly marked not_evaluated rather than silently omitted, since replicate runs must cover the same subjects and represent genuine perturbations.