Plot output with cached images — renderCachedPlot

renderCachedPlot(
  expr,
  cacheKeyExpr,
  sizePolicy = sizeGrowthRatio(width = 400, height = 400, growthRate = 1.2),
  res = 72,
  cache = "app",
  ...,
  outputArgs = list()
)

Arguments

expr	An expression that generates a plot.
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.
sizePolicy	A function that takes two arguments, `width` and `height`, and returns a list with `width` and `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 `sizeGrowthRatio()` for more information on the default sizing policy.
res	The resolution of the PNG, in pixels per inch.
cache	The scope of the cache, or a cache object. This can be `"app"` (the default), `"session"`, or a cache object like a `diskCache()`. See the Cache Scoping section for more information.
...	Arguments to be passed through to `grDevices::png()`. These can be used to set the width, height, background color, etc.
outputArgs	A list of arguments to be passed through to the implicit call to `plotOutput()` when `renderPlot` is used in an interactive R Markdown document.

Description

Renders a reactive plot, with plot images cached to disk.

Details

expr is an expression that generates a plot, similar to that in renderPlot. Unlike with renderPlot, this expression does not take reactive dependencies. It is re-executed only when the cache key changes.

cacheKeyExpr is an expression which, when evaluated, returns an object which will be serialized and hashed using the 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 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, 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 digest::digest() function.

Internally, the result from cacheKeyExpr is combined with the name of the output (if you assign it to output$plot1, it will be combined with "plot1") to form the actual key that is used. As a result, even if there are multiple plots that have the same cacheKeyExpr, they will not have cache key collisions.

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 cache parameter. There are two ways of having Shiny automatically create and clean up the disk cache.

1: To scope the cache to one run of a Shiny application (shared among possibly multiple user sessions), use 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. When the application stops running, the cache will be deleted. If plots cannot be safely shared across users, this should not be used.
2: To scope the cache to one session, use 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.

If either "app" or "session" is used, the cache will be 10 MB in size, and will be stored stored in memory, using a memoryCache() object. Note that the cache space will be shared among all cached plots within a single application or session.

In some cases, you may want more control over the caching behavior. For example, you may want to use a larger or smaller cache, share a cache among multiple R processes, or you may want the cache to persist across multiple runs of an application, or even across multiple R processes.

To use different settings for an application-scoped cache, you can call shinyOptions() at the top of your app.R, server.R, or global.R. For example, this will create a cache with 20 MB of space instead of the default 10 MB:

  shinyOptions(cache = memoryCache(size = 20e6))

To use different settings for a session-scoped cache, you can call shinyOptions() at the top of your server function. To use the session-scoped cache, you must also call renderCachedPlot with cache="session". This will create a 20 MB cache for the session:

  function(input, output, session) {
    shinyOptions(cache = memoryCache(size = 20e6))

    output$plot <- renderCachedPlot(
      ...,
      cache = "session"
    )
  }

If you want to create a cache that is shared across multiple concurrent R processes, you can use a diskCache(). You can create an application-level shared cache by putting this at the top of your app.R, server.R, or global.R:

  shinyOptions(cache = diskCache(file.path(dirname(tempdir()), "myapp-cache"))

This will create a subdirectory in your system temp directory named myapp-cache (replace myapp-cache with a unique name of your choosing). On most platforms, this directory will be removed when your system reboots. This cache will persist across multiple starts and stops of the R process, as long as you do not reboot.

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:

  shinyOptions(cache = diskCache("./myapp-cache"))

In this case, resetting the cache will have to be done manually, by deleting the directory.

You can also scope a cache to just one plot, or selected plots. To do that, create a memoryCache() or diskCache(), and pass it as the cache argument of renderCachedPlot.

Interactive plots

renderCachedPlot can be used to create interactive plots. See plotOutput() for more information and examples.