This article outlines the various methods of accessing and using R in Displayr. For a guided walk through of how to do this and specific examples you can also review our Using R in Displayr Video Series.
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).
A Calculation is an output in a Document, created as follows:
- Calculation > Custom Code > create box on page.
- Enter code written in the R Language under R CODE. This code can be used to create tables, visualizations or any other calculations.
- Displayr will render various outputs automatically -- HTML will get processed as HTML, Matrices and tables will get rendered 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 Properties > 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. 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 Sets
An R Data Set can be added to a project by doing the following:
- Data Sets > Plus (+) > R or Anything > Data > Data Sets > 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 it 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 Properties > 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 Properties > R CODE. Note that Standard R references fields on the Inputs and Chart tab, so if you overwrite those settings in the code those fields will not be taken into account.
Other R Behavior
R code is automatically re-run whenever:
- Data or outputs that are inputs into R calculations are changed (unless Properties > R CODE > Automatic is un-checked 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 per How to Automatically Update Calculations, Variables and Data Sets Using R or you insert Anything > Report > Automatic Updating per How to Automatically Update a Page.
R code is a part of a document's dependency graph of modifications/calculations, which can impacts speed on large documents. You can review How to Optimize Speed of Displayr Documents for more information.
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.
- Tables and Calculations will highlight in blue.
- Variables will highlight in yellow.
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 Sets 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.
- When referencing default tables, R can only pull in statistics from Inputs > 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, R is unable to bring in significance results from the Arrows and Font colors setting. For a workaround for this see How to Add Statistical Significance to a Table Using the Formattable R Package and How to Add Statistical Significance to AutoFit Tables.
- When referencing default tables that include nested span labels, such as banner tables, R will by default only bring in the bottom-most labels. 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 67MB.
- 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.