Package 'bayesROE'

Bayesian Regions of Evidence Raster Plot

Description

Compute and visualize the Bayesian Regions of Evidence (Raster), that is, the set of normal priors for an effect size which - when combined with the observed data - lead to a specified posterior probability for the effect size being more extreme than a specified minimally relevant effect size.

Usage

rasterROE(
  ee,
  se,
  delta = 0,
  alpha = 0.025,
  type = "threshold",
  larger = TRUE,
  meanLim = c(-3 * abs(ee), 3 * abs(ee)),
  sdLim = c(0, 5 * se),
  nGrid = 200,
  cols = NULL,
  cols_alpha = 1,
  add = FALSE
)

Arguments

ee	Effect estimate.
se	Standard error of effect estimate.
delta	Minimally relevant effect size. Defaults to zero. Can also be a vector of numerical values to representing different regions.
alpha	Posterior probability that the effect size is less extreme than delta. Defaults to 0.025. Can also be a vector of numerical values representing different regions.
type	Character indicating if regions of evidence should be constructed for a non-inferiority claim using the first element of delta and all elements of alpha ("threshold"), for a non-inferiority claim using the all elements of delta and the first element of alpha ("probability"), for an equivalence claim using the first two elements of delta and all elements of alpha ("equivalence"), or for a prior-data conflict using only the first element of alpha ("conflict"). Defaults to "threshold".
larger	Logical indicating if effect size should be larger (TRUE) or smaller (FALSE) than delta. Ignored when type = "equivalence" or type = "conflict". Defaults to TRUE.
meanLim	Limits of prior mean axis.
sdLim	Limits of prior standard deviation axis.
nGrid	Resolution of grid points (on both axes). Defaults to 200.
cols	Character containing the HEX color code of the upper and lower region of evidence, respectively. Defaults to NULL, which triggers automated color picking by calling ggplot2:scale_fill_viridis_d()
cols_alpha	Numeric value indicating the relative opacity of any region of evidence (alpha channel). Defaults to 1 (no transparency).
add	Logical indicating if a separate geom_raster layer should be created that can be added to an existing plot (TRUE), or if an entire regions of plot should be created (FALSE). Defaults to FALSE.

Value

A bayesROE object (a list containing the ggplot object, the data for the plot, and the empty tipping point function)

References

Hoefler, M., Miller, R. (2022, April 04). Bayesian regions of evidence (for normal distributions). doi:10.31234/osf.io/mg23h

Examples

## data with p < 0.025 for H0: delta < 0, but p > 0.025 for H0: delta < 0.3
d <- 0.4
d_se <- 0.1
delta <- c(0, 0.3)

rasterROE(ee = d, se = d_se, delta = delta, meanLim = c(-1, 1))


## reproducing Figure 3 from Hoefler & Miller (2023)
ee <- 9
se <- 3.9
delta <- c(0, 3.75)

rasterROE(ee = ee, se = se, delta = delta, alpha = 0.05)$plot +
  ggplot2::annotate(geom = "point", y = ee, x = se, shape = 4)
  ggplot2::coord_flip(xlim = c(0, 12), ylim = c(-5, 10))

---

Bayesian Regions of Evidence Ribbon Plot

Description

Compute and visualize the Bayesian Regions of Evidence (Ribbon), that is, the set of normal priors for an effect size which - when combined with the observed data - lead to a specified posterior probability for the effect size being more extreme than a specified minimally relevant effect size.

Usage

ribbonROE(
  ee,
  se,
  delta = 0,
  alpha = 0.025,
  type = "threshold",
  larger = TRUE,
  meanLim = c(pmin(2 * ee, 0), pmax(0, 2 * ee)),
  sdLim = c(0, 3 * se),
  nGrid = 500,
  relative = TRUE,
  cols = NULL,
  cols_alpha = 1,
  addRef = FALSE,
  sceptPrior = 0,
  addEst = FALSE
)

Arguments

ee	Effect estimate.
se	Standard error of effect estimate.
delta	Minimally relevant effect size. Defaults to zero. Can also be a vector of numerical values to representing different regions.
alpha	Posterior probability that the effect size is less extreme than delta. Defaults to 0.025. Can also be a vector of numerical values representing different regions.
type	Character indicating if regions of evidence should be constructed for a non-inferiority claim using the first element of delta and all elements of alpha ("threshold") or for a non-inferiority claim using the all elements of delta and the first element of alpha ("probability"). Defaults to "threshold".
larger	Logical indicating if effect size should be larger (TRUE) or smaller (FALSE) than delta. Defaults to TRUE.
meanLim	Limits of prior mean axis. Defaults to interval between zero and two times the effect estimate.
sdLim	Limits of prior standard deviation axis. Defaults to interval between zero and three times the standard error.
nGrid	Number of grid points (on the standard error axis). Defaults to 500.
relative	Logical indicating whether a second x-axis and y-axis with relative prior mean and relative prior variance should be displayed. Defaults to TRUE.
cols	Character containing the HEX color code of the upper and lower region of evidence, respectively. Defaults to NULL, which triggers automated color picking by calling ggplot2:scale_fill_viridis_d()
cols_alpha	Numeric value indicating the relative opacity of any region of evidence (alpha channel). Defaults to 1 (no transparency).
addRef	Logical indicating if a reference cross representing the minimum sceptical prior is added to the plot. Defaults to FALSE.
sceptPrior	Numeric value indicating the effect location of the minimum sceptical prior. Defaults to 0.
addEst	Logical indicating if a point symbol representing the mean and standard error of the effect estimate (ee, se) is added to the plot. Defaults to FALSE.

Value

A bayesROE object (a list containing the ggplot object, the data for the plot, and the tipping point function)

References

Pawel, S., Matthews, R. and Held, L. (2021). Comment on "Bayesian additional evidence for decision making under small sample uncertainty". Manuscript submitted for publication. Code available at https://osf.io/ymx92/

Examples

## data with p < 0.025 for H0: delta < 0, but p > 0.025 for H0: delta < 0.3
d <- 0.4
d_se <- 0.1
delta <- c(0, 0.3)
ribbonROE(ee = d, se = d_se, delta = delta, meanLim = c(-1, 1))

## reproducing Figure 1 from Hoefler & Miller (2023)
ee <- 3.07
se <- 1.19
ribbonROE(ee = ee, se = se, delta = c(0,3), alpha = 0.025, 
  cols = c("#F5FF82", "#27CC1E"))$plot + 
  ggplot2::annotate(geom = "point", y = ee, x = se, shape = 4) +
  ggplot2::coord_flip(ylim = c(-5, 15))

---

Shiny Application to Visualize Bayesian Regions of Evidence

Description

Initialize and execute a local Shiny session to interactively visualize and explore the Bayesian Regions of Evidence. Parameters entries from the sidebar are passed to the bayesROE function.

Usage

run_app(
  onStart = NULL,
  options = list(launch.browser = TRUE),
  enableBookmarking = NULL,
  uiPattern = "/",
  init = NULL,
  cols = NULL,
  ...
)

Arguments

onStart	A function that will be called before the app is actually run. This is only needed for shinyAppObj, since in the shinyAppDir case, a global.R file can be used for this purpose.
options	Named options that should be passed to the runApp call (these can be any of the following: "port", "launch.browser", "host", "quiet", "display.mode" and "test.mode"). You can also specify width and height parameters which provide a hint to the embedding environment about the ideal height/width for the app.
enableBookmarking	Can be one of "url", "server", or "disable". The default value, NULL, will respect the setting from any previous calls to enableBookmarking(). See enableBookmarking() for more information on bookmarking your app.
uiPattern	A regular expression that will be applied to each GET request to determine whether the ui should be used to handle the request. Note that the entire request path must match the regular expression in order for the match to be considered successful.
init	Named list containing the arguments that are passed to the bayesROE function: ee, se, delta, alpha.
cols	Named list of RGB hexadecimal color keys.
...	arguments to pass to golem_opts. See '?golem::get_golem_options' for more details.

Examples

# reproducing Figure 3 from Hoefler and Miller (2023)
init <- list(ee = 9, se = 3.9, delta = c(0, 3.75), alpha = 0.025)
cols <- list(col_lower = "#F5FF82", col_upper = "#27CC1E")
if(interactive()){
   run_app(init = init, cols = cols)
}

---

Shiny Application to Visualize Bayesian Regions of Evidence (deprecated interface)

Description

Initialize and execute a local Shiny session to interactively visualize and explore the Bayesian Regions of Evidence. Parameters entries from the sidebar are passed to the bayesROE function. The function has been deprecated in favor of bayesROE::run_app() and is only retained for downward compatibility.

Usage

shinyROE(init = NULL, ...)

Arguments

init	Named list containing the arguments that are passed to the bayesROE function: ee, se, delta, alpha.
...	arguments to pass to golem_opts. See '?golem::get_golem_options' for more details.

Examples

# reproducing Figure 3 from Hoefler and Miller (2023)
init <- list(ee = 9, se = 3.9, delta = c(0, 3.75), alpha = 0.025)
if(interactive()){
   shinyROE(init = init)
}

---