Model Documentation

Class: WhereClauseCompoundExpression

The abstract WhereClauseCompoundExpression class provides a template for classes that are used to define compound expressions in the compoundExpression attribute of the WhereClause class (and any other data selection classes). There are 3 specializations of the WhereClauseCompoundExpression class:

ER Diagram: WhereClauseCompoundExpression

In each instance of a WhereClauseCompoundExpression class:

  • The logicalOperator attribute contains a value from the ExpressionLogicalOperatorEnum enumeration:
    • "AND" or "OR" are used in compound expressions that combine 2 or more subclauses, each of which may be a simple condition, another compound expression, or a reference to an instance of an identified WhereClause class (see below).
    • "NOT" is used in compound expressions that negate another (single) subclause. The subclause will be either another compound expression or a reference to an identified WhereClause class (see below). Note that a compound expression should generally not be created to negate a single simple condition; another simple condition using the inverse comparator should be created instead (i.e., using "NE" vs. "EQ", "LT" vs. "GE", "GT" vs. "LE", or "NOTIN" vs. "IN").
  • The whereClauses attribute contains either the 2 or more subclauses being combined by the compound expression, or the single subclause being negated. Each subclause contains the level and order attributes (to position the subclause relative to other subclauses) and 1 of the following attributes:
    • condition, from an instance of the WhereClause class defining the subclause as a simple condition,
    • compoundExpression, from an instance of the WhereClause class defining the subclause as another compound expression,
    • subClauseId, from an instance of one of the specializations of the ReferencedWhereClause class (see below) and containing the identifier value of a referenced instance of an identified WhereClause class.

The abstract ReferencedWhereClause class provides a template for the 3 classes that are each used to reference instances of 1 of the identified WhereClause classes:

  • The ReferencedAnalysisSet class is used in whereClauses attribute of the CompoundSetExpression class to reference an instance of the AnalysisSet class.
  • The ReferencedDataSubset class is used in whereClauses attribute of the CompoundSubsetExpression class to reference an instance of the DataSubset class.
  • The ReferencedGroup class is used in whereClauses attribute of the CompoundGroupExpression class to reference an instance of the Group class.

Each instance of a ReferencedWhereClause class contains the level and order attributes, and the subClauseId attribute which holds the identifier value for the referenced instance of the identified WhereClause class.

Example

This example shows an instance of the DataSubset specialization of the WhereClause class that defines a compound expression for "Treatment-emergent adverse events resulting in death". The compound expression specifies that the value of the TRTEMFL variable in the ADAE dataset is equal to "Y" and either the value of the AESDTH variable in the ADAE dataset is equal to "Y" or the value of the AEOUT variable in the ADAE dataset is equal to "FATAL", which could be expressed as:
  • ADAE.TRTEMFL EQ 'Y' AND (ADAE.AESDTH EQ 'Y' OR ADAE.AEOUT EQ 'FATAL') 

Lines 1-5:

Show the attributes of the DataSubset specialization of the WhereClause class:

  • level is assigned as "1" because this is the "top" level of the specification of the selection criterion.
  • order is "1" because level is "1" and this is not a specialization of the Group class.
  • The presence of the compoundExpression attribute indicates that a compound expression is being defined.
Lines 6-7:

Show the attributes of an instance of the CompoundSubsetExpression specialization of the WhereClauseCompoundExpression class (because this is a compound expression within a DataSubset class):

  • The value of the logicalOperator attribute is "AND" which indicates that both subclauses specified in the whereClauses attribute have to be satisfied.
  • The whereClause attribute contains 2 subclauses, both represented as instances of the WhereClause class (because these are subclauses within a CompoundSubsetExpression class) with "2" as the value of the level attribute (1 greater than the level of the DataSubset class specifying this compound expression):
    • Lines 8-10: Show the first subclause (order = 1) defined as a simple condition.
    • Lines 18-18: Show the second subclause (order = 2) defined as another compound expression. 
Lines 19-20:

Show the attributes of an instance of the WhereClauseCompoundExpression class (because this is a compound expression within a WhereClause class):

  • The value of the logicalOperator attribute is "OR" which indicates that either of the subclauses specified in the whereClauses attribute has to be satisfied.
  • The whereClause attribute contains two subclauses, both of which are simple conditions represented as instances of the WhereClause class (because these are subclauses within a WhereClauseCompoundExpression class) with "3" as the value of the level attribute (1 greater than the level of the WhereClause class specifying this compound expression). The values of the order attribute are "1" and "2" to order the subclauses within this level.

YAML Example
id: DSS-TEAE-DTH
label: Treatment-emergent adverse events resulting in death
level: 1
order: 1
compoundExpression:
  logicalOperator: AND
  whereClauses:
  - level: 2
    order: 1
    condition:
      dataset: ADAE
      variable: TRTEMFL
      comparator: EQ
      value:
      - Y
  - level: 2
    order: 2
    compoundExpression:
      logicalOperator: OR
      whereClauses:
      - level: 3
        order: 1
        condition:
          dataset: ADAE
          variable: AESDTH
          comparator: EQ
          value:
          - Y
      - level: 3
        order: 2
        condition:
          dataset: ADAE
          variable: AEOUT
          comparator: EQ
          value:
          - FATAL

This compound expression could be represented in tabular form as shown in the following table where:

  • Each instance of the WhereClause class (and its DataSubset specialization) is represented on a separate row.
  • The values of the id and label attributes of the DataSubset class have be propagated onto all rows representing subclauses within the defined data subset.

$titleHtml
idlabellevelorderlogicalOperatordatasetvariablecomparatorvalue
DSS-TEAE-DTHTreatment-emergent adverse events resulting in death11AND



DSS-TEAE-DTHTreatment-emergent adverse events resulting in death21
AEAETRTEMFLEQY
DSS-TEAE-DTHTreatment-emergent adverse events resulting in death22OR



DSS-TEAE-DTHTreatment-emergent adverse events resulting in death31
AEAEAESDTHEQY
DSS-TEAE-DTHTreatment-emergent adverse events resulting in death32
AEAEAEOUTEQFATAL
$warningHtml

Example

This example shows an instance of the DataSubset specialization of the WhereClause class that defines a compound expression for "Example flag 1 is not missing or N". The compound expression of this data subset:
  • Negates another compound expression that specifies that the value of the EXMPFL variable in the ADVS dataset is missing or the value of the EXMPFL variable in the ADVS dataset is equal to "N".
  • Could be expressed as:
    • NOT (ADVS.EXMPLFL EQ '' OR ADVS.EXMPLFL EQ 'N')

Note that this is a relatively simple example that has been created to illustrate the use of "NOT"; in practice, it would be better to simplify this criterion by using the logically equivalent inverse criterion: ADVS.EXMPLFL NE '' AND ADVS.EXMPLFL NE 'N'. The "NOT" logical operator would generally only be used to negate either:

  • more complex compound expressions where the logically inverse criterion is more difficult to express, or
  • compound expressions in which subclauses are referenced by identifier values (as described in the AnalysisSet and GroupingFactor sections).

Lines 1-5:

Show the attributes of the DataSubset specialization of the WhereClause class:

  • level is assigned as "1" because this is the "top" level of the specification of the selection criterion.
  • order is "1" because level is "1" and this is not a specialization of the Group class.
  • The presence of the compoundExpression attribute indicates that a compound expression is being defined.
Lines 6-7:

Show the attributes of an instance of the CompoundSubsetExpression specialization of the WhereClauseCompoundExpression class (because this is a compound expression within a DataSubset class):

  • The value of the logicalOperator attribute is "NOT", which indicates that the subclause specified in the whereClauses attribute is being negated.
  • The whereClause attribute contains a single subclause, which is another compound expression represented as an instance of the WhereClause class (because this is a subclause within a CompoundSubsetExpression class) with "2" as the value of the level attribute (1 greater than the level of the DataSubset class specifying this compound expression). The value of the order attribute is "1" because this is the first (and only) subclause within this level.
Lines 11-12:

Show the attributes of an instance of the WhereClauseCompoundExpression class (because this is a compound expression within a WhereClause class):

  • The value of the logicalOperator attribute is "OR" which indicates that either of the subclauses specified in the whereClauses attribute has to be satisfied.
  • The whereClause attribute contains 2 subclauses, both of which are simple conditions represented as instances of the WhereClause class (because these are subclauses within a WhereClauseCompoundExpression class) with "3" as the value of the level attribute (1 greater than the level of the WhereClause class specifying this compound expression). The values of the order attribute are "1" and "2" to order the subclauses within this level.

YAML Example
id: DSS-EXMPL-NOT
label: Example flag is not missing or N
level: 1
order: 1
compoundExpression:
  logicalOperator: NOT
  whereClauses:
  - level: 2
    order: 1
    compoundExpression:
      logicalOperator: OR
      whereClauses:
      - level: 3
        order: 1
        condition:
          dataset: ADVS
          variable: EXMPLFL
          comparator: EQ
          value:
      - level: 3
        order: 2
        condition:
          dataset: ADVS
          variable: EXMPLFL
          comparator: EQ
          value:
          - N

This compound expression could be represented in tabular form as shown in the following table where:

  • Each instance of the WhereClause class (and its DataSubset specialization) is represented on a separate row.
  • The values of the id and label attributes of the DataSubset class have be propagated onto all rows representing subclauses within the defined data subset.

$titleHtml
idlabellevelorderlogicalOperatordatasetvariablecomparatorvalue
DSS-EXMPL-NOTExample flag is not missing or N11NOT



DSS-EXMPL-NOTExample flag is not missing or N21OR



DSS-EXMPL-NOTExample flag is not missing or N31
ADVSEXMPLFLEQ
DSS-EXMPL-NOTExample flag is not missing or N32
ADVSEXMPLFLEQN
$warningHtml

Example

This example shows the definition of 2 grouping factors based, each represented as an instance of the GroupingFactor class within the analysisGroupings attribute of the reporting event.

Lines 2-37:

Show the attributes of the instance of the GroupingFactor class for the first grouping factor, "Treatment" (line 3), which is defined as being based on the ADSL TRT01A grouping variable (lines 4 and 5). The grouping factor is not data-driven (line 6), so the groups attribute is included (line 7) and contains 3 predefined groups, each specified as a simple condition represented as an instance of the Group class:

  • Lines 8-17: Show the first predefined group (order = 1), which is identified as "AnlsGrouping_05_Trt_1", named as "Placebo" (line 9), and contains a simple condition specifying that the value of the TRT01A variable in the ADSL dataset is equal to "Placebo", which could be expressed as:
    • ADSL.TRT01A EQ 'Placebo'
  • Lines 18-27: Show the second predefined group (order = 2), which is identified as "AnlsGrouping_05_Trt_2", named as "Xanomeline Low Dose" (line 19), and contains a simple condition specifying that the value of the TRT01A variable in the ADSL dataset is equal to "Xanomeline Low Dose", which could be expressed as:
    • ADSL.TRT01A EQ 'Xanomeline Low Dose'
  • Lines 28-37: Show the third predefined group (order = 3), which is identified as "AnlsGrouping_05_Trt_3", named as "Xanomeline High Dose" (line 29), and contains a simple condition specifying that the value of the TRT01A variable in the ADSL dataset is equal to "Xanomeline High Dose", which could be expressed as:
    • ADSL.TRT01A EQ 'Xanomeline High Dose'
Lines 38-68:

Show the attributes of the instance of the GroupingFactor class for the third grouping factor, "On Active Treatment" (line 39). Although the groups within this grouping factor are defined as compound expressions (lines 49 and 63), the grouping variable is specified as ADSL TRT01A (lines 40 and 41) because all the subclauses of the compound expressions are identified as groups that are simple conditions based on the TRT01A variable. The grouping factor is not data-driven (line 42), so the groups attribute is included (line 43) and contains 2 predefined groups, each specified as a compound expression represented as an instance of the Group class:

  • Lines 44-57: Show the first predefined group (order = 1), which is identified as "AnlsGrouping_06_ActTrt_1", named as "Yes", and labeled as "Y". The compound expression defined for this group uses the "OR" logical operator (line 50) to combine 2 subclauses, each of which is represented as an instance of the ReferencedGroup class.
    • Lines 52-54: Show the first subclause (level = 2, order = 1), which is a reference to the instance of the Group class identified as "AnlsGrouping_05_Trt_2" (line 54).
    • Lines 55-57: Show the second subclause (level = 2, order = 2), which is a reference to the instance of the Group class identified as "AnlsGrouping_05_Trt_2" (line 57).

      When the identifier values specified the 2 subclauses are used to retrieve the definitions of the identified groups, this compound expression could be expressed as:

    • ADSL.TRT01A EQ 'Xanomeline Low Dose' OR ADSL.TRT01A EQ 'Xanomeline High Dose'
  • Lines 58-68: Show the second predefined group (order = 2), which is identified as "AnlsGrouping_06_ActTrt_2", named as "No", and labeled as "N". The compound expression defined for this group uses the "NOT" logical operator (line 64) to negate the condition(s) specified by the subclause. The subclause is specified as an instance of the ReferencedGroup class, in which the subClauseId attribute references the instance of the Group class identified as "AnlsGrouping_06_ActTrt_1" (line 68). When the identifier values for this referenced group ("AnlsGrouping_06_ActTrt_1") and groups it references ("AnlsGrouping_05_Trt_2" and "AnlsGrouping_05_Trt_2") are used to retrieve the original group definitions, this compound expression could be expressed as:
    • NOT (ADSL.TRT01A EQ 'Xanomeline Low Dose' OR ADSL.TRT01A EQ 'Xanomeline High Dose')

YAML Example
analysisGroupings:
- id: AnlsGrouping_05_Trt
  name: Treatment
  groupingDataset: ADSL
  groupingVariable: TRT01A
  dataDriven: false
  groups:
  - id: AnlsGrouping_05_Trt_1
    name: Placebo
    level: 1
    order: 1
    condition:
      dataset: ADSL
      variable: TRT01A
      comparator: EQ
      value:
      - Placebo
  - id: AnlsGrouping_05_Trt_2
    name: Xanomeline Low Dose
    level: 1
    order: 2
    condition:
      dataset: ADSL
      variable: TRT01A
      comparator: EQ
      value:
      - Xanomeline Low Dose
  - id: AnlsGrouping_05_Trt_3
    name: Xanomeline High Dose
    level: 1
    order: 3
    condition:
      dataset: ADSL
      variable: TRT01A
      comparator: EQ
      value:
      - Xanomeline High Dose
- id: AnlsGrouping_06_ActTrt
  name: On Active Treatment
  groupingDataset: ADSL
  groupingVariable: TRT01A
  dataDriven: false
  groups:
  - id: AnlsGrouping_06_ActTrt_1
    name: Yes
    label: Y
    level: 1
    order: 1
    compoundExpression:
      logicalOperator: OR
      whereClauses:
      - level: 2
        order: 1
        subClauseId: AnlsGrouping_05_Trt_2
      - level: 2
        order: 2
        subClauseId: AnlsGrouping_05_Trt_3
  - id: AnlsGrouping_06_ActTrt_2
    name: No
    label: N
    level: 1
    order: 2
    compoundExpression:
      logicalOperator: NOT
      whereClauses:
      - level: 2
        order: 1
        subClauseId: AnlsGrouping_06_ActTrt_1

These grouping factors and their predefined groups could be represented in tabular form as shown in the following table where:

  • Each row represents an instance of one of the following classes, with attribute values for the related instance of the GroupingFactor class represented on every row:
    • Group: each predefined group is represented on a separate line (rows where level = 1).
    • ReferencedGroup: for each predefined group that includes a compound expression, any subclause that references another predefined predefined group by identifier is represented on a separate row (rows where level = 2), where the identifier value of the referenced predefined group shown in the "subClauseId" column and the attribute values of the related instance of the Group class are also shown.
  • Although it would be possible, in this representation, the referenced identifier values have not been used to retrieve the details of the simple conditions from the original group definitions.

$titleHtml
idnamegroupingDatasetgroupingVariabledataDrivengroup_idgroup_namegroup_labellevelorderlogicalOperatorsubClauseIddatasetvariablecomparatorvalue
AnlsGrouping_05_TrtTreatmentADSLTRT01AFALSEAnlsGrouping_05_Trt_1Placebo
11

ADSLTRT01AEQPlacebo
AnlsGrouping_05_TrtTreatmentADSLTRT01AFALSEAnlsGrouping_05_Trt_2Xanomeline Low Dose
12

ADSLTRT01AEQXanomeline Low Dose
AnlsGrouping_05_TrtTreatmentADSLTRT01AFALSEAnlsGrouping_05_Trt_3Xanomeline High Dose
13

ADSLTRT01AEQXanomeline High Dose
AnlsGrouping_06_ActTrt

On Active Treatment

ADSLTRT01AFALSEAnlsGrouping_06_ActTrt_1YesY11OR




AnlsGrouping_06_ActTrtOn Active TreatmentADSLTRT01AFALSEAnlsGrouping_06_ActTrt_1YesY21
AnlsGrouping_05_Trt_2



AnlsGrouping_06_ActTrtOn Active TreatmentADSLTRT01AFALSEAnlsGrouping_06_ActTrt_1YesY22
AnlsGrouping_05_Trt_3



AnlsGrouping_06_ActTrtOn Active TreatmentADSLTRT01AFALSEAnlsGrouping_06_ActTrt_2NoN12NOT




AnlsGrouping_06_ActTrtOn Active TreatmentADSLTRT01AFALSEAnlsGrouping_06_ActTrt_2NoN21
AnlsGrouping_06_ActTrt_1



$warningHtml

See the AnalysisSet section for an example of a compound expression that uses instances of the ReferencedAnalysisSet class to reference instances of the AnalysisSet class.

Note that the ARS Model is designed to support the specification of analyses of data in ADaM datasets, which are expected to be "analysis-ready." In analysis-ready datasets, any complex criteria needed to define either subject populations or the grouping of data for analysis will usually have been applied to create flagging or grouping variables. These flagging and grouping variables can usually then be referenced in the specification of simple conditions, so compound expressions should generally not be required for the definition of subject populations (using the AnalysisSet class) or groups within grouping factors (using the Group class).

« WhereClauseCondition

Analysis Components »

  • No labels