| super_bf {baymedr} | R Documentation |
Bayes factor for superiority designs
Description
super_bf computes a Bayes factor for superiority designs with a
continuous dependent variable.
Usage
super_bf(
x = NULL,
y = NULL,
n_x = NULL,
n_y = NULL,
mean_x = NULL,
mean_y = NULL,
sd_x = NULL,
sd_y = NULL,
ci_margin = NULL,
ci_level = NULL,
prior_scale = 1/sqrt(2),
direction = "high"
)
Arguments
x |
A numeric vector of observations for the control group. |
y |
A numeric vector of observations for the experimental group. |
n_x |
A numeric vector of length one, specifying the sample size of the control group. |
n_y |
A numeric vector of length one, specifying the sample size of the experimental group. |
mean_x |
A numeric vector of length one, specifying the mean of the dependent variable in the control group. |
mean_y |
A numeric vector of length one, specifying the mean of the dependent variable in the experimental group. |
sd_x |
A numeric vector of length one, specifying the standard deviation
of the dependent variable in the control group. Only |
sd_y |
A numeric vector of length one, specifying the standard deviation
of the dependent variable in the experimental group. Only |
ci_margin |
A numeric vector of length one, specifying the margin of the
confidence interval (i.e., the width of the confidence interval divided by
2) of the mean difference on the dependent variable between the
experimental and control groups. The value should be a positive number Only
|
ci_level |
A numeric vector of length one, specifying the confidence
level of |
prior_scale |
A numeric vector of length one, specifying the scale of the Cauchy prior distribution for the effect size under the alternative hypothesis (see Details). The default value is r = 1 / sqrt(2). |
direction |
A character vector of length one, specifying the direction of superior scores. 'low' indicates that low scores on the measure of interest correspond to a superior outcome and 'high' (the default) indicates that high scores on the measure of interest correspond to a superior outcome (see Details). |
Details
The formulation of the null and alternative hypotheses for the superiority design differs depending on whether high or low scores on the dependent variable represent superiority. In both cases, the null hypothesis (i.e., H0) states that the population means of the experimental group and the control group are equivalent. In the case where high scores correspond to superiority, the alternative hypothesis states that the population mean of the experimental group is higher than the population mean of the control group. Thus, the alternative hypothesis goes in the positive direction (i.e., H+). In turn, in the case where low scores correspond to superiority, the alternative hypothesis states that the population mean of the experimental group is lower than the population mean of the control group. Thus, the alternative hypothesis goes in the negative direction (i.e., H-). The dependent variable must be continuous.
Since the main goal of super_bf is to establish superiority,
the resulting Bayes factor quantifies evidence in favor of the alternative
hypothesis. In the case where low values represent superiority we have BF-0,
whereas in the case where high values represent superiority we have BF+0.
Evidence for the null hypothesis can easily be calculated by taking the
reciprocal of the original Bayes factor (i.e., BF0- = 1 / BF-0 and BF0+ = 1 /
BF+0). Quantification of evidence in favor of the null hypothesis is
logically sound and legitimate within the Bayesian framework (see e.g., van
Ravenzwaaij et al., 2019).
super_bf can be utilized to calculate a Bayes factor based on
raw data (i.e., if arguments x and y are defined) or summary
statistics (i.e., if arguments n_x, n_y, mean_x, and
mean_y are defined). In the latter case, the user has the freedom to
supply values either for the arguments sd_x and sd_y
OR ci_margin and ci_level. Arguments with 'x' as a
name or suffix correspond to the control group, whereas arguments with 'y' as
a name or suffix correspond to the experimental group (i.e., the group for
which we seek to establish superiority).
For the calculation of the Bayes factor, a Cauchy prior density centered on 0
is chosen for the effect size under the alternative hypothesis. The standard
Cauchy distribution, with a location parameter of 0 and a scale parameter of
1, resembles a standard Normal distribution, except that the Cauchy
distribution has less mass at the center but heavier tails (Liang et al.,
2008; Rouder et al., 2009). The argument prior_scale specifies the
width of the Cauchy prior, which corresponds to half of the interquartile
range. Thus, by adjusting the Cauchy prior scale with prior_scale,
different ranges of expected effect sizes can be emphasized. The default
prior scale is set to r = 1 / sqrt(2).
super_bf creates an S4 object of class
baymedrSuperiority, which has multiple slots/entries (e.g.,
type of data, prior scale, Bayes factor, etc.; see Value). If it is desired
to store or extract solely the Bayes factor, the user can do this with
get_bf, by setting the S4 object as an argument (see Examples).
Value
An S4 object of class baymedrSuperiority is returned. Contained are a description of the model and the resulting Bayes factor:
test: The type of analysis
hypotheses: A statement of the hypotheses
h0: The null hypothesis
h1: The alternative hypothesis
data: A description of the data
type: The type of data ('raw' when arguments
xandyare used or 'summary' when argumentsn_x,n_y,mean_x,mean_y,sd_x, andsd_y(orci_marginandci_levelinstead ofsd_xandsd_y) are used)-
...: values for the arguments used, depending on 'raw' or 'summary'
-
prior_scale: The scale of the Cauchy prior distribution
bf: The resulting Bayes factor
A summary of the model is shown by printing the object.
References
Gronau, Q. F., Ly, A., & Wagenmakers, E.-J. (2020). Informed Bayesian t-tests. The American Statistician, 74(2), 137-143.
Liang, F., Paulo, R., Molina, G., Clyde, M. A., & Berger, J. O. (2008). Mixtures of g priors for Bayesian variable selection. Journal of the American Statistical Association, 103(481), 410-423.
Rouder, J. N., Speckman, P. L., Sun, D., Morey, R. D., & Iverson, G. (2009). Bayesian t tests for accepting and rejecting the null hypothesis. Psychonomic Bulletin & Review, 16(2), 225-237.
van Ravenzwaaij, D., Monden, R., Tendeiro, J. N., & Ioannidis, J. P. A. (2019). Bayes factors for superiority, non-inferiority, and equivalence designs. BMC Medical Research Methodology, 19(1), 71.
Examples
## super_bf using raw data:
# Assign model to variable.
super_raw <- super_bf(x = rnorm(100, 10, 15),
y = rnorm(130, 13, 10))
# Extract Bayes factor from model.
get_bf(super_raw)
# ----------
# ----------
## super_bf using summary statistics with data from Skjerven et al. (2013).
## EXAMPLE 1
# Assign model to variable.
super_sum_ex1 <- super_bf(n_x = 201,
n_y = 203,
mean_x = 68.1,
mean_y = 63.6,
ci_margin = (15.5 - (-6.5)) / 2,
ci_level = 0.95,
direction = "low")
# Extract Bayes factor from model.
get_bf(super_sum_ex1)
# ----------
## super_bf using summary statistics with data from Skjerven et al. (2013).
## EXAMPLE 2
# Assign model to variable.
super_sum_ex2 <- super_bf(n_x = 200,
n_y = 204,
mean_x = 47.6,
mean_y = 61.3,
ci_margin = (24.4 - 2.9) / 2,
ci_level = 0.95,
direction = "low")
# Extract Bayes factor from model.
get_bf(super_sum_ex2)