Formula basics

Formulas are a special language used on Conjointly to perform tasks such as:

• Adding calculated variable in your experiment,
• Calculating revenue in the simulator,
• Weighting respondents,
• Piping, including in redirects.

The language is inspired by R. While knowledge of R is not required, those familiar with R will find it easy to use formulas on Conjointly. One key difference is a much more relaxed approach to data types. For example, 1 + "2" is not allowed in R, but it is allowed on Conjointly and returns 3.

You can test and debug your formulas using the Interactive debugger tab in Preview mode. The debugger can also be accessed by adding ?debugger=on to your survey URL, for example https://conjointly.online/study/629614/2yttrza1hv4k2mzvx2lb?debugger=on.

There are only four data types in formulas:

• Numbers (e.g. 1, 2.5, -3.14), which are always treated as double-precision floating point numbers (“numeric” type in R). However, for comparisons, precision is limited to six decimal places.
• Strings (e.g. "hello", "world"). All operations on them are case-insensitive.
• Booleans (i.e. TRUE or FALSE).
• Undefined, which is a special value that is returned when a variable is not defined. When formulas are used in piping inside the survey, an undefined value will be shown as 🤷.

Algebraic functions

Algebraic functions perform basic mathematical operations. They always return a number.

Important notes:

• Just like in R, if the supplied value is a string, it is converted to a number. If the string cannot be converted to a number, the result is 0.
• + does not work as a concatenator.
• If either argument is undefined, the result is undefined.
• All numbers are treated as double-precision floating point numbers (“numeric” type in R).
• If a vector of numbers is supplied, operation is done on the first element of the vector only.

Example usages of algebraic functions are provided below.

Max and min functions

The max and min functions return the minimum or maximum value from a set of arguments. They always return a number.

Important notes:

• The functions require at least 2 arguments.
• A maximum of 500 arguments are allowed; if more are provided, only the first 500 are considered.
• All arguments are converted to numbers following these rules:
  • All numbers are treated as double-precision floating point numbers (“numeric” type in R).
  • 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.
  • undefined values are converted to 0.
  • 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.

Example usages of min and max functions are provided below:

Rounding formulas

Rounding formulas are used to adjust numerical values to a desired precision:

Example usages are provided below.

Comparison operators

Comparison operators are used to compare two variables. Comparisons operators always return TRUE or FALSE.

Rules for comparing strings:

• For the == and != operators:
  • If one of the supplied values is a string, it is converted to a number. If the string cannot be converted to a number, it will be forced to 0.
  • If both variables are strings, the comparison is done alphabetically. For example, "a"=="b" returns FALSE and "a"=="a" returns TRUE. Comparison is case-sensitive.
• For other operators, strings are converted to numbers. If a string cannot be converted to a number, it will be forced to 0.

Important notes:

• If a vector of numbers is supplied, operation is done on the first element of the vector only.
• Precision of numbers is limited to six decimal places. It is achieved by checking if the absolute value of differences is greater than one millionth.
• False values work as in JavaScript: undefined will be equated to 0, or "0", for an empty string, or FALSE (and vice versa).

Example usages of comparison operators are provided below.

Boolean operators

Boolean operators are used to combine or exclude comparison operations. Boolean operators always return TRUE or FALSE.

Important notes:

• If a vector of numbers is supplied, operation is done on the first element of the vector only.
• If either argument is not boolean (i.e. a number or a string), it is converted to boolean under the same rules as x!=0.

Example usages of boolean operators are provided below.

if and ifs functions

These functions return values depending on whether a condition is true or not:

• if('condition', 'then', ['else']) checks condition and returns a value if it is TRUE or a different value if it is FALSE.
• ifs('condition1', 'then1', ['condition2'], ['then2'], ..., ['else']) returns a value that corresponds to the first TRUE condition, or the “else” value if all specified conditions are FALSE.

Conditions can be specified using comparison operators. If a condition is not boolean (i.e. a number or a string), it is converted to boolean under the same rules as x!=0.

If the “else” value is not specified, it is assumed to be undefined. If an undefined value is returned in a redirect formula, the redirect is not performed.

Example usages of if are provided below:

Example usages of ifs are provided below: