shiny/man/renderCachedPlot.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render-cached-plot.R
\name{renderCachedPlot}
\alias{renderCachedPlot}
\title{Plot output with cached images}
\usage{
renderCachedPlot(expr, cacheKeyExpr, sizePolicy = sizeGrowthRatio(width = 400,
  height = 400, growthRate = 1.2), res = 72, cache = "app", ...,
  env = parent.frame(), quoted = FALSE, outputArgs = list())
}
\arguments{
\item{expr}{An expression that generates a plot.}

\item{cacheKeyExpr}{An expression that returns a cache key. This key should
be a unique identifier for a plot: the assumption is that if the cache key
is the same, then the plot will be the same.}

\item{sizePolicy}{A function that takes two arguments, \code{width} and
\code{height}, and returns a list with \code{width} and \code{height}. The
purpose is to round the actual pixel dimensions from the browser to some
other dimensions, so that this will not generate and cache images of every
possible pixel dimension. See \code{\link{sizeGrowthRatio}} for more
information on the default sizing policy.}

\item{res}{The resolution of the PNG, in pixels per inch.}

\item{cache}{The scope of the cache, or a cache object. This can be
\code{"app"} (the default), \code{"session"}, or a cache object like
a \code{\link{diskCache}}. See the Cache Scoping section for more
information.}

\item{...}{Arguments to be passed through to \code{\link[grDevices]{png}}.
These can be used to set the width, height, background color, etc.}

\item{env}{The environment in which to evaluate \code{expr}.}

\item{quoted}{Is \code{expr} a quoted expression (with \code{quote()})? This
is useful if you want to save an expression in a variable.}

\item{outputArgs}{A list of arguments to be passed through to the implicit
call to \code{\link{plotOutput}} when \code{renderPlot} is used in an
interactive R Markdown document.}
}
\description{
Renders a reactive plot, with plot images cached to disk.
}
\details{
\code{expr} is an expression that generates a plot, similar to that in
\code{renderPlot}. Unlike with \code{renderPlot}, this expression does not
take reactive dependencies. It is re-executed only when the cache key
changes.

\code{cacheKeyExpr} is an expression which, when evaluated, returns an object
which will be serialized and hashed using the \code{\link[digest]{digest}}
function to generate a string that will be used as a cache key. This key is
used to identify the contents of the plot: if the cache key is the same as a
previous time, it assumes that the plot is the same and can be retrieved from
the cache.

This \code{cacheKeyExpr} is reactive, and so it will be re-evaluated when any
upstream reactives are invalidated. This will also trigger re-execution of
the plotting expression, \code{expr}.

The key should consist of "normal" R objects, like vectors and lists. Lists
should in turn contain other normal R objects. If the key contains
environments, external pointers, or reference objects -- or even if it has
such objects attached as attributes -- then it is possible that it will
change unpredictably even when you do not expect it to. Additionally, because
the entire key is serialized and hashed, if it contains a very large object
-- a large data set, for example -- there may be a noticeable performance
penalty.

If you face these issues with the cache key, you can work around them by
extracting out the important parts of the objects, and/or by converting them
to normal R objects before returning them. Your expression could even
serialize and hash that information in an efficient way and return a string,
which will in turn be hashed (very quickly) by the
\code{\link[digest]{digest}} function.
}
\section{Cache scoping}{


  There are a number of different ways you may want to scope the cache. For
  example, you may want each user session to have their own plot cache, or
  you may want each run of the application to have a cache (shared among
  possibly multiple simultaneous user sessions), or you may want to have a
  cache that persists even after the application is shut down and started
  again.

  To control the scope of the cache, use the \code{cache} parameter. There
  are two ways of having Shiny automatically create and clean up the disk
  cache.

\describe{
  \item{1}{To scope the cache to one session, use \code{cache="session"}.
    When a new user session starts -- in other words, when a web browser
    visits the Shiny application -- a new cache will be created on disk
    for that session. When the session ends, the cache will be deleted.
    The cache will not be shared across multiple sessions.}
  \item{2}{To scope the cache to one run of a Shiny application (shared
    among possibly multiple user sessions), use \code{cache="app"}. This
    is the default. The cache will be shared across multiple sessions, so
    there is potentially a large performance benefit if there are many users
    of the application. If plots cannot be safely shared across users, this
    should not be used.}
 }

  If either \code{"session"} or \code{"app"} is used, the cache will be 5 MB
  in size, and will be stored stored in a temporary directory. Note that a
  single cache will be shared for all plots within a single application.

  In some cases, you may want to have finer-grained control over the caching
  behavior. For example, you may want to use a larger or smaller cache, or
  you may want the cache to persist across multiple runs of an application,
  or even across multiple R processes. To use this finer-grained control,
  pass a \code{\link{DiskCache}} object as the \code{cache} parameter.

  Here are some ways to create a cache with other behaviors:

\describe{
  \item{3}{To have the cache persist across multiple runs of an R process,
    use \code{cache=DiskCache$new(dirname(tempdir()), "plot1_cache")}.
    This will create a subdirectory in your system temp directory named
    \code{plot1_cache} (replace \code{plot1_cache} with a unique name of
    your choosing). On most platforms, this directory will be removed when
    your system reboots.}
  \item{4}{To have the cache persist even across multiple reboots, you
    can create the cache in a location outside of the temp directory.
    For example, it could be a subdirectory of the application, as in
    \code{cache=DiskCache$new("plot1_cache")}. You may need to manually
    remove this directory to clear the cache.}
}
}

\examples{
## Only run examples in interactive R sessions
if (interactive()) {

# A basic example
shinyApp(
  fluidPage(
    sidebarLayout(
      sidebarPanel(
        sliderInput("n", "Number of points", 4, 32, value = 8, step = 4)
      ),
      mainPanel(plotOutput("plot"))
    )
  ),
  function(input, output, session) {
    output$plot <- renderCachedPlot({
        Sys.sleep(2)  # Add an artificial delay
        seqn <- seq_len(input$n)
        plot(mtcars$wt[seqn], mtcars$mpg[seqn],
             xlim = range(mtcars$wt), ylim = range(mtcars$mpg))
      },
      cacheKeyExpr = { list(input$n) }
    )
  }
)



# An example that allows resetting the cache
mydata <- reactiveVal(data.frame(x = rnorm(400), y = rnorm(400)))

ui <- fluidPage(
  sidebarLayout(
    sidebarPanel(
      sliderInput("n", "Number of points", 50, 400, 100, step = 50),
      actionButton("newdata", "New data")
    ),
    mainPanel(
      plotOutput("plot")
    )
  )
)

server <- function(input, output, session) {
  observeEvent(input$newdata, {
    mydata(data.frame(x = rnorm(400), y = rnorm(400)))
  })

  output$plot <- renderCachedPlot(
    {
      Sys.sleep(2)
      d <- mydata()
      seqn <- seq_len(input$n)
      plot(d$x[seqn], d$y[seqn], xlim = range(d$x), ylim = range(d$y))
    },
    cacheKeyExpr = { list(input$n, mydata()) },
    cache = "app"
  )
}

shinyApp(ui, server)


}

}
\seealso{
See \code{\link{renderPlot}} for the regular, non-cached version of
  this function.
}