R: Group and effect size plotting in base R.

DurgaPlot {Durga}

R Documentation

Group and effect size plotting in base R.

Description

Plot grouped data and effect size in base R, with control over a large range of possible display formats and options. To plot your data, first calculate group differences by calling DurgaDiff, then pass the result to DurgaPlot. Because there are so many parameters to this function, they are prefixed according to the component they affect. Hence, for example, all parameters that affect box plots are prefixed with box.

Usage

DurgaPlot(
  es,
  contrasts,
  group.dx = 0,
  group.colour = "Set2",
  points = TRUE,
  points.method = c("quasirandom", "pseudorandom", "smiley", "maxout", "frowney",
    "minout", "tukey", "tukeyDense", "jitter", "overplot"),
  points.spread = ifelse(points.method == "jitter", 0.1, 0.3),
  points.dx = group.dx,
  points.adjust = 1,
  points.params = list(),
  violin = isFALSE(box) && isFALSE(bar),
  violin.shape = c("left-half", "right-half", "full"),
  violin.fill = TRUE,
  violin.params = list(),
  violin.adj = 1.5,
  violin.width = 0.35,
  violin.trunc = TRUE,
  violin.dx = group.dx,
  box = FALSE,
  box.fill = TRUE,
  box.outline = TRUE,
  box.notch = FALSE,
  box.params = list(boxwex = 0.8, staplewex = 0.5, outwex = 0.5),
  box.dx = group.dx,
  bar = FALSE,
  bar.fill = TRUE,
  bar.width = 0.8,
  bar.dx = group.dx,
  ef.size = TRUE,
  ef.size.position = c("right", "below"),
  ef.size.violin = TRUE,
  ef.size.violin.fill = TRUE,
  ef.size.violin.shape = c("right-half", "left-half", "full"),
  ef.size.violin.trunc = TRUE,
  ef.size.pch = 17,
  ef.size.lty = 1,
  ef.size.lwd = 2,
  ef.size.ticks = NULL,
  ef.size.label = es$effect.name,
  ef.size.dx = 0,
  ef.size.adj.margin = TRUE,
  ef.size.top.pad = 2.5,
  ef.size.height = 0.35,
  ef.size.mean.line.dx = group.dx,
  ef.size.line.col = "grey50",
  ef.size.line.lty = ifelse(ef.size.position == "below", 3, 1),
  ef.size.line.lwd = 1,
  ef.size.params = list(),
  paired = es$paired.data,
  paired.lty = 1,
  paired.lwd = 1,
  central.tendency = isFALSE(box) && isFALSE(bar),
  central.tendency.type = c("mean", "median"),
  central.tendency.symbol = c("point", "segment"),
  central.tendency.width = violin.width,
  central.tendency.params = list(),
  central.tendency.dx = group.dx,
  error.bars = !isFALSE(central.tendency) || !isFALSE(bar),
  error.bars.type = c("CI", "SD", "SE"),
  error.bars.lty = 1,
  error.bars.lwd = 3,
  error.bars.cross.width = 0,
  x.axis = TRUE,
  x.axis.dx = group.dx,
  xlab = "",
  left.ylab = es$data.col.name,
  left.las = graphics::par("las"),
  add = FALSE,
  xlim,
  ylim,
  ...
)

Arguments

`es`	Data returned from a call to `DurgaDiff`
`contrasts`	Set of contrasts (i.e. group comparisons) to be plotted. Defaults to contrasts passed to `DurgaDiff`, otherwise `". - group1"` (where `group1` is the first group). See Details for more information.
`group.dx`	Used to shift group centres horizontally. E.g., `group.dx = c(0.1, -0.1)` will group into pairs. Individual components can be shifted independently using the appropriate `*.dx` parameters.
`group.colour`	Colours to use for each group. Either an `RColorBrewer` palette name or a vector of colours.
`points`	If not `FALSE`, points are plotted. If `TRUE`, points are displayed with a default colour (which is the group colour with 40% transparency). You may specify a vector of colours; if length 1, all points are drawn with the specified colour. If length is less than the number of data points, points in each group are drawn with the appropriate colour (extra colours are ignored). Otherwise, `points` should be a vector of colours with a value for each data point.
`points.method`	Method used to avoid overplotting points. Use `"overplot"` to overplot points and `"jitter"` to add random noise to each x-value. See `offsetX` for remaining methods.
`points.spread`	Numeric value used to adjust the points scatter method points horizontally (ignored if `points.method = "overplot"`).
`points.dx`	Horizontal shift to be applied to points in each group.
`points.adjust`	Adjust the bandwidth used to calculate kernel density when drawing points. Smaller values mean a tighter fit.
`points.params`	List of named parameters to pass on to `points`, e.g. `DurgaPlot(es, points = "black", points.params = list(pch = 21, bg = as.numeric(factor(data$Sex)) + 1))`.
`violin`	If not `FALSE`, violin plots are drawn. Violins are simply probability density plots, with density on the x-axis and value on the y-axis. If `TRUE`, violins are drawn in default colours. Otherwise specifies the colour of the violin borders.
`violin.shape`	Desired violin shape - left-half only (`"left"`), right-half only (`"right"`), or a full violin (`"full"`).
`violin.fill`	Colour used to fill violins. Specify `FALSE` or `NA` to leave violins unfilled.
`violin.params`	Additional graphical parameters applied to drawing violins. May include `density`, `angle`, `lty`, `lwd`, `lend` etc. Values are passed on to `polygon`; see its help page for details.
`violin.adj`	Value used to control violin plot smoothness by adjusting the kernel density bandwidth. Higher values produce a smoother plot. Passed unchanged as the `adjust` argument to the `density` function.
`violin.width`	Width of maximum violin horizontal extents, as a proportion of the distance between groups.
`violin.trunc`	Numeric value that specifies what vertical proportion of the violin is truncated.
`violin.dx`	Horizontal shift to be applied to each violin.
`box`	If not `FALSE`, draw a box-and-whisker plot of the grouped values. Value may be a colour, in which case the box borders are plotted with the colour(s). See `boxplot`.
`box.fill`	Colour used to fill the bodies of the box-and-whisker plot. If FALSE or NA, bodies are not filled.
`box.outline`	If FALSE, don't draw outliers with the box plot.
`box.notch`	If TRUE, draws notches in the sides of the boxes. See `boxplot.stats` for the calculations used.
`box.params`	List with additional graphical parameters to control the box plot appearance. Many aspects of the plots can be controlled, e.g. `box.params = list(outpch = NA)` prevents outlier points from being drawn. See `bxp` graphical parameters for a complete list.
`box.dx`	Horizontal shift to be applied to each box.
`bar`	If not `FALSE`, draw a bar plot of the group means or medians, according to `central.tendency`. May be `TRUE` or a colour.
`bar.fill`	Colour used to fill bars.
`bar.width`	Width of bars.
`bar.dx`	Horizontal shift to be applied to each bar.
`ef.size`	If not `FALSE`, effect sizes are plotted. May be `TRUE` or a colour.
`ef.size.position`	Effect sizes are plotted to the right of the main plot if there is only one effect size to plot and `ef.size.position != "below"`. If the effect size is drawn to the right, you will need to increase the size of the right margin before plotting (see `par(mar = ...)`).
`ef.size.violin`	If not `FALSE`, boostrapped effect size estimates are shown as a violin plot. May be a colour that is used for the violin border and fill (unless `ef.size.violin.fill` is specified).
`ef.size.violin.fill`	Colour used to fill effect size violins. Default is a transparent version of `ef.size.violin`.
`ef.size.violin.shape`	Shape of the effect size violin. One of `"right-half"`, `"left-half"` or `"full"`.
`ef.size.violin.trunc`	If `TRUE`, effect size violin is truncated vertically so that it just covers the estimated effect size.
`ef.size.pch`	Symbol to represent mean effect size.
`ef.size.lty`	Line style for the effect size error bar.
`ef.size.lwd`	Line weight for the effect size error bar.
`ef.size.ticks`	Optional locations and labels for ticks on the effect size y-axis. E.g. to interpret effect size using Cohen's default values, specify `ef.size.ticks = c("Large negative effect" = -0.8, "Medium negative effect" = -0.5, "Small negative effect" = -0.2, "No effect" = 0, "Small positive effect" = 0.2, "Medium positive effect" = 0.5, "Large positive effect" = 0.8)`
`ef.size.label`	Label to display on y-axis for effect size.
`ef.size.dx`	Horizontal shift to be applied to each contrast/effect size. Unlike other `.dx` parameters, `ef.size.dx` is indexed by contrast rather than group. When effect size is below the plot, the `group.dx` for the group above the effect size is also added.
`ef.size.adj.margin`	If TRUE (the default), the right margin (if ES is right) or bottom margin (if ES is below) is automatically increased to make room to display the effect size or axis annotations. The margins are restored before control returns from `DurgaPlot`.
`ef.size.top.pad`	Gap (in units of default character height scaled by `cex`) between the bottom of the main plot region and the top of the effect size plot region. Only applies when effect size is positioned below.
`ef.size.height`	Height of the effect size plot region as a proportion of the main plot region. Only applies when effect size is positioned below.
`ef.size.mean.line.dx`	Horizontal shift to be applied to the start (i.e. left end) of the group mean horizontal lines when effect size is on the right.
`ef.size.line.col`	Colour of horizontal effect-size lines that depict group means if effect size is on the right, otherwise colour of line at y = 0.
`ef.size.line.lty`	Line style of horizontal effect-size lines.
`ef.size.line.lwd`	Line width of horizontal effect-size lines.
`ef.size.params`	List of graphical parameters to apply when drawing effect sizes. These parameters are passed to `par` before drawing the effect size. E.g. `ef.size.params = list(mgp = c(3.5, 1, 0))` will shift the effect size y-axis label to the left or right (for `ef.size.position` `"below"` or `"right"` respectively). `ef.size.params = list(las = 1)` will rotate the effect size axis labels without rotating the main axis labels.
`paired`	If not `FALSE` and the data a paired, lines are drawn joining the individual data points. May be `TRUE` or a colour. Defaults to `TRUE` if the data are paired (i.e. the `id.col` argument was specified in the call to `DurgaDiff`).
`paired.lty`	Line style for pair lines.
`paired.lwd`	Line width for pair lines.
`central.tendency`	If not `FALSE`, a visual indicator of central tendency is drawn. May be `TRUE` or a colour, in which case it is used for mean/median and error bars.
`central.tendency.type`	Should the indicated measure of central tendency be `"mean"` or `"median"`?
`central.tendency.symbol`	Should central tendency be shown as a point or a horizontal line segment?
`central.tendency.width`	Width of the central tendency line segment.
`central.tendency.params`	Additional arguments to be passed to `points` (if `central.tendency.symbol == "point"`) or `segments` (if `central.tendency.symbol == "segment"`).
`central.tendency.dx`	Horizontal shift to apply to central tendency indicator and error bars.
`error.bars`	Should error bars be displayed? May be the colour to be used for error bars.
`error.bars.type`	Should error bars depict 95% confidence intervals of the mean (`"CI"`), standard deviation (`"SD"`) or standard error (`"SE"`)?
`error.bars.lty`	Line style for error bars.
`error.bars.lwd`	Line width for error bars.
`error.bars.cross.width`	Length (in inches) of the horizontal crossbars at the ends of the error bars. If 0, no crossbar is drawn.
`x.axis`	if TRUE, display the x-axis ticks and labels. The effect of `x.axis = FALSE` is similar to setting `xaxt = "n"` in a base R plot.
`x.axis.dx`	Horizontal shifts to be applied to each x-axis tick and label.
`xlab`	X axis label.
`left.ylab`	Left-hand y-axis label.
`left.las`	Orientation of axis labels on left-hand y-axis label (0 = parallel to axis, 1 = horizontal).
`add`	If TRUE, the effect size plot is added to the current plot. If FALSE, a new plot is created.
`xlim`, `ylim`	If specified, overrides the default plot extents.
`...`	Additional arguments are passed on to the `plot` function.

Details

Group data may be visualised in multiple ways: points, violin, box and bar. Each visualisation type is controlled by a set of parameters with the same prefix. To display a type, for example box plots, specify box = TRUE. Rather than box = TRUE, you may specify a colour (e.g. box \ "blue"), which is used as the border/outline for the boxes. You may also specify a vector of colours, one for each group. For points, you may specify a colour for each individual point. When colours are not specified, they default to the group colours (group.colour).

Group data annotations are controlled with parameters central.tendency and error.bars. central.tendency visually represents the mean or median (central.tendency.type) of each group, while error.bars are vertical bars showing the 95% CI of the mean, standard deviation or standard error of the groups (error.bars.type).

An effect size (for our purposes) is the difference in means between two groups. Effect size display is controlled by ef.size. The set of effect sizes (aka "contrasts") to be plotted is controlled by the contrasts parameter. If a single effect size is displayed, it may be positioned to the right of - or below - the main plot (ef.size.position). If more than one effect size is displayed, it must be below the main plot. If below, an effect size is drawn underneath its primary group. See DurgaBrackets for a way to display multiple effect sizes that would overlap if displayed as normal effect sizes.

Custom labels for individual effects can be specified as part of the contrasts parameter. If contrasts is a named vector, the names are used as contrast labels, e.g. contrasts = c("Adult change" = "adult - control", "Juvenile change" = "juvenile - control"). A more flexible (although more advanced) method is to assign the label.plot member of a DurgaDiff object within x, see Examples for usage.

The contrasts parameter may be a single string, a vector of strings, or a matrix. A single string has a format such as "group1 - group2, group3 - group4". A single asterisk, "*" creates contrasts for all possible pairs of groups. A single string such as ".- control" compares all groups against the "control" group, i.e. the "." expands to all groups except the named group. A vector of strings looks like c("group1 - group2", "group3 - group4"). If a matrix is specified, it must have a column for each contrast, with the first group in row 1 and the second in row 2. See also the contrasts parameter to DurgaDiff. It is an error to attempt to plot a contrast that was not estimated by DurgaDiff.

Value

A list (returned invisibly) with 4 elements:

`es`	Value of the `es` parameter.
`extents`	Matrix with the x-axis locations and y-axis extents of each displayed group.
`plot.differences`	A list of the displayed differences, as `DurgaGroupDiff` objects. Will be an empty list if no effect sizes are shown.
`palette`	Vector of colours used by default for each group.

References

Gardner, M. J., & Altman, D. G. (1986). Confidence intervals rather than P values: estimation rather than hypothesis testing. Br Med J (Clin Res Ed), 292(6522), 746-750. doi:10.1136/bmj.292.6522.746

Cumming, G. (2012). Understanding the new statistics : effect sizes, confidence intervals, and meta-analysis (1st edition ed.). New York: Routledge.

Examples


d <- DurgaDiff(petunia, "height", "group")
# Default plot
DurgaPlot(d)

# Boxplot with a single effect size plotted on the right
DurgaPlot(d, contrasts = "westerham_cross - self_fertilised",
          box = TRUE, points = "black", points.params = list(cex = 0.8))

# Use confidence brackets to show all group differences
p <- DurgaPlot(d, ef.size = FALSE, group.colour = "Set1",
          points = "black", points.method = "jitter",
          points.params = list(pch = 21), points.dx = 0.15,
          violin.dx = -0.05, violin = "black", violin.adj = 0.5,
          ylim = c(12, 75))
DurgaBrackets(p)

# Adjust group names, contrasts
d <- DurgaDiff(petunia, 1, 2,
               groups = c("self-fertilised" = "self_fertilised",
                          "intercrossed" = "inter_cross",
                          "Westerham-crossed" = "westerham_cross"),
               contrasts = c("Westerham-crossed - self-fertilised",
                             "Westerham-crossed - intercrossed",
                             "intercrossed - self-fertilised"))
# Shift the 2nd effect size horizontally (Westerham-crossed - intercrossed)
# so it doesn't overlap another
DurgaPlot(d, ef.size.dx = c(0, -2, 0))

# Custom difference labels with italics
d <- DurgaDiff(petunia, 1, 2)
d$group.differences[[3]]$label.plot <- expression(italic("sp. 2")~"-"~italic("sp. 1"))
d$group.differences[[2]]$label.plot <- expression(italic("sp. 3")~"-"~italic("sp. 1"))
DurgaPlot(d)

[Package Durga version 2.0 Index]