How to Use R in Displayr

Using R in Displayr is different than using R on your computer (see details here). In Displayr, you use R to create individual items in your Document. This article outlines the various methods of accessing and using R in Displayr. For a guided walkthrough of how to do this and specific examples, you can also review our Using R in Displayr Video Series. To jump to a particular topic, click on the section link below:

Creating and Modifying Items

1. Calculations

2. R Variables

Tips for writing R Code

R Limitations

Creating and Modifying Items

There are a number of ways to use R from within Displayr:

Entering R code directly into a Calculation.
Creating an R Variable.
Creating a new Data Set using R.
Accessing pre-written R code using menus and forms. This is how most advanced analyses are conducted in Displayr (e.g., regression, principal components analysis). This is referred to as Standard R.

Automatic updating - Any R code that is created via Calculations, Standard R, or QScripts is set to automatically update when the inputs change (e.g., if the input data changes, if a new data file is created, or if other options are changed).

1. Calculations

A Calculation is an output in the Report that uses R code. It is created as follows:

In the toolbar (if you are on a Page) or the hover > + menu of the Report tree, click Calculation > Custom Code to insert an R-based output.
[Optional] Click to place the output on the Page, if working on a Page.
Enter the code written in the R Language in the Code panel that opens. This code can be used to create tables, visualizations (though not all visualizations are based on R code), or any other calculations.
Displayr will render various outputs automatically -- HTML will get processed as HTML, Matrices and tables will render to look like built-in tables, and more.
[Optional] If you would like to see the terminal view of the R Code you are running, in the Properties, tick the Data > Output > Show raw R output checkbox. This can be very useful when troubleshooting your code.

See How to Add a Custom Calculation for more details about using Calculations. Calculations can also contain custom functions that can be referenced from other R Code, see more in How to Create Custom R Functions. You can Hide calculations so that they do not export to the final Dashboard or Report.

2. R Variables

An R Variable is a variable in a data set that uses an R calculation to create the values. You can create them one at a time or in batches. To create an R variable:

From the Data Sources pane, hover over a variable where you'd like to create your R variable(s).
Click the + button on the right to get to the variable inserter menu.
Go to Custom Code > R and choose the Structure of variable set you'd like to create.

See How to Create a Custom R Variable for more details. Because you cannot preview the results from your R code when creating a variable, many times it is best to first create the code in a Calculation to confirm the results are as expected. Then you can copy it over to the variable's R Code.

3. R Data Set

An R Data Set can be added to a project by doing the following:

Data Sources > Plus (+) > R Code.
A dialogue with a field for the name of the data set and a code panel will open. Note that the data returned by the R code must have a tabular structure (i.e., be a matrix, data.table, or data.frame).

Because you cannot preview the results from your R code when creating a variable, many times it is best to first create the code in a Calculation to confirm the results are as expected. Then copy it over to the data set R Code.

4. Standard R

It is possible to do just about any form of data analysis using R by writing code. Where we think analyses are likely to be used by many of our users, we have made them available via a graphical user interface (i.e., menus and/or buttons and the like, without needing to write code). We refer to the analyses that we have made available via a graphical user interface as Standard R.

Note that R code in a Standard R object can be further edited by clicking Data > Attributes > Code from Properties to open the Code panel. For example, the following pie chart was created by clicking Visualization > Pie > Pie, but you can view and modify the R code that creates it in Data > Attributes > Code. Note that Standard R references fields on the Data and Chart tabs, so if you overwrite those settings in the code, those fields will not be taken into account. If you do not see a Data > Attributes > Code option in Properties when your visualization is selected, then it is a visualization built directly into the tool, and its underlying code is not accessible or editable.

Updating

R code is automatically re-run whenever:

Data or outputs that are inputs into R calculations are changed (unless Data > Calculate Automatically is unchecked in Properties). Examples include: a variable set used was recoded, the data set is updated, and a combo box used to create a filter is changed.
The R code contains instructions for updating at a specified frequency using How to Set Up Schedules in Displayr.

R code is a part of a document's Inputs & Outputs of modifications/calculations, which can impact the speed of large documents. You can review How to Optimize Speed of Displayr Documents for more information.

Helpful highlighting

When you create R code in Displayr, the code is colored and highlighted in a way to make it easier to see what items are being referenced.

Hovering over the name of an input will show you a preview of the data. When referencing other variables, any categories that have been merged in the related table will flow through to R, and any that have been removed will be excluded. By clicking the name in the preview, Displayr will then take you to the object, for example, to a Page where a table exists or to the Data Sources tree where the variable exists.

Strings will be colored red.
Some functions and other constructs will be colored blue. You can also hover over an R function to see the relevant Help documentation.
Comments - which are used to help document code and are not processed by R are colored green.

Tips for writing R Code

R is case-sensitive, so make sure you have matched the case in your referencing.
If adding data using R or creating an R variable, try the code out in a Calculation first to make sure it returns what you expect. Then copy it to your R variable.
Use # in your R code to add comments so it's easy to see what each section of code does. This will help you remember the intent of the code and will help the Displayr Support team and others in your organization understand the intent, if any collaboration is needed:
```
#this is a comment about the following code
x = 1 #this is also a comment about this line of code
```
In many instances, it's useful to simply look at some of your variables/tables in the code to spot unexpected inputs or results. To do so, hover over the highlighted name in your code. For instance, the code below won't return the number of people who prefer Diet Coke (coded as 1 in the data) because the data in R is the value label and not the underlying numeric value:
When working with Calculations, tick Data > Output > Show raw R output to see which exact line in your code is causing the error in your code. For example, what line of the code is actually returning the error below?

After ticking Show raw R output, you'll see that the 4th line is returning the error because we have the incorrect syntax within the brackets (the [,1] is not needed in this instance because totalcoke is only one column).

Use Show raw R output to check variables and results as you are in the process of writing code to be sure your code is doing what you expect. For example, the code below calculates a ratio of Coke consumed per week vs the max response, but the result is showing up as missing.
By adding a line to view what the max is, you'll see it is coming up as NA because we have forgotten to add in na.rm=T to our max() function.
Many errors and warnings are pretty generic and abstract-sounding, but you can Google them to see examples from other people who are receiving this error to tip you off to what may be the issue with your code. For example, the "incorrect number of dimensions" error below:

gives you an idea when you Google it that it doesn't fit with the structure:

R Limitations

Some are listed in How R Works Differently in Displayr Compared to Other Programs.
When referencing default tables, R will by default have only statistics from Data > Statistics > Cells in the Properties. The Right and Below statistics are stored in separate attributes in the table object, see How to Reference Statistics - Right and Statistics - Below in R.
When referencing tables where the Rows is using a Nominal-Multi or -Grid variable set, the Columns will be nested underneath the columns from the set. If the table has a variable set in the Columns that also has nested column labels, R will only bring in the top and bottom-most labels by default. See How to Work with Nested Banners and Spans in R Tables for more information.
When importing R data sets, R is unable to bring in variable labels, as R does not have the concept of both Name and Label. This means each variable will be labeled using the variable name.
Calculations and R data sets are by default restricted to 128MB.
There are certain keywords used by R that you should not use as names for your variables, calculations, and data sets. Using one may conflict with some of our automations and cause unintended results. These names include: list, length, exists, assign, names, rep, any, stop, min, max, matrix, attr, sum.