Type:	Package
Title:	Calibration of P-Values for Point Null Hypothesis Testing
Version:	1.0.0
Description:	Calibrate p-values under a robust perspective using the methods developed by Sellke, Bayarri, and Berger (2001) <doi:10.1198/000313001300339950> and obtain measures of the evidence provided by the data in favor of point null hypotheses which are safer and more straightforward to interpret.
License:	GPL-3 | file LICENSE
URL:	https://pedro-teles-fonseca.github.io/pcal/, https://github.com/pedro-teles-fonseca/pcal
BugReports:	https://github.com/pedro-teles-fonseca/pcal/issues
Encoding:	UTF-8
LazyData:	true
Depends:	R (≥ 2.10)
Imports:	Rdpack (≥ 0.7)
Suggests:	covr (≥ 3.5.0), testthat (≥ 2.3.2), knitr (≥ 1.28), rmarkdown (≥ 2.1)
RdMacros:	Rdpack
RoxygenNote:	7.1.0
NeedsCompilation:	no
Packaged:	2020-07-03 19:42:27 UTC; pedro
Author:	Pedro Fonseca [aut, cre], Rui Paulo [ctb, ths], FCT [fnd]
Maintainer:	Pedro Fonseca <pedro.teles.fonseca@outlook.com>
Repository:	CRAN
Date/Publication:	2020-07-06 09:20:09 UTC

Lower Bounds on Bayes Factors for Point Null Hypotheses

Description

Calibrate p-values under a robust Bayesian perspective so that they can be interpreted as lower bounds on Bayes factors in favor of point null hypotheses.

Usage

bcal(p)

Arguments

Details

bcal uses the calibration of p-values into lower bounds for Bayes factors developed in Sellke et al. (2001):

B(p) = -e \, p \, log (p)

for p < (1/e) and

B(p) = 1

otherwise, where p is a p-value on a classical test statistic and B(p) approximates the smallest Bayes factor that is found by changing the prior distribution of the parameter of interest (under the alternative hypothesis) over wide classes of distributions.

Sellke et al. (2001) noted that a scenario in which they definitely recommend this calibration is when investigating fit to the null model/hypothesis with no explicit alternative in mind. Pericchi and Torres (2011) warn that despite the usefulness and appropriateness of this p-value calibration it does not depend on sample size and hence the lower bounds obtained with large samples may be conservative.

Value

bcal returns a numeric vector with the same length as p.

References

Pericchi L, Torres D (2011). “Quick anomaly detection by the Newcomb—Benford law, with applications to electoral processes data from the USA, Puerto Rico and Venezuela.” Statistical Science, 26(4), 502–516.

Sellke T, Bayarri MJ, Berger JO (2001). “Calibration of p values for testing precise null hypotheses.” The American Statistician, 55(1), 62–71.

See Also

• pcal for a p-value calibration that returns lower bounds on the posterior probabilities of point null hypotheses.

• bfactor_interpret and bfactor_interpret_kr for the interpretation of Bayes factors.

• bfactor_log_interpret and bfactor_log_interpret_kr for the interpretation of the logarithms of Bayes factors.

• bfactor_to_prob to turn Bayes factors into posterior probabilities.

Examples

# Calibration of a typical "threshold" p-value:
bcal(.05)

# Calibration of typical "threshold" p-values:
bcal(c(.1, .05, .01, .005, .001))

# Application: chi-squared goodness-of-fit test,
# lower bound on the Bayes factor in favor of the null hypothesis:
x <- matrix(c(12, 41, 25, 33), ncol = 2)
bcal(chisq.test(x)[["p.value"]])

Interpretation of Bayes factors

Description

Quantify the strength of the evidence provided by the data to a model/hypothesis according to the Bayes factor interpretation scale suggested by Jeffreys (1961).

Usage

bfactor_interpret(bf)

Arguments

Details

Bayes factors are a summary of the evidence provided by the data to a model/hypothesis. Jeffreys (1961) suggested the interpretation of Bayes factors in half-units on the base 10 logarithmic scale, as indicated in the following table:

bfactor_interpret takes Bayes factors as input and returns the strength of the evidence in favor of the model/hypothesis in the numerator of the Bayes factors (usually the null hypothesis) according to the aforementioned table.

When comparing results with those from standard likelihood ratio tests, it is convenient to put the null hypothesis in the denominator of the Bayes factor so that bfactor_interpret returns the strength of the evidence against the null hypothesis. If bf was obtained with the null hypothesis on the numerator, one can use bfactor_interpret(1/bf) to obtain the strength of the evidence against the null hypothesis.

Value

Returns a character vector with the same length as bf.

References

Jeffreys H (1961). Theory of probability, Oxford Classic Texts In The Physical Sciences, 3 edition. Oxford University Press.

See Also

• bfactor_interpret_kr for an alternative interpretation scale.

• bfactor_log_interpret and bfactor_log_interpret_kr for the interpretation of the logarithms of Bayes factors.

• bfactor_to_prob to turn Bayes factors into posterior probabilities.

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

Examples

# Interpretation of one Bayes factor
bfactor_interpret(1.5)

# Interpretation of many Bayes factors
bfactor_interpret(c(0.1, 1.2, 3.5, 13.9, 150))

# Application: chi-squared goodness-of-fit test.
# Strength of the evidence provided by the lower
# bound on the Bayes factor in favor of the null hypothesis:
x <- matrix(c(12, 15, 14, 15), ncol = 2)
bfactor_interpret(bcal(chisq.test(x)[["p.value"]]))

Interpretation of Bayes factors

Description

Quantify the strength of the evidence provided by the data to a model/hypothesis according a Bayes factor interpretation scale suggested by Kass and Raftery (1995).

Usage

bfactor_interpret_kr(bf)

Arguments

Details

Bayes factors are a summary of the evidence provided by the data to a model/hypothesis. Because it can be useful to consider twice the natural logarithm of the Bayes factor, which is in the same scale as the familiar deviance and likelihood ratio test statistics, Kass and Raftery (1995) suggested the following Bayes factor interpretation scale:

bfactor_interpret_kr takes Bayes factors as input and returns the strength of the evidence in favor of the model/hypothesis in the numerator of the Bayes factors (usually the null hypothesis) according to the aforementioned table.

When comparing results with those from standard likelihood ratio tests, it is convenient to put the null hypothesis in the denominator of the Bayes factor so that bfactor_interpret_kr returns the strength of the evidence against the null hypothesis. If bf was obtained with the null hypothesis on the numerator, one can use bfactor_interpret_kr(1/bf) to obtain the strength of the evidence against the null hypothesis.

Value

Returns a character vector with the same length as bf.

References

Kass RE, Raftery AE (1995). “Bayes factors.” Journal of the American Statistical Association, 90(430), 773–795.

See Also

• bfactor_interpret for the original interpretation scale suggested by Harold Jeffreys.

• bfactor_log_interpret and bfactor_log_interpret_kr for the interpretation of the logarithms of Bayes factors.

• bfactor_to_prob to turn Bayes factors into posterior probabilities.

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

Examples

# Interpretation of one Bayes factor
bfactor_interpret_kr(1.5)

# Interpretation of many Bayes factors
bfactor_interpret_kr(c(0.1, 1.2, 3.5, 13.9, 150))

# Application: chi-squared goodness-of-fit test.
# Strength of the evidence provided by the lower
# bound on the Bayes factor in favor of the null hypothesis:
x <- matrix(c(12, 15, 14, 15), ncol = 2)
bfactor_interpret_kr(bcal(chisq.test(x)[["p.value"]]))

Interpretation of the logarithms of Bayes factors

Description

Quantify the strength of the evidence provided by the data to a model/hypothesis according to the Bayes factor interpretation scale suggested by Jeffreys (1961).

Usage

bfactor_log_interpret(bf, base = exp(1))

Arguments

Details

Bayes factors are a summary of the evidence provided by the data to a model/hypothesis, and are often reported on a logarithmic scale. Jeffreys (1961) suggested the interpretation of Bayes factors in half-units on the base 10 logarithmic scale, as indicated in the following table:

bfactor_log_interpret takes (base base) logarithms of Bayes factors as input and returns the strength of the evidence provided by the data in favor of the model/hypothesis in the numerator of the Bayes factors (usually the null hypothesis) according to the according to the aforementioned table.

When comparing results with those from standard likelihood ratio tests, it is convenient to put the null hypothesis in the denominator of the Bayes factor so that bfactor_log_interpret returns the strength of the evidence against the null hypothesis. If bf was obtained with the null hypothesis on the numerator, one can use bfactor_log_interpret(1/bf) to obtain the strength of the evidence against the null hypothesis.

Value

Returns a character vector with the same length as bf.

References

Jeffreys H (1961). Theory of probability, Oxford Classic Texts In The Physical Sciences, 3 edition. Oxford University Press.

See Also

• bfactor_log_interpret_kr for an alternative interpretation scale.

• bfactor_interpret and bfactor_interpret_kr for the interpretation of Bayes factors in levels.

• bfactor_to_prob to turn Bayes factors into posterior probabilities.

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

Examples

# Interpretation of one Bayes factor (on the natural log scale)
bfactor_log_interpret(log(1.5))

# Interpretation of many Bayes factors (on the natural log scale)
bfactor_log_interpret(log(c(0.1, 1.2, 3.5, 13.9, 150)))

# Interpretation of many Bayes factors (on the log10 scale)
bfactor_log_interpret(log10(c(0.1, 1.2, 3.5, 13.9, 150)), base = 10)

Interpretation of the logarithms of Bayes factors

Description

Quantify the strength of the evidence provided by the data to a model/hypothesis according a Bayes factor interpretation scale suggested by Kass and Raftery (1995).

Usage

bfactor_log_interpret_kr(bf, base = exp(1))

Arguments

Details

Bayes factors are a summary of the evidence provided by the data to a model/hypothesis, and are often reported on a logarithmic scale. Because it can be useful to consider twice the natural logarithm of the Bayes factor, which is in the same scale as the familiar deviance and likelihood ratio test statistics, Kass and Raftery (1995) suggested the following Bayes factor interpretation scale:

bfactor_log_interpret_kr takes (base base) logarithms of Bayes factors as input and returns the strength of the evidence provided by the data in favor of the model/hypothesis in the numerator of the Bayes factors (usually the null hypothesis) according to the aforementioned table.

When comparing results with those from standard likelihood ratio tests, it is convenient to put the null hypothesis in the denominator of the Bayes factor so that bfactor_log_interpret_kr returns the strength of the evidence against the null hypothesis. If bf was obtained with the null hypothesis on the numerator, one can use bfactor_log_interpret_kr(1/bf) to obtain the strength of the evidence against the null hypothesis.

Value

Returns a character vector with the same length as bf.

References

Kass RE, Raftery AE (1995). “Bayes factors.” Journal of the American Statistical Association, 90(430), 773–795.

See Also

• bfactor_log_interpret for the original interpretation scale suggested by Harold Jeffreys

• bfactor_interpret and bfactor_interpret_kr for the interpretation of Bayes factors in levels.

• bfactor_to_prob to turn Bayes factors into posterior probabilities.

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

Examples

# Interpretation of one Bayes factor, natural log
bfactor_log_interpret_kr(1.5)

# Interpretation of many Bayes factors, natural log
bfactor_log_interpret_kr(c(0.1, 1.2, 3.5, 13.9, 150))

# Interpretation of many Bayes factors, base 10 log
bfactor_log_interpret_kr(log10(c(0.1, 1.2, 3.5, 13.9, 150)), base = 10)

Turn Bayes Factors Into Posterior Probabilities

Description

Update the prior probabilities of models/hypotheses to posterior probabilities using Bayes factors.

Usage

bfactor_to_prob(bf, prior_prob = 0.5)

Arguments

Details

bfactor_to_prob computes the posterior probability of the null hypothesis using the following equation from Berger and Delampady (1987):

P(\textrm{null} \, \textrm{hypothesis}|\textrm{data}) = \left(1 + \frac{1 - {null\_prob}}{null\_prob} \times \frac{1}{bf}\right)^{-1}

where bf is a Bayes factor if favor of the null hypothesis and prior_prob is the prior probability of the null hypothesis. The alternative hypothesis has prior probability 1 - prior_prob and posterior probability 1 - bfactor_to_prob(bf, prior_prob).

The prior_prob argument is optional and is set to 0.5 by default, implying prior equiprobability of hypotheses. prior_prob can only be of length equal to length(bf), in which case each prior probability in prior_prob will be updated using the corresponding element of bf, or of length 1, in which case it will be recycled (if length(bf) > 1) and each element of bf will update the same prior_prob value.

Value

If length(bf) > 1 then bfactor_to_prob returns a numeric vector with the same length as bf, otherwise it returns a numeric vector with the same length as prior_prob.

References

Berger JO, Delampady M (1987). “Testing precise hypotheses.” Statistical Science, 2(3), 317–335.

See Also

• bfactor_interpret and bfactor_interpret_kr for the interpretation of Bayes factors.

• bfactor_log_interpret and bfactor_log_interpret_kr for the interpretation of the logarithms of Bayes factors.

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

• pcal for a p-value calibration that returns lower bounds on the posterior probabilities of point null hypotheses.

Examples

# With a Bayes factor that is indifferent between the null and the alternative hypotheses:
bfactor_to_prob(1)

# Same as above but the null hypothesis has high prior probability:
bfactor_to_prob(1, .99)

# Posterior probability of the null as a function of different prior probabilities:
bfactor_to_prob(1, seq(.5, 1, .1))

# With Bayes factors that favor the null hypothesis:
round(bfactor_to_prob(seq(2, 50, 2.5)), 3)

# Same as above but the null hypothesis has low prior probability:
round(bfactor_to_prob(seq(2, 50, 2.5), prior_prob = .01), 3)

# Posterior probabilities obtained with Bayes factors that favor the alternative hypothesis:
round(bfactor_to_prob(seq(0, 1, .05)), 3)

# Same as above but the null hypothesis has high prior probability:
round(bfactor_to_prob(seq(0, 1, .05), prior_prob = .99), 3)

# Application: chi-squared goodness-of-fit test,
# lower bound on the posterior probability of the null hypothesis:
x <- matrix(c(12, 41, 25, 33), ncol = 2)
bfactor_to_prob(bcal(chisq.test(x)[["p.value"]]), prior_prob = .9)

Lower Bounds on the Posterior Probabilities of Point Null Hypotheses

Description

Calibrate p-values under a robust perspective so that they can be interpreted as either lower bounds on the posterior probabilities of point null hypotheses or as lower bounds on the probabilities of type I errors.

Usage

pcal(p, prior_prob = 0.5)

Arguments

Details

Sellke et al. (2001) developed a calibration of p-values into lower bounds for the posterior probabilities of point null hypotheses or lower bounds for the probabilities of type I errors for the case when both the null and the alternative hypotheses have 0.5 prior probability. pcal generalizes the aforementioned calibration for prior probabilities other than 0.5.

pcal starts by transforming the values in p into lower bounds on Bayes factors using bcal and then uses bfactor_to_prob together with prior probabilities prior_prob to turn those Bayes factors into posterior probabilities. For each element of p, pcal returns an approximation of the smallest posterior probability of the null hypothesis that is found by changing the prior distribution of the parameter of interest (under the alternative hypothesis) over wide classes of distributions.

The prior_prob argument is optional and is set to 0.5 by default, implying prior equiprobability of hypotheses. prior_prob can only be of length equal to the length of p, in which case each prior probability in prior_prob is used in the calibration of the corresponding element of p, or of length 1, in which case it will be recycled (if length(p) > 1) and the same prior_prob value is used in the calibration of all the elements of p.

The output of pcal can also be interpreted as lower bounds on the probabilities of type I errors. Note that the output of this calibration has both Bayesian and Frequentist interpretations. Sellke et al. (2001) noted that a scenario in which they definitely recommend this calibration is when investigating fit to the null model with no explicit alternative in mind. Pericchi and Torres (2011) warn that despite the usefulness and appropriateness of this p-value calibration it does not depend on sample size, and hence the lower bounds obtained with large samples may be conservative.

Value

If length(p) > 1 then pcal returns a numeric vector with the same length as p, otherwise it returns a numeric vector with the same length as prior_prob.

References

Pericchi L, Torres D (2011). “Quick anomaly detection by the Newcomb—Benford law, with applications to electoral processes data from the USA, Puerto Rico and Venezuela.” Statistical Science, 26(4), 502–516.

Sellke T, Bayarri MJ, Berger JO (2001). “Calibration of p values for testing precise null hypotheses.” The American Statistician, 55(1), 62–71.

See Also

• bcal for a p-value calibration that returns lower bounds on Bayes factors in favor of point null hypotheses.

Examples

# Calibration of a typical "threshold" p-value:
pcal(.05)

# Calibration of typical "threshold" p-values:
pcal(c(.1, .05, .01, .005, .001))

# Application: chi-squared goodness-of-fit test,
# lower bound on the posterior probability of the null hypothesis:
x <- matrix(c(12, 41, 25, 33), ncol = 2)
pcal(chisq.test(x)[["p.value"]])