sensitivity_grid: Sensitivity grid over prior hyperparameters

In bayprior: Bayesian Prior Elicitation and Diagnostics for Clinical Trials

Sensitivity grid over prior hyperparameters

Description

Evaluates how posterior inferences change as prior hyperparameters vary over a specified grid. This is the core function for demonstrating robustness of trial conclusions to prior choice.

Usage

sensitivity_grid(
  prior,
  data_summary,
  param_grid,
  target = c("posterior_mean", "posterior_sd", "prob_efficacy"),
  threshold = 0.3
)

Arguments

prior	A bayprior object (the reference prior).
data_summary	Named list as for prior_conflict.
param_grid	Named list of numeric vectors, one per hyperparameter to vary. Names must match hyperparameter names in prior$params. Example: list(alpha = seq(1, 8, 0.5), beta = seq(2, 20, 1)).
target	Character vector. Which posterior quantities to compute. Any of "posterior_mean", "posterior_sd", "prob_efficacy".
threshold	Numeric. Efficacy threshold used in Pr(theta > threshold). Default 0.30.

Details

The hyperparameter grid is defined over a single distribution family, so when prior is a mixture (e.g. from aggregate_experts or robust_prior), a single-family working prior is derived first, via the internal .mixture_working_prior() helper. As of this version, that working prior is obtained in two steps: first, the mixture's pooled mean and SD are computed exactly (see the mean/var formula in aggregate_experts); second, those pooled moments are matched to the dominant component's distribution family using that family's own moment-matching identities (see elicit_beta, elicit_normal, elicit_gamma, or elicit_lognormal for the specific formula used). The grid therefore reflects the full pooled information, not just one component. A message reports the working prior used. If the dominant component's family cannot be moment-matched from mean/SD alone ("exponential" or "weibull"), the function falls back to the dominant component by weight and issues an explicit warning identifying which component was used and why.

Value

An object of class bayprior_sensitivity.

Examples

prior <- elicit_beta(mean = 0.30, sd = 0.10, method = "moments",
                     label = "Response rate")
sa <- sensitivity_grid(
  prior,
  data_summary = list(type = "binary", x = 14, n = 40),
  param_grid   = list(alpha = seq(1, 8, 0.5), beta = seq(2, 20, 1))
)
plot_tornado(sa)
plot_sensitivity(sa, target = "posterior_mean")

bayprior documentation built on Aug. 27, 2026, 1:09 a.m.