Introduction to Methods

Summary

Methods provide a means of programmatically filling values into itemData fields using inputs from other areas of the application. Methods are established within the CRF Design > Study Library component and are attached to the Item into which the returned value should populate. Example use cases for methods may include:

Calculating age based off of date of birth
Calculating BMI based off of height and weight
Summing total volume of void collections
Transcribing urine interval stop time into the start time field of the next interval

Understanding Method Fields

Name: For organizational purposes only, method name helps users locate methods in the study library.

Description: For organizational purposes only, method description helps users understand the intended purpose of the method. This is the normative content of the Method.

Method Type: For organizational purposes only, method type describes the programmatic strategy of the method. Options include: Computation, Imputation, Transpose, and Other.

Formal Expression Context: For organizational purposes only, formal expression context is used to describe who wrote the method. Typically, this will be FH or IQVIA if the ClinSpark product team wrote the method, or, Customer Name if the customer wrote the method.

Formal Expression: The Formal Expression field is the functioning part of a method. This field contains a machine-readable expressions that implements calculations based on defined inputs to return a value. Multiple FormalExpressions can be provided if each has a different Context attribute, allowing the same expression to be represented in forms appropriate to multiple systems.

Attaching Methods to Items

A method is attached to the Item Reference for which a calculated value is to be returned.

Assumptions and Conditions

Methods fire upon saving the containing Form.
The data type returned by the method’s formal expression must match the data type of the item to which the method is attached.

Measurement Units

When creating a method, it may be desirable to specify measurement units for a calculation. To prevent a “units required” error during data collection, a Measurement Unit in the Study Library must be assigned to the item storing the calculated results, and this item’s measurement unit must match the ‘measurementunitname’ value defined in the method. For instance, if we are using height and weight to calculate BMI, the Study Library Measurement Unit of “kg/m²” must be assigned to the BMI item and the Study Library Method calculating BMI must have ‘measurementunitname’ set to “kg/m²”. Not setting the BMI item’s measurement unit to “kg/m² and ‘measurementunitname’ to “kg/m² will provide a “units required” error or unpredictable results depending on the setup.

Examples

Age

This method calculates Age using collected items named BRTHDTC.

var age = null;
var dob = findFirstItemDateByName(formJson, null, 'BRTHDTC');
if (dob != null) {
  var today = new Date();
  var birthDate = new Date(dob);
  age = today.getFullYear() - birthDate.getFullYear();
  var m = today.getMonth() - birthDate.getMonth();
  if (m < 0 || (m === 0 && today.getDate() < birthDate.getDate())) {
    age--;
  }
  age = Math.floor(age).toString();
}
return age;

Copy datetime

When multiple labs, PKs etc are being collected in one form and the desire is that each tube has the same date time capture time, replace Item Name with the name of the item from which datetime will be pulled with the following method:

var DT = findFirstItemValueByName(formJson, "Item Name");

return DT;