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 |
contrasts |
Set of contrasts (i.e. group comparisons) to be plotted.
Defaults to contrasts passed to |
group.dx |
Used to shift group centres horizontally. E.g.,
|
group.colour |
Colours to use for each group. Either an
|
points |
If not |
points.method |
Method used to avoid overplotting points. Use
|
points.spread |
Numeric value used to adjust the points scatter method
points horizontally (ignored if |
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
|
violin |
If not |
violin.shape |
Desired violin shape - left-half only ( |
violin.fill |
Colour used to fill violins. Specify |
violin.params |
Additional graphical parameters applied to drawing
violins. May include |
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 |
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 |
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
|
box.params |
List with additional graphical parameters to control the
box plot appearance. Many aspects of the plots can be controlled, e.g.
|
box.dx |
Horizontal shift to be applied to each box. |
bar |
If not |
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 |
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.violin |
If not |
ef.size.violin.fill |
Colour used to fill effect size violins. Default
is a transparent version of |
ef.size.violin.shape |
Shape of the effect size violin. One of
|
ef.size.violin.trunc |
If |
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.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 |
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 |
ef.size.top.pad |
Gap (in units of default character height scaled by
|
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 |
paired |
If not |
paired.lty |
Line style for pair lines. |
paired.lwd |
Line width for pair lines. |
central.tendency |
If not |
central.tendency.type |
Should the indicated measure of central tendency
be |
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
|
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 ( |
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.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
|
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 |
extents |
Matrix with the x-axis locations and y-axis extents of each displayed group. |
plot.differences |
A list of the
displayed differences, as |
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.
See Also
DurgaDiff
, DurgaBrackets
,
DurgaTransparent
, offsetX
, boxplot
,
bxp
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)