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 thequestion
object and in turn use this to declareattr
as thevalueAttributes
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.
Next
How to Create a Banner via QScript
Later
How to Create User Input Prompts in QScripts
How to Create Diagnostic Messages and Perform Validations via QScript
How to Modify Variables and Value Attributes via QScript
How to Create Custom Variables via QScript
How to Add Folders and Text Outputs via QScript
How to Create Tables and R Calculations via QScript
How to Create a Chart via QScript
How to Modify Tables via QScript
See Also
How to Create a Custom QScript
Comments
0 comments
Article is closed for comments.