4. Logical Specification

The ELM Expression component defines a mechanism for representing the structure of logic. The following table lists the core elements defined by the ELM:

Table 4‑A

Every expression in ELM is represented as a descendant of the abstract base element Expression. In addition, several abstract descendants are introduced to support the representation of unary, binary, ternary, and n-ary operators. Note that an expression need not descend from one of these descendants, it may descend from Expression directly.

Support for simple values is provided by the Literal class. This class defines properties to represent the type of the value, as well as the value itself.

The following table lists the simple value classes available in ELM:

Table 4‑B

The Literal class is used to represent values for simple primitive types: Boolean, String, Integer, Decimal, DateTime, and Time.

The result type of a Literal is the type of the primitive being represented.

For more information on the primitive types, see the Types section in the CQL Reference.

ELM defines a standard set of comparison operators for use with simple values. Each comparison operator takes two arguments of the same type, and returns a boolean indicating the result of the comparison. Note that for comparison operators, if either or both operands evaluate to null, the result of the comparison is null, not false.

The following table lists the comparison operators available in ELM:

Table 4‑C

The following example illustrates a simple Equal comparison:

Figure 4‑B

For more information on the semantics of the various comparison operators, see the Comparison Operators section of the CQL Reference.

ELM defines logical operators that can be used to combine the results of logical expressions. And and Or can be used to combine any number of results, and Not can be used to invert the result of any expression.

Note that these operators are defined with 3-valued logic semantics, allowing the operators to deal consistently with missing information.

The following table lists the logical operators available in ELM:

Table 4‑D

The following example illustrates a simple And expression:

Figure 4‑C

For more information on the semantics of these operators, refer to the Logical Operators section in the CQL Reference.

ELM defines several nullological operators that are useful for dealing with potentially missing information. These are Null, IsNull, IsTrue, IsFalse, and Coalesce.

The following table lists the logical operators available in ELM:

Table 4‑E

For more information on the semantics of these operators, refer to the Nullological Operators section in the CQL Reference.

ELM defines several conditional expressions that can be used to return different values based on a condition, or set of conditions. These are the If (conditional) expression, and the Case expression.

The conditional expression allows a simple condition to be used to decide between one expression or another.

The case expression has two varieties, one that is equivalent to repeated conditionals, and one that allows a specific comparand to be identified and compared with each item to determine a result.

The following table lists the conditional operators available in ELM:

Table 4‑F

The following examples illustrates a simple If expression (i.e. if / then / else):

Figure 4‑D

The following example illustrates a more complex multi-conditional Case expression:

Figure 4‑E

And finally, an equivalent comparand-based Case expression:

Figure 4‑F

ELM provides a complete set of arithmetic operators to allow for manipulation of integer and real values within artifacts. In general, these operators have the expected semantics for arithmetic operators.

Note that if an operand evaluates to null, the result of the operation is defined to be null. This provides consistent semantics when dealing with missing information.

The following table lists the arithmetic operators available in ELM:

Table 4‑G

The following example illustrates a simple Add expression:

Figure 4‑G

For more information on the semantics of these operators, refer to the Arithmetic Operators section in the CQL Reference.

ELM defines a set of string operators to allow for manipulation of string values within artifact definitions.

Indexes within strings are defined to be 0-based.

Note that except as noted within the documentation for each operator, if any argument evaluates to null, the result of the operation is also defined to be null.

The following table lists the string operators available in ELM:

Table 4‑H

For more information on the semantics of these operators, refer to the String Operators section in the CQL Reference.

ELM defines several operators for representating the manipulation of date and time values. These operators are defined using a common precision type that allows the various precisions (e.g. day, month, week, hour, minute, second) of time to be manipulated.

Except as noted within the documentation for each operator, if any argument evaluates to null, the result of the operation is also defined to be null.

The following table lists the date and time operators available in ELM:

Table 4‑I

For more information on the semantics of these operators, refer to the Date/Time Operators section in the CQL Reference.

ELM defines a complete set of operators for use in defining and manipulating interval values.

Constructing an interval is performed with the Interval expression, which allows the beginning and ending of the interval to be specified, as well as whether the interval beginning and ending is exclusive (open), or inclusive (closed).

ELM defines support for basic operations on intervals including determining length, accessing interval properties, and determining interval boundaries.

ELM also supports complete operations involving comparisons of intervals, including equality, membership testing, and inclusion testing.

In addition, the language supports operators for combining and manipulating intervals.

The following table provides a complete listing of the interval operators available in ELM:

Table 4‑J

Note that ELM does not include a definition for During because it is synonymous with IncludedIn.

For more information on the semantics of these operators, refer to the Interval Operators section in the CQL Reference.

Structured values in ELM are values with sets of named elements (tuples), each of which may have a value of any type. Structured values are most commonly used to represent clinical information such as encounters, problems, and procedures.

The Tuple class represents construction of a new structured value, with the values for each element supplied by TupleElement instances.

To access elements of a structured value, use the Property expression. A property expression has a path attribute, an optional source element, and a value element. The source element returns the structured value to be accessed. In some contexts, such as within a Filter expression, the source is implicit. If used outside such a context, a source must be provided.

The path attribute specifies a property path relative to the source structured value. The property expression returns the value of the property specified by the property path. Property paths are allowed to include qualifiers (.) as well as indexers ([x]) to indicate that subelements should be traversed. Indexers specified in paths must be literal integer values.

The following table lists the structured value operators available in ELM:

Table 4‑K

The following example illustrates the construction of a tuple using the Tuple class:

Figure 4‑H

The following example illustrates the construction of a structured value using the Instance class:

Figure 4‑I

ELM allows for the expression and manipulation of lists of values of any type. The most basic list operation is the List class, which represents a simple list selector.

Basic list operations include testing for membership, indexing, and content. ELM also supports comparison of lists, including equality and inclusion determination (subset/superset). Supported operations on single lists include filtering, sorting, and computation. For multiple lists, ELM supports combining through union and intersection, as well as computing the difference.

The use of the scope attribute allows for more complex expressions such as correlated subqueries.

ELM also supports a flattening operator, Flatten to construct a single list from a list of lists.

The following table provides a complete listing of the list operators available in ELM:

Table 4‑L

For more information on the semantics of these operators, refer to the List Operators section in the CQL Reference.

For computing aggregate quantities, ELM defines several aggregate operators. These operators perform computations on lists of values, either on the elements of the list directly, or on a specific property of each element in the list.

Unless noted in the documentation for each operator, aggregate operators deal with missing information by excluding elements which have no value before performing the aggregation. In addition, an aggregate operation performed over an empty list is defined to return null, except as noted in the documentation for each operator (e.g. Count).

The following table lists the aggregate operators available in ELM:

Table 4‑M

For more information on the semantics of these operators, refer to the Aggregate Functions section in the CQL Reference.

ELM provides the following elements for type specifiers, testing, casting, and conversion:

Table 4‑N

For more information on the semantics of these operators, refer to the Type Operators section in the CQL Reference.

ELM provides a mechanism for expressing the structure of a query using the following classes:

Table 4‑O

For more information on query semantics, refer to the Queries section of the Author’s Guide, as well as the Multi-Source Queries and Non-Retrieve Queries sections of the Developer’s Guide.

ELM provides a mechanism for reusing expressions by declaring a named expression. This construct is similar to a function call with no parameters in a traditional imperative language, with the exception that since ELM is a pure-functional system, the result of the evaluation could be cached by an implementation to avoid performing the same computation multiple times.

In addition, ELM provides a more traditional function call with named parameters that can then be accessed by the expression in the function body, and passed as part of the call from the invoking context.

The ExpressionDef class is used to define a named expression that can then be referenced by other expressions. The FunctionDef class is used to define a function and its parameters.

Note that circular expression references are not allowed, but that named expressions can be defined in any order, so long as the actual references do not result in a cycle.

The following table lists the expression definition components available in ELM:

Table 4‑P

The ExpressionDef class introduces the notion of context which can be either Patient or Population. This context defines how the contained expression is evaluated, either with respect to a single patient, defined by the evaluation environment, or with respect to a population. For more information about patient context, please refer to the External Data section.

All access to external data within ELM is represented by Retrieve expressions.

The Retrieve class defines the data type of the request, which determines the type of elements to be returned. The result will always be a list of values of the type specified in the request.

The type of the elements to be returned is specified with the dataType attribute of the Retrieve, and must refer to the name of a type within a known data model specified in the dataModels element of the library definition.

In addition, the Retrieve introduces the ability to specify optional criteria for the request. The available criteria are intentionally restricted to the set of codes involved, and the date range involved. If these criteria are omitted, the request is interpreted to mean all data of that type.

Note that because every expression is being evaluated within a context (either Patient or Population) as defined by the containing ExpressionDef, the data returned by a retrieve depends on the context. For the Patient context, the data is returned for a single patient only, as defined by the evaluation environment. Whereas for the Population context, the data is returned for all patients.

The following table lists the expressions relevant to defining external data in ELM:

Table 4‑Q

For working with clinical data, ELM defines operators for terminology sets, quantities, and calculating age.

The following table lists the classes representing clinical information in ELM:

Table 4‑R

In addition to external data, ELM provides a mechanism for defining parameters to an artifact. A library can define any number of parameters, each of which has a name, and a defined type, as well as an optional default value.

Parameter values, if any, are expected to be provided as part of the evaluation request, and can be accessed with a ParameterRef expression in any expression throughout the library.

The following table lists the expressions relevant to parameters in ELM:

Table 4‑S

ELM does not reference any specific data model, and so can be used to represent logic expressed against any data model. These data models are specified using the UsingDef class. This class provides attributes for specifying the name and version of the data model. An ELM library can reference any number of models.

The name of the model is an implementation-specific identifier that provides the environment with a mechanism for finding the model description. The details of how that model description is provided are part of the physical representation.

The following table lists the elements relevant to data models in ELM:

Table 4‑T

ELM defines the notion of a library as the basic container for logic constructs. Libraries consist of sets of declarations including data model references, library references, valueset definitions, parameters, functions, and named expressions. The Library class defines this unit and defines properties for each of these types of declarations.

Once defined, libraries can then be referenced by other libraries with the IncludeDef class, which defines properties for the name and version of the library being referenced, as well as a local name that is used to access components of the library.

The following table lists the elements relevant to libraries in ELM:

Table 4‑U

ELM defines a utility operation that is useful for generating run-time messages, warnings, traces, and errors. The operator is a single, general-purpose function intended to provide a single implementation point for messaging and run-time error functionality when those messages are generated from ELM logic.

The source parameter is always a generic value, which is always the result of the operator and is purely passthrough. This allows the operation to appear at any point in any expression of ELM.

The optional condition parameter determines whether or not the message is generated. If no condition is supplied, the default is true and the message is generated.

There is an optional code parameter which allows a coded representation of the message. (Note this is an error token such as an integer or string, not a clinical terminology Code).

There is an optional severity parameter which allows the severity of the message to be specified, one of: