How to Use R in Displayr

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

Updating

Helpful highlighting

Tips for writing R Code

R Limitations

Creating and Modifying

There are a number of ways to access 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 a Document, created as follows:

Calculation > Custom Code from the toolbar and create a box on the page.
Enter code written in the R Language in the R Code editor. 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.
If you would like to see the terminal view of the R Code you are running, check the Data > Output > Show raw R output checkbox. This can be very useful when troubleshooting your code.

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 to not export them 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 (see How to Create a Custom R Text Variable and How to Create a Custom Numeric R Variable) or in batches (see How to Create Multiple R Variables).

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 or Anything > Data > Data Set > Add.
These data sets need to have a tabular structure.

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 via Data > Show Advanced Options > R Code > Edit R Code. 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 > Show Advanced Options > R Code > Edit 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 > Show Advanced Options > R Code box on your visualization, 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 the object inspector). 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 dependency graph of modifications/calculations, which can impact the speed on 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, check 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 in 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 can only pull in statistics from Data > Statistics > Cells. The Right and Below statistics are not recognized, but you can add the equivalent as Cells statistics in order to reference these.
When referencing default tables that include nested span labels, such as banner tables, R will only bring in the 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.