epi.betabuster: An R version of Wes Johnson and Chun-Lung Su's Betabuster

In epiR: Tools for the Analysis of Epidemiological Data

An R version of Wes Johnson and Chun-Lung Su's Betabuster

Description

A function to return shape1 and shape2 parameters for a beta distribution, based on expert elicitation.

Usage

epi.betabuster(mode, conf, imsure, x, conf.level = 0.95, max.shape1 = 100, 
   step = 0.001)

Arguments

mode	scalar, the mode of the variable of interest. Must be a number between 0 and 1.
conf	level of confidence (expressed on a 0 to 1 scale) that the true value of the variable of interest is greater or less than argument x.
imsure	a character string, if "greater than" you are making the statement that you are conf confident that the true value of the variable of interest is greater than x. If "less than" you are making the statement that you are conf confident that the true value of the variable of interest is less than x.
x	scalar, value of the variable of interest (see above).
conf.level	magnitude of the returned confidence interval for the estimated beta distribution. Must be a single number between 0 and 1.
max.shape1	scalar, maximum value of the shape1 parameter for the beta distribution.
step	scalar, step value for the shape1 parameter. See details.

Details

The beta distribution has two parameters: shape1 and shape2, corresponding to a and b in the original version of BetaBuster. If r equals the number of times an event has occurred after n trials, shape1 = (r + 1) and shape2 = (n - r + 1).

Take care when you're parameterising probability estimates that are at the extremes of the 0 to 1 bounds. If the returned shape1 parameter is equal to the value of max.shape1 (which, by default is 100) consider increasing the value of the max.shape1 argument. The epi.betabuster functions issues a warning if these conditions are met.

Value

A list containing the following:

shape1	the shape1 parameter for the estimated beta distribution.
shape2	the shape2 parameter for the estimated beta distribution.
mode	the mode of the estimated beta distribution.
mean	the mean of the estimated beta distribution.
median	the median of the estimated beta distribution.
lower	the lower bound of the confidence interval of the estimated beta distribution.
upper	the upper bound of the confidence interval of the estimated beta distribution.
variance	the variance of the estimated beta distribution.
exp	a statement of the arguments used for this instance of the function.

Author(s)

Simon Firestone (Melbourne Veterinary School, Faculty of Science, The University of Melbourne, Parkville Victoria 3010, Australia) with acknowledgements to Wes Johnson and Chun-Lung Su for the original standalone software.

References

Christensen R, Johnson W, Branscum A, Hanson TE (2010). Bayesian Ideas and Data Analysis: An Introduction for Scientists and Statisticians. Chapman and Hall, Boca Raton.

Su C-L, Johnson W (2014) Beta Buster. Software for obtaining parameters for the Beta distribution based on expert elicitation. URL: https://cadms.vetmed.ucdavis.edu/diagnostic/software.

Examples

## EXAMPLE 1:
## If a scientist is asked for their best guess for the diagnostic sensitivity
## of a particular test and the answer is 0.90, and if they are also willing 
## to assert that they are 80% certain that the sensitivity is greater than 
## 0.75, what are the shape1 and shape2 parameters for a beta distribution
## satisfying these constraints? 

rval.beta01 <- epi.betabuster(mode = 0.90, conf = 0.80, imsure = "greater than", 
   x = 0.75, conf.level = 0.95, max.shape1 = 100, step = 0.001)
rval.beta01$shape1; rval.beta01$shape2

## The shape1 and shape2 parameters for the beta distribution that satisfy the
## constraints listed above are 9.875 and 1.986, respectively.

## This beta distribution reflects the probability distribution obtained if 
## there were 9 successes, r:
r <- rval.beta01$shape1 - 1; r

## from 10 trials, n:
n <- rval.beta01$shape2 + rval.beta01$shape1 - 2; n

dat.df01 <- data.frame(x = seq(from = 0, to = 1, by = 0.001), 
   y = dbeta(x = seq(from = 0, to = 1,by = 0.001), 
   shape1 = rval.beta01$shape1, shape2 = rval.beta01$shape2))

## Density plot of the estimated beta distribution:

## Not run: 
library(ggplot2)

ggplot(data = dat.df01, aes(x = x, y = y)) +
  theme_bw() +
  geom_line() + 
  scale_x_continuous(name = "Test sensitivity") +
  scale_y_continuous(name = "Density")

## End(Not run)


## EXAMPLE 2:
## The most likely value of the specificity of a PCR for coxiellosis in 
## small ruminants is 1.00 and we're 97.5% certain that this estimate is 
## greater than 0.99. What are the shape1 and shape2 parameters for a beta 
## distribution satisfying these constraints?

epi.betabuster(mode = 1.00, conf = 0.975, imsure = "greater than", x = 0.99, 
   conf.level = 0.95, max.shape1 = 100, step = 0.001)

## The shape1 and shape2 parameters for the beta distribution that satisfy the
## constraints listed above are 100 and 1, respectively. epi.betabuster 
## issues a warning that the value of shape1 equals max.shape1. Increase
## max.shape1 to 500:

epi.betabuster(mode = 1.00, conf = 0.975, imsure = "greater than", x = 0.99, 
   conf.level = 0.95, max.shape1 = 500, step = 0.001)

## The shape1 and shape2 parameters for the beta distribution that satisfy the
## constraints listed above are 367.04 and 1, respectively.

epiR documentation built on Sept. 30, 2024, 9:16 a.m.