bayprior

bayprior logo

CRAN status R CMD check codecov Live app

Overview

bayprior is an advanced interactive R package and Shiny application designed for biostatisticians and clinical researchers to implement Bayesian Prior Elicitation, Conflict Diagnostics, and Sensitivity Analysis for clinical trials.

bayprior focuses on a specific stage of the Bayesian trial workflow: how do you construct, validate, and justify your prior to a regulator? This complements the existing R ecosystem for Bayesian trial design and historical-data borrowing by bringing structured elicitation, prior-data conflict diagnostics, and regulatory report generation together in one integrated workflow. The FDA’s 2026 draft guidance on Bayesian methods makes this a growing area of focus.

bayprior enables users to:

  • Elicit structured priors — SHELF-style quantile matching, moment matching, and the interactive roulette method across Beta, Normal, Gamma, Log-Normal, Exponential, and Weibull families.
  • Aggregate expert opinions — Linear or logarithmic pooling of multiple expert priors with pairwise Bhattacharyya agreement diagnostics and cross-family compatibility validation.
  • Diagnose prior-data conflict — Box’s p-value, surprise index, Bhattacharyya overlap, and multivariate Mahalanobis distance, supporting binary, continuous, Poisson/count, and survival data types.
  • Quantify sensitivity — Posterior conclusions evaluated across hyperparameter grids via tornado plots and influence heatmaps, with independent data entry.
  • Build robust priors — Sceptical, robust mixture, and calibrated power priors for regulatory sensitivity analyses.
  • Generate regulatory reports — Self-contained HTML, PDF, or Word (.docx) prior justification reports rendered via Quarto.

Features and Modules

Module Detail Primary Output Goal
Prior Elicitation Quantile matching, moment matching, SHELF roulette for Beta / Normal / Gamma / Log-Normal / Exponential / Weibull Fitted density plot + parameter table Structured expert prior elicitation
Expert Pooling Linear and logarithmic opinion pooling with support compatibility validation Consensus density overlay + Bhattacharyya matrix Aggregate multi-expert beliefs
Conflict Diagnostics Box p-value, surprise index, KL divergence, Bhattacharyya overlap; binary, continuous, Poisson, and survival data Prior-Likelihood-Posterior overlay Detect prior misspecification
Mahalanobis Check Two-endpoint multivariate conflict test Chi-sq p-value + per-parameter z-scores Co-primary endpoint trials
Sensitivity Analysis Hyperparameter grid over posterior mean, SD, CrI width, Pr(efficacy); independent data entry Tornado plot + influence heatmap Demonstrate robustness to regulators
Sceptical Prior Spiegelhalter-Freedman centred-at-null prior Prior density + summary statistics Conservative regulatory sensitivity
Robust Mixture Schmidli et al. MAP robust mixture prior Robust vs informative density overlay Protection against misspecification
Power Prior Ibrahim-Chen calibrated borrowing weight via Bayes Factor Calibration curves + optimal delta Principled historical data borrowing
Export Report HTML / PDF / Word (.docx) prior justification document via Quarto Regulatory-ready self-contained report Submission documentation

Core Methodology

Prior Elicitation

Three structured elicitation approaches are implemented. Quantile matching fits a parametric distribution to expert-specified probability-value pairs via numerical optimisation. Moment matching derives hyperparameters analytically from an expert-supplied mean and SD. The SHELF roulette method (Oakley & O’Hagan, 2010) lets the expert allocate chips across histogram bins, fitting a parametric family to the chip allocation in real time.

All three methods support six distribution families:

Family Support Typical use
Beta (0, 1) Response rates, proportions
Normal (-Inf, Inf) Mean differences, log odds ratios
Gamma (0, Inf) Event rates, variances, survival times
Log-Normal (0, Inf) Hazard ratios, PK parameters
Exponential (0, Inf) Constant hazard rates, Poisson rate priors
Weibull (0, Inf) Non-constant hazard survival times (OS, PFS)

Prior-Data Conflict Diagnostics

Conflict detection follows Box (1980). Four complementary metrics are computed:

  • Prior predictive p-value — tests whether observed data is plausible under the prior predictive distribution.
  • Surprise index — standardised distance between prior mean and observed data.
  • Bhattacharyya overlap — distributional overlap between prior and normalised likelihood.
  • KL divergence — information-theoretic distance from prior to likelihood.

Four data types are supported:

Data type Conjugate update Typical endpoint
Binary (x events / n) Beta-Binomial Response rate, ORR
Continuous (mean, SD, n) Normal-Normal Mean difference
Poisson / count (events / exposure) Gamma-Poisson Adverse event rate
Survival (events / follow-up time) Gamma-Exponential Hazard rate, OS, PFS

Validation and Compatibility Checks

bayprior includes a comprehensive validation layer:

  • Prior-data compatibility — warns when a prior family is atypical for the selected data type.
  • Pooling compatibility — blocks pooling of distributions with incompatible supports; warns for same-support cross-family pooling.
  • Sensitivity compatibility — warns for single-parameter families and cross-family mixture grids.

Sensitivity Analysis

The sensitivity module is fully independent of conflict diagnostics — users can enter observed data directly without running conflict diagnostics first. Results are visualised as tornado plots and influence heatmaps. A dedicated sensitivity_cri() function tracks credible interval width specifically — a key regulatory quantity.

Robust and Power Priors

The robust mixture prior (Schmidli et al., 2014) mixes the informative prior with a vague Normal component. The sceptical prior (Spiegelhalter & Freedman, 1994) is centred at the null treatment effect. The power prior (Ibrahim & Chen, 2000) down-weights historical data by delta in (0, 1], calibrated to achieve a target Bayes Factor.

Installation

Type Source Command
Release CRAN install.packages("bayprior")
Development GitHub remotes::install_github("ndohpenngit/bayprior")

PDF reports require Quarto CLI and a LaTeX installation:

install.packages("tinytex")
tinytex::install_tinytex()

Quick Start

library(bayprior)

# Elicit a Beta prior
prior <- elicit_beta(mean = 0.35, sd = 0.10, method = "moments",
                     label = "Response rate", expert_id = "Expert_1")
plot(prior)

# Pool two experts
e1  <- elicit_beta(mean = 0.30, sd = 0.10, method = "moments", expert_id = "E1")
e2  <- elicit_beta(mean = 0.42, sd = 0.12, method = "moments", expert_id = "E2")
agg <- aggregate_experts(list(E1 = e1, E2 = e2), weights = c(0.6, 0.4))

# Conflict diagnostics
cd <- prior_conflict(prior, list(type = "binary", x = 18, n = 40))
print(cd)

# Sensitivity analysis
sa <- sensitivity_grid(
  prior,
  data_summary = list(type = "binary", x = 18, n = 40),
  param_grid   = list(alpha = seq(1, 8, 0.5), beta = seq(2, 20, 1)),
  target       = c("posterior_mean", "prob_efficacy"),
  threshold    = 0.30
)
plot_tornado(sa)

# Robust and sceptical priors
rob  <- robust_prior(prior, vague_weight = 0.20)
scep <- sceptical_prior(null_value = 0.20, family = "beta", strength = "moderate")

# Generate regulatory report
prior_report(
  prior           = prior,
  conflict        = cd,
  sensitivity     = sa,
  robust_prior    = rob,
  sceptical_prior = scep,
  output_format   = "html",
  trial_name      = "TRIAL-001",
  sponsor         = "Example Pharma Ltd",
  author          = "N.P., Biostatistician"
)

# Launch the Shiny app
run_app()

Vignettes

Vignette Covers
bayprior-introduction Full end-to-end workflow overview
prior-elicitation All six families and three elicitation methods
conflict-diagnostics All four data types; univariate and multivariate
sensitivity-analysis Grid sensitivity, tornado plots, CrI tracking
robust-priors Robust mixture, sceptical, and power priors
regulatory-reporting Report generation and compliance checklist 
browseVignettes("bayprior")

References

  • O’Hagan, A. et al. (2006). Uncertain Judgements: Eliciting Experts’ Probabilities. Wiley.
  • Box, G. E. P. (1980). Sampling and Bayes’ inference in scientific modelling and robustness. JRSS-A, 143, 383-430.
  • Oakley, J. E. & O’Hagan, A. (2010). SHELF: the Sheffield Elicitation Framework. University of Sheffield.
  • Schmidli, H. et al. (2014). Robust meta-analytic-predictive priors in clinical trials with historical control information. Biometrics, 70, 1023-1032.
  • Ibrahim, J. G. & Chen, M.-H. (2000). Power prior distributions for regression models. Statistical Science, 15, 46-60.
  • Spiegelhalter, D. J., Freedman, L. S. & Parmar, M. K. B. (1994). Bayesian approaches to randomized trials. JRSS-A, 157, 357-416.
  • U.S. Food and Drug Administration (2026). Use of Bayesian Methodology in Clinical Trials of Drug and Biological Products (Draft Guidance for Industry).