Calculated Field (Script)

Introduction

Calculated fields allow you to create mathematical formulas that use values associated with responses to calculate various values, such as averages, maximum values, minimum values, standard deviations, etc.

To build a formula you can use any type of field/response that has a numeric value assigned.

See below the list of questions that have, or may have, associated numerical values and can be used in a formula:

• Numerical questions (Integers, decimals and quantity using Emojis)
• Single Select Questions (Dropdown, Radio and Buttons)
• Multiple Selection Questions (Checkboxes and Buttons)
• Date and time issues
• Assessment Questions (Facial Expressions and Emojis)
• File upload issues (number of files uploaded)

Creating a simple formula

Imagine you want to create a formula that calculates the average weight of a series of samples of a certain product. So, imagine the form has the following questions:

• Sample weight 1
• Sample weight 2
• Sample weight 3

In this case, each question should be configured with a unique field name, for example, sample_weight_1, sample_weight_2, and sample_weight_3. // TODO: Add images

To do this, you must create a calculated field and then add the desired formula:

function calculateValue() {
    return (resp.sample_weight_1.number
          + resp.sample_weight_2.number
          + resp.sample_weight_3.number) / 3;
}

Let's analyze each part of the formula:

• function calculateValue() is the function that will be executed to calculate the value of the calculated field. This function cannot be renamed, it must always have this name, it cannot receive parameters and it must return a numeric value or null.
• resp is an object that contains all the responses from the form.
• resp.peso_amostra_1 is a structure that contains the data associated with the answer to the question peso_amostra_1, such as:
• number is the numeric value of the answer
• name is the name of the question field, e.g. peso_amostra_1
• tags is a list of tags associated with the question
• Finally, the formula calculates the arithmetic mean of the response values, adding sample_weight_1, sample_weight_2, sample_weight_3 and dividing by 3.

Variable names

You can use any name for the variables, but it is recommended that you use names that make sense for your form.

Autocomplete

You can use Ctrl+Space or Ctrl+Shift+Space keys to activate autocomplete manually.

General response attributes

All answers have at least three attributes: name, tags, and one or more attributes specific to the answer type, for example, number for numeric questions, text for text questions, etc.

name {#name]

name: string

Question name. Example: sample_weight_1

tags [tags]

tags: string[];

List of question tags, example: ['weight', 'sample']

Tags are used to group questions and make it easier to create formulas. For example, to calculate the average of the weights of several samples, simply put a tag on each weight question, for example, #weight, and use that tag in the formula:

function calculateValue() {
    return avgByTag('#weight');
}

Where avgByTag means: "average by tag".

Specific response attributes

See below for a list of specific attributes available for each response type:

text

text?: string;

Textual content of the answer, available for questions of the type:

• One line text
• Multi-line text
• E-mail

Character "?"

The "?" character indicates that the attribute is optional, that is, it may or may not exist. If the user answers the question the attribute will exist, otherwise it will not exist.

label

label?: string;

Label or Text linked to the selected option, available for questions of the type:

• Single selection
• Multiple selection
• Facial expressions

number

number?: number;

Numeric content of the response, either the content provided by the user or the numeric content linked to the selected option. Available for questions such as:

• Integer numbers
• Decimal numbers
• Quantity using Emojis
• Mathematical formula
• Single/simple selection
• Facial expressions
• Time/Hour

dateStr

dateStr?: string;

Date in text form (string). Format: YYYY-MM-DDTHH:MM:SSZ, ex: 2030-12-31T23:59:59Z

Available for questions such as:

• Date
• Date and time

lat

lat?: number;

Latitude of the geographic coordinate given in the response

long

lon?: number;

Longitude of the geographic coordinate given in the response

items

items?: ISelectedItem[];

List of selected items, available for questions of the type:

• Multiple selection
• Ordering

Each item in the items list has the following attributes:

• label: string: Label or Text linked to the selected option.
• number?: number: Numeric content of the selected option.
• position?: number: Number representing the order chosen by the user for the selected item. Only available in Ordering type questions

Available functions

The functions below are tools that assist in creating formulas, allowing you to perform complex calculations on dozens or hundreds of answers with just one line of code.

all

function all(): IResponse[];

Returns a list (array) with all existing answers up until the moment the code is executed, that is, the answers to the questions that appear before this element.

Attention

This warning applies to all functions that return a list of responses.

findByTag

function findByTag(oneOrMoreTagNames: string | string[]): IResponse[];

Returns a list (array) with the responses that have the specified tags.
Only questions that appear before this element will be analyzed.

Example:

The function below returns the number of responses that have the #weight tag, that is, the number of samples filled out by the user.

function calculateValue() {
    const qntSamples = findByTag('#peso').filter(r => hasContent(r.number)).length;
    return qntSamples;
}

avgByTag

function avgByTag(...oneOrMoreTagNames: string[]): number;

Calculates the average of the numeric values of responses that have the specified tags.

Answers that do not have a numerical value are ignored.

Only questions that appear before this element will be analyzed.

Tip

Ex.: If you use the following formula to calculate the average of 3 weights: (weight1 + weight2 + weight3) / 3, the result will only be correct if all 3 samples are filled. Otherwise the result will be incorrect.

Image that the user has filled only 2 samples, namely weight1 and weight2, and left the third sample blank, in this case the result of the formula will be: (weight1 + weight2) / 3, which is different from the correct result: (weight1 + weight2) / 2.

To avoid this type of situation, it is recommended to use the avgByTag function to calculate the average, as it properly handles blank answers, that is, the result will always be correct.

sumByTag

function sumByTag(...oneOrMoreTagNames: string[]): number;

Calculates the sum of the numeric values of the responses that have the specified tags.

Only questions that appear before this element will be analyzed.

countByTag

function countByTag(...oneOrMoreTagNames: string[]): number;

Returns the number of responses that have the specified tags.

Only questions that appear before this element will be analyzed.

maxByTag

function maxByTag(...oneOrMoreTagNames: string[]): number | undefined;

Returns the largest numeric value found in responses that have the specified tags, or 'undefined' if no value is found.

Answers that do not have a numerical value are ignored.

Only questions that appear before this element will be analyzed.

minByTag

function minByTag(...oneOrMoreTagNames: string[]): number | undefined;

Returns the smallest numeric value found in responses that have the specified tags, or 'undefined' if no value is found.

Answers that do not have a numerical value are ignored.

Only questions that appear before this element will be analyzed.

hasContent

declare function hasContent(value: any): boolean;

Returns true if the value provided is different from undefined, null, [] or an empty string ('').

isEmpty

declare function isEmpty(value: any): boolean;

Returns true if the value provided is undefined, null, [] or an empty string ('').

Examples

Example 1

In this example we will show how to calculate the values of the Bhaskara Formula. The purpose of this example is to show how to store partial values in variables and how to use these values to perform more complex calculations.

In this example we will also see how to use predefined mathematical functions, such as Math.sqrt and Math.pow.

Definition of Bhaskara's formula:

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

function calculateValue() {
    let a = resp.a.number;
    let b = resp.b.number;
    let c = resp.c.number;

    let delta = Math.pow(b, 2) - 4 * a * c;

    let x1 = (-b + Math.sqrt(delta)) / (2 * a);
    let x2 = (-b - Math.sqrt(delta)) / (2 * a);
    return x1; // or x2
}

Where: Math.pow(b, 2) is equivalent to b²
Math.sqrt(delta) is equivalent to √delta

Example 2

In this example we will see how to calculate the Fibonacci sequence. The objective of this example is to show that it is possible to define and use different functions, including recursive functions, thus allowing the creation of more complex calculations.

function calculateValue() {
    const n = resp.any_question_answer.number;
    return fibonacci(n);
}

function fibonacci(n: number): number {
    if (n <= 1) {
        return n;
    }
    return fibonacci(n - 1) + fibonacci(n - 2);
}

Predefined mathematical functions

Name	Description
abs(x)	Returns the absolute value of x
steels(x)	Returns the arccosine of x, in radians
acosh(x)	Returns the hyperbolic arccosine of x
asin(x)	Returns the arcsine of x, in radians
asinh(x)	Returns the hyperbolic arcsine of x
atan(x)	Returns the arctangent of x as a numeric value between -PI/2 and PI/2 radians
atan2(y, x)	Returns the arctangent of the quotient of its arguments
atanh(x)	Returns the hyperbolic arctangent of x
cbrt(x)	Returns the cubic root of x
ceil(x)	Returns x, rounded up to the nearest integer
clz32(x)	Returns the number of leading zeros in a 32-bit binary representation of x
cos(x)	Returns the cosine of x (x is in radians)
cosh(x)	Returns the hyperbolic cosine of x
exp(x)	Returns the value of Ex
expm1(x)	Returns the value of Ex minus 1
floor(x)	Returns x, rounded down to the nearest integer
fround(x)	Returns the closest floating-point (32-bit single precision) representation of a number
log(x)	Returns the natural logarithm of x
log10(x)	Returns the base 10 logarithm of x
log1p(x)	Returns the natural logarithm of 1 + x
log2(x)	Returns the base-2 logarithm of x
max(x1,x2,..)	Returns the number with the largest value
min(x1,x2,..)	Returns the number with the smallest value
pow(x, y)	Returns the value of x raised to the y
random()	Returns a random number between 0 and 1
round(x)	Round x to the nearest integer
sign(x)	Returns the sign of a number (checks if it is positive, negative or zero)
sin(x)	Returns the sine of x (x is in radians)
sin(x)	Returns the hyperbolic sine of x
sqrt(x)	Returns the square root of x
tan(x)	Returns the tangent of an angle
tanh(x)	Returns the hyperbolic tangent of a number
trunc(x)	Returns the integer part of a number (x)

Predefined mathematical constants

Name	Description
Math.AND	Returns Euler's number (approx. 2.718)
Math.PI	Returns PI (approx. 3.14)
Math.SQRT2	Returns the square root of 2 (approx. 1.414)
Math.SQRT1_2	Returns the square root of 1/2 (approx. 0.707)
Math.LN2	Returns the natural logarithm of 2 (approx. 0.693)
Math.LN10	Returns the natural logarithm of 10 (approx. 2.302)
Math.LOG2E	Returns the base-2 logarithm of E (approx. 1.442)
Math.LOG10E	Returns the base-10 logarithm of E (approx. 0.434)