tinyplot (version 0.8.0)

tinyplot_add: Add new elements to the current tinyplot

Description

This convenience function grabs the preceding tinyplot call and updates it with any new arguments that have been explicitly provided by the user. It then injects add=TRUE and evaluates the updated call, thereby drawing a new layer on top of the existing plot. plt_add() is a shorthand alias for tinyplot_add().

Usage

tinyplot_add(...)
plt_add(...)

Value

By default, no return value; called for the side effect of producing a plot. If record = TRUE (or globally via tpar(record = TRUE)), the plot is instead returned invisibly as a "recordedtinyplot" object, which can be replayed later; see recordedtinyplot.

Arguments

...

All named arguments override arguments from the previous calls. Arguments not supplied to tinyplot_add remain unchanged from the previous call. Arguments are captured unevaluated and spliced into the updated call, so those that rely on non-standard evaluation against data---e.g. subset = cyl == 4 or weights = wt---behave the same as in a direct tinyplot call.

Adding versus drawing

tinyplot_add() layers new elements on top of the existing plot. The complementary, top-level tinyplot(..., draw = <>) argument works in the opposite direction: it layers underneath the main plot elements.

However, note that draw is fully generic---it accepts any drawing or annotation expression---and this includes tinyplot_add() itself. Passing draw = tinyplot_add(...) thus yields a regular tinyplot layer, inheriting from the enclosing call in the usual way, but drawn below the main elements rather than above them. See Examples.

Limitations

• tinyplot_add() works reliably only when adding to a plot originally created using the tinyplot.formula method with a valid data argument. We cannot guarantee correct behavior if the original plot was created with the atomic tinyplot.default method, due to potential environment mismatches. (An exception is when the original plot arguments---x, y, etc.---are located in the global environment.)

• Automatic legends for the added elements will be turned off.

Examples

#
## Basic use

tinyplot(Sepal.Width ~ Sepal.Length | Species,
  facet = ~Species,
  data = iris)
tinyplot_add(type = "lm") ## or : plt_add(type = "lm")

## the previous line is equivalent to (but much more convenient than)
## re-writing the full call with the new type and `add=TRUE`:
# tinyplot(Sepal.Width ~ Sepal.Length | Species,
#          facet = ~Species,
#          data = iris,
#          type = "lm",
#          add = TRUE)

## arguments relying on non-standard evaluation (e.g. `subset`) work too:
tinyplot(mpg ~ wt, data = mtcars)
tinyplot_add(subset = cyl == 4, col = "red", pch = 16)

#
## add(ing) vs draw(ing)

dat = data.frame(x = 1:3, y = 0)

## the `draw` argument layers *underneath* the main plot elements...
tinyplot(
  y ~ x, data = dat, pch = 19, cex = 10,
  draw = abline(h = 0, lwd = 4, col = "hotpink")
)

## ... whereas `tinyplot_add()` layers *on top*.
tinyplot(y ~ x, data = dat, pch = 19, cex = 10)
tinyplot_add(type = type_hline(0), lwd = 4, col = "hotpink")

## combine = best of both worlds? Since `draw` is generic, we can hand it
## `tinyplot_add()` directly. The line is drawn as a regular tinyplot layer,
## but underneath once more. This is especially useful for, say. flipped
## plots since correct axes inheritance is preserved. (Note that a plain
## `abline(h = 0)` is not flip-aware)
tinyplot(
  y ~ x, data = dat, pch = 19, cex = 10, flip = TRUE,
  draw = tinyplot_add(type = type_hline(0), lwd = 4, col = "hotpink")
)