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

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

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 Q which data set these variables come from. This is achieved by using the dataFiles property of our 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 set 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 in the Variables and Questions tab in the Name column. 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, multiple-variable questions can also be referenced in similar fashion through getQuestionByName and getQuestionsByName.

In our data set, we have a variable set with a Question name 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 Question name of this question:

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 questions 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 Question Type which can be returned by adding the questionType property:

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

In this case, the result is Pick Any - Grid.

Variable and value attributes

Both variables and questions 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 under the Values ... button.
Each of the below properties is included in our log:
- name - this is the equivalent of the Question Name.
- label - this is the label of the variable as shown in the Variables and Questions tab.
- sourceLabel - this is the original label of the variable from the raw data set.
- uniqueValues - this is an array of all values within the question.
- valueLabels - this is an array of all value labels within the question. Note, this uses a function from the QScript Value Attributes Functions library.
- getLabel - this is the label of a specified value within the question.
- 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 Pick Any and Pick Any - Grid questions.
- getIsMissingData - this is for checking whether this value has been ticked in the Missing Data 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 question to work with:

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

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

q.name = "New name"; // Rename the question 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