Package 'gibbsTI'

Title: Calibrated Gibbs Posteriors for Tolerance Intervals
Description: Provides tools for constructing one-sided and two-sided nonparametric tolerance intervals using calibrated Gibbs posteriors. The methods target population quantiles and content levels while achieving nominal frequentist coverage through data-driven calibration. The methodology is described in Pourmohamad, Richardson, and Sansó (2026) <doi:10.1080/00401706.2026.2699103>.
Authors: Tony Pourmohamad [aut, cre], Robert Richardson [aut], Bruno Sansó [aut]
Maintainer: Tony Pourmohamad <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-07-22 10:51:11 UTC
Source: https://github.com/cran/gibbsTI

Help Index

Fit a Gibbs Posterior Tolerance Interval

Description

Constructs a one-sided or two-sided nonparametric tolerance interval from a calibrated Gibbs posterior. The learning rate eta is chosen automatically by Gibbs posterior calibration (GPC) so that the interval attains the nominal frequentist coverage, or it can be fixed by the user.

Usage

gibbsTI(
  x,
  side = c("one", "two"),
  type = c("upper", "lower"),
  target = c("content", "quantile"),
  content = 0.95,
  confidence = 0.9,
  tau = NULL,
  tau_lower = NULL,
  tau_upper = NULL,
  eta_method = c("GPC", "fixed"),
  eta = NULL,
  max_iter = 15,
  control = list(),
  n_mcmc = 5000,
  burnin = 1000,
  thin = 1,
  seed = NULL,
  verbose = TRUE
)

Arguments

x

Numeric vector of observations (at least 5, all finite).
side

Direction of the interval: "one" (one-sided) or "two" (two-sided, centered).
type

For one-sided intervals only, "upper" (bound above) or "lower" (bound below). Ignored when side = "two".
target

Calibration target: "content" (default; the interval is defined by a population proportion) or "quantile" (the interval targets explicit population quantiles supplied through tau, tau_lower, tau_upper).
content

Population proportion the interval should contain, in (0, 1) (e.g. 0.95). Used when target = "content"; when target = "quantile" it only supplies defaults for any unset ⁠tau_*⁠ argument.
confidence

Frequentist confidence level in (0, 1) (e.g. 0.90). This is both the GPC coverage target (1 - alpha) and the posterior level read off as the reported limit.
tau

Target quantile for a one-sided "quantile" interval, in (0, 1). Only used when target = "quantile"; ignored when target = "content".
tau_lower, tau_upper

Lower/upper target quantiles for a two-sided "quantile" interval, in (0, 1) with tau_lower < tau_upper. Only used when target = "quantile"; ignored when target = "content".
eta_method

How the Gibbs learning rate eta is chosen: "GPC" (default; data-driven calibration) or "fixed" (use the supplied eta).
eta

Gibbs learning rate (positive). Optional starting value when eta_method = "GPC" (defaults to 1); required when eta_method = "fixed".
max_iter

Maximum number of Robbins-Monro iterations for the GPC search (default 15). Only used when eta_method = "GPC".
control

A list of control parameters for the MCMC samplers and GPC:

  • B: Number of bootstrap replicates for calibration (default 200).

  • tol: Convergence tolerance for eta (default 1e-3).

  • c, gamma: Step-size parameters for Robbins-Monro (defaults 0.5, 0.75).

  • w, m: Slice sampler width and max steps for one-sided intervals.

  • prop_sd: Proposal standard deviation for Metropolis-Hastings in the two-sided case.

  • n_samps_calib: MCMC samples used per bootstrap during calibration (default 1000).

  • burnin_calib: Burn-in used per bootstrap during calibration (default 200).

n_mcmc

Number of posterior draws retained for the final interval, after burn-in and thinning (default 5000).
burnin

Number of initial iterations discarded as burn-in (default 1000).
thin

Thinning interval: every thin-th post-burn-in draw is kept (default 1).
seed

Optional integer random seed for reproducibility.
verbose

Logical; if TRUE, prints progress messages.

Value

An object of class "gibbsTI": a list with the fitted interval (a numeric limit for one-sided fits, or a list with lower and upper for two-sided fits), the calibrated eta, the retained posterior samples, the data, the quantile level(s) tau_used, calibration diagnostics (calibrated_coverage, eta_history), and the settings used. Use print(), summary(), and plot() on the result.

Examples

set.seed(1)
x <- rnorm(50)

# Fast: fix the learning rate (no calibration search)
fit <- gibbsTI(x, side = "one", type = "upper", eta_method = "fixed",
               eta = 1, n_mcmc = 500, burnin = 200, verbose = FALSE)
print(fit)


# Data-driven GPC calibration (slower) for a two-sided 95%/90% interval
fit2 <- gibbsTI(x, side = "two", content = 0.95, confidence = 0.90,
                seed = 1, verbose = FALSE)
summary(fit2)