Syntax Guide
Syntax Guide: Filtered Answer Options
For categorical single
select and
multi-select
questions, Survey Solutions allows you to filter the answer options so
that not all the answer options for the question will be displayed to
the interviewer. Filtering answer options can help improve data quality
so that an interviewer cannot select answer options that are either
impossible or highly unlikely. For example, for a question where the
interviewer has to select the household member’s father, you can filter
the answer options so that anyone that is younger than the household
member will not be displayed.
Syntax Guide: Multi-select questions
Two types of multi-select questions
There are two types of multi-select questions. They differ not only in the way they appear, but in the way their answers can be referenced with Survey Solutions’ conditions language.
Click below on the type of multi-select question that interests you:
Series of tick boxes
Technical introduction
When the interviewer answers a multi-select question, the answers are stored in an array.
November 30, 2016Syntax Guide: List questions
List questions are recorded as Tuple<decimal, string> data type.
Each item in a list question response consists of two elements. One is the item number, and the other is the accompanying text. For example, in the list question displayed. “Paul Smith” is the text element (Item2) and “2” is the number(Item1).
List of household members =
[
{1, “Mary Smith”}
{2, “Paul Smith”}
{3, “Richard Smith”}
]
Syntax Guide: Text questions
Responses to text questions are recorded as a string data
type. The content for these types of
questions consists of characters (e.g. the letter “A”), group of
characters (e.g. “Mat”), or class of characters (e.g. white or empty
space).
The following functions can be used in conditions for text questions:
- Length: Checks the number of characters
- “A text”: Checks that the response is exactly equal to a specified text (“A text”)
- Contains: Checks that the response includes a specified text
- ConsistsOf: Checks that the response includes one or more of the specified characters
- IsAlphaLatin: Checks that the response consists of latin characters
- IsAlphaLatinOrDelimiter: Checks that the response consists of latin characters and delimiters
- IsNullOrWhiteSpace: Checks that the response is null or consists of blank spaces
November 28, 2016
Syntax Guide: Barcode questions
Responses for barcode questions are recorded as a string data
type.
The following functions can be used in conditions for barcode questions:
- Length: Checks the number of characters
- StartsWith: Checks that the barcode starts with specific characters
- EndsWith: Checks that the barcode ends with specific characters
- IsNumber: Checks that the barcode is a number
- ConsistsOf: Checks that the barcode consists of a specific set characters
Length
Description
Checks the number of characters.
Syntax Guide: GPS questions
Responses for the GPS questions are recorded as:
class {
double Latitude;
double Longitude;
double Accuracy;
double Altitude;
}
The following functions can be used in conditions for GPS questions:
- Longitude, Latitude, Accuracy, and Altitude. Retrieves the latitude/longitude/accuracy/altitude of a GPS coordinate.
- InRectangle. Check if the coordinates are inside a rectangle.
- GpsDistance. Calculate the distance between two coordinates in meters.
- GpsDistanceKm. *Calculate the distance between two coordinates in kilometers. *
Longitude, Latitude, Accuracy, and Altitude
Description
Retrieves the latitude/longitude/accuracy/altitude of a GPS coordinate.
November 22, 2016Syntax Guide: Date questions
There are two types of date questions: Calendar and Current time. Both
of these questions are recorded as DateTime? data
type.
Responses for the calendar data questions are recorded as {Year, Month,
Day}. Meanwhile, responses to the current time questions are recorded as
{Year, Month, Day, Hour, Minute, Second}.
Calendar
Comparisons
- Relational Operators. Less than, greater than, equal to, etc
- InRange. Checks if the date falls within an interval.
Perform Calculations
- FullYearsBetween. Computes full years between an earlier and later date.
- FullYearsSince. Computes full years between a later date with an earlier date.
- CenturyMonthCode.Computes elapsed time in months with Century Month Code(CMC).
- TotalDays. Computes elapsed time in days.
- Value.AddYears/Months/Days. *Add or subtract years, months, or days. *
Extract Information
- Value.Year/Month/Day. Retrieve the year, month, or day.
- New DateTime. Constructs a new date.
- IsDate. Confirms that a date matches a calendar date.
Current Time
Extract Information
Perform Calculations
- AddHours.Compute a date by adding a number of hours.
- AddMinutes. Compute a date by adding a number of minutes.
Operators
Description
Compare a calendar date with another using the relational operators.
November 19, 2016Syntax Guide: Single-select questions
Common tasks
The section below lists the common tasks, and the elements of the syntax for accomplishing them.
Comparison to a value
- Relational Operators
- less than, greater than, equal to, etc.
Comparison to a range
- InRange. Checks if the selected answer falls within a range of user-specified values.
Comparison to a list of values
- InList. Checks whether the selected answer is among the set of enumerated values.
- IsNoneOf. Confirms that the selected answer is not among the set of enumerated values.
Count the number of values
- CountValue. Counts the number of times a specified value is recorded as the answer to the set of enumerated questions.
Syntax explained
InRange
Syntax
singleSelect.InRange(a,b)
Description
Checks if the selected answer falls within a range of user-specified values. Returns true if
November 17, 2016Syntax Guide: Numeric Questions
Responses to numeric questions are recorded in the long data type for integer numbers and record in the double data type for real numbers (ie 1.5, 2.73, 15.25, 2.0).
The following functions and operators can be used in conditions for
numeric questions:
Comparison to a value
- Relational Operators: less than, greater than, equal to, etc
Comparison to a range or several values
- InRange: Checks if the number falls within a range
- InList: Checks if the number falls within a list of numbers
August 18, 2016
Section functions
Section functions (introduced in v19.02) are functions that may be used in Survey Solutions’ syntax to get some useful indicators about the completeness of the sections, such as to establish whether a certain section has been fully answered.
The following functions are defined for sections:
| IsSectionAnswered() | returns a boolean true if all the [enabled] questions in the section have been answered, and false otherwise. |
| EnabledQuestionsCount() | returns the total number of questions currently enabled in the section. |
| NumberUnansweredQuestions() | returns the total number of questions that have not been answered in the section. |
| EnabledAnsweredQuestionsCount() | returns the total number of questions that have been answered in the section. |
All of these functions must receive a certain section identifier as an argument, for example:
IsSectionAnswered(DemogSect)
Available C# Namespaces
Survey Solutions uses C# language for writing the expressions, such as enabling
or validation conditions. The C# language organizes classes of objects into
namespaces. To use a class from a namespace the C# program must have access to
the corresponding namespace. Survey Solutions provides access to the following
namespaces:
System(except these specific properties:DateTime.Now,DateTime.UtcNow,DateTime.Today)System.CollectionsSystems.Collections.GenericSystem.LinqSystem.Linq.ExpressionsSystem.Linq.QueryableSystem.Text.RegularExpressions
You can click on the name of the namespace to see which classes, functions, etc.
the namespace avails for the user. System.Linq.Queryable is technically a class,
documented here.
Forbidden type error
Survey Solutions uses C# language for writing the expressions, such as enabling or validation conditions. Yet, where we thought the language features may be misused to create vulnerabilities, we’ve restricted its use by disallowing certain C# data types, such as accessing files or network.
If you are getting a “Forbidden type” error (corresponding error codes are WB0272, WB0273, WB0274, WB0275) the expression you’ve written is probably following the correct syntax, but is not going to compile for the reason of security.
July 20, 2021Syntax Guide: Using LINQ Expressions for Conditions in Rosters
Rosters are common survey instruments (ie household roster, assets roster, food consumption roster). Using Language Integrated Query (LINQ) and lambda expressions in the C# language, we are able to code enabling and validation conditions for rosters that can both:
- Horizontally: Refer to the values of other variables for the current occurrence
- Vertically: Refer to the values of the same variable for other items in the roster
In this article, we will cover the general syntax, common
operators, provide a few examples on how to
write enabling and validation conditions for rosters. Additionally, this
article also provide links to more resources on LINQ
expressions.
Syntax Guide: System Generated Variables
These are variables that are created by Designer to allow the user
to refer to certain variables or lines in a roster in enabling
conditions or
validation
conditions. More
detail is provided below about useful system variables:
self, @rowcode, @optioncode, and
@current.
self
For validation conditions, a very useful system generate variable is self. This variable denotes the value of the question being validated. Using self instead of the question’s variable name in a question’s validation conditions is advised because you will not have to change the variable name in the validation condition if the variable name for the question is changed.
August 16, 2016Syntax Guide: Operators
Designer has built-in operators that can be used in enabling conditions or validations. This article explains the following operators that you can use in your instrument:
Arithmetic Operators
The following table shows the arithmetic operators supported by Survey Solutions. Arithmetic expressions are evaluated from left to right. For the example, assume A = 20 and B = 10
| Operator | Description | Example |
|---|---|---|
| + | Addition: returns the sum | A + B = 35 |
| - | Subtraction: returns the difference | A - B = 10 |
| * | Multiplication: returns the product | A * B = 200 |
| / | Division: returns the quotient | B / A = 2 |
| % | Modulus: returns the remainder after an integer division | B % A = 0 (The remainder of 20 divided by 10 is 0) |
August 15, 2016
Dealing with exceptions
An exception is a situation where the computer can’t proceed with a
normal flow of commands.
A common example is a division by zero. The result of this operation is
not defined. In statistics a concept of a missing value is introduced,
and we normally don’t bother about the process. We know the result of X
divided by zero ;will be a missing.
In C# division by zero will cause the program to abort with an exception. The programmer can envelop the risky code into a wrapper, similar to how you capture { } a certain code in Stata. In Survey Solutions we always do this behind the scenes for the users, so when an exception occurs:
August 10, 2016Data types
Survey Solutions uses C# language for enabling and validation conditions. C# is a contemporary general purpose object-oriented programming language, widely documented. When writing expressions in C# language, and especially when using standard C# and custom Survey Solutions functions it is important to keep in mind the definitions of the various Survey Solutions objects.
Below the types of Survey Solutions objects are explained in terms of standard C# classes and types. Links are provided to the corresponding definitions on Microsoft’s site.
August 9, 2016