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" becomes 25).
  • Strings that cannot be converted to numbers become 0 (including empty strings).
  • TRUE is converted to 1.
  • FALSE is converted to 0.
  • + 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:

SituationFormulaResultComment
The GET variable gender is maleGETvariable("gender") * 50because "male" is forced into 0
The GET variable gender was not recordedGETvariable("gender") * 50because the empty string is forced into 0
The GET variable age is 20GETvariable("age") * 5100because GETvariable("age") is converted into the number 20
"3" + 58because 3 is forced into the number 3
"male" + " bird"0because + does not work as a concatenator
Not yet implemented15 %% "male"undefinedbecause "male" is forced into 0, and 15 %% 0 returns undefined (see the modulo operator)
Not yet implemented15 == (15 %% "male")undefinedbecause undefined values propagate through every operator, including ==

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") returns 25.
  • toNumber("abc") returns 0.
  • toNumber(c("25", "abc")) returns 25 because the first element of the vector is considered.

Conversion to 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:

SituationFormulaResultComment
!0TRUEbecause 0!=0 is FALSE
!1FALSEbecause 1!=0 is TRUE
!-1FALSEbecause -1!=0 is TRUE
!""TRUEbecause ""!=0 is FALSE
1|0TRUE
9&7TRUEbecause 9!=0 is TRUE and 7!=0 is TRUE
!-0.00000001TRUEbecause -0.00000001!=0 is FALSE
!-0.001FALSEbecause -0.001!=0 is TRUE
The GET variable gender is maleGETvariable("gender") & 5FALSEbecause "male" is forced into 0
The GET variable gender was not recordedGETvariable(“gender”) | 5TRUEthe empty string is forced into 0, but 5!=0 is TRUE
The GET variable gender was not recordedGETvariable(“gender”) | 0FALSEbecause the empty string is forced into 0
The GET variable gender was not recordedGETvariable("gender") & 0FALSEbecause the empty string is forced into 0
The GET variable age is 20!GETvariable("age")FALSEbecause GETvariable("age") is converted into the number 20, and 20!=0 is TRUE
!undefinedundefinedbecause undefined values are contagious and propagate through the formula
![1, 2, 3]FALSEbecause the first element of the vector (1) is considered, and 1!=0 is TRUE
![undefined, 2, 3]undefinedbecause the first element of the vector is undefined, and undefined values are contagious and propagate through the formula

Conversion to strings

In all functions 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.:
    • 25 becomes "25",
    • -0.001 becomes "-0.001", and
    • 1234567.89 becomes "1234567.89".
  • TRUE is converted to "1".
  • FALSE is converted to "0".
  • undefined values remain undefined.

toString

The function toString(x) can be used to explicitly convert a single value into a string using the same rules described above. It is equivalent to concat(x) if x is a single value (not a vector).

Signature: toString(x)

Examples:

  • toString(25) returns "25".
  • toString(-0.001) returns "-0.001".
  • toString(c(1234567.89, 4)) returns "1234567.89".

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:

FormulaResult
toFormat(25, "0.00")"25.00"
toFormat(25, "0.000")"25.000"
toFormat(25, "0")"25"
toFormat(25, "0.##")"25"
toFormat(25.5, "0.##")"25.5"
toFormat(25.555, "0.##")"25.56"
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

Undefined values can occur when an invalid argument is passed to a function (e.g. a wrong question/item/stimulus ID that is not part of the experiment or monadic block). They can also occur when attempting to access an answer when that is impossible (e.g. the question was not shown, or the function does not work for that question type).

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. The same applies to comparison operators: answer(1234) == 5 returns undefined, not FALSE. The exceptions are isNA and naTo0, which exist to check for and replace undefined values, and extra arguments that a function ignores.

A calculation that has no numeric result, such as 0/0, also returns undefined.

If an undefined value is returned in a redirect formula, it will be substituted with the text "undefined". If, as a result, the whole redirect URL is invalid (e.g. does not start with http:// or https://), the redirect is not performed at all.

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, unless you handle them with isNA or naTo0.

isNA and naTo0 work in every context where formulas are used, including surveys, reports, weightings, and the simulator. In the formula editor modal, they are listed under Undefined values.

isNA

The function isNA(x) checks whether a value is undefined. It returns TRUE if x is undefined, and FALSE otherwise. It never returns undefined itself. To check that a value is defined, use !isNA(x).

Signature: isNA(x)

Examples:

SituationFormulaResultComment
isNA(undefined)TRUE
isNA(0)FALSEbecause 0 is a defined value
isNA("")FALSEbecause an empty string is a defined value
isNA("undefined")FALSEbecause the text "undefined" is a string, not the undefined value
isNA(FALSE)FALSE
Question 1234 was not shown to the respondentisNA(answer(1234))TRUEbecause answer(1234) returns undefined
Question 1234 was not shown to the respondent!isNA(answer(1234))FALSE
isNA(c(1, 2, 3))FALSE
isNA(c(1, undefined, 2))TRUEbecause a vector with any undefined element is treated as undefined
isNA(c())TRUEbecause an empty vector is undefined
isNA(0/0)TRUEbecause 0/0 has no numeric result
isNA(toDateTime("2023-13-01 10:45:49"))TRUEbecause the date cannot be converted

For example, to show a follow-up question only to respondents who have a top level from a conjoint, use the calculated variable !isNA(topLevel(attribute_id)) in the display logic.

naTo0

The function naTo0(x) converts an undefined value into 0 and returns any other value unchanged. For a single value, it is equivalent to if(isNA(x), 0, x). Defined values keep their type: strings stay strings and Booleans stay Booleans. If x is a vector, only its first element is returned.

Signature: naTo0(x)

Examples:

SituationFormulaResultComment
naTo0(undefined)0
naTo0(5)5
naTo0("hello")"hello"because defined values are not converted to numbers
naTo0("")""because an empty string is a defined value
naTo0(TRUE)TRUE
Question 1234 was not shown to the respondentanswer(1234) + 5undefinedbecause undefined values are contagious
Question 1234 was not shown to the respondentnaTo0(answer(1234)) + 55because naTo0 replaces undefined with 0 before the addition
naTo0(c(1, 2, 3))1because only the first element of the vector is returned
naTo0(c(1, undefined))0because a vector with any undefined element is treated as undefined
naTo0(0/0)0because 0/0 has no numeric result

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.

If there is an undefined value among the extra ignored arguments, it does not affect the result of the function. For example, round(12.2, 2, undefined) will still return the same result as round(12.2) because the extra arguments are ignored.

Custom functions

Functions prefixed with c_ (e.g. c_responseEnd) are treated as custom functions (specified in customisations) 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.