Select the number of signatures for a channel-by-sample count matrix

bp_select_k() runs the bp-route K survey over a rank grid and applies the ported three-layer arbitration (parity plan P2, semantic port of the msuiter ms_select_k() at main@dad30440): the SUITOR-style CV argmin (layer 1, first minimum / lowest rank on ties; switchable off with cv = FALSE), the consensus stability veto (layer 2, upstream reference thresholds avg >= 0.8, min_cluster >= 0.2, sum >= 1.0) and diagnostic-only Wilcoxon columns (layer 3 – they never arbitrate). All stochastic layers derive from the single seed (seed-law: same seed, byte-identical verdict and diagnostics).

bp_select_k(
  counts,
  k_grid = 2:5,
  replicates = .BP_SURVEY_REPLICATES,
  k_folds = .BP_SURVEY_FOLDS,
  n_seeds = .BP_SURVEY_NSEEDS,
  cv = TRUE,
  seed = 1L
)

Arguments

counts: a numeric channel-by-sample count matrix with row and column names, finite and non-negative (the extraction catalogue).
k_grid: positive whole-number ranks to evaluate, each no larger than min(nrow(counts), ncol(counts)); evaluated ascending.
replicates: single whole number >= 2: ensemble fits per rank feeding the consensus stability.
k_folds: single whole number in [2, nrow(counts)]: SUITOR folds over the held-out cells.
n_seeds: single whole number >= 1: best-of-n fits per fold.
cv: single logical: run layer 1? FALSE demotes the CV columns to NA and arbitrates on the stability veto alone.
seed: single whole number >= 0: the root seed of every derived stream in the survey.

Value

A named list with k (the selected rank, single positive integer) and k_evidence (the full-surface evidence table, one row per grid rank, column order is the contractual .BP_K_EVIDENCE_COLUMNS). An undecidable grid (no rank passes the veto) raises with the undecidable diagnosis – the pipeline-integration analogue degrades instead (see bp_extract_signatures(k_select = "arbitrate")).

Examples

# A planted two-signature catalogue (synthetic, deterministic): two
# blocks of channels with anti-phased sample loadings. The arbitration
# reads the planted K = 2 off the CV curve and the stability veto.
m <- matrix(1, 60, 20,
  dimnames = list(paste0("ch", 1:60), paste0("smp", 1:20)))
m[1:6, 1:10] <- 40
m[31:36, 11:20] <- 40
m[31:36, 1:10] <- 8
m[1:6, 11:20] <- 8
res <- bp_select_k(m, k_grid = 2:3, seed = 7L)
if (!identical(res$k, 2L)) stop("the survey must arbitrate K = 2")
if (!is.data.frame(res$k_evidence) || !any(res$k_evidence$selected))
  stop("the evidence table must carry exactly one selected row")

Select the number of signatures for a channel-by-sample count matrix

Arguments

Value

See also

Examples