How to Reference Different Items in Your Document in R

Introduction

This article describes how to reference R objects in your Displayr document and avoid ambiguous referencing. You can also use our new point and click features to insert these references automatically per How to Use Point and Click Inside R Code.

Requirements

• A dataset loaded in a document.
• 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 back ticks.

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 Sets tree and drag it over to your custom code output or variable.

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 Properties > GENERAL > Name in the object inspector on the right. 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.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 Properties > 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#Parameter_Value_Substitution.
• 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.
• QFileFormatVersion: A number that will increase whenever there is a major version of Q, and when change occur 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.

Where this occurs, any R code that refers to the non-unique name needs to be made unambiguous by using a Fully Qualified Name:

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

See Also

How to Work with R in Displayr