Introduction to the Quenchtec syntax language

Quenchtec use addresses and logical expressions to create logic commands. A logical expression checks whether an address (reference to questions and their values) resolves to either True or False.  The results determine how the system will respond. The syntax is general i.e. it works in questionnaire design and data collection, data management tools and in the analysis part of the system. It also works as a scripting language in Research Analyzer. 

In general it is a very comprehensive language, and as soon as you grasp the structure you will (hopefully) see the beauty of the language; You may perform very advanced and even global operations in a script - in any part of the system – and sometimes with only a single line of code or two.

The difference between addresses and logical expressions

The Research Studio uses two different concepts in scripting: Addresses and logical expressions

Addresses are generally used in one of the following scenarios:

• In questionnaire design it is used to determine valid answers (masking / range control)
• In analysis it is used to decide what part of the data set is to be analyzed (graphics, tables)

Logical expressions are generally used in one of the following scenarios:

• In questionnaire design: Determine who will/will not receive a question. (Filter commands / “goto” expressions)
• In analysis it is used to define local or global filters (universe) in tables, graphs and other analysis.

Addresses and logical expressions can be used together. Conditions for which answers are available are based on previously answered questions (conditional range control).

Filters and addresses are also uses extensively in data management tools and this enables you to create cleaning statements, filter data sets, create analysis weights and create hierarchical data sets using the split tool.

In this section we will concentrate on how to use the addresses and logical expressions in the questionnaire design process.

Addresses: Syntax

An address describes an area that can contain one or more of the listed elements.  An address is characterized by the following:

• The “backslash” \ is always the first character of the question address.
• Answer codes are contained within “hard brackets” = [  ].

A basic logical expression always includes an address that may be any of these:

• \Q - question
• \Q.S - question.sub question
• \Q.R - question.row
• \Q.S.R - question.sub question.row

Examples of Addresses

Addresses: Special Characters

Each of the address components Q, S, and R can include some of the following special characters:

Logical Expressions: Syntax

Logical expressions are "value lists" that always begin with an address and end with a desired value for that address. Logical expressions are characterized by the following:

• Always begins with a “backslash” \.
• After the “backslash”, there must always be an address that describes an element or combination of elements.
• After the address comes the equal sign =.
• After the equals sign comes the value list.

For example:

\1=1:3 when used in a filter, means question will be asked only if responses were made to the first three answers in question 1.

Examples of Logical Expressions

Logical Expressions: Special Characters

Combination of Advanced Logical Expressions (logical operators)

• ! - NOT
• | - OR (pipe)
• & - AND
• ( ) - Group complex expressions

Special Characters Used in Filters and Range Control

When collecting data in Research Studio, the system automatically tracks if a question (sub question for question type single/multiple, each row for all other question types) has been asked or not to a particular respondent. The reason for not asking a question/row can be because of any logic in the questionnaire (for example, skips, gotos or filters). As soon as a question has been asked or answered, the information is stored in the database. Regardless of the question type, the user notes if the respondent gave an answer.

The table below shows the special characters used to filter if a question exists or if it has been asked/answered/not answered.

The “-“ character, representing no answer, can only be true if the question was asked but no answer was given. This extra information often greatly simplifies the creation of logic in a questionnaire.

However, if you want to ask a question only if the respondent answered another question, you can simple specify filter=”\some_question=*”.

Likewise, if you want to filter or limit responses based on the response to that question and another question (we don’t care if this was answered), we specify filter=”\some_question=?”. This way, there is no need to repeat complex filters in all questions typically following a gate question. You can do the complex logic in this gate question and then later on, simply refer to the gate question being asked.

Syntax Used for Filter Expressions

The addressing syntax used for filter expressions varies with the sub question type used:

• For sub question types: single and multiple, you specify the left-hand side of the filter using the question ID and a sub question letter, and the value on the right-hand side with the “code” value for the row.
• Example:
• For a Gender question with id=”sex” and two rows, Male (code1) and Female (code 2). The filter=”\sex.a=1” meansMale.
• On this question, one can override the code values. If Male is given code 102 and Female is given 210, then the filter=”\sex.a=102”, meaning Male.
• If there is only one sub question, one is allowed to type filter=”\sex=102”.

Note: The right hand side of the expression is always a “code” value, not a row number.

• For all other sub question types: single-grid, multi-grid, numeric and time you need to specify a different address syntax. You specify the left-hand side of the filter using the question ID, sub question letter and the row number. Each element is separated by a period. On the right-hand side is the code value of the column header.

o    For a single-grid or multiple-grid: specify the code value of the column header.

Example: For a Scale question with ID=”grid” and with the code values in the column header of scale 1,2,3,4,5, the syntax will be filter=”\grid.a.1=1”. This means that in the question with ID grid sub question a, in row “1’ (the first row), the user has selected the option corresponding to the code value “1”. Just as with a normal single or multiple choice question, the code value in the column header of grid questions can be specified to be different from the scale 1,2,3,4,5. Typically, the scale may be reversed to 5,4,3,2,1 or you can have totally random codes assigned to each column.

o    For a numeric sub question: specify the value or the range that a user should answer for the filter to be true.

Example: For an Age question, if filter=”\age.a.1=20:40”, this means that the user should enter a value between 20 and 40. Again, for this type of question, if there is only one sub question and one row, you can specify filter=”\age=20:40”.

Note: If there are more sub questions and more rows, this will generate a validation error.

o    Use the % sign for synchronous filters on sub question types single grid, multi grid, numeric and time: The % sign will be replaced with the row number (if used on the left-hand side in sub question of the mentioned types) or the code value(if used on the right-hand side corresponding to each row in succession).

Example: If you start with a sub question that is a multiple choice, “Which of these cars do you know?” and the second sub question is a single grid, “How would you rate these cars on a scale from 1 to 5, the filter in this sub question can be written as filter=”\.a=%” (note that if you are in the same question, you do not need to specify the ID of the question). Suppose you follow this up with a third sub question, “For cars that get a rating of 4 or 5, allocate 100 points to these cars”. The filter for this third sub question will be filter=”\.b.%=4:5”. The range attribute must be used to tell the system what the sum of all the points should be, as in sub question range=”#100”.

Note: Often the filter and answer control (range) expressions are usually interconnected in Research Studio. A filter is used to determine which questions/sub questions/rows to display, while a range is used to limit or qualify what responses are allowed. In other words, the filter determines which rows to show, while the range specifies what values are allowed to be entered.