Conditional Actions - Compute

Automatically Compute a Value Based on a Formula

The conditional action (CA) type "Compute" allows a form designer to automatically derive a number or a date based on a formula that pulls factors from other fields or known values. Additionally, the computation can be forced to only run based on a defined condition.

Computations will fire either right when the condition is met (the trigger event), or when the user saves the form. Additionally, the field will display with a calculator icon next to the field. If the user taps it, it will only compute if the condition is true.

Computations will only function on Number fields or Date/Time fields and must include a formula that gets derived. Avoid using a computation to populate a field with a single variable or system constant.

To create a compute CA, select the type (1), define the criteria/condition (2), and then build the formula using the operators available in the formula section (3):

If a condition is not defined, the computation will always run when the user saves the form.

In the example above, a formula was written for Body Mass Index. Formulas must be written in a liner format from left to right by adding the variables and operators in the order seen from left to right. Here's an example for the first five items in the formula below.

 

To delete a single item, select it by clicking the bottom right corner of that item and then use the delete button:

Important points about formulas:

  • If a variable in the formula does not exist, the computation will not run. The only exception to that is in a sum or choice (dropdown/radio) fields where the formula assumes a blank as zero.
  • When computing a value with date/time fields involved, consider the form's date granularity. The formula defined must take that granularity into account. For example, if the form's granularity is set to 'Hours' and a formula is computing the difference between two dates by the formula (Date2-Date1), the value returned will be in hours. To adjust the value in Day units, either change the date granularity on the form or adjust the formula to ((Date2-Date1)/24)

Common Used Formulas

Description Formula
Body Mass Index (metric) ((weight kg)/((height cm/100)*(height cm/100)))
Body Mass Index (standard) ((weight lbs) / ((height in)*(height in))x 703)
Body Surface Area (BSA) (0.007184) * (POW(heightvalue,(.725)) * (POW(weightvalue,(.425))

 

Mathematical Functions

Functions including a single parameter
SQR: Square function which can be used as SQR(X)
SQRT: Square root function which can be used as SQRT(X)
EXP: The exponential function, exp(x), calculates the value of e to the power of x, where e is the base of the natural logarithm, 2.718281828.   Can be used as EXP(X)
SIN: Sinus function which can be used as SIN(X), X is a real-type expression. Sin returns the sine of the angle X in radians.
COS: Cosinus function which can be used as COS(X), X is a real-type expression. COS returns the cosine of the angle X in radians.
ATAN: ArcTangent function which can be used as ATAN(X)
SINH: Sinus Hyperbolic function which can be used as SINH(X)
COSH: Cosinus Hyperbolic function which can be used as COSH(X)
COTAN: which can be used as COTAN(X)
TAN: which can be used as TAN(X)
LN: natural log, which can be used as LN(X)
LOG: 10-based log, which can be used as LOG(X)
ABS: absolute value, which can be used as ABS(X)
SIGN: SIGN(X) returns -1 if X<0; +1 if X>0, 0 if X=0; 
TRUNC: Discards the fractional part of a number. e.g. TRUNC(-3.2) is -3, TRUNC(3.2) is 3.
CEIL: CEIL(-3.2) = 3, CEIL(3.2) = 4
FLOOR: FLOOR(-3.2) = -4, FLOOR(3.2) = 3


Functions including two parameters

INTPOW: The INTPOW function raises Base to an integral power. INTPOW(2, 3) = 8. Note that result of INTPOW(2, 3.4) = 8 as well.
POW: The Power function raises the Base to any power. For fractional exponents or exponents greater than MaxInt, the Base must be greater than 0.  

Example for BSA: (0.007184) * (POW(heightvalue,(.725)) * (POW(weightvalue,(.425))

For negative exponents, subtract the desired exponent from zero. Example: POW ([FieldName], 0 - 2.2)

LOGN: The LogN function returns the log base N of X. Example: LOGN(10, 100) = 2

MIN: MIN(2, 3) is 2.

MAX: MAX(2, 3) is 3

Functions involving no parameters

RND: RND() function generates a random number (double value) between 0 and 1. 

Functions with multiple parameters
SUM: SUM(2,3,5,...) functions return the sum of its arguments. There is no preset limit on the number of parameters. 

BRANCHING FUNCTIONS

IF: The IF(b, case1, case2) function provides branching capability. If b is not 0, then it returns case1, else it returns case2. Behavior is similar to C#'s: return b? case1 : case2;

If b==0 then case1 will not be Evaluated, and vice versa. Example: IF(HEIGHT, 3/HEIGHT, 3) will make sure 3/HEIGHT does not cause division by zero.

 

Date Computations and Granularity

Date Granularity determines the level of detail you want on your date/time computations. The more detail (granularity), the more converting you will have to do on your formulas. The rules of date/time formulas, however, are pretty straightforward. TrialKit will convert all date values to the granularity unit. It assumes that all numbers entered are in the proper unit or are converted to another unit for display. Regardless of which granularity level you define, you can still calculate to a lower unit. 

For example, if you define seconds as your granularity unit, you can calculate and display days and years. However, if you use days as your granularity unit, you cannot calculate to seconds, minutes, or hours.

As mentioned earlier there are four levels of granularity that can be used when computing dates. These levels are set at Form/Page Properties in the Data section of the Form Builder application.

The 4 levels of granularity include Second, Minute, Hour, and Day (No time calculations)

When TrialKit evaluates date/time formulas, it takes defined fields, retrieves their values, and converts them to time since 01-01-0001. Depending on the selected granularity, that value is expressed differently. 

For example, if you use the granularity Hour, the date is expressed numerically as hours since 01-01-0001. Therefore, if you are finding the difference between two dates and you want to express that in hours, you can simply subtract the two dates, and it will return hours. However, if you wanted to express that difference in days, you would want to divide that number by 24.

One other note about form-based Date Granularity. If you are using external fields in your calculation, and that external field is of type Date/Time, it will use the granularity of the form where the computation is defined and not the form where the field was originally created.

Date Computation Examples

Calculate Age using a granularity of hour:
To calculate a subject’s age the basic formula is (Assuming day granularity)

(CurrentDate – DateOfBirth) / 365.25
However, we are using hour granularity, therefore we must add the following to the formula: (CurrentDate – DateOfBirth) / 24 / 365.25
The difference between the Current Date and Date of Birth will be calculated and expressed in hours. However, we do not want age in hours, we want age in years. Therefore we must convert age in hours to age in years. We do this by dividing the age in hours by 24 and then dividing that by 365.25. That gives us the age in years. The following shows the formula in TrialKit. DM_DATE2 is the CurrentDate and DM_DATE1 is the DateofBirth.

Please note, with the example of age, it is typically desired as a rounded value to the lowest whole value. The system will not automatically round down on computations, so for age specifically, it is suggested to use a function such as FLOOR within the formula.

( FLOOR (( CurrentDate-Date of birth) / 365.25 ))

Calculate Elapsed Time in Minutes

To achieve this we will need to define our form to use Minute granularity. Remember you cannot convert up the granularity scale (hours to minutes).
First, you will need two-time fields.
In this example, the two fields are Date/Time fields defined using Time Only with Seconds.
Next, you will need to create a number field to display and store the elapsed time. If using this method, be sure to set the appropriate maximum length and desired decimal places on the number field.
The last step is to create the formula. It should look like this:

Computing an Anniversary Date

You can also compute date fields.
Date fields are computed by taking an existing date field and adding a number to that date field.
As with all date computations, the number is assumed to be in the form’s Date Granularity time unit.
So calculating a 30-day anniversary date from the Procedure Date, would mean just adding 30 to the Date Of Procedure field.
That, of course, assumes that the date granularity for the form is days. If not, you must convert whatever the time unit is to days.
So if it is hours, you would simply add 30 days’ worth of hours (24 * 30).
We want to calculate a 30-day anniversary date. However, our form time unit is minutes.
First, we must have a date field to calculate the anniversary date.
Next, we need to create our computed field formula. Notice we are converting 30 days to minutes.
Then we need to have our anniversary date field. By clicking the compute icon our anniversary date is calculated.

Compute an Estimated Time

Computing times is the same as computing dates.
You have to understand your date granularity unit.
Then simply add a time number to a time field.
Let’s calculate a time:
first we need two-time fields; one to calculate from the other to hold the computed time:
Next, let’s add 2 hours to Time 1. Remember, we are using seconds as our date granularity so we must convert hours to seconds:
Because we are using seconds for our date granularity, we can now calculate a time accurate to the second.