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. In order to prevent overload the Displayr server ignores any update frequency less than 600 seconds. Do keep in mind that if an input (dependency) of an R-based item is update, the R-based item will trigger a recalculation automatically.
Requirements
- An R-based item in your Displayr document.
- Purchased Server time for private dashboards and API hours (view hours).
Method - Updating with flipTime functions
The preferred method to achieve updating uses the R package flipTime. Do keep in mind that using this feature does count towards your Server time for private dashboards and API hours (view hours) allotment, see Tracking API Hours. There are 3 options you can specify within the update functions, where options =
"only when open"- causes R-based item to automatically recalculate at the scheduled time interval if the document is currently open by a user"wakeup"- causes the document to be opened by the software and the item recalculation to occur"snapshot"- causes the document to be opened and the dashboard to be re-published after the recalculations have updated.
UpdateEvery()
The function UpdateEvery allows you to specify a number of "minutes", "hours", "weeks", or "months" as follows:
#load the R package of functions
library(flipTime)
#make item automatically recalculate every 5 days and snapshot republishes the dashboard
UpdateEvery(5, "days", options = "snapshot")
UpdateAt
The function UpdateAt is more flexible and allows specification of an initial update date, time and timezone, then a recurring update frequency thereafter. For example:
#load the R package of functions
library(flipTime)
#update automatically every 3 days after May 15, 2017 at 6pm New York time
UpdateAt("05-15-2017 18:00:00", us.format = TRUE, time.zone = "America/New_York", units = "days", frequency = 3, options = "wakeup")
See here for a list of time zones.
Method - Updating with message()
The older way of updating, involves using the R function message(). Do keep in mind that using this feature does count towards your Server time for private dashboards and API hours (view hours) allotment, see Tracking API Hours. However, it is preferable to use the flipTime package above as it is more robust. An example using message() is the following:
#recalculate every hour while the document is open
message("R output expires in 3600.0 seconds")
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.:
#recalculate every hour, open the document on the back-end if not already open
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.
#recalculate every hour, open the document on the back-end if not already open
message("R output expires in 3600.0 seconds with wakeup and snapshot")
Important Functionality
Dependencies
Automatically updating an R-based item will cause all upstream dependencies that have expired to update with one small caveat.
If a Calculation with an automatic update from above depends on an R Data Set (either directly or via intermediate calculations) then you will need to use the same automatic update code without wakeup in the R Data Set code as well. 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).
Any downstream dependencies from the R item that was automatically updated 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.
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-based 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.
Additional Notes
- 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.
- 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.
Next
How to Automatically Update Dashboards in Displayr
How to Automatically Republish a Dashboard
How to Create Dashboards with Real-Time Updating
How to Set Up a Slack Alert of Updating Errors from your Displayr account