Skip to contents

Bayesian Posterior or Posterior Predictive Probability for a Single Continuous Endpoint

Source: R/pbayespostpred1cont.R
pbayespostpred1cont.Rd

Computes the Bayesian posterior probability or posterior predictive probability for continuous-outcome clinical trials under a Normal-Inverse-Chi-squared (or vague Jeffreys) conjugate model. The function supports controlled, uncontrolled, and external designs, with optional incorporation of external data through power priors. Vector inputs for bar_y_t, s_t, bar_y_c, and s_c are supported for efficient batch processing (e.g., across simulation replicates in pbayesdecisionprob1cont).

Usage

pbayespostpred1cont(
  prob = "posterior",
  design = "controlled",
  prior = "vague",
  CalcMethod = "NI",
  theta0,
  nMC = NULL,
  n_t,
  n_c = NULL,
  m_t = NULL,
  m_c = NULL,
  kappa0_t = NULL,
  kappa0_c = NULL,
  nu0_t = NULL,
  nu0_c = NULL,
  mu0_t = NULL,
  mu0_c = NULL,
  sigma0_t = NULL,
  sigma0_c = NULL,
  bar_y_t,
  bar_y_c = NULL,
  s_t,
  s_c = NULL,
  r = NULL,
  ne_t = NULL,
  ne_c = NULL,
  alpha0e_t = NULL,
  alpha0e_c = NULL,
  bar_ye_t = NULL,
  bar_ye_c = NULL,
  se_t = NULL,
  se_c = NULL,
  lower.tail = TRUE
)

Arguments

prob

A character string specifying the probability type. Must be 'posterior' or 'predictive'.

design

A character string specifying the trial design. Must be 'controlled', 'uncontrolled', or 'external'.

prior

A character string specifying the prior type. Must be 'vague' (Jeffreys) or 'N-Inv-Chisq' (Normal-Inverse-Chi-squared conjugate).

CalcMethod

A character string specifying the calculation method. Must be 'NI' (numerical integration), 'MC' (Monte Carlo), or 'MM' (Moment-Matching approximation). For large nsim or multi-scenario use, 'MM' is strongly recommended; see Details.

theta0

A numeric scalar giving the threshold for the treatment effect (difference in means).

nMC

A positive integer giving the number of Monte Carlo draws. Required when CalcMethod = 'MC'; otherwise NULL.

n_t

A positive integer giving the number of patients in the treatment group in the proof-of-concept (PoC) trial.

n_c

A positive integer giving the number of patients in the control group in the PoC trial. Required for design = 'controlled' or 'external'; set to NULL for design = 'uncontrolled'.

m_t

A positive integer giving the number of patients in the treatment group for the future trial. Required when prob = 'predictive'; otherwise set to NULL.

m_c

A positive integer giving the number of patients in the control group for the future trial. Required when prob = 'predictive'; otherwise set to NULL.

kappa0_t

A positive numeric scalar giving the prior precision parameter for the treatment group. Required when prior = 'N-Inv-Chisq'; otherwise NULL.

kappa0_c

A positive numeric scalar giving the prior precision parameter for the control group. Required when prior = 'N-Inv-Chisq' and design = 'controlled'; otherwise NULL.

nu0_t

A positive numeric scalar giving the prior degrees of freedom for the treatment group. Required when prior = 'N-Inv-Chisq'; otherwise NULL.

nu0_c

A positive numeric scalar giving the prior degrees of freedom for the control group. Required when prior = 'N-Inv-Chisq' and design = 'controlled'; otherwise NULL.

mu0_t

A numeric scalar giving the prior mean for the treatment group. Required when prior = 'N-Inv-Chisq'; otherwise NULL.

mu0_c

A numeric scalar giving the prior mean for the control group (design = 'controlled' with prior = 'N-Inv-Chisq') or the hypothetical control mean (design = 'uncontrolled'). Required for uncontrolled design; otherwise NULL.

sigma0_t

A positive numeric scalar giving the prior scale for the treatment group. Required when prior = 'N-Inv-Chisq'; otherwise NULL.

sigma0_c

A positive numeric scalar giving the prior scale for the control group. Required when prior = 'N-Inv-Chisq' and design = 'controlled'; otherwise NULL.

bar_y_t

A numeric scalar or vector giving the sample mean for the treatment group. When a vector of length nsim is supplied, all posterior parameters are computed simultaneously for all replicates.

bar_y_c

A numeric scalar or vector giving the sample mean for the control group. Required for design = 'controlled' or 'external'; set to NULL for uncontrolled design.

s_t

A positive numeric scalar or vector giving the sample standard deviation for the treatment group.

s_c

A positive numeric scalar or vector giving the sample standard deviation for the control group. Required for design = 'controlled' or 'external'; otherwise NULL.

r

A positive numeric scalar giving the variance scaling factor for the hypothetical control. Required for design = 'uncontrolled'; otherwise NULL. The hypothetical control scale is \(\mathrm{sd.control} = \sqrt{r} \cdot \mathrm{sd.treatment}\).

ne_t

A positive integer giving the number of patients in the treatment group of the external data set. Required when design = 'external' and external treatment data are available; otherwise set to NULL.

ne_c

A positive integer giving the number of patients in the control group of the external data set. Required when design = 'external' and external control data are available; otherwise set to NULL.

alpha0e_t

A numeric scalar in (0, 1] giving the power prior weight for the external treatment data. Required when external treatment data are used; otherwise set to NULL.

alpha0e_c

A numeric scalar in (0, 1] giving the power prior weight for the external control data. Required when external control data are used; otherwise set to NULL.

bar_ye_t

A numeric scalar giving the external treatment group sample mean. Required when ne_t is provided; otherwise NULL.

bar_ye_c

A numeric scalar giving the external control group sample mean. Required when ne_c is provided; otherwise NULL.

se_t

A positive numeric scalar giving the external treatment group sample SD. Required when ne_t is provided; otherwise NULL.

se_c

A positive numeric scalar giving the external control group sample SD. Required when ne_c is provided; otherwise NULL.

lower.tail

A logical scalar; if TRUE (default), the function returns \(P(\mathrm{effect} \le \theta_0)\), otherwise \(P(\mathrm{effect} > \theta_0)\).

Value

A numeric scalar or vector in [0, 1]. When the input data parameters (bar_y_t, etc.) are vectors of length \(n\), a vector of length \(n\) is returned.

Details

Under the Normal-Inverse-Chi-squared (N-Inv-ChiSq) conjugate model, the marginal posterior/predictive distribution of the group mean follows a non-standardised t-distribution, parameterised by a location \(\mu_j\), a scale \(\sigma_j\), and degrees of freedom \(\nu_j\) that depend on the design and probability type. The final probability is computed by one of three methods:

  • NI: exact numerical integration via ptdiff_NI.

  • MC: Monte Carlo simulation via ptdiff_MC.

  • MM: Moment-Matching approximation via ptdiff_MM.

Performance note: CalcMethod = 'NI' calls integrate() once per element of the input vector, which is prohibitively slow for large vectors (e.g., nsim x n_scenarios). CalcMethod = 'MC' creates an nMC x n matrix internally, consuming \(O(nMC \cdot n)\) memory. For large-scale simulation use CalcMethod = 'MM', which is fully vectorised and exact in the normal limit.

Examples

# Example 1: Controlled design - posterior probability with N-Inv-Chisq
pbayespostpred1cont(
  prob = 'posterior', design = 'controlled', prior = 'N-Inv-Chisq',
  CalcMethod = 'NI', theta0 = 2, n_t = 12, n_c = 12,
  kappa0_t = 5, kappa0_c = 5, nu0_t = 5, nu0_c = 5,
  mu0_t = 5, mu0_c = 5, sigma0_t = sqrt(5), sigma0_c = sqrt(5),
  bar_y_t = 2, bar_y_c = 0, s_t = 1, s_c = 1,
  m_t = NULL, m_c = NULL, r = NULL,
  ne_t = NULL, ne_c = NULL, alpha0e_t = NULL, alpha0e_c = NULL,
  bar_ye_t = NULL, bar_ye_c = NULL, se_t = NULL, se_c = NULL,
  lower.tail = FALSE
)
#> [1] 0.2438672

# Example 2: Uncontrolled design - posterior probability with vague prior
pbayespostpred1cont(
  prob = 'posterior', design = 'uncontrolled', prior = 'vague',
  CalcMethod = 'MM', theta0 = 1.5, n_t = 15, n_c = NULL,
  bar_y_t = 3.5, bar_y_c = NULL, s_t = 1.2, s_c = NULL,
  mu0_c = 1.5, r = 1.2,
  kappa0_t = NULL, kappa0_c = NULL, nu0_t = NULL, nu0_c = NULL,
  mu0_t = NULL, sigma0_t = NULL, sigma0_c = NULL,
  m_t = NULL, m_c = NULL,
  ne_t = NULL, ne_c = NULL, alpha0e_t = NULL, alpha0e_c = NULL,
  bar_ye_t = NULL, bar_ye_c = NULL, se_t = NULL, se_c = NULL,
  lower.tail = FALSE
)
#> [1] 0.8484152

# Example 3: External design - posterior probability
pbayespostpred1cont(
  prob = 'posterior', design = 'external', prior = 'N-Inv-Chisq',
  CalcMethod = 'MM', theta0 = 2, n_t = 12, n_c = 12,
  kappa0_t = 5, kappa0_c = 5, nu0_t = 5, nu0_c = 5,
  mu0_t = 5, mu0_c = 5, sigma0_t = sqrt(5), sigma0_c = sqrt(5),
  bar_y_t = 2.5, bar_y_c = 1, s_t = 1.1, s_c = 0.9,
  m_t = NULL, m_c = NULL, r = NULL,
  ne_t = 10, ne_c = 10, alpha0e_t = 0.5, alpha0e_c = 0.5,
  bar_ye_t = 2, bar_ye_c = 0.5, se_t = 1, se_c = 0.8,
  lower.tail = FALSE
)
#> [1] 0.08934116

# Example 4: Controlled design - posterior predictive probability
pbayespostpred1cont(
  prob = 'predictive', design = 'controlled', prior = 'N-Inv-Chisq',
  CalcMethod = 'MM', theta0 = 1, n_t = 12, n_c = 12,
  kappa0_t = 5, kappa0_c = 5, nu0_t = 5, nu0_c = 5,
  mu0_t = 5, mu0_c = 5, sigma0_t = sqrt(5), sigma0_c = sqrt(5),
  bar_y_t = 2, bar_y_c = 0, s_t = 1, s_c = 1,
  m_t = 20, m_c = 20, r = NULL,
  ne_t = NULL, ne_c = NULL, alpha0e_t = NULL, alpha0e_c = NULL,
  bar_ye_t = NULL, bar_ye_c = NULL, se_t = NULL, se_c = NULL,
  lower.tail = FALSE
)
#> [1] 0.6961224

# Example 5: Uncontrolled design - posterior predictive probability
pbayespostpred1cont(
  prob = 'predictive', design = 'uncontrolled', prior = 'vague',
  CalcMethod = 'MM', theta0 = 1.5, n_t = 15, n_c = NULL,
  bar_y_t = 3.5, bar_y_c = NULL, s_t = 1.2, s_c = NULL,
  mu0_c = 1.5, r = 1.2,
  kappa0_t = NULL, kappa0_c = NULL, nu0_t = NULL, nu0_c = NULL,
  mu0_t = NULL, sigma0_t = NULL, sigma0_c = NULL,
  m_t = 20, m_c = 20,
  ne_t = NULL, ne_c = NULL, alpha0e_t = NULL, alpha0e_c = NULL,
  bar_ye_t = NULL, bar_ye_c = NULL, se_t = NULL, se_c = NULL,
  lower.tail = FALSE
)
#> [1] 0.8745171

# Example 6: External design - posterior predictive probability
pbayespostpred1cont(
  prob = 'predictive', design = 'external', prior = 'N-Inv-Chisq',
  CalcMethod = 'MM', theta0 = 1, n_t = 12, n_c = 12,
  kappa0_t = 5, kappa0_c = 5, nu0_t = 5, nu0_c = 5,
  mu0_t = 5, mu0_c = 5, sigma0_t = sqrt(5), sigma0_c = sqrt(5),
  bar_y_t = 2.5, bar_y_c = 1, s_t = 1.1, s_c = 0.9,
  m_t = 20, m_c = 20, r = NULL,
  ne_t = 10, ne_c = 10, alpha0e_t = 0.5, alpha0e_c = 0.5,
  bar_ye_t = 2, bar_ye_c = 0.5, se_t = 1, se_c = 0.8,
  lower.tail = FALSE
)
#> [1] 0.594831