How to Reference Different Items in Your Project in R

Introduction

This article describes how to reference R objects in your Displayr document and avoid ambiguous referencing. This is important in conjunction with How to Work with Data in R.

Method

1. References to variables and questions

With R you can reference either the variable name or the question label. If the question label has spaces in it, however, you must wrap it in back ticks. These can be found on the Variables and Questions tab:

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 question could be made up of multiple variables. As well as the raw data, variables and questions have attributes providing metadata about the variable or question, see How to Extract Information from an R Object.

2. References to built-in tables

New tables and other types of outputs (strings, charts, variables, data files) can be created by manipulating built-in tables. Every table has a unique Reference name, which can be viewed and changed by right clicking on the table and selecting Reference name.

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 Reference name of table.age.by.gender.

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

3. References to other R Outputs

Like a table, an R Output has both a Reference Name and a Label. The Name must be unique within a document and is what is used to reference the output in code. For example, if one R Output 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 right-clicking on an R Output in the Report Tree and selecting Reference Name....
3. By changing the Name, if the Name and the Reference Name are the same and there are no other R Outputs with the same Reference Name.
4. 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 and Filters in R.
• 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.

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.
• An R Output 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:

• R Outputs: 
  • 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 
  • Example: Colas.sav$Age, Colas.sav$Questions$Age 

See Also

How to Learn R

How to Use R in Q

How R Works Differently in Q Compared to Other Programs

How to Use Different Types of Data in R

How to Work with Data in R

How to Work with R Loops

How to Work with Conditional R Formulas

How to Add a Custom R Output to your Report

How to Create a Custom R Variable

How to Use R to Add Data Sets