# epi.betabuster: An R version of Wes Johnson and Chun-Lung Su's Betabuster In epiR: Tools for the Analysis of Epidemiological Data

 epi.betabuster R Documentation

## 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 June 22, 2024, 10:57 a.m.