bp_select_k: Select the number of signatures for a channel-by-sample count...

In sigminer: Extract, Analyze and Visualize Mutational Signatures for Genomic Variations

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

Description

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).

Usage

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")).

See Also

.bp_k_arbitrate() for the private arbitration core, bp_extract_signatures() for the opt-in route integration.

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.
# The budget arguments are reduced below the production defaults so the
# example stays within CRAN runtime limits; the seeded verdict is
# unchanged under the full default budget.
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,
  replicates = 2L, k_folds = 4L, n_seeds = 1L)
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")

sigminer documentation built on Oct. 21, 2026, 9:06 a.m.