Build custom formulas in FYTT
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 KPIs and Assessments. The functionality is the same in both places, but Assessments allow you to use the Assessment metrics as part of the equation rather than exercise attributes.
BASICS
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:
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 (read more on arrays if you want to get nerdy). 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:
You can also put KPI and Assessment variables in an array:
However, an array does not automatically evaluate to a number, so this by itself would be an invalid formula. You need to do something to the array to return 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:
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
This method also accepts an optional inclusive argument to specify "less than or equal to."
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.