WhereClauseCompoundExpression

Model Documentation

The WhereClauseCompoundExpression class is used to define compound expressions in the compoundExpression attribute of the WhereClause class (and any of its specializations).

Error rendering macro 'excerpt-include'

No link could be created for 'ARSP:Class Diagram: WhereClauseCompoundExpression'.

There are 3 specializations of the WhereClauseCompoundExpression class:

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

In each instance of the WhereClauseCompoundExpression class (or any of its specializations):

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 either a simple condition or another compound expression.
- "NOT" is used in compound expressions that negate another (single) subclause, which will be another compound expression.
The whereClauses attribute contains,
- in a compound expression that combines selection criteria: 2 or more subclauses, each represented as an instance of the WhereClause class or 1 of its specializations; or
- in a compound expression that negates another compound expression: a single subclause represented as an instance of the WhereClause class or 1 of its specializations.

The representation of the instance(s) of the WhereClause class (or its specializations) in the whereClauses attribute depends which type of WhereClauseCompoundExpression is being used.

In instances of either the WhereClauseCompoundExpression class itself (which is used in instances of the WhereClause class) or the CompoundSubsetExpression specialization (which is used in the DataSubset specialization of the WhereClause class), each subclause in the whereClauses attribute is represented as an instance of the WhereClause class, in which:
- The level is 1 greater than the level of the instance of the WhereClause in which the compound expression is being defined.
- The order attribute is:
  - used to order this subclause with respect to the other subclauses with which it is being combined (i.e., 1 for the first, 2 for the second, and so on)
  - assigned as "1" for a subclause that is being negated.
- Either the condition attribute is used to specify the subclause as a simple condition (for subclauses being combined) or the compoundExpression attribute is used to specify the subclause as another compound expression.
In instances of the CompoundSetExpression specialization (which is used in the AnalysisSet specialization of the WhereClause class), each subclause in the whereClauses attribute is specified as a reference to the identifier value of another instance of the AnalysisSet class.
In instances of the CompoundGroupExpression specialization (which is used in the Group specialization of the WhereClause class), each subclause in the whereClauses attribute is specified as a reference to the identifier value of another instance of 1 of the specializations of the Group class (AnalysisGroup or DataGroup).

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

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