08 June 2017 |
How to Link Documents in Displayr
Sometimes it is helpful if one Displayr document can refer to information in another document. For example, one document may contain an analysis of sales data, and you may want to include some aspect of that analysis in another document, so that it automatically updates when the original document updates.
In this post, I describe how to move data from a source document to a destination document as a four-step process using Dropbox.
1. Create access token for Dropbox
To use Dropbox, we need to tell Dropbox to create what it calls an app.
Go to the Dropbox App Console and log in (you need a Dropbox account to do this). Click on Create App, choose the Dropbox API and select App folder as the access type of the app. This means that the app (and token) you create will only have access to a single folder, and cannot be used to modify files in other folders of your Dropbox. If you have more than one Dropbox account you will also need to choose which account to use.
After the app is created, you will be taken to the settings page for the app. Scroll to the OAuth2 section and click Generate access token to output a text string which you can copy and paste into Displayr.
2. Create an R Output
The next step is to open your source document and create the item that you want to make available to the other document. This can be an object of any type (e.g. strings, numbers, tables, regression models) as long as it is an R Output. The basic steps to creating this are:
- Create an R Output using Insert > Analysis > R Output.
- Create whatever it is that you wish to export in the R Output. You can do this by any of:
- Typing the name of an object into the code box of the R Output. The example on the the right refers to a table called table.Age.
- Dragging from the Data tree into the code box.
- Dragging an object from the Pages section into the code box.
- Inserting your own R code.
- Check the Automatic checkbox.
- Add the following anywhere in your R code:
library(flipTime) UpdateEvery(1, "weeks")
This tells Displayr that the object should be updated if it is older than 1 week and the document is open, or if the object is used by another object. I explain this in more detail in the step below. Alternatively, you could use the following format which allows a first update time and date to be specified:
library(flipTime) UpdateAt("30-11-2017 18:00:00", time.zone = "Europe/Madrid", units = "months", frequency = 1)
Should you not be in Madrid, the full list of time zones is available here.
- Find the Name of the output by clicking on it and then looking under Properties > GENERAL.
The R Output will be displayed on the page so you can check that it contains the information you want to export.
I have created an example document in Displayr here. It contains a regression model called gam.model, that we will export to Dropbox in following step.
3. Export the R Output
The R output is exported by creating another new R Output to perform the actual export function. Select the checkbox to set the update to be Automatic, and paste in the following code (where you replace gam.model with the Name of your object and dropbox access token with the token from Step 1):
library(flipAPI) ExportToDropbox(gam.model, 'dropbox access token', reexport.seconds = 604800)
If you click Calculate and no error message appears, then you should be able to see a file called <object>.rds in the Dropbox folder for the app created in Step 1. If you get an error message about “object not found”, then check that you have used the object Name and not the Label in the second line of code above.
The reexport.seconds argument tells Displayr how often the object should be exported. In this example, the source dashboard will be re-woken every 604800 seconds (i.e. 1 week) and the R output will be updated, including any upstream R outputs that have expired. Because of the expiry message we inserted in Step 2, this includes gam.model. In most cases, the time interval specified in Step 2 and Step 3 should be the same. See the source document for more details about updating dependencies.
4. Import the R Output
To import into the destination document, we again create a new R Output, and paste in two lines of R code:
library(flipAPI) gam.model.copy = ImportFromDropbox('gam.model.rds', 'dropbox access token')
Note that the second line refers to the name of the file (gam.model.rds) that was created in Part 3, above. Once the object is imported, we can treat it as if it was created in the current document. For example, we can extract parameter estimates or predict from the imported model with just a few more lines of R.
If we wanted to publish the object in a report, but do not need to manipulate it with code, then there is no need for Dropbox. After step 2, use Export > Embed then paste the link into your website or document. The UpdateAt or UpdateEvery function will refresh the embedding at the specified frequency.
Author: Carmen Chan
Carmen is a member of the Data Science team at Displayr. She enjoys looking for better ways to manipulate and visualize data. Carmen studied statistics and bioinformatics at the University of New South Wales.