Bootstrap percentile confidence intervals for signature exposures
Source:R/fit.R
ms_fit_bootstrap.Rd`ms_fit_bootstrap()` quantifies sampling uncertainty of the fitted exposures by **nonparametric (multinomial) bootstrap** (research/02 section 2 semantics): every replicate resamples each sample's mutations from its empirical channel distribution, refits the selected method, and the exposure distribution across replicates yields the 2.5 **percentile CI** and the **support stability** (the frequency with which the share-rule zeroing keeps each exposure). Parallelism runs between replicates only (per-call pool, contract 6); the output is a pure function of `(catalog, signatures, method, n_boot, seed)` and is bit-identical for every thread count. All violations raise `msuiter_error_*` conditions.
Usage
ms_fit_bootstrap(
catalog,
signatures,
method = "nnls",
n_boot = 200,
seed = 1,
nb_size = 8,
zero_threshold = 0.01,
n_threads = NULL,
bca = FALSE,
return_draws = FALSE
)Arguments
- catalog
An [MsCatalog] object, as returned by [ms_tally()] or [ms_catalog()].
- signatures
The dictionary to fit against: a numeric matrix (channels x signatures) or an [MsSignature], resolved exactly as in [ms_fit()].
- method
Single string: the fitting method reused for every replicate (`"nnls"` default, `"likelihood_bidirectional"` or `"lrt"`; see [ms_fit()]).
- n_boot
Single positive whole number: the number of bootstrap replicates (default 200, the signature.tools.lib `nboot` family anchor). sigminer's serial budget is cleared by >= 100x on the Rust per-call pool (CAPABILITY-MATRIX L-D).
- seed
Single non-negative whole number: the master seed addressing the per-boot canonical PCG64 streams (boot `b` draws on
StreamId{replicate: b, rank: 0, fold: 0}; per-sample resamples consume the boot's stream sequentially in fixed sample order). Same seed, same output – bit-identically.- nb_size, zero_threshold
As in [ms_fit()].
- n_threads
NULL (resolve the `msuiter.threads` option, capped by `_R_CHECK_LIMIT_CORES_`) or a single non-negative integer pool size; 0 means the rayon default.
- bca
Single logical (default `FALSE`): additionally compute the **BCa interval** (bias-corrected and accelerated; Hall 1988) from the SAME replicates – zero extra resampling. `z0 = Phi^{-1}(#{boot < point}/B)` corrects median bias and the acceleration comes from the fixed-active-set analytic jackknife (one LDL^T per sample, not a per-mutation refit). Cells whose correction is below the MC noise of the bounds (`|z0| < 0.1` and `|a| < 0.05`), past the acceleration cap (`|a| > 0.2`), below the stability floor (`< 0.9`), or at the zeroing boundary fall back to the percentile interval with an explicit flag. When `TRUE`, the exposures carry `bca_lower`, `bca_upper`, `bca_fallback` (labelled matrices; fallback = 1) and `ci_method = "bca"` attributes, and the support table gains a `bca_fallback` column. The percentile attributes are unchanged.
- return_draws
Single logical (default `FALSE`): attach the RAW boot exposure cube as attribute `boot_draws` ([signature, sample, boot]; post-zeroing/post-rescale) for the histogram face [plot_boot_distribution()].
Details
**Result.** An [MsFit] whose point exposures/tests are one ordinary [ms_fit()] run of the selected method, enriched with the bootstrap evidence: the exposures matrix carries `ci_lower`, `ci_upper`, `support_stability` (each a labelled signatures x samples matrix), `n_boot`, `seed` and `ci_level` attributes, and the `support` table gains the `boot_stability` column. The percentile bounds are computed kernel-side with type-7 linear interpolation (the R `quantile` default) over the post-zeroing replicate exposures, each replicate rescaled onto its sample's original mutation total by the same rule as the point fit's `rescale = TRUE` (the divisor is the replicate's exposure column sum), so the CI is directly comparable to the point exposures.