How to Modify Variables and Value Attributes via QScript

This article describes how to combine, duplicate, delete, move, and set attributes for variables and variable sets 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 are familiar with the different Structures and Value Attributes for Variable Sets.
You have read How to Create a Custom QScript and How to Work with Variables via QScript.
You are using one of the methods from How to Use QScripts in Displayr.

Method

Combine

When you wish to combine multiple variables together or change the Structure of a variable set, you can use combineVariablesAsSet by entering the name, desired Structure, and an array of the variables to apply this function to. This function comes from the QScript Utility Functions library so needs to additionally be referenced at the start of the code. It is the same as using the Combine option in the Tools menu or from the Data Sources tree.

Let's use the Q5 variables as an example as these have been combined automatically with Q6 due to containing the same structure and labels. On this occasion, we wish to set Q5 separately. This can be achieved as follows:

includeWeb('QScript Utility Functions');
var data_file = project.dataFiles[0];
combineVariablesAsSet("Q5","Binary - Multi",data_file.getVariablesByName("Q5_"))

Alternatively, we could create an array with square brackets, using getVariableByName, and specify each of the variables individually. Below is how we would do this for the remaining Q6 variables:

includeWeb('QScript Utility Functions');
var data_file = project.dataFiles[0];
combineVariablesAsSet("Q6","Binary - Multi",
   [data_file.getVariableByName("Q6_1"),
   data_file.getVariableByName("Q6_2"),
   data_file.getVariableByName("Q6_3"),
   data_file.getVariableByName("Q6_4"),
   data_file.getVariableByName("Q6_5"),
   data_file.getVariableByName("Q6_6"),
   data_file.getVariableByName("Q6_7"),
   data_file.getVariableByName("Q6_8"),
   data_file.getVariableByName("Q6_9"),
   data_file.getVariableByName("Q6_10"),
   data_file.getVariableByName("Q6_11")]);

Duplicate

Both variables and variable sets are able to be duplicated. On this occasion, we want to duplicate our Age (q4) variable. We could duplicate Age at the variable level by referencing the variable Name:

var v = project.dataFiles[0].getVariableByName('q4');
v.duplicate();

We could also do this at the question level by referencing the variable (set) Label and providing a label for the new variable (set):

var q = project.dataFiles[0].getQuestionByName('Age');
q.duplicate('Age New');

If there is a need to create a copy of a variable but also change the variable type, we can instead use duplicateAs to, for example, make a categorical or Nominal copy of the numeric variable q24a.wdh:

var v = project.dataFiles[0].getVariableByName("q24a.wdh");
v.duplicateAs("Categorical");

Delete

Deleting variables and variable sets, on the other hand, involve separate functions. Importantly, only duplicated or constructed variables can be deleted in Displayr and not variables from the raw data set. We can use the duplicated Age New variable from above and remove it just as easily:

var q = project.dataFiles[0].getQuestionByName('Age New');
q.deleteQuestion();

This could also be done at the variable level by referencing the duplicated variable name:

var v = project.dataFiles[0].getVariableByName('q4_2');
v.deleteVariable();

Or you can use a combination of the two, provided the correct object type is returned:

var v = project.dataFiles[0].getQuestionByName('Age New').variables[0];
v.deleteVariable();

Move

Moving variables is also possible via QScript. If we wanted to move Age after Q5, we could use moveAfter as follows:

var data_file = project.dataFiles[0];
var q1 = project.dataFiles[0].getQuestionByName('Age'); 
var q2 = project.dataFiles[0].getQuestionByName('Q5');
data_file.moveAfter(q1.variables,q2.variables[0]);

Note, the second argument of moveAfter must be a single variable or position. This means we could set the position to the very top of our data set by using null:

data_file.moveAfter(q1.variables,null);

Or we could move Age to the very bottom by returning the last variable index in our data set using data_file.variables[data_file.variables.length-1]):

var data_file = project.dataFiles[0];
var q1 = project.dataFiles[0].getQuestionByName('Age');
data_file.moveAfter(q1.variables,data_file.variables[data_file.variables.length-1]);

Value attributes

The values, value labels, and data settings in variable sets are referred to as Value Attributes and can be found in the object inspector under Data > Properties > Values. QScripts likewise have access to these properties.

Let's look at our Do they pre-pay calls? question as an example. There are categories for 0,3,4,6 that don't fit in with the expected 'Yes' or 'No' responses, so we will need to tidy this up.

We can do this by returning the valueAttributes object of our question:

var q = project.dataFiles[0].getQuestionByName('Do they pre-pay calls?');
var attr = q.valueAttributes;
attr.setLabel(0,"NA");
attr.setValue(0,99);
attr.setIsMissingData(3,true);
attr.setIsMissingData(4,true);
attr.setIsMissingData(6,true);

We first use setLabel to set the label of value 0 as NA.
We then use setValue to change the value from 0 to 99.
And we set values 3,4 and 6 as Exclude from analyses using setIsMissingData.

Let's look at another example which uses some of the functions from earlier in this article but also lets us set binary variables. In this case, we will convert our Mobile rating variable set into a binary variable set that counts Strongly agree and Agree a little:

includeWeb('QScript Utility Functions');
var q = project.dataFiles[0].getQuestionByName('Mobile');
var top2 = q.duplicate('Mobile Top 2');
combineVariablesAsSet("Mobile Top 2","Binary - Multi",top2.variables)
var attr = top2.valueAttributes;
attr.setCountThisValue(1,true);
attr.setCountThisValue(2,true);
attr.setCountThisValue(9,false);

We duplicate our Mobile variable set by first returning the question object and declare this as top2.
We then use combineVariablesAsSet to change the Structure of our duplicated variable set to Binary - Multi.
As before, we can reference the valueAttributes property to update our settings. By using setCountThisValue, it allows us to count values 1 and 2 (i.e. Strongly agree and Agree a little) and not count 9 (DON'T KNOW) which is ticked by default as it expects the highest value to more often than not be the desired selection.

Variable and variable set properties

QScripts can also be used to modify labels. For example, in our data set, we have a misspelled variable set called Percieved proportion of time the but we can use the question object's name property to remedy this:

var q = project.dataFiles[0].getQuestionByName('Percieved proportion of time the');
q.name = "Perceived proportion of time";

We also notice that "vodafone" has been misspelled as "vodaphone" in the fourth variable of our Proportion of people with variable set.

This can be replaced be using the label property of the relevant variable object:

var q = project.dataFiles[0].getQuestionByName('Proportion of people with');
q.variables[3].label = "vodafone"

We can also achieve this by referencing the specific variable name:

var v = project.dataFiles[0].getVariableByName('q30voda');
v.label = "vodafone"

When combined with a for...loop, we can even perform actions to all variables or variable sets at once, such as replacing all instances of "Telstra (Mobile Net)" in the variable Label with "Telstra":

var variables = project.dataFiles[0].variables;
var n_vars = variables.length;

for (var i = 0; i < n_vars; i++) {
     var label = variables[i].label;
     variables[i].label = label.replace("Telstra (Mobile Net)","Telstra");
}

variables stores all the variable objects in our data set.
n_vars uses length to find the number of variables to loop through.
We use a for...loop to iterate through every variable, where i represents the index value and label stores the original variable label.
variables[i].label then updates the variable label by replacing the specified text in the existing label.

Other variable set properties, such as those found in the object inspector under Data > Properties, can likewise be accessed through the question object.

Usable as a filter:

var f = project.dataFiles[0].getQuestionByName('Q5');
f.isFilter = true;

Usable as a weight:

var w = project.dataFiles[0].getQuestionByName('Gender');
w.isWeight = true;

Hidden except in the data tree:

var h = project.dataFiles[0].getVariableByName('choiceid').question;
h.isHidden = true;

Setting the above to false will uncheck these settings.

How to Create Custom Variables via QScript

Later

How to Add Pages, Folders, and Headings via QScript

How to Create Tables and Calculations via QScript

How to Create a Visualization via QScript

How to Modify Tables via QScript

Articles in this section

Requirements

Method

Combine

Duplicate

Delete

Move

Value attributes

Variable and variable set properties

Next

Later

See Also

Articles in this section

Requirements

Method

Combine

Duplicate

Delete

Move

Value attributes

Variable and variable set properties

Next

Later

See Also

Related articles