Weight sensitivity analysis

sensitivity_analysis() perturbs the resolved scoring weights using a Dirichlet distribution and reports how often the verdict or enzyme ranking changes. It compares each perturbation with the stored reference score and applies the scoring hard-fail rule consistently.

Usage

sensitivity_analysis(
  x,
  nu = 63,
  n_iter = 2000L,
  chunk_size = 100L,
  importance = FALSE,
  corner_cases = FALSE
)

Arguments

x: An evaluate_digest(), compare_digests(), batch_evaluate(), or batch_compare_enzymes() result.
nu: Dirichlet concentration scaling factor. Controls how much the perturbed weights are allowed to vary from the resolved reference weights. Must be at least 0.1. Default 63 gives a standard deviation of approximately 0.05 for a weight of 0.2. Larger values produce tighter distributions. Smaller values allow more variation.
n_iter: Number of Monte Carlo iterations. Default 2000L.
chunk_size: Number of score rows to process per chunk in batch mode. Default 100L bounds the largest score-by-iteration matrix.
importance: Logical. If TRUE, compute the squared Pearson correlation between each sampled weight and the composite score across iterations. These marginal associations are descriptive, can reflect dependence among Dirichlet weights, and do not form a variance decomposition.
corner_cases: Logical. If TRUE, report the composite score when each weight is at its exact 95 percent marginal Dirichlet interval bound. Other weights retain their reference proportions. Corner diagnostics are available for single-protein and multi-enzyme inputs, not batch inputs.

Value

A mode-dependent list:

Single-protein output contains iterations, convergence, summary, and settings. iterations contains sampled weights, iteration, composite_score, and verdict. convergence contains iteration, cumulative_stability, and mc_se. summary contains verdict_pct, composite_ci, composite_mean, reference_composite, reference_weights, reference_verdict, and requested diagnostics.
Multi-enzyme output contains summary and settings. summary contains top1_stability, kendall_mean, kendall_defined_fraction, reference_composites, and requested per-enzyme diagnostics.
Batch output contains per_protein, summary, and settings. per_protein contains protein_id, reference_composite, verdict_instability, composite_mean, composite_lo, composite_hi, and remaining input columns. summary contains total_instability, mean_ci_width, ci_width_quantiles, reference_weights, and requested weight_importance.

Every settings list records distribution, nu, n_iter, applicable chunk_size, reference_weights, fixed_zero_weights, and verdict_thresholds.

Details

The function draws from the current R random-number generator and advances its state. It does not set or restore a seed. Callers control reproducibility outside the function.

Interpreting results

Monte Carlo estimates are approximate, and their precision depends on n_iter. Tied top scores share credit equally. Kendall correlation is undefined when the reference or sampled scores have only one rank.

Limitations

The analysis perturbs only weights within the Dirichlet framework. It does not test alternative scoring functions, verdict thresholds, or parameter ranges. The distribution is a package-chosen computational stress test, not an empirical uncertainty model. A reference weight of zero remains zero in every draw. Stability does not establish that a weight or verdict is biologically correct.

Examples

if (requireNamespace("withr", quietly = TRUE)) {
  bsa_path <- system.file("extdata", "P02769.fasta", package = "pepVet")
  res <- evaluate_digest(bsa_path, enzyme = "trypsin")
  sens <- withr::with_seed(
    42,
    sensitivity_analysis(res, n_iter = 1000L)
  )
  sens$summary$verdict_pct
}
#>     Good Moderate     Poor 
#>        1        0        0