WhereClauseCompoundExpression

Model Documentation

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:

The CompoundSetExpression specialization is used to define compound expressions in the AnalysisSet class, as shown in the AnalysisSet section.
The CompoundSubsetExpression specialization is used to define compound expressions in the DataSubset class, as shown in the DataSubset section.
The CompoundGroupExpression specialization class is used to define compound expressions in the Group class, as shown in the GroupingFactor section.

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 the 2 or more subclauses being combined by the compound expression, or the single subclause being negated. Each subclause is represented as an instance of either:
- the WhereClause class, containing a the definition of a condition or another compound expression, or
- one of the specializations of the ReferencedWhereClause class, containing a referenced to an 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 (to position the subclause relative to other subclauses) 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

id	label	level	order	logicalOperator	dataset	variable	comparator	value
DSS-TEAE-DTH	Treatment-emergent adverse events resulting in death	1	1	AND
DSS-TEAE-DTH	Treatment-emergent adverse events resulting in death	2	1		AEAE	TRTEMFL	EQ	Y
DSS-TEAE-DTH	Treatment-emergent adverse events resulting in death	2	2	OR
DSS-TEAE-DTH	Treatment-emergent adverse events resulting in death	3	1		AEAE	AESDTH	EQ	Y
DSS-TEAE-DTH	Treatment-emergent adverse events resulting in death	3	2		AEAE	AEOUT	EQ	FATAL

$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

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

$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, and
the GroupingFactor section for an example of compound expressions that use instances of the ReferencedGroup class to reference instances of the Group 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 either the AnalysisGroup or DataGroup specialization of the Group class).

Page tree

WhereClauseCompoundExpression