How to Create Diagnostic Messages and Perform Validations via QScript

Introduction

This article describes how to create message alerts and validations in a QScript. This could be used for internal testing and for ensuring the requirements of the code are met.

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 How to Create a Custom QScript, How to Work with Variables via QScript and How to Create User Input Prompts in QScripts.
You are using one of the methods from How to Use QScripts in Displayr. Note, the selection list prompt example is only available via the QScript Editor.

Method

Diagnostic messages

Two methods for generating message notifications are alert and log. These work in QScript the way you would expect for JavaScript functions. They allow you to display information in a message box.

For example, the following checks to see if a variable called weight exists and, if it does not, alerts the user:

if (project.dataFiles[0].getVariableByName("weight") == null) 
    alert("Data file does not contain a variable called 'weight'.");

This will return the same as the below:

if (project.dataFiles[0].getVariableByName("weight") == null) 
    log("Data file does not contain a variable called 'weight'.");

Validations

Adding code specifically for validation can help prevent any holes where your script will error due to trying to run the script from an incorrect state or entering unexpected characters in an input field.

1. General

In the following example, we will return all the data files in our project using project.dataFiles and then check the length or number of files in this array. If it returns 0, that is there are no data files present, then the assert function will abort your script with a specified message:

assert(project.dataFiles.length == 0, 
                       "There is no data file in your document so this script can't be run.");

You can also throw an error when a condition is true. For example, some Displayr functions require a unique identifier to first be specified in your data set. The below code will first check whether this has been set. If not, you will be alerted to choose an appropriate variable:

var data_file = project.dataFiles[0];
var case_ids = data_file.caseIdentifiers;
if (case_ids == null || typeof case_ids == "String")
throw("Case IDs are not set for " + data_file.name + ". Please choose an ID variable and try again.");

If your intention is to prevent an error from occurring rather than alert it to the user, the try...catch approach can come in handy, as it allows your script to recover without actually erroring:

try {
     //....try doing something
} catch (e) {
     //...if it errors, do something else instead
}

2. Custom function

Another method for validation is to place all your code within a single function. This allows you to exit the function by returning false with an optional message. The basic format is below:

functionName()

function functionName() {

//... place code here

}

In the below example, we have called our function main() and will validate a user prompt to ensure the entered item is a number rather than text:

main();

function main() {
var val = prompt("Enter a value");
if(isNaN(parseFloat(val))) {
   log("This is not a number");
   return false;
}

//.... the rest of your code
}

Within our function we declare our user prompt as val.
We then perform an if condition by forcing val into a number using the parseFloat function. If the entered item is not a number it will return a NaN (not a number). The isNaN function checks whether this assertion is true, and if it is, we log a message and return false. This will abort the script and display our message.
If the entered item is a number then the rest of the code will continue to run.

Similarly, when using a user selection list box that requires users to choose a variable set, we can tell it to only display the relevant types of variable sets and add a check to ensure a selection is actually made:

includeWeb('QScript Selection Functions')
main();

function main() {
var data_file = project.dataFiles[0];
var allowed = getAllQuestionsByStructures([data_file], ["Nominal","Binary - Multi"]);
var selection = selectManyQuestions("Please select multiple variable sets",allowed).questions;
if(selection.length==0) {
   log("No variable sets have been selected") ;
   return false;
}

//.... the rest of your code
}

Within our function we declare our data file and use getAllQuestionsByStructures to only populate the user input with variable sets of a specified Structure, namely, Nominal and Binary - Multi.
The user selection prompt itself is created with selectManyQuestions and directly references our allowed variable sets.
We then perform an if condition by finding the number of selections via the length property. If there is no selected variable set, we log a message and return false. This will abort the script and display our message.
If one or more variable sets are selected then the rest of the code will continue to run.