Package 'ciCalibrate'

Calibrate confidence intervals to support intervals

Description

This function computes a support interval for an unknown parameter based on either a confidence interval for the parameter or a parameter estimate with standard error.

Usage

ciCalibrate(
  ci = NULL,
  ciLevel = 0.95,
  estimate = mean(ci),
  se = diff(ci) * 0.5/stats::qnorm(p = 0.5 * (1 + ciLevel)),
  siLevel = 1,
  method = c("SI-normal", "SI-normal-local", "SI-normal-nonlocal", "mSI-all",
    "mSI-normal-local", "mSI-eplogp"),
  priorMean,
  priorSD
)

Arguments

ci	Confidence interval given as a numeric vector of length two.
ciLevel	Confidence level. Defaults to 0.95.
estimate	Parameter estimate. Only required if no confidence interval and confidence level are specified.
se	Standard error of the parameter estimate. Only required if no confidence interval and confidence level are specified.
siLevel	Support level. Defaults to 1.
method	Calibration method. Can either be "SI-normal", "SI-normal-local", "SI-normal-nonlocal", "mSI-all", "mSI-normal-local", or "mSI-eplogp". Defaults to "SI-normal". See details for more information.
priorMean	Prior mean, only required for "SI-normal".
priorSD	Prior standard deviation / spread, only required for "SI-normal", "SI-normal-local", "SI-normal-nonlocal".

Details

A support interval with support level $k$ is defined by the parameter values $\theta_0$ for which the Bayes factor contrasting $H_0\colon \theta = \theta_0$ to $H_1\colon \theta \neq \theta_0$ is larger or equal than $k$, i.e., the parameter values for which the data are at least $k$ times more likely than under the alternative. Different prior distributions for the parameter $\theta$ under the alternative $H_1$ are available:

• method = "SI-normal": a normal prior centered around priorMean with standard deviation priorSD, i.e., $\theta \,|\, H_1 \sim N(\code{priorMean}, \code{priorSD}^2)$

• method = "SI-normal-local": a local normal prior with standard deviation priorSD, i.e., $\theta \,|\, H_1 \sim N(\theta_0, \code{priorSD}^2)$

• method = "SI-normal-nonlocal": a nonlocal normal moment prior with spread parameter priorSD, i.e., a prior with density $f(\theta \,|\, H_1) = N(\theta \,|\, \theta_0, \code{priorSD}^2) \times (\theta - \theta_0)^2/\code{priorSD}^2$

The function also allows to compute minimum support intervals which require to only specify a class of priors for the parameter under the alternative and then compute the minimum Bayes factor over the class of alternatives. The following classes of prior distribution are available:

• method = "mSI-all": the class of all prior distributions under the alternative, this leads to the narrowest support interval possible

• method = "mSI-normal-local": the class of local normal prior distributions under the alternative, i.e., $\theta \,|\, H_1 \sim N(\theta_0, v)$ with $v \geq 0$

• method = "mSI-eplogp": the class of monotonically decreasing beta prior distributions on the p-value of the data $p = 2(1 - \Phi(|\code{estimate} - \theta_0|/\code{se}))$, i.e. $p \,|\, H_1 \sim \mbox{Be}(\xi, 1)$ with $\xi \geq 1$

Value

Returns an object of class "supInt" which is a list containing:

si	The computed support interval.
bfFun	The computed Bayes factor function.
estimate	The specified parameter estimate.
se	The specified standard error.
siLevel	The specified support level.
ciLevel	The specified confidence level.
priorParams	The specified prior parameters.

Author(s)

Samuel Pawel

References

Pawel, S., Ly, A., and Wagenmakers, E.-J. (2023). Evidential Calibration of Confidence Intervals. The American Statistician. doi:10.1080/00031305.2023.2216239

Wagenmakers, E.-J., Gronau, Q. F., Dablander, F., and Etz, A. (2020). The support interval. Erkenntnis. doi:10.1007/s10670-019-00209-z

Examples

## confidence interval of hazard ratio needs to be transformed to log-scale
ciHR <- c(0.75, 0.93)
ci <- log(ciHR)

## normal prior under the alternative hypothesis H1
m <- log(0.8) # prior mean
s <- 2 # prior sd

## compute 10 support interval
si <- ciCalibrate(ci = ci, method = "SI-normal", priorMean = m,
                  priorSD = s, siLevel = 10)
si # on logHR scale
exp(si$si) # on HR scale

## plot Bayes factor function and support interval
plot(si)

## minimum support interval based on local normal priors
msi <- ciCalibrate(ci = ci, method = "mSI-normal-local")
plot(msi)

---

Plot method for class "supInt"

Description

Plots Bayes factor function and support interval at the specified support level.

Usage

## S3 method for class 'supInt'
plot(x, xlim = x$estimate + c(-1, 1) * 3 * x$se, ...)

Arguments

x	Object of class "supInt"
xlim	Limits of x-axis
...	Other arguments passed to plot

Value

Generates a plot of the Bayes factor function with support interval

Author(s)

Samuel Pawel

Examples

## compute 3 support interval
si3 <- ciCalibrate(ci = c(0.3, 1.5), method = "SI-normal", priorMean = 0,
                   priorSD = 2, siLevel = 3)

## plot Bayes factor function and support interval
plot(si3, xlim = c(0, 1.75))

---

Print method for class "supInt"

Description

Prints parameter estimate, confidence interval, and support interval.

Usage

## S3 method for class 'supInt'
print(x, ...)

Arguments

x	Object of class "supInt"
...	Other arguments (for consistency with the generic)

Value

Prints text summary in the console and invisibly returns the "supInt" object

Author(s)

Samuel Pawel

Examples

## compute and print 5 support interval
si5 <- ciCalibrate(ci = c(-2, -0.5), method = "SI-normal", priorMean = -0.3,
                   priorSD = 2, siLevel = 5)
print(si5)

---