Automatically Updating R Outputs, R Variables, and R Data Sets

R Outputs, R Variables, and R Data Sets can be made to refresh automatically after a specified time period by including a line of code with a message or a function call. For a more gentle introduction to automatic updating, see this post.

Updating With flipTime

The preferred method to achieve updating uses the R package flipTime. Its function UpdateEvery allows the user to specify a number of "minutes", "hours", "weeks", or "months" as follows:
library(flipTime)
UpdateEvery(5, "days", options = "snapshot")

where options = "only when open" causes the calculation in the same R Output to occur at the scheduled time interval if the document is open, "wakeup" causes the document to be opened and the calculation to occur, and "snapshot" causes the document to be opened and the dashboard to be re-published after the calculation has updated.

The flipTime function UpdateAt is more flexible and allows specification of an initial update date, time and timezone, then a recurring update frequency thereafter. For example:

library(flipTime)
UpdateAt("05-15-2017 18:00:00", us.format = TRUE, time.zone = "America/New_York", units = "days", frequency = 3, options = "wakeup")

causes the output to be updated every 3 days starting on 05-15-2017 at 18:00:00.

See the R documentation for UpdateAt and UpdateEvery for more details.

See here for a list of time zones.

Updating With message()

The older way of updating, involves using the R function message(). It is preferred to use the above approach with flipTime. An example of the message is the following:

message("R output expires in 3600.0 seconds")

The calculation will be re-run after the given number of seconds. In this case 3600 seconds corresponds to one hour. The decimal point and the word "seconds" may both be omitted.

Note that the above code will only effect a refresh while the document is open. If you are using Displayr and would like the system to re-open the document in the background in order to re-run the calculation, just include the suffix "with wakeup", e.g.:

message("R output expires in 3600.0 seconds with wakeup")

When using the "with wakeup" form, note that the calculation may actually be re-run up to several minutes after the requested time, depending on the size and complexity of the document, server load and other factors.

It is not possible to perform long-running calculations (over 230 seconds) when using the "with wakeup". Documents must remain open to run such calculations.

After a "with wakeup"-style refresh, you can optionally cause a snapshot to be taken of the document by adding "and snapshot" to the message. The effect will be that any viewers of the document will see the changes reflected, e.g.

message("R output expires in 3600.0 seconds with wakeup and snapshot")

Updating With Dependencies

Updating an R object will cause all upstream dependencies that have expired to update. Any downstream dependencies will be marked as "out of date" and will recalculate upon opening or refreshing a view mode document as a result of the "with wakeup" message.

If an R Output depends on a dynamic R Data Set (either directly or via intermediate calculations) then an expiry without wakeup and with the same frequency as the R Output expiry should be added to the R code for the data set. This can be achieved with either the message or the functions. This ensures that the previous data will have expired and so be refreshed for every update of the object.

Note that when updating data sets, serious and unrecoverable errors may occur if there are changes in the structure of the data file (e.g., new variables, changes of variable type).

In order to prevent overload the Displayr server ignores any expiry less than 600 seconds.

Precedence

If a single piece of R code attempts to set up more than one schedule, e.g. via multiple calls to either message or UpdateEvery, the schedule with the least number of seconds is preferred. That is, the earliest wins. If multiple schedules are returned with the same number of seconds, but differing with respect to "with wakeup" or "and snapshot", only one schedule will be effected, which will be selected arbitrarily.

If multiple "with wakeup" schedules are put in place, e.g. by re-running the R code via the "Calculate" button before a previously scheduled automatic update has taken place, the schedule with the least number of seconds is preferred. Any other schedules for the same object are deleted prior to the update taking place. If there is a tie between schedules with the same number of seconds, a schedule with "and snapshot" is preferred.

Error Feedback

When an R object is updated in the background there is no immediate feedback if something goes wrong (e.g. if an error occurs in your R code). Displayr addresses this situation in multiple ways:

• If an error occurs during scheduled updating "with wakeup" the update will be automatically re-tried one hour later. The retry process continues until the update succeeds, the object is removed from the document or the document is deleted.
• Company administrators can view a status page which list any failing "with wakeup" updates. A link to the status page is shown at the bottom of the "Account" tab of the administrative page: click the cog icon at the top right then choose "Account".
• Displayr provides an integration with the Slack messaging system whereby Displayr will perform a daily check of the company's documents. If at the time of the check there are any R objects awaiting retry due to an error during scheduled R updating "with wakeup", Displayr will send a Slack message. The message summarises the number of errors which are outstanding and provides a link to the status page.

To set up the integration with Slack, follow these steps:

1. Create an incoming webhook in Slack using the following link: https://displayr.slack.com/apps/new/A0F7XDUAZ-incoming-webhooks. You don't need to set a username or icon because Displayr will override these settings.
2. Go to the "Settings" tab of the administrative page: Click the cog icon at the top right then choose "Settings".
3. Scroll to the Webhooks table at the bottom. (If the table is not visible you may first need to flag the company as a multi-user company: click the "Expand" button.)
4. Click "New Webhook".
5. Copy the URL from Slack into the "URL" field and ensure "Kind" is set to R update failures to Slack (aggregating).
6. Click "Save".

Additional Notes

Note that if an object is referred to by an HTML embedding, then the update of the embedding may be delayed due to caching by the content delivery network.

Importantly, any R Outputs must be run at least once before automatic updating will be triggered. If you have uploaded an Archive Pack you should go through and click Calculate for those R Outputs which are set to update automatically.