capturePlot {R.devices}

Captures a plot such that it can be redrawn later/elsewhere

Description

Captures a plot such that it can be redrawn later/elsewhere.

This feature is only supported in R (>= 3.3.0).

Usage

capturePlot(expr, envir=parent.frame(), type=nulldev, ...)

Arguments

expr

The expression of graphing commands to be evaluated.

envir

The environment where expr should be evaluated.

type

The type of graphics device used in the background. The choice should not matter since the result should be identical regardless. All graphics is captured but any output is also voided by sending the output to a "null" file.

...

Additional arguments passed to the graphics device.

Details

Note that plot dimensions/aspect ratios are not recorded. This means that one does not have to worry about those when recording the plot. Instead, they are specified when setting up the graphics device(s) in which the recorded plot is replayed (see example).

Value

Returns a recordedplot object, which can be replayPlot():ed. If replayed in an interactive session, the plot is displayed in a new window. For conveniency, the object is also replayed when print():ed.

Replaying / replotting on a different architecture

In order to replay a recordedplot object, it has to be replayed on an architecture that is compatible with the one who created the object. If this is not the case, then replayPlot() will generate an Incompatible graphics state error. The as.architecture() function of this package tries to coerce between different architectures, such that one can replay across architectures using replayPlot(as.architectures(g)). For convenience, the recorded plot returned by capturePlot() is automatically coerced when print():ed.

Author(s)

Henrik Bengtsson

References

[1] Paul Murrell et al., Recording and Replaying the Graphics Engine Display List, December 2015. https://www.stat.auckland.ac.nz/~paul/Reports/DisplayList/dl-record.html

See Also

Internally recordPlot() is used.

Examples

if (getRversion() >= "3.3.0") {
oopts <- R.devices::devOptions("*", path=file.path(tempdir(), "figures"))

g <- capturePlot({
  plot(1:10)
})

## Display
print(g)

## Display with a 2/3 height-to-width aspect ratio
toDefault(aspectRatio=2/3, { print(g) })

## Redraw to many output formats using whatever PNG, EPS, and PDF
## device outputs available
devEval(c("{png}", "{eps}", "{pdf}"), aspectRatio=2/3, print(g))

R.devices::devOptions("*", path=oopts$path)
} ## if (getRversion() >= "3.3.0")