Plot output with cached images — renderCachedPlot

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

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 cachem::cache_disk(). 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.

alt

Alternate text for the HTML <img> tag if it cannot be displayed or viewed (i.e., the user uses a screen reader). In addition to a character string, the value may be a reactive expression (or a function referencing reactive values) that returns a character string. NULL or "" is not recommended because those should be limited to decorative images (the default is "Plot object").

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.

width, height

not used. They are specified via the argument sizePolicy.

Description

Renders a reactive plot, with plot images cached to disk. As of Shiny 1.6.0, this is a shortcut for using bindCache() with renderPlot().

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.

Interactive plots

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

See also

See renderPlot() for the regular, non-cached version of this function. It can be used with bindCache() to get the same effect as renderCachedPlot(). For more about configuring caches, see cachem::cache_mem() and cachem::cache_disk().

Examples