Monte Carlo calibration grid for exposure confidence intervals
Source:R/calibrate.R
ms_calibration_grid.Rd`ms_calibration_grid()` measures the **empirical coverage** of the [ms_fit_bootstrap()] confidence intervals over a grid of catalog sizes and true signature shares – the M3b calibration experiment behind the MSU-Fit estimand-(2) declaration (design memo vignettes/articles/devlog-2026-10-04-M3b-design-memo.qmd, sections 1-3, PI ruling 2026-10-04). Per grid cell (one catalog size N x one true share) the kernel draws `m` synthetic replicates from the selected generative arm, fits each with the production face (`"likelihood_bidirectional"`, share zeroing at 0.01, TMB rescale) and tallies whether the true exposure lies inside the selected CI face over every truth-supported signature (the marginal coverage event), plus the compound-zeroing confusion tallies (estimand 3).
Usage
ms_calibration_grid(
sigs,
n_grid,
shares,
m = 2000,
n_boot = 1000,
bca = FALSE,
n_threads = NULL,
seed = 1,
n_samples = 1,
nb_size = 8,
arm = "multinomial",
window = .MS_CALIBRATION_WINDOW
)Arguments
- sigs
Numeric matrix (channels x signatures): the truth dictionary of ONE entropy arm of the memo's N x H* x share grid (the entropy axis is a separate call per truth dictionary). Columns must be non-negative with positive mass; the channel count is arbitrary (the kernel normalizes the truth spectrum internally, memo section 2.1).
- n_grid
Increasing vector of positive whole numbers: the swept catalog-size (mutation burden N) axis, e.g. the memo's 11 log points `c(50, 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000)`.
Numeric vector in \([0, 1]\): the swept TRUE share of the target signature (dictionary column 1; the residual mass splits equally over the remaining columns, last entry taking the exact remainder – the kernel's frozen truth convention). Share 0 makes the target a decoy (the estimand-(3) FPR cell).
- m
Single positive whole number: Monte Carlo replicates per grid cell (the memo's M; the frozen bench protocol is `m = 2000`, which derives the default 4SE acceptance window).
- n_boot
Single positive whole number: bootstrap replicates inside every Monte Carlo fit (frozen protocol: 1000).
- bca
Single logical (default `FALSE`): read the BCa face instead of the percentile face for the coverage event (the PI-ruled default interval family; `bca = FALSE` reads the plain percentile bounds).
- 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. Parallelism runs BETWEEN (cell x replicate) units only; the output is bit-identical for every thread count.
- seed
Single non-negative whole number: the master seed of the canonical PCG64 stream layout (the grid is a bitwise function of it; memo section 2.1 stream layout).
- n_samples
Single positive whole number (default 1): synthetic catalog columns per replicate (the memo protocol is one synthetic sample per replicate).
- nb_size
Single positive number: the negative-binomial size of the fit face (mSigAct `nbinom.size`; default 8, the SBS96 anchor). Only used by the likelihood methods internally; see [ms_fit()].
- arm
Single string: the generative model – `"multinomial"` (default; the total-conserving MAIN arm, the calibration-declaration carrier), `"poisson"` (the exact negative- binomial limit) or `"nb:<size>"` (the Jiang per-channel overdispersion stress arm, e.g. `"nb:8"` at the mSigAct kappa anchor). The two arm families must never be mixed into one calibration claim (memo section 2.2).
- window
Numeric `c(lo, hi)`: the inclusive acceptance band of the verdict (default `c(0.930, 0.970)`, the frozen 4SE window at `m = 2000`).
Details
**Truth convention (frozen).** Grid cell `c = n_idx * length(shares) + share_idx` (1-based in the returned table) draws its truth spectrum as: signature 1 carries `share * N`; the residual `N - share * N` splits equally over signatures 2..k (the last entry takes the exact remainder), so the spectrum sums to N exactly in double arithmetic. A `k = 1` dictionary degenerates to the single signature carrying the whole catalog.
**Determinism.** The output is a pure function of the inputs: `threads 1` and `N` are bit-identical, and the same `seed` reproduces the table bitwise. MC streams live on `StreamId{replicate, rank: cell_id, fold: 0}` – disjoint from the bootstrap (`rank = 0`) and CV (`fold >= 1`) bands.
**Result.** A data.frame with one row per grid cell (n_grid-major x shares order): `n` (catalog size), `share` (true share), `cell` (1-based cell id), `mean_coverage` (pooled marginal coverage fraction), `se` (binomial standard error at the observed fraction), `n_reps` (replicates aggregated), `pass_window` (kernel-side window membership), and the confusion tallies `true_zero` / `false_keep` / `false_zero` / `kept_covered` / `kept_missed` (estimand 3, memo section 3). Attributes carry the protocol echoes (`window`, `arm`, `bca`, `n_boot`, `seed`, `n_samples`, `nb_size`). Feed the table to [ms_calibration_verdict()] for the structured verdict and to [plot_calibration_curve()] for the coverage-vs-N curve.
All violations raise `msuiter_error_*` conditions.