Defining a Calculated Variable

To define a calculated variable, follow these steps:

  1. Choose Survey / Calculations from the DatStat Illume Survey Designer menu
  2. Click the Add button to add a new calculated variable, or double click on the name of an existing calculation to edit it.  You may also copy and paste an existing calculation.

DS_CalulationEditor.gif

  1. In the Calculation Editor, give the calculated variable a unique name if it does not already have one. Provide a description to help users remember what this variable calculates.
  2. Choose a data type. The data type to choose depends on what result is expected from the expression. Mathematical operations and any true/false expression produce numbers, so these require a numeric data type. (True expressions are equal to 1; false expressions are equal to 0.) Expressions that return text data require a Text data type.
  3. Assign an optional default value. This will be the value of the calculation when there are not enough data to perform the actual calculation. For example, if the calculation is the sum of A, B and C, the calculation will contain the default value until the participant has answered questions A, B and C.
  4. Click Insert Expression to select survey variables to include in the calculation.
    • NOTE:  Whereas in other places in a survey you can pipe the value of a variable using a single letter tag such as “V” for “Value”, in the Calculations editor you must write out the tag fully, thus Value is acceptable but V is not.
  5. In the Expression Calculator, choose the variables required to perform the calculation. To select more than one variable, hold down the Control key while you click on each variable to include. Note that the selected variables appear in an expression below the variable list. The expression uses only addition. This can be changed going forward.

DS_CalculationExpressionCalculator.gif

  1. After choosing all of the variables to include in the calculation, click Paste. The expression will be pasted into the Calculation Editor. Beneath the Insert Expression button, the message “Calculation is valid and evaluated successfully.” should be visible.
  2. Now edit the calculation by hand. Illume will evaluate any simple and complex JScript.NET expressions. Expressions cannot include user-defined objects or functions, but they can include built-in JScript.NET objects, datatypes, methods and operators. Note JScript.NET is the version of JavaScript used by Microsoft Windows and Internet Explorer. It is essentially a superset of standard JavaScript (a.k.a. ECMAScript). See Microsoft’s JScript.NET Language Reference for more information about JScript.NET. If there is a problem with the calculation, a message describing the problem will appear below the Insert Expression button, and the offending part of the calculation will be highlighted in red. If the calculation is valid JScript.NET but the calculation editor does not have enough information to evaluate it, you’ll see the message Calculation is valid but failed to evaluate. The calculation will be evaluated while the survey is running, if there is enough information to perform the evaluation. (I.e., if the participant answered the questions to which the expression refers.)
  1. Click OK .

NOTE: Illume uses parentheses to determine precedence when evaluating calculations.