DurgaBrackets {Durga}

Annotate a DurgaPlot with confidence brackets

Description

Brackets are added to a DurgaPlot that already exists. That means you must ensure there is sufficient space for the brackets above the plot. To do this, either specify ylim to DurgaPlot, or create a large top margin (par(mar = c(...))) and the turn off the plot frame (DurgaPlot(..., frame.plot = FALSE)). In either case, experiment with the values until the result is visually pleasing. The annotation can be drawn into the margin as it will not be cropped.

Usage

DurgaBrackets(
  plot.stats,
  contrasts,
  labels = "level CI",
  br.lwd = NULL,
  br.col = NULL,
  br.lty = 1,
  lb.col = NULL,
  lb.font = NULL,
  lb.cex = 1,
  snap.to = 1,
  shorten = 1.5,
  tip.length = 2,
  data.gap = 2.5,
  vertical.gap = 1.3,
  text.pad = 1.5,
  round.fn = function(x) signif(x, 2),
  ...
)

Arguments

plot.stats

Object returned by the call to DurgaPlot

contrasts

Set of contrasts (i.e. group comparisons) to be displayed as brackets. Defaults to contrasts passed to DurgaDiff. Can be specified as a character string ("group 1 - group 2") or a list of DurgaDiff objects. The bracket label always displays the effect size for right-hand-group - left-hand-group, regardless of the order that groups are specified in contrasts, i.e. contrasts = "G1 - G2" will appear the same as contrasts = "G2 - G1".

labels

Text to display above each bracket. May be NULL, otherwise one of: "diff" (displayed text is "<difference in means>"), "CI" ("[<lower>, <upper>]"), "level CI" ("<level>% CI [<lower>, <upper>]") or "diff CI" ("<difference in means> [<lower>, <upper>]"); a vector of texts to display for each element of diffs, or a function called with one argument; a DurgaGroupDiff object, which should return the label to be displayed.

br.col, br.lwd, br.lty

Graphical parameters (colour, line weight and style) that control the bracket appearance - passed to segments. May be a single value or a vector with one value per bracket. Refer to Details for default values.

lb.col, lb.cex, lb.font

Graphical parameters (colour, scale and font) that control the label appearance - passed to text. May be a single value or a vector with one value per bracket. Refer to Details for default values.

snap.to

Snaps the base of the lowest brackets onto horizontal grid lines separated by snap.to mm. Used to improve aesthetics of vertical alignment.

shorten

Amount (mm) to shrink brackets at each end

tip.length

Length of bracket tips (mm). May be a vector with length 2; length of tip at groups 1 and 2 respectively

data.gap

Vertical distance (mm) between top-most data point and bottom of bracket

vertical.gap

Vertical distance (mm) between overlapping brackets

text.pad

Gap (mm) between bracket and text

round.fn

By default, numbers displayed as text are printed to 2 significant figures. To change this behaviour, set round.fn to a function with one argument that converts its argument to the value to be displayed.

...

Additional arguments passed to text

Details

Default values for br.lwd, br.col, lb.col and lb.font depend on the confidence intervals (CI) being plotted. If the CI covers 0, brackets and text are grey. If the CI does not cover 0, text is dark grey and bold, and brackets are dark grey with a line width of 2.

Value

No return value. DurgaBrackets is called for its side effect of adding confidence brackets to the current plot.

See Also

DurgaPlot

Examples

d <- DurgaDiff(petunia, 1, 2)
# Don't draw frame because brackets will appear in the upper margin
p <- DurgaPlot(d, ef.size = FALSE, frame.plot = FALSE)
# Add the brackets to the plot
DurgaBrackets(p, lb.cex = 0.8)

# Only draw brackets that do not include zero
p <- DurgaPlot(d, ef.size = FALSE, frame.plot = FALSE)
diffs <- Filter(function(pwes) (pwes$bca[4] > 0 || pwes$bca[5] < 0), p$es$group.differences)
DurgaBrackets(p, contrasts = diffs)