Confidence Curves

Confidence curves are a way to show the confidence in an estimate computed from sample data. They are useful because they show all confidence levels simultaneously, thereby giving a good sense of the accuracy of the estimate, without forcing the researchers to make a more or less arbitrary choice for one confidence level.

ggConfidenceCurve(metric = "d",
                  value = NULL,
                  n = NULL,
                  conf.level = NULL,
                  wRange = c(0.05, 0.8),
                  curveSize = 1,
                  curveColor = "black",
                  confRange = c(1e-04, 0.9999),
                  confLines = c(0.5, 0.8, 0.95, 0.99),
                  widthLines = c(min(wRange), 0.1, 0.2, 0.3, max(wRange)),
                  lineColor = brewer.pal(9, 'Set1'),
                  lineSize = 1,
                  lineAlpha = .5,
                  xlab = metric,
                  steps = 1000,
                  theme = theme_bw(),
                  gradient=NULL,
                  gradientWidth=.01,
                  outputFile = NULL,
                  outputWidth = 16,
                  outputHeight = 16,
                  ggsaveParams = list(units='cm',
                                      dpi=300,
                                      type="cairo"))

Arguments

metric	The metric, currently only 'd' (Cohen's d) and 'r' (Pearson's r) are implemented.
value	The value for which to create the confidence curve plot.
n	The sample size for which to create the confidence curve plot. If n is specified, the y axis shows confidence levels (i.e. a conventional confidence curve is generated). If n is set to NULL, the y axis shows sample sizes. Either n or conf.level must be NULL.
conf.level	The confidence level for which to create the confidence curve plot. If conf.level is specified, the y axis shows sample sizes. If conf.level is set to NULL, the y axis shows confidence levels (i.e. a conventional confidence curve is generated). Either n or conf.level must be NULL.
wRange	The range of 'half-widths', or margins of error, to plot in the confidence curve plot if no sample size is specified (if n=NULL).
curveSize	The line size of the confidence curve line.
curveColor	The color of the confidence curve line.
confRange	The range of confidence levels to plot.
confLines, widthLines	If a traditional confidence curve is generated, lines can be added to indicate the metric values corresponding to the lower and upper confidence interval bounds. For an inverse confidence curve, lines can be added to inficate the metric values and sample sizes corresponding to specific margins of error (or 'half-widths').
lineColor	If confidence or 'interval width lines' lines are added (see confLines), this is the color in which they are drawn. Specify a vector (e.g. brewer.pal(9, 'Set1')) to have the colors drawn in different colors for each confidence level or width.
lineSize	If confidence lines or 'interval width lines' are added (see confLines and widthLines), these arguments specify the color and size in which they are drawn.
lineAlpha	The alpha value (transparency) of the confidence lines or 'interval width lines'.
xlab	The label on the x axis.
steps	The number of steps to use when generating the data for the confidence curves' more steps yield prettier, smoother curves, but take more time.
theme	The ggplot theme to use.
gradient	Whether to use a gradient as background to make the confidence more explicit. This is experimental and pretty influential in terms of how the plot looks. The default gradient, used when passing TRUE, uses black as background color when the confidence is 0 percent, and white for 100 percent. If two colors are specified, these are used instead.
gradientWidth	If using a gradient, the width of the geom_tile geoms used to create the gradient.
outputFile	A file to which to save the plot.
outputWidth, outputHeight	Width and height of saved plot (specified in centimeters by default, see ggsaveParams).
ggsaveParams	Parameters to pass to ggsave when saving the plot.

Value

A ggplot2 plot.

References

Bender, R., Berg, G., & Zeeb, H. (2005). Tutorial: Using confidence curves in medical research. Biometrical Journal, 47(2), 237-247. http://doi.org/10.1002/bimj.200410104

Birnbaum, A. (1961). Confidence curves: An omnibus technique for estimation and testing statistical hypotheses. Journal of the American Statistical Association, 56(294), 246-249. http://doi.org/10.1080/01621459.1961.10482107

See also

cohensdCI, pwr.cohensdCI, confIntR, pwr.confIntR

Examples

ggConfidenceCurve(metric='d', value = .5, n = 128);
ggConfidenceCurve(metric='d', value = .5, conf.level = .95);