IGS University of Twente

Relevance Equations

Relevance Equations

Relevance equations are the most powerful and flexible way of setting up routing. They use mathematical equations and some conditional programming. Anyway with a basic knowledge of any programming language should be able to pick up relevance equations quickly, and even to those who have no computer or programming skills, they are simple enough to understand with a few minutes of research. Additionally, LimeSurvey translates conditions set with the condition manager to relevance equations automatically, which means that you can set a basic condition with the condition manager, and then fine-tune it in the relevance equation. The possibilities are quite literally, endless.

How do relevance equations work?

Relevance equations are set when you edit a question or question group, in the relevance equation field at the bottom of the screen. In their simplest form, relevance equations have three building blocks, and look like this;

Where X and Y are variables you want to compare to each other, and the equals sign is the operator. When this equation is true, the question will show. (Note; this is why we fill in ‘1’ (the binary or computer form of ‘true’) when we want a question to always show. If the relevance field is empty, LimeSurvey also treats it as true.)

The variables can be anything, a previous answer, a token value, a constant, random number, and mostly anything else that you can come up with. You can also compare multiple variables, compute new variables on the fly, and create complex equations. In the rest of this manual we will refer to the question that is being hid or shown depending on the relevance equation as the routed question, and any question we use to determine if the routed question should be shown as source questions.

Getting started

To create a simple relevance equation, you need to know the question code of the source question, the label of the answer(s) to the source question, an operator, and a value to compare against. Let’s say we have a gender question with the code ‘sex’, we might then use the following relevance equation in the routed question to only show if the respondent is male.

Operator

Description

==

equals

<

lt

lower than

<=

le

lower than or equal to

=>

ge

greater than or equal to

>

gt

greater than

!=

not equal to

In this simple example, sex is the code for the gender question, ‘==’ is the equals operator and ‘M’ is the label for male. Of course, there are many more comparisons possible, as shown in the table below. IMPORTANT: the operator for equal to is ‘==’ and NOT ‘=’. In computer languages, ‘=’ is an assignment operator. The equation sex = ‘M’ would assign the value ‘M’ to the variable sex, which is not what we are trying to do, and would probably result in an error.

Multiple conditions

In the previous section we explained how to create a simple relevance equation. We will now expand this by adding more conditions. Let’s say we want a question to only show when the respondent is male and under 18. We have two questions for these variables coded ‘sex’ and ‘age’. The relevance equation would then look like this;

We have linked two basic equations with the ‘&&’ operator, which stands for ‘AND’. We could also just use the word ‘AND’ to achieve the same effect. If we used ‘OR’ or ‘||’, the question would show up if the respondent was either male or younger than 18. We can add any number of extra conditions, and create very complex relevance equations by combining them. To help with this, we can use ‘(‘ and ‘)’ to group conditions and execute them together, similar to how mathematical equations work. For example;

Would show the question if the respondent is either male and younger than 18, or female and older than 65. (Note; actually, leaving out the brackets would produce the exact same result in this case, as ‘AND’ is processed before ‘OR’. However, assist readability of equations, and to always err on the safe side, you should probably add the brackets anyway.)

Advanced conditions

We can also do more advanced conditions; for example, if we had a question weight and height, we could compute BMI, and show an additional question to those with a high BMI. A simple way to do this would be;

This assumes that we have the variable height in meters, as well as the variable weight in kilograms. It would then calculate BMI (height2/weight) and display the question if the result was higher than 35. However, this would probably go wrong a lot! First of all, we have not checked whether the respondent has actually answered the height and weight questions, and if they have, if they have actually filled in their height in metres, not centimetres, or inches. We can circumvent some of these problems by setting the height and weight questions to be mandatory and only accept numerical input, and have a separate question to ask for the units of measurement the respondent uses. We should probably also make sure the value of height is somewhere in an expected range. The resulting equation could look like this;

This function first checks what units are selected in the ‘units’ question, if it is metric it will then check whether the height is smaller than 3 metres (a higher value would suggest the respondent entered height in centimetres), and computes BMI. If this is not the case, it will compute BMI after dividing height by 100. Finally, if the units were not metric, it will calculate BMI for imperial units (assuming the only options in the units question were metric or imperial. The ‘if’ statements are actually functions, which work very similar to if statements in excel. The syntax is if(equation, action if true, [action if not true]). In layman’s terms, the if function first checks if a particular statement is true, in this case if the units are metric and if height is smaller then 3, and then executes either the first or the second section of code within it, which are separated by a comma. In theory you can have an infinite amount of nested if statements. More information on if statements can be found in the tailoring section.

There are a large number of other functions that you can use for advanced relevance equations, you can find a list of them here.

Troubleshooting

When you save a relevance equation, you go back to the question overview screen. Besides showing the name and description, this also shows a marked-up version of your relevance code. Any errors will be highlighted with a red box. Hover your mouse over this box to see a description of what went wrong.

Final notes

·

First of all, you can find more detailed and in-depth information on the Expression Manager on the LimeSurvey manual.

·

If you are confused, you can always define a condition in the condition manager first. Saving it will automatically convert the condition to a relevance equation which you can then use as the basis of a more complicated relevance equation

o

When you do this, make sure to copy the text of the equation to a text file somewhere, and then delete the conditions you created. If there is a condition set in the condition manager this always overrides the relevance equation and resets it even if you edit it manually.

o

The conditions manager will save variable names in a different format. It will use a SGQA code, which will look something like 123X12X2X1. This stands for the number of the survey, question group, question and answer (if applicable) in the LimeSurvey database. You can safely replace these codes with the question code.

·

If you need the value of a particular sub question, you can access it with QUESTIONCODE_SUBQUESTIONLABEL. For example, if we had an array of scales with the code ‘array’, with 5 sub questions labelled 1 to 5, and we wanted the answer to the 3rd sub question, we would use ‘array_3’ to get this value.

·

Constants should always have parenthesis surrounding them. ‘M’ is a constant, while M without the parenthesis would be seen as the name of a variable. Since this variable (probably) does not exist, it would give an error. Since numbers cannot be the names of variables, you technically do not have to add parenthesis around numbers, but it doesn’t hurt either, so it’s probably a good idea to add them anyway for the sake of consistency.