The formula field allows you to build an equation by stringing together variables and operators to produce a custom formula. This field is available for metrics, assessments, and surveys. The functionality is the same in every places, but assessments and surveys allow you to use the associated metrics as part of the equation.

Writing formulas

The formula field is easy to use, but it's very important that you add each item separately. You can select each element from the dropdown of available inputs, or you can type the element and push enter:

If you try to type out the equation all at once, it will not be recognized as a valid equation:

In addition to the equation operators and variables, you can input numbers as part of the formula by simply typing in the number you want to add and hitting enter.

When all is said and done, the formula must evaluate to return a number. Otherwise the formula is invalid.

Special operators

The formula builder has some special operators that make it easier to work with data and build complex logic. The syntax roughly resembles the Ruby programming language, but we've added a few custom methods.

Arrays

An array is an object that contains a group of other objects. In the context of the formula builder, an array will ultimately evaluate to a group of numbers. In it's simplest form, an array looks something like this:

[1, 2, 3, 4, 5, 6]

You can also use metrics as objects in an array:

[Sleep, Stress, Fatigue]

Arrays must be followed by an array operator

An array does not automatically evaluate to a number, so an array by itself is not a valid formula. You need to add an array operator in order to return a number as a valid output.

Array operators

The Ruby programming language has a number of built-in methods for arrays, some of which are included in the formula builder, like max and min. To use one of these methods, simply chain it to the end of the array:

[1, 2, 3, 4].max

In addition to the built-in Ruby methods, we've built a few custom methods for the array class to add additional functionality. Below are the basic array methods available within the formula builder.

.abs

Returns the absolute value of the statement (must operate on a number or expression that returns a number).

(5 - 7).abs
=> 2

-2.abs
=> 2

.max

Returns the maximum value in the array.

.min

Returns the minimum value in the array

.mean

Returns the mean value of all numbers in the array.

Array index

Ruby has a built-in method for arrays called "index." This method accepts an argument and returns the position of that argument in the array:

["a", "b", "c"].index("b")
=> 1

Arrays are 0 indexed, meaning the first element in the array has a position of 0. So in the example above, "b" is the at the 1 position, so the index method returns 1.

We've added some special index methods that provide useful functionality when working with array indices.

.max_index

Returns the position of the maximum value in the array.

[3, 1, 4, 2].max_index
=> 2

.min_index

Returns the position of the minimum value in the array.

[3, 1, 4, 2].min_index
=> 1

.inclusion_index(value)

Returns the position of the first element in the array that includes the given value.

[...3, 3...6, 6...10, 10...].inclusion_index(7)
=> 2

This method is special in that the elements in the array need to respond to the include? method in order for it to work properly. The include? method simply evaluates whether or not the the given value in included within the array: [1, 2].include?(2) => true.

The inclusion_index method is primarily intended to be used with a special Ruby object called a Range, which is demonstrated in the example above.

.count_if_between(start_value, stop_value, inclusive = 0)

Counts the number of values that are greater than the start_value and less than the stop_value.

[1, 2, 3, 4].count_if_between(1, 4)
=> 2

This method accepts an optional inclusive argument, which, if set to 1, changes the logic to use "greater than or equal to" and "less than or equal to."

[1, 2, 3, 4].count_if_between(1, 4, 1)
=> 4

.count_if_greater_than(value, inclusive = 0)

Counts the number of values that are greater than the given value.

[1, 2, 3, 4].count_if_greater_than(1)
=> 3

This method also accepts an optional inclusive argument to specify "greater than or equal to."

.count_if_less_than(value, inclusive = 0)

Counts the number of values that are less than the given value.

[1, 2, 3, 4].count_if_less_than(1)
=> 3

Range

The formula builder includes the Ruby syntax for an exclusive range. It is expressed using three consecutive periods. The "exclusive" designation means that the range excludes the last number. In other words, it includes all values between the first value and up to, but not including the last value. Below are some examples.

0...10

This effectively represents a range from 0 to all numbers under 10. This would include 9, 9.1, 9.9999, and so forth.

...10

This effectively represents a range of all numbers below 10 and up until, but not including 10. This would include -99, 0, 9.99, etc.

10...

This effectively represents a range from 10 and up, all the way to infinity.