How to Reference Different Items in Your Document in R

Because R calculations are run via cloud R servers, you must specifically reference all the variables and outputs you need for your calculation in your code. Note that, unlike a regular R session, you are not able to reference the entire Data Set imported into the Data Sources tree as a whole, and instead, you must reference the individual Variable Sets you need directly in the code. This article describes how to reference objects in your Displayr document and avoid ambiguous referencing in R code. You can also use our point-and-click features to insert these references automatically, per How to Use Point and Click Inside R Code. This article covers:

1. References to variables and variable sets

2. References to tables

3. References to other Calculations

4. References to things inside your R Environment

5. Avoiding ambiguous names

Requirements

For more detailed examples of how to reference various data, see How to Work with Data in R.

Method

1. References to variables and variable sets

With R, you can reference either the variable name or the variable set/question label. If the variable set label has spaces in it, however, you must wrap it in backticks.

As an example, I have a single variable called Q1 with the label of Q1. How old are you?. To reference the variable, I would use Q1 but to reference the question, it would be `Q1. How old are you?`.

In this case, using either option produces the same result, but the distinction can be important as a variable set could be made up of multiple variables.

In general, the easiest way to ensure correct referencing is to select the relevant variable (set) in the Data Sources tree and drag it over to your custom code output or variable.

Once you've added your variable to your code, you should hover over it to preview the data being used by R. This will show you if you need to reference the number value or the value label in your code when working with the variable. For example, R uses the category label for categorical (Nominal) variables.

2. References to tables

New tables and other types of outputs (strings, charts, variables, data files) can be created by manipulating tables. Every table has a Name, which can be viewed and changed by clicking on the table and going to General > General > Name in the object inspector . A table's Name is automatically constructed from its Label, which is, in turn, automatically created from its contents. For example, a table that shows Age in its rows and Gender in its columns, will have a Label of Age by Gender and a Name of table.Age.Categories.by.gender.

Where a table's reference name is the same as the name of a variable (set) or other R-based calculation, you can distinguish between the different types by using QTables$reference.name (e.g., QTables$table.2).

3. References to other Calculations

Like a table, a Calculation has both a Name and a Label. The Name must be unique within a document. The Name is used to refer to other calculations in code. For example, if one calculation has a reference name of x, the code x * 2 in another calculation will show the value of x multiplied by 2.

There are a number of ways of changing the Name of a calculation:

1. By changing the Name in the object inspector via General > General.
2. By assigning a variable name in the last line of code. For example, the following code creates a Calculation with a Name of dog containing the string (or, in R parlance, character) Sherlock:

dog <- "Sherlock"

4. References to things inside your R Environment

In addition to being able to reference data from other outputs and variables, there are also special variables that you can access within R:

• QFilter: see How to use the Filter(s) Dropdown to Quickly Filter R Outputs using QFilter.
• QCalibratedWeight/QCalibrationWeight: see Weights in R.
• QDataFrame/QInputs/QFormula: see R GUI Controls (see the Parameter_Value_Substitution section).
• QOutputSizeWidth: the width of the R output in inches.
• QOutputSizeHeight: the height of the R output in inches.
• productName: Q or Displayr.
• QAllowLargeResultObject(): Call this, supplying a number of bytes, to allow larger than default outputs from R. The default limit exists to save users from unintentionally large outputs, which might be slow to download. Note that this function can override the size of the entire output returned by the R server (i.e. what is shown in the browser AND any invisible saved attributes and underlying data). There is a separate limit of 40 MB for the actual image/widget displayed in the browser which cannot be overridden because it will cause browsers to crash.
• QFileFormatVersion: A number that will increase whenever there is a major version of Q, and when a change occurs in the file format.
• QSettings contains general project settings such as default colors and statistical assumption values.
• QAppearance contains settings specific to this R Output, such as decimal places, font, and other formatting options.
• QFileFormatVersion is the Q version number, which can be helpful in detecting an older client.
• QNObservations is the number of observations (rows) in the dataset which an R variable adds to.

More details for QSettings, QAppearance, QFileFormatVersion, and QNObservations can be found in the Accessing Graphical User Interface Properties from R example dashboard.

You can use R's tempfile and tempdir as normal, but any files you create will be deleted when your code finishes. Temporary files cannot exceed 500MB.

5. Avoiding ambiguous names

There are situations where two objects may have the same Name. For example:

• A table and a variable may both have the Name of Q2.
• A Calculation and a table may both have the name brand.health.
• You have multiple data sets in your document which both include the same variables.

When two items have the same Name in Displayr, any R code that refers to the non-unique name needs to be made unambiguous by using a Fully Qualified Name. Below is a list of how to reference a specific item if its Name is duplicated, depending on what type of item it is:

• Calculation: 
  • Syntax: QROutputs$item.name
  • Example: QROutputs$r.output.3
• Table: 
  • Syntax: QTables$item.name
  • Example: QTables$age.by.gender.3
• Variable: 
  • Syntax: data.set.name$variable.name or data.set.name$Variables$variable.name
  • Example: Colas.sav$d1 or Colas.sav$Variables$d1
• Variable Set: 
  • Syntax: data.set.name$question.name, data.set.name$Questions$question.name or data.set.name$VariableSets$variable.set.name
  • Example: Colas.sav$Age, Colas.sav$Questions$Age or Colas.sav$VariableSets$Age

Note that while the data set name is part of some of the Fully Qualified Names above, you cannot reference only the data.set.name set or only data.set.name$Variables or data.set.name$VariableSets. You can only reference individual variables or variable sets by name directly in the code.

See Also

How to Use R in Displayr