This article describes how to reference and use the various properties of variables in your data set using a QScript.
- The importdata.zip file, which includes the Phone data set that we will use for this article.
- You are using one of the methods from How to Use QScripts in Q.
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:
If we only have a single loaded data set, we append the index value in square brackets like so:
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();
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):
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):
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:
Like with referencing variables, multiple-variable questions can also be referenced in similar fashion through
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:
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:
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:
An important distinction between
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 // 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:
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
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;
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.label + "'");
log("First variable raw label: '" + q.variables.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_fileso this can be used in the following line.
- We also declare
qwhich returns the
questionobject and in turn use this to declare
valueAttributesobject. 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.
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: