=== Using Conditions in ODM 1.3 ===

Author: Jozef Aerts, XML4Pharma

Applicable to: ODM version 1.3

== Introduction ==

CDISC ODM Version 1.3 introduces the concept of "skip conditions".
Skip conditions are conditions under which a question ("Item"), a group of questions ("ItemGroup"), a form ("Form") or a study visit ("StudyEvent") may be skipped.

The most typical example is a question about pregnancy ("Is the subject pregnant?") which doesn't make any sense in case the subject is male.
So in the latter case, the question should disappear from the electronic case report form (eCRF). When however (e.g. in the same form), it is ticked that the subject is female, the question should (re)appear on the eCRF.

Defining that a question is a skip question is done using the "CollectionExceptionConditionOID" element at "ItemRef". For example:

  <ItemGroupDef OID="IG.SubjectCondition" Name="Subject General Condition">
    <ItemRef ItemOID="IT.SEX"/>
    <ItemRef ItemOID="IT.PREGNANCY" CollectionExceptionConditionOID="COND.MALE" />
  </ItemGroupDef>

Where the "CollectionExceptionConditionOID" refers to a "ConditionDef" element with the OID (identifier) "COND.MALE".

For completeness, let us first give the definitions for "IT.SEX" and "IT.PREGNANCY":

  <ItemDef OID="IT.SEX" Name="Sex of the subject" DataType="text" Length="1">
    <Question>
      <TranslatedText xml:lang="en">Sex of the subject</TranslatedText>
    </Question>
    <CodeListRef CodeListOID="CL.SEX"/>
  </ItemDef>
  <ItemDef OID="IT.PREGNANCY" Name="Pregnancy" DataType="boolean">
    <Question>
      <TranslatedText xml:lang="en">Check when the subject is pregant</TranslatedText>
    </Question>
  </ItemDef>
  <CodeList OID="CL.SEX" Name="Sex codelist" Datatype="text">
    <CodeListItem CodedValue="F">
      <Decode>
        <TranslatedText xml:lang="en">Female</TranslatedText>
      </Decode>
    </CodeListItem>
    <CodeListItem CodedValue="M">
      <Decode>
        <TranslatedText xml:lang="en">Male</TranslatedText>
      </Decode>
    </CodeListItem>
  </CodeList>

The question with OID "IT.SEX" ("Sex of the subject") has an associated codelist "CL.SEX" indicating that the two only possible values are "F" and "M". This is what is stored in the database.
What the user sees on the screen however (at least for the english language) is described in the "TranslatedText" element.

The question with OID "IT.PREGNANCY" ("Pregnancy") is of data type "boolean" (new in ODM 1.3) so can only have the values "true"  or "false".
The latter has an associated skip condition "COND.MALE" which is given at the "ItemRef" level. Adding the condition to the "Ref" level rather than on the "Def" level has been done in order to make the question reusable, and so that different conditions can be applied to different instances of the same question.

So "COND.MALE" is an OID, referring to a "ConditionDef" element with the same OID, and which describes the condition under which the question about pregnancy should be skipped:

  <ConditionDef OID="COND.MALE" Name="Condition that the subject is male">
    <Description>
      <TranslatedText xml:lang="en">do not collect when the subject is male</TranslatedText>
    </Description>
  </ConditionDef>

The "Description" element is MANDATORY. It describes the condition in human-understandable language. 
One may also add one or more machine readable expressions. The "Description" element is then used as a fallback for the case the receiving system cannot interprete the machine-readable expressions.
Machine-readable expressions in ODM come as "FormalExpression" elements. They contain a "Context" attribute describing under which context the expression can be evaluated, and the expression itself as text content. 
For example:

  <ConditionDef OID="COND.MALE" Name="Condition that the subject is male">
    <Description>…</Description>
    <FormalExpression Context="MyScriptingLanguage">$SEX = 'M'</FormalExpression>
  </ConditionDef>

Usually, the value of the "Context" describes a programming language, such as "Java", "C#", "Perl", "C++" or a scripting language such as "JavaScript", "SQL" or "MyScriptingLanguage".
It is important to note that the value of "Context" is not standardized and is solely an agreement between sender and receiver. 
This means that if the receiving system does not understand what the language "MyScriptingLanguage" is, or cannot interprete it, than the fallback mechanism must be used, e.g. by printing the text of "Description" (here "do not collect when the subject is male" on the screen.

A disadvantage of this approach is that the expressions are not universally portable between applications. However, the ODM team did not want to enforce a specific programming language, nor develop a new scripting language. They left it up to the implementors to agree between sender and receiver what programming/scripting language should be used.

However, it is required that the expression evaluates to "true" or "false".

For me personally, the scripting language of choice, is one used with XML itself, i.e. XPath or XQuery. For example, one can write an XPath expression which evaluates the "ItemData" that is used to store the results of the form.
For example:

  <FormalExpression Context="XPath">../ItemData[@ItemOID='IT.SEX'][@Value='M']</FormalExpression>

The latter returning "true" when the (internal) captured value for question "IT.SEX" is "M", and returning "false" when otherwise.

Skips condition cannot only be applied to single questions (Item) but also to groups of questions (ItemGroup), forms (Form) or visits (StudyEvent).
For example, one can define a skip condition for the use of the "Adverse Events" form: 

  <StudyEventDef OID="SE.WEEKLY" Name="weekly form" Repeating="Yes">
    <FormRef FormOID="FM.WEEKLY"/>
    <FormRef FormOID="FM.AE" CollectionExceptionConditionOID="COND.NO_AE"/>
  </StudyEventDef>

The condition "COND.NO_AE" can then be described to do a lookup in the form "FM.WEEKLY" whether in that form the box "Was any adverse event experienced by the subject?" was ticked or even do a lookup in the clinical database.

== Skip conditions and conditional navigation ==

Skip conditions are a very simple way of navigation. They are however insufficient in case complex workflows between visits, forms … etc. need to be described.
For these cases, vendor extensions may be developed.

Such extensions have been developed by us for several vendors.

The upcoming "Trial Design ODM-extension" will contain a section in which workflows for activities (such as visits) can be described. It also uses the "ConditionDef" element for describing the condition under which a next visit should be executed, an activity started, or a transition from one epoch to another is allowed.
As such, this new, standardized extension reuses existing ODM features as much as possible.

== Implementation examples ==

A number of examples of  how ODM skip conditions have been implemented in EDC can be found on our website at [[http://www.xml4pharma.com/ODMinEDC/Samples.html]].

== Conclusions ==

The ODM 1.3 standard allows to define a number of "skip conditions" for visits, forms, subforms and questions. These conditions have been implemented in such a way that almost any machine-readable language can be used to describe the condition. 
The ODM implementation of the condition description ("ConditionDef") will also be used in future with more complex rules, such as timing rules, scheduling rules, etc..