Sample distribution based plotting of proportions

This function visualises percentages, but avoids a clear cut for the sample point estimate, instead using the confidence (as in confidence interval) to create a gradient. This effectively hinders drawing conclusions on the basis of point estimates, thereby urging a level of caution that is consistent with what the data allows.

ggProportionPlot(
  dat,
  items = NULL,
  loCategory = NULL,
  hiCategory = NULL,
  subQuestions = NULL,
  leftAnchors = NULL,
  rightAnchors = NULL,
  compareHiToLo = TRUE,
  showDiamonds = FALSE,
  diamonds.conf.level = 0.95,
  diamonds.alpha = 1,
  na.rm = TRUE,
  barHeight = 0.4,
  conf.steps = seq(from = 0.001, to = 0.999, by = 0.001),
  scale_color = c("#21908CFF", "#FDE725FF"),
  scale_fill = c("#21908CFF", "#FDE725FF"),
  rank.conf = FALSE,
  linetype = 1,
  theme = ggplot2::theme_bw(),
  returnPlotOnly = TRUE
)

# S3 method for ggProportionPlot
print(x, ...)

# S3 method for ggProportionPlot
grid.draw(x, ...)

Arguments

dat: The dataframe containing the items (variables), or a vector.
items: The names of the items (variables). If none are specified, all variables in the dataframe are used.
loCategory: The value of the low category (usually 0). If not provided, the minimum value is used.
hiCategory: The value of the high category (usually 1). If not provided, the maximum value is used.
subQuestions: The labels to use for the variables (for example, different questions). The variable names are used if these aren't provided.
leftAnchors: The labels for the low categories. The values are used if these aren't provided.
rightAnchors: The labels for the high categories. The values are used if these aren't provided.
compareHiToLo: Whether to compare the percentage of low category values to the total of the low category values and the high category values, or whether to ignore the high category values and compute the percentage of low category values relative to all cases. This can be useful when a variable has more than two values, and you only want to know/plot the percentage relative to the total number of cases.
showDiamonds: Whether to add diamonds to illustrate the confidence intervals.
diamonds.conf.level: The confidence level of the diamonds' confidence intervals.
diamonds.alpha: The alpha channel (i.e. transparency, or rather 'obliqueness') of the diamonds.
na.rm: Whether to remove missing values.
barHeight: The height of the bars, or rather, half the height. Use .5 to completely fill the space.
conf.steps: The number of steps to use to generate the confidence levels for the proportion.
scale_color, scale_fill: A vector with two values (valid colors), that are used for the colors (stroke) and fill for the gradient; both vectors should normally be the same, but if you feel adventurous, you can play around with the number of conf.steps and this. If you specify only one color, no gradient is used but a single color (i.e. specifying the same single color for both scale_color and scale_fill simply draws bars of that color).
rank.conf: Whether to let the fill and color gradients use the confidence or the ranked confidence.
linetype: The linetype() to use (0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash, 6 = twodash).
theme: The theme to use.
returnPlotOnly: Whether to only return the ggplot2() plot or the full object including intermediate values and objects.
x: The object to print/plot.
...: Any additional arguments are passed on to print and grid.draw.

Value

A ggplot2() object (if returnPlotOnly is TRUE), or an object containing that ggplot2() object and intermediate products.

Details

This function used confIntProp() to compute confidence intervals for proportions at different levels of confidence. The confidence interval bounds at those levels of confidence are then used to draw rectangles with colors in a gradient that corresponds to the confidence level.

Note that percentually, the gradient may not look continuous because at the borders between lighter and darker rectangles, the shade of the lighter rectangle is perceived as even lighter than it is, and the shade of the darker rectangle is perceived as even darker. This makes it seem as if each rectange is coloured with a gradient in the opposite direction.

Author

Gjalt-Jorn Peters

Maintainer: Gjalt-Jorn Peters gjalt-jorn@userfriendlyscience.com

Examples