esvis (version 0.2.0)

binned_plot: Quantile-binned effect size plot

Description

Plots the effect size between two groups by matched (binned) quantiles (i.e., the results from qtile_es), with the matched quantiles plotted along the x-axis and the effect size plotted along the y-axis. The intent is to examine how (if) the magnitude of the effect size varies at different points of the distributions.

Usage

binned_plot(formula, data, ref_group = NULL, qtiles = seq(0, 1, 0.3333),
  scheme = "ggplot2", se = TRUE, shade_col = NULL, shade_alpha = 0.3,
  annotate = FALSE, refline = TRUE, refline_lty = 2, refline_lwd = 2,
  rects = TRUE, rect_colors = c(rgb(0.2, 0.2, 0.2, 0.1), rgb(0.2, 0.2, 0.2,
  0)), lines = TRUE, points = TRUE, legend = NULL, theme = "standard",
  ...)

Arguments

formula

A formula of the type out ~ group where out is the outcome variable and group is the grouping variable. Note the grouping variable must only include only two groups.

data

The data frame that the data in the formula come from.

ref_group

Optional character vector (of length 1) naming the reference group to be plotted on the x-axis. Defaults to the highest scoring group.

qtiles

The quantile bins to split the data by and calculate effect sizes. This argument is passed directly to qtile_es. Essentially, this is the binning argument. Defaults to seq(0, 1, .33) which splits the distribution into thirds (lower, middle, upper). Any sequence is valid, but it is recommended the bins be even. For example seq(0, 1, .1) would split the distributions into deciles.

scheme

What color scheme should the lines follow? Defaults to mimic the ggplot2 color scheme. Other options come from the viridisLite package, and must be installed first. These are the same options available in the package: "viridis", "magma", "inferno", and "plasma". These color schemes work well for color blindness and print well in black and white. Alternatively, colors can be supplied manually through a call to col (through ...).

se

Logical. Should the standard errors around the effect size point estimates be displayed? Defaults to TRUE, with the uncertainty displayed with shading.

shade_col

Color of the standard error shading, if se == TRUE. Defaults to the same color as the lines.

shade_alpha

Transparency level of the standard error shading. Defaults to 0.3.

annotate

Logical. Defaults to FALSE. When TRUE and legend == "side" the plot is rendered such that additional annotations can be made on the plot using low level base plotting functions (e.g., arrows). However, if set to TRUE, dev.off must be called before a new plot is rendered (i.e., close the current plotting window). Otherwise the plot will be attempted to be rendered in the region designated for the legend). Argument is ignored when legend != "side".

refline

Logical. Defaults to TRUE. Should a diagonal reference line, representing the point of equal probabilities, be plotted?

refline_lty

Line type of the reference line. Defaults to 2.

refline_lwd

Line width of the reference line. Defaults to 2.

rects

Logical. Should semi-transparent rectangles be plotted in the background to show the binning? Defaults to TRUE.

rect_colors

Color of rectangles to be plotted in the background, if rects == TRUE. Defaults to alternating gray and transparent. Currently not alterable when theme == "dark", in which case the rects alternate a semi-transparent white and transparent.

lines

Logical. Should the points between effect sizes across qtiles be connected via a line? Defaults to TRUE.

points

Logical. Should points be plotted for each qtiles be plotted? Defaults to TRUE.

legend

The type of legend to be displayed, with possible values "base", "side", or "none". Defaults to "side", when there are more than two groups and "none" when only comparing two groups. If the option "side" is used the plot is split into two plots, via layout, with the legend displayed in the second plot. This scales better than the base legend (i.e., manually manipulating the size of the plot after it is rendered), but is not compatible with multi-panel plotting (e.g., par(mfrow = c(2, 2)) for a 2 by 2 plot). When producing multi-panel plots, use "none" or "base", the latter of which produces the legend with the base legend function.

theme

Visual properties of the plot. There are currently only two themes implemented - a standard plot and a dark theme. If NULL (default), the theme will be produced with a standard white background. If "dark", a dark gray background will be used with white text and axes.

...

Additional arguments passed to plot. Note that it is best to use the full argument rather than partial matching, given the method used to call the plot. While some partial matching is supported (e.g., m for main, it is generally safest to supply the full argument).

Examples

# NOT RUN {
# Default binned effect size plot
binned_plot(math ~ condition, star)

# Change the reference group to regular sized classrooms
binned_plot(math ~ condition, 
		star,
		ref_group = "reg")

# Change binning to deciles
binned_plot(math ~ condition, 
		star,
		ref_group = "reg",
		qtiles = seq(0, 1, .1))

# Suppress the standard error shading
binned_plot(math ~ condition, 
		star,
		se = FALSE)

# Change to dark theme
binned_plot(math ~ condition, 
		star,
		theme = "dark")
# }