The R Project SVN R

Rev

Rev 86000 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
42333 ripley 1 
% File src/library/grDevices/man/recordplot.Rd
68948 ripley 2 
% Part of the R package, https://www.R-project.org
61579 ripley 3 
% Copyright 1995-2013 R Core Team
42333 ripley 4 
% Distributed under GPL 2 or later
5 
 
27442 ripley 6 
\name{recordPlot}
7 
\alias{replayPlot}
56186 murdoch 8 
\alias{recordPlot}
27442 ripley 9 
\alias{print.recordedplot}
10 
\title{Record and Replay Plots}
11 
\description{
12 
  Functions to save the current plot in an \R variable, and to replay it.
13 
}
14 
\usage{
69595 murrell 15 
recordPlot(load=NULL, attach=NULL)
16 
replayPlot(x, reloadPkgs=FALSE)
27442 ripley 17 
}
18 
\arguments{
69595 murrell 19 
  \item{load}{If not \code{NULL}, a character vector of package names,
20 
    which are saved as part of the recorded plot.}
21 
  \item{attach}{If not \code{NULL}, a character vector of package names,
22 
    which are saved as part of the recorded plot.}
23 
  \item{x}{A saved plot.}
24 
  \item{reloadPkgs}{A logical indicating whether to reload and/or
25 
    reattach any packages that were saved as part of the recorded plot.}
27442 ripley 26 
}
27 
\details{
86000 hornik 28 
  These functions record and replay the display list of the current
27442 ripley 29 
  graphics device.  The returned object is of class
30 
  \code{"recordedplot"}, and \code{replayPlot} acts as a \code{print}
31 
  method for that class.
58648 ripley 32 
 
33 
  The returned object is stored as a pairlist, but the usual methods for
34 
  examining \R objects such as \code{\link{deparse}} and
61433 ripley 35 
  \code{\link{str}} are liable to mislead.
30649 murrell 36 
}
38921 ripley 37 
\section{Warning}{
69314 murrell 38 
  The format of recorded plots may change between \R versions, so
39 
  recorded plots should \strong{not} be used as a permanent
40 
  storage format for \R plots.
41 
 
42 
  As of \R 3.3.0, it is possible (again)
43 
  to replay a plot from another \R session using, for example,
44 
  \code{\link{saveRDS}} and \code{\link{readRDS}}.
45 
  It is even possible to replay a plot from another \R version,
46 
  however, this will produce warnings, may produce errors,
47 
  or something worse.
27442 ripley 48 
}
69314 murrell 49 
\section{Note}{
50 
  Replay of a recorded plot may not produce the correct result
51 
  (or may just fail) if the display list contains a call to
52 
  \code{\link{recordGraphics}} which in turn contains an expression
53 
  that calls code from a non-base package other than \pkg{graphics}
54 
  or \pkg{grid}.  The most well-known example of this is a plot
70922 hornik 55 
  drawn with the package \CRANpkg{ggplot2}.  One solution is to load
69314 murrell 56 
  the relevant package(s) before replaying the recorded plot.
69595 murrell 57 
  The \code{load} and \code{attach} arguments to \code{recordPlot}
58 
  can be used to automate this - any packages named in \code{load}
59 
  will be reloaded, via \code{\link{loadNamespace}}, and any packages
60 
  named in \code{attach} will be reattached, via \code{\link{library}},
61 
  as long as \code{reloadPkgs} is \code{TRUE} in the call to
62 
  \code{replayPlot}.  This is only relevant when attempting to
63 
  replay in one R session a plot that was recorded in a different R session.
69314 murrell 64 
}
27442 ripley 65 
\value{
30649 murrell 66 
  \code{recordPlot} returns an object of class \code{"recordedplot"}.
27442 ripley 67 
 
68 
  \code{replayPlot} has no return value.
69 
}
84839 murrell 70 
\references{
88603 hornik 71 
  \bibshow{R:Murrell+Ooms+Allaire:2015}
84839 murrell 72 
}
63984 murdoch 73 
\seealso{
86000 hornik 74 
  The display list can be turned on and off using \code{\link{dev.control}}.
63984 murdoch 75 
  Initially recording is on for screen devices, and off for print devices.
76 
}
27442 ripley 77 
\keyword{iplot}