Formulas under the hood: details and examples
Conversion to numbers
In all functions and algebraic operators where a numeric argument is expected, the formula language will try to convert an argument of another type into a number using these rules:
- Strings that can be converted to numbers are converted (e.g.,
"25"becomes25). - Strings that cannot be converted to numbers become
0(including empty strings). TRUEis converted to1.FALSEis converted to0.+does not work as a concatenator (use the concat function instead).- If a vector of numbers is supplied, operation is done on the first element of the vector only.
- If an argument is a function, it is calculated first and its result is passed as an argument, which is then converted to a number according to the rules described above.
All numbers are treated as double-precision floating point numbers (“numeric” type in R).
Example usages of algebraic functions are provided below:
| Situation | Formula | Result | Comment |
|---|---|---|---|
The GET variable gender is male | GETvariable("gender") * 5 | 0 | because male is forced into 0 |
The GET variable gender was not recorded | GETvariable("gender") * 5 | 0 | because the empty string is forced into 0 |
The GET variable age is 20 | GETvariable("age") * 5 | 100 | because age is converted into the number 20 |
"3" + 5 | 8 | because 3 is forced into the number 3 | |
"male" + " bird" | 0 | because + does not work as a concatenator |
toNumber
The function toNumber(x) can be used to explicitly convert a value into a number using the same rules described above. It is equivalent to x*1 but can be more readable in some cases.
Signature: toNumber(x)
Examples:
toNumber("25")returns25.toNumber("abc")returns0.
Arguments that expect Booleans
In all functions and Boolean operators where a Boolean argument is expected, the formula language will try to convert an argument of another type into a Boolean using the x!=0 rule, where x is the argument value converted to a number according to the rules described above.
This means:
| Situation | Formula | Result | Comment |
|---|---|---|---|
!0 | TRUE | because 0!=0 is FALSE | |
!1 | FALSE | because 1!=0 is TRUE | |
!-1 | FALSE | because -1!=0 is TRUE | |
!"" | TRUE | because ""!=0 is FALSE | |
1|0 | TRUE | ||
9&7 | TRUE | because 9!=0 is TRUE and 7!=0 is TRUE | |
!-0.00000001 | TRUE | because -0.00000001!=0 is FALSE | |
!-0.001 | FALSE | because -0.001!=0 is TRUE | |
The GET variable gender is male | GETvariable("gender") & 5 | FALSE | because male is forced into 0 |
The GET variable gender was not recorded | GETvariable(“gender”) | 5 | TRUE | the empty string is forced into 0, but 5!=0 is TRUE |
The GET variable gender was not recorded | GETvariable(“gender”) | 0 | FALSE | because the empty string is forced into 0 |
The GET variable gender was not recorded | GETvariable("gender") & 0 | FALSE | because the empty string is forced into 0 |
The GET variable age is 20 | !GETvariable("age") | FALSE | because age is converted into the number 20, and 20!=0 is TRUE |
!undefined | undefined | because undefined values are contagious and propagate through the formula | |
![1, 2, 3] | FALSE | because the first element of the vector (1) is considered, and 1!=0 is TRUE | |
![undefined, 2, 3] | undefined | because the first element of the vector is undefined, and undefined values are contagious and propagate through the formula |
Arguments that expect strings
In all functions and operators where a string argument is expected, the formula language will try to convert an argument of another type into a string using these rules:
- Numbers are converted to their string representation, e.g.:
25becomes"25",-0.001becomes"-0.001", and1234567.89becomes"1234567.89".
TRUEis converted to"1".FALSEis converted to"0".undefinedvalues remain undefined.
toString
The function toString(x) can be used to explicitly convert a value into a string using the same rules described above. It is equivalent to concat(x) but can be more readable in some cases.
Signature: toString(x)
Examples:
toString(25)returns"25".toString(-0.001)returns"-0.001".
Not yet implemented: toFormat
The function toFormat(x, format) can be used to convert a number into a string with specific formatting. The x is a number. The format argument is a string that specifies the desired formatting using the number format codes in Excel for Mac. It is particularly useful for working with currencies
Examples:
| Formula | Result |
|---|---|
toFormat(25, "0.00") | "25.00" |
toFormat(25, "0.000") | "25.000" |
toFormat(25, "0") | "25" |
toFormat(25, "0.##") | "25" |
toFormat(25, "0.##") | "25.5" |
toFormat(25, "$0.00") | "$25.00" |
toFormat(25, "0.00%") | "2500.00%" |
toFormat(0.25) | undefined because the format argument is required and not provided |
Undefined values
If an undefined value is returned in a redirect formula, the redirect is not performed.
Undefined values are contagious and propagate through the formula. This means that if an argument of a function is undefined, the function will return undefined as well. For example, if answer(1234) returns undefined, then answer(1234) + 5 will also return undefined.
Not yet implemented: There are special functions that can be used to check for undefined values:
isNA(x)returnsTRUEifxisundefined, andFALSEotherwise.naTo0(x)convertsundefinedvalues to0, and leaves other values unchanged. It is equivalent toif(isNA(x), 0, x).
Undefined values are only automatically converted to 0 in the context of respondent weightings. In all other contexts, they remain undefined and propagate through the formula.
Vectors
The formula language also supports vectors, which are lists of values of the same type. They are created using square brackets (e.g. [1, 2, 3] or ["a", "b", "c"]).
If a vector is supplied where a single value is expected, only the first element of the vector is considered:
| Situation | Formula | Result | Comment |
|---|---|---|---|
| A vector of numbers is supplied | [1, 2, 3]*5 | 5 | Only the first element of the vector (1) is considered |
| A vector of strings is supplied | GETvariable(["gender", "age"]) | male | Only the first element of the vector ("gender") is considered |
But some functions, like concat, max, min, are designed to work with vectors and will process all elements of the vector.
When mixed data types are supplied in a vector, the formula language will try to convert all elements of the vector to a single type:
- If any element is
undefined, all values will be converted toundefined. - If any element is a string and there are no undefined elements, all values will be converted to strings.
- If any element is a number and there are no strings and no undefined elements, all values will be converted to numbers.
What if there are too many arguments?
If a function is supplied with more arguments than it expects, the extra arguments are ignored. For example, round(12.2, 2) will return the same result as round(12.2) because the second argument (2) is ignored.
Custom functions
Functions prefixed with c_ (e.g. c_responseEnd) are treated as custom functions and skip formula validation.
These functions apply to pipe-in formulas in the respondent interface only. They are not valid in reports (e.g. for Deep probe).
While custom functions are not subject to the unknown function validation, the expression passed as an argument must still be syntactically valid. For example, c_answer(32233dsfsfgg) will fail validation as the argument (32233dsfsfgg) is not a valid expression.