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. 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