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

Arguments

… All named arguments override arguments from the previous calls. Arguments not supplied to tinyplot_add remain unchanged from the previous call.

Value

No return value, called for side effect of producing a plot.

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

  • There are two important limitations when adding layers to faceted plots:

    • Avoid resizing the graphics window after the first layer is drawn, since it will lead to any subsequent layers being misaligned. This is a limitation of base R’s graphics engine and cannot be reliably preempted or corrected by tinyplot. Note that resizing non-faceted plots is always fine, though. See: https://github.com/grantmcdermott/tinyplot/issues/313

    • On Positron, specifically, alignment issues may occur even without resizing. A warning will be triggered when (i) Positron is detected and (ii) a user attempts to add layers to a faceted plot. Again, this issue is not present for non-faceted plots. See the upstream bug report: https://github.com/posit-dev/positron/issues/7316

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

Examples

library("tinyplot")

tinyplot(Sepal.Width ~ Sepal.Length | Species,
  facet = ~Species,
  data = iris)

tinyplot_add(type = "lm") ## or : plt_add(type = "lm")

## Note: the previous function 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)