esvis (version 0.2.0)

pp_plot: Produces the paired probability plot for two groups

Description

The paired probability plot maps the probability of obtaining a specific score for each of two groups. The area under the curve (auc) corresponds to the probability that a randomly selected observation from the x-axis group will have a higher score than a randomly selected observation from the y-axis group.

Usage

pp_plot(formula, data, ref_group = NULL, cut = NULL, cut_table = FALSE,
  grid = NULL, scheme = "ggplot2", annotate = FALSE, refline = TRUE,
  refline_col = NULL, refline_lty = 2, refline_lwd = 2, text = NULL,
  text_x = 0.8, text_y = 0.2, text_size = 1.5, shade = NULL,
  shade_col = NULL, leg = NULL, n_1 = FALSE, 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.

cut

Integer. Optional vector (or single number) of scores used to annotate the plot. If supplied, line segments will extend from the corresponding x and y axes and meet at the PP curve.

cut_table

Logical. Should a data.frame of the cuts and corresponding proportions be returned? Defaults to FALSE.

grid

Logical. Should gridlines behind the plot be displayed according to the theme?

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 ...).

annotate

Logical. Defaults to FALSE. When TRUE and leg == "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 leg != "side".

refline

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

refline_col

Color of the reference line.

refline_lty

Line type of the reference line.

refline_lwd

Line width of the reference line.

text

Logical. Should the link{auc} and link{v} statistics be displayed on the plot? Defaults to TRUE when there are two groups. Cannot currently be displayed for more than two groups.

text_x

The x-axis location for the text.

text_y

The y-axis location for the text.

text_size

The size of the text to be displayed. Defaults to 2.

shade

Logical. Should the area under the curve be shaded? Defaults to TRUE if there are only two group. Currently it cannot be produced for more than two groups.

shade_col

The color of the shading. Defaults to the second color in the chosen color scheme.

leg

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.

n_1

Logical. Should the lines on the legend be displayed when there is only one curve? Defaults to FALSE, and is relevant when values to cut are provided. Forced to TRUE if legend == "side" and no values to cut are supplied.

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).

Value

The arguments supplied to the plot are silently returned for testing purposes.

Examples

# NOT RUN {
# Prouduce default Probability-Probability plot with two groups
dev.off()
pp_plot(math ~ freelunch, star)

# Suppress shading and effect-size annotation
pp_plot(math ~ freelunch, 
		star, 
		shade = FALSE, 
		text = FALSE)

# Change color of shading & line, line width, and title
pp_plot(math ~ freelunch, 
		star, 
		shade_col = grDevices::rgb(0.1, 0.8, 0.2, 0.5), 
		col = "purple", lwd = 5, 
		main = "Probability-Probability Plot")

# Change to dark theme
pp_plot(math ~ freelunch, star, theme = "dark")

# Produce default PP plot w/multiple groups
pp_plot(mean ~ grade, seda)

# Change reference group to third grade
pp_plot(mean ~ grade, 
		seda, 
		ref_group = "3")

# }