How Calculations Work

For each calculation, Illume creates a variable with the same name as the calculation. Illume attempts to evaluate all of the calculations in the survey each time a participant moves from one page to the next.   Illume relies on piping to grab the value of variables used in the calculation.  For example, if a participant entered “200” in response to the question named WEIGHT that asked “What is your weight (in pounds)?”, Illume substitutes 200 for the tag {Value:WEIGHT}.

Illume will perform value substitutions (aka piping) on any variables for which it has data. It does not matter whether that data came from a participant response, from a variable appended to the survey URL, or from data that was pre-loaded from the participant list.  If Illume cannot perform the calculation, the value of the calculation will be the default value set for the calculation in the Survey Calculations Editor.  If no default value is set, and Illume cannot perform the calculation, the value for the calculation will be null (empty).

There are three conditions under which Illume cannot perform a calculation:

  1. The expression is invalid. The Survey Calculations Editor will tell you if your calculation is invalid before you save it.
  2. The expression includes variables whose values are unanswered or unknown.
  3. The calculation would result in an error. The most common causes of this are attempting divide by zero and supplying a value of the wrong data type. For example, if your calculation is {Value:HEIGHT} / {Value:WEIGHT}, design the survey to allow only numeric values for the height and weight questions. Illume can divide by the numeric value “150” but it cannot divide by the text value “one hundred and fifty.”

The calculation itself is a JScript.NET expression, or a series of JScript.NET statements. Illume evaluates the JScript.NET using the eval() function and sets the value of the calculated variable to whatever eval() returns.

There are two things to note about eval() in JScript.NET:

  1. eval() returns the value of the last expression in the script.
  2. eval() does not permit a return statement.

EXAMPLE:  The following calculation determines the total price for a quantity of some material, then applies a discount of 5%:

var weightInGrams = {Value:KILOGRAMS} * 1000;

var pricePerGram = 0.13;

var totalPrice = weightInGrams * pricePerGram;

var discount = 0.05;

totalPrice * (1 – discount);

Notice that the value to be returned is expressed on the last line as totalPrice * (1 – discount), and that there is no return statement. Because JScript’s eval() returns the value of the last expression, the result of the calculation will be the value of the last expression in the calculation.

Calculation Operators

The following operators are available for calculated variables:

Arithmetic Operators

  • + (Plus Sign) Used for addition.
  • – (Minus Sign) Used for subtraction.
  • * (Asterisk) Used for multiplication.
  • / (Forward Slash) Used for division.
  • ^ (Carat) Raises a number to a power. E.g. 5^3 is 5 to the third power, or 125.
  • % (Percent Sign) Modulo operator, used to find the remainder of a division operation

Comparison Operators

  • == Is equal.
  • != Is not equal.
  • < Is less than.
  • Is greater than
  • <= Is less than or equal to
  • = Is greater than or equal to

Logical Operators

  • && And
  • || Or
  • ?: If/then/else