`ms_select_k()` evaluates the consensus-CV extraction pipeline over a grid of candidate ranks and applies the default three-layer K arbitration (ARCHITECTURE section 5): the SUITOR CV argmin (layer 1), the consensus stability veto (layer 2, upstream default thresholds `avg >= 0.8`, `min_cluster >= 0.2`, sum `>= 1.0`) and a diagnostic-only Wilcoxon layer (layer 3; deliberate divergence from the upstream ranksums-steered search, PI ruling 2026-09-30 – the diagnostic columns are placeholders in this unit).
Usage
ms_select_k(
catalog,
k_grid,
replicates = 8L,
max_iter = 200L,
seed = 1,
k_folds = 10L,
n_seeds = 10L,
cv = TRUE,
threads = NULL,
...
)Arguments
- catalog
An [MsCatalog] object, as returned by [ms_tally()] or [ms_catalog()].
- k_grid
positive whole-number ranks to evaluate; each must not exceed `min(nrow(counts), ncol(counts))`. The grid is evaluated in ascending order.
- replicates
single whole number >= 2: ensemble fits per rank (multi-initialization only, no bootstrap).
- max_iter
single positive whole number: KL-NMF iterations per ensemble fit and ECM rounds per CV unit.
- seed
single whole number in [0, 2^31 - 1] seeding every stream.
- k_folds
single whole number in [2, nrow(counts)]: SUITOR folds.
- n_seeds
single positive whole number: SUITOR seeds per (rank, fold) – the documented v0.2 budget divergence from the upstream 30.
- cv
single logical: run layer 1? `cv = FALSE` fills the CV evidence columns with NA and arbitrates on the stability veto alone (memo section 3). Budget note: the v0.2 kernel face computes the CV grid inside the pipeline call regardless; `cv = FALSE` currently only changes the arbitration inputs.
- threads
NULL or a single non-negative integer pool size (the ensemble phase runs on the per-call pool).
- ...
No passthrough arguments: anything arriving in `...` is rejected as an argument-spelling error (`msuiter_error_input`).
Value
A named list with: * `k`: the selected rank (single positive integer), * `k_evidence`: the evidence table (data.frame, one row per grid rank) with the memo schema: `k`, `cv_test_deviance`, `cv_test_mse`, `cv_train_mse`, `fold_test_deviance` (list column, per-fold held-out deviance), `n_seeds_converged` (placeholder NA: the CV kernel does not yet surface per-seed convergence), `avg_stability`, `min_cluster_stability`, `per_signature_stability` (list column), `wilcoxon_p_vs_prev` / `wilcoxon_l2_median_delta` (placeholders, diagnostic layer not implemented), `passes_veto`, `is_argmin`, `selected`, `veto_reason`.
An undecidable grid (no rank passes the veto) raises `msuiter_error_kselect` with the full evidence table attached as the `k_evidence` condition field.