— Jozef Aerts 2009/02/28 10:53

Author: Jozef Aerts, XML4Pharma

Applicable to: ODM version 1.3, 1.2, 1.1

Rangechecks are very usefull in EDC: they allow to obtain much cleaner data in case the rangecheck is performed on the client where data is entered, i.e. when the client is configured so that (numeric) values outside the range given by the rangecheck are not accepted. Depending on the implementation, the user will receive a notice when entering values outside the acceptable range, and/or will not be able to submit the form (eCRF) until all entered values are within the ranges given by the rangecheck.

The CDISC ODM Standard has a simple, but efficient way to define rangechecks on items. Additionally (as of ODM 1.3), more complicated rangechecks can be defined in any computer language using the “FormalExpression” element.

Each “ItemDef” element can have zero or more “RangeCheck” child elements. Each of these “RangeCheck” elements defines a single check. So one will e.g. need a “RangeCheck” to define a lower bound for the value, and a “RangeCheck” for the upper bound for the value. Furthermore, rangechecks can be defined as being “Hard”, meaning that if the value is out of range, the value should be rejected. When the rangecheck is being defined as “Soft”, a warning should be issued, but the value should be accepted upon submit. So for the simple case of a lower and upper bound, one can have 4 rangechecks:

In this example, we have 4 rangechecks:

• An upper, hard bound (SoftHard=“Hard”) with a value of 220: if the value entered is higher, it cannot be accepted
• An upper, soft bound (SoftHard=“Soft”) with a value of 180: if the value entered is between 180 and 220, a warning message will be issued
• A lower, hard bound with a value of 30: if the value entered is lower, it cannot be accepted
• A lower, soft bound with a value of 50: if the value entered is between 30 and 50, a warning message will be issued

The comparator, i.e. the mathematical operation to be used for the comparison, is given by the “Comparator” attribute. It can have following values:

• “LT” : less than
• “LE” : less than or equal to
• “GT” : greater than
• “GE” : greater than or equal to
• “EQ” : equal to
• “NE” : not equal to
• “IN” : one of listed values
• “NOTIN” : not any of list values

The value to be checked is given by one (usually) or more (only in the case the operator is “IN” or “NOTIN”) “CheckValue” elements. For example, the following defines a range of 'even' numbers between 0 and 10:

Only in case the operator is “IN” or “NOTIN”, more than 1 “CheckValue” is allowed. In all other cases, the number of “CheckValue” elements is limited to 1.

The error and warning messages are given by the “ErrorMessage” element, which is fully internationalized, meaning that one can give an error message for each language/culture in which the (e)CRF is deployed. For example:

Another important feature to note is the “MeasurementUnitRef” element. In many cases, the user will have the choice between different units of measurement (it can however be fixed by the deployment), for which (of course) different rangechecks applies. A typical example is the subject's “Height” which is typically measured in Anglosaxon countries in inches, and is measured in centimeters in other countries.

So, if we define an upper bound for the height of 220cm (or 90 inches), we need to define two rangechecks, one for the “cm” unit, and one for the “inch” unit:

The “MeasurementUnitOID”s are references to “MeasurementUnit” elements in the “BasicDefinitions” section of the ODM file:

Logically, the “MeasurementUnitRef” elements within the “RangeCheck” elements should be the same as those given as direct child elements of “ItemDef”.

As of ODM 1.3, a “FormalExpression” element may be used in place of a “CheckValue”. In that case, the contents of the “Comparator” element must be ignored (i.e. it does not have a meaning anymore). The “FormalExpression” element allows to add machine-readable code for which the outcome must be “true” or false”, meaning that the value entered by the user is validated by the code, and that the return value is “true” when it is an acceptable value for the rangecheck, and return “false” when the value is not an acceptable value for the rangecheck.

The machine language to be used for interpretation is given by the “Context” attribute. Examples are “Java”, “C#”, “Perl”, “JavaScript”, “PHP”, “SQL”, “XPath”, “XQuery” or even “MyNewScriptingLanguage”. It is important to notice here that the language used, and the way the code is interpreted, is entirely defined by the agreements between sender and receiver of the ODM file. The reason is that the ODM Team did not want to enforce a specific language for defining complicated machine-readable expressions: every implementor of the ODM is free to use its own computer language, in agreement with its partners in the process.

An example:

defining that the maximum height is 230cm for male subjects and 210cm for female subjects.

Very special and sincere thanks to prof. Inyoung Choi, The Catholic University of Korea, College of Medicine, Department of Preventive Medicine, for providing the Korean translations and adding them to the ODM file.