This article describes how to make R-based calculations, variables and data sets refresh automatically after a specified time period by including a line of code with a message or a function call.
A Displayr document.
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:
UpdateEvery(5, "days", options = "snapshot")
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.
UpdateAt is more flexible and allows specification of an initial update date, time and timezone, then a recurring update frequency thereafter. For example:
UpdateAt("05-15-2017 18:00:00", us.format = TRUE, time.zone = "America/New_York", units = "days", frequency = 3, options = "wakeup")
The above causes the output to be updated every 3 days starting on 05-15-2017 at 18:00:00.
Updating With message()
The older way of updating, involves using the R function
message(). However, it is preferable 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 a Calculation 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 Calculation 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.
If a single piece of R code attempts to set up more than one schedule, e.g. via multiple calls to either
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.
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 can be accessed from your document via the Profile icon > Account settings > GENERAL > Miscellaneous > Scheduled R update status.
- 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 summarizes the number of errors which are outstanding and provides a link to the status page. See How to Set Up a Slack Alert of Updating Errors from your Displayr account.
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 Calculations must be run at least once before automatic updating will be triggered. If you have uploaded an archived project you should go through and click Calculate for those Calculations which are set to update automatically.