How to Work with Variables via QScript

This article describes how to reference and use the various properties of variables in your data set using a QScript.

Requirements

A Displayr Enterprise user license which includes the ability to add custom analysis menu items or use the Displayr API.
The importdata.zip file which includes the Phone data set that we will use for this article.
You have read JavaScript Fundamentals and How to Create a Custom QScript.
You are using one of the methods from How to Use QScripts in Displayr.
You are familiar with the different Structures and Value Attributes for Variable Sets.

Method

As with any object-oriented language like JavaScript, there is a set structure of parent-child properties. This is no different when referencing variables. In this context, we are referring to "variables" as columns of data in your data set as opposed to declared scripting variables.

Data file

In order to reference specific variables, we need to first tell Displayr which data set these variables come from. This is achieved by using the dataFiles property of our document or project to first return an array of all added data sets:

project.dataFiles

If we only have a single loaded data set, we append the index value in square brackets like so:

project.dataFiles[0]

Remember, JavaScript is zero-based, so 0 is the first item in the array. If you had multiple data sets and wanted to reference the second, you would instead use 1 as your index.

Another method of selection which avoids having to specify the data set is to use the requestOneDataFileFromProject function from the QScript Selection Functions library to ensure the appropriate Data Sets tree is selected:

includeWeb('QScript Selection Functions');
var data_file = requestOneDataFileFromProject();

Variables

The main method of referencing variables in your data set is by name which is found on the object inspector under Properties > GENERAL > Name. This takes the form of getVariableByName for single variables and getVariablesByName for multiple variables.

When referencing a specific variable only, the name is case-sensitive so the below would return Top of mind awareness (q5) but using Q5 would instead result in an error (as the latter does not exist):

project.dataFiles[0].getVariableByName('q5')

When referencing multiple variables, the name is case-insensitive so the below would return q5 and all the unaided awareness Q5 variables (Q5_1 to Q5_11):

project.dataFiles[0].getVariablesByName('Q5')

This function essentially finds all instances of this string in the variable name. If you wanted to only include the unaided awareness variables, you could use Q5_ as the string parameter.

To instead return an array of all variables in your data set, you would use the following:

project.dataFiles[0].variables

Variable sets

Like with referencing variables, combined variable sets can also be referenced in similar fashion through getQuestionByName and getQuestionsByName.

In our data set, we have a variable set with a Label of q20. This is referred to in QScript as the question.name. So we could return our entire variable set (variables q20a1 to q20s8) by referencing this label as follows:

project.dataFiles[0].getQuestionByName('q20')

If we instead used the below, we would still get the same result, as "q2" is only included in the Label of this variable set:

project.dataFiles[0].getQuestionsByName('q2')

The equivalent getVariablesByName function, on the other hand, would return all variables from q20a1 to q29, as "q2" is common to all these variable names.

To instead return an array of all variable sets in your data set, you would use the following:

project.dataFiles[0].questions

An important distinction between variable and question is that the question object of q20 is a single object but there are 152 variable objects. Certain properties need to reference one of the two but you can go from one to the other:

variable.question // returns the 'Question' property of the declared variable
question.variables[0] // returns the first 'Variable' property of the declared question

This also works in conjunction with other properties. So if you wish to return the variable type of the first variable from q20, either of the below will work:

project.dataFiles[0].getQuestionByName('q20').variables[0].variableType
project.dataFiles[0].getVariableByName('q20a1').variableType

The variableType property will in most cases return either Numeric, Text, Categorical, or Ordered Categorical.

Variable sets additionally have a defined Structure which incorporates variable type and is found on the object inspector under Properties > GENERAL > Structure. This can be returned by adding the variableSetStructure property:

project.dataFiles[0].getQuestionByName('q20').variableSetStructure

In this case, the result is Binary - Grid.

Variable and value attributes

Both variables and variable sets in turn have their own properties for storing, for example, variable labels and value attribute settings.

Below we will again use q20 as an example. Here, we will return the most common properties as a log:

var data_file = project.dataFiles[0];
var q = data_file.getQuestionByName('q20');
var attr = q.valueAttributes;
log("Object: '" + q + "'");
log("Variable set label: '" + q.name + "'");
log("First variable label: '" + q.variables[0].label + "'");
log("First variable raw label: '" + q.variables[0].sourceLabel + "'");
log("Variable set values: '" + q.uniqueValues + "'");
includeWeb('QScript Value Attributes Functions');
log("Variable set value labels: '" + valueLabels(q) + "'");
log("Label of value 0: '" + attr.getLabel(0) + "'");
log("Value 0 checked in 'Count This Value': '" + attr.getCountThisValue(0) + "'");
log("Value 0 set to 'Exclude from analyses': '" + attr.getIsMissingData(0) + "'");

In order to reuse references and simplify the code, we first declare data_file so this can be used in the following line.
We also declare q which returns the question object and in turn use this to declare attr as the valueAttributes object. This object references the properties found in the object inspector under Properties > DATA VALUES.
Each of the below properties is included in our log:
- name - this is the equivalent of the Variable Set Label.
- label - this is the label of the variable as shown in the Data Sets tree.
- sourceLabel - this is the original label of the variable from the raw data set.
- uniqueValues - this is an array of all values within the variable set.
- valueLabels - this is an array of all value labels within the variable set. Note, this uses a function from the QScript Value Attributes Functions library.
- getLabel - this is the label of a specified value within the variable set.
- getCountThisValue - this is for checking whether this value has been checked in the Count This Value column of the Value Attributes screen. This is only appropriate for Binary - Multi and Binary - Multi (Grid) questions.
- getIsMissingData - this is for checking whether this value has been set to Exclude from analyses in the Missing Values column of the Value Attributes screen.

Your log prompt will look like the below:

In addition to returning the various variable parameters and settings, we can also update them.

Let's begin by again declaring the data file and variable set to work with:

var data_file = project.dataFiles[0];
var q = data_file.getQuestionByName('q20');

Next, we will update the variable set, variable and value labels, and set the Count This Value setting:

q.name = "New name"; // Rename the variable set as "New name"
var qvar = q.variables[0]; // Define 'qvar' as the first variable in this question
qvar.label = "New label"; // Change the 'Label' field for this variable to "New label"
qvar.valueAttributes.setCountThisValue(1, true); // Tick code 1 to be a counted 'Pick Any' value

If we instead look at our Age variable, we can likewise set the value label, change the value, and update the Missing Data settings as follows:

var q = data_file.getQuestionByName('Age');
var qvar = q.variables[0];
qvar.valueAttributes.setLabel(1,"Under 16"); // Change value label for code 1 to "Under 16"
qvar.valueAttributes.setValue(1,99); // Change source value of 1 to 99
qvar.valueAttributes.setIsMissingData(NaN, false); // Untick 'blank' as Missing Data

See Online JavaScript Libraries for reference guides detailing all the available functions.

How to Create a Banner via QScript