Authoring Measures in CQL
This topic will provide a complete discussion of using Clinical Quality Language (CQL) to author electronic Clinical Quality Measures (eCQMs). The discussion assumes familiarity with clinical quality measurement in general, and the representation of eCQMs using Health Quality Measure Format (HQMF) and Quality Data Model (QDM) in particular.
Clinical Quality Language (CQL) is a high-level query language, meaning that it can be used to write expressions that determine what data is to be returned, not how it is to be returned. How the data is to be returned is part of the implementation of a quality measure, and may be accomplished in any number of ways, so CQL is intentionally silent on any of those details, allowing the logic expressed by CQL queries to be used in a broad variety of implementation environments to achieve the same result.
One of the central constructs available in CQL is the expression, which is any sequence of CQL that returns a value. Values are the data that CQL operates on, and can be simple values like the integer 5 and the string John Doe, or they can be complex structures (or rows, also called tuples) like a QDM Encounter, Performed, which contains attributes such as admissionSource and relevantPeriod that are themselves values of different types.
The type of value that an expression returns is based on the contents of the expression. For example, an expression that consists only of a value, such as 5 will simply return that value. Operators, such as + and * can be used to create more complex expressions such as 2 + 3, which will return the result of evaluating the operation, the value 5 in this case. Expressions can also make use of functions, such as CalculateAge() that allow more complex operations to be defined and reused.
One of the most important types of values available in CQL is the list, which is a sequence of values of any type. Lists can contain simple values, like a list of integers, { 1, 2, 3 }, or they can contain tuples, like a list of encounters.
CQL includes a full suite of operators and functions to allow expressions to be written that can describe the logic and criteria used to precisely represent clinical quality measures. The following sections will discuss how to use this language to author a measure from the ground up.
One of the first considerations when expressing a clinical quality measure in CQL is determining what the measure is counting. Is the measure patient-based, meaning that the measure is expressed as some relationship between populations of patients, or is the measure counting some other kind of case such as encounters or procedures?
If the measure is patient-based, then the criteria we define will all return true or false for each specific patient, indicating whether the patient is part of the population being defined by that criteria. A true or false value is type Boolean in CQL, and many of the built-in operations such as comparison (e.g. value > 5) return values of this type.
For example, to express the demographic criteria for a patient-based measure, we can define an In Demographic expression:
define "In Demographic":
AgeInYearsAt(start of "Measurement Period") >= 13
This example returns true or false for a given patient, depending on whether they satisfy the criteria (13 years of age or older at the start of the measurement period).
Often, we want to identify whether a patient has had a particular type of encounter as part of a patient-based measure. For example:
define "Inpatient Encounters":
["Encounter, Performed": "Inpatient Encounter Codes"] Encounter
where Encounter.relevantPeriod during "Measurement Period"
This expression returns a list of encounters for the patient that match one of the codes in the Inpatient Encounter Codes value set, and that occurred during the measurement period. Now because the result of this expression is a list of encounters, we use an exists to turn the value into a Boolean so we combine it with the previous expression:
define "Initial Population":
"In Demographic"
and exists ("Inpatient Encounters")
However, if we are counting encounters in an episode-of-care measure, the population criteria will all need to result in lists of encounters:
define "Measurement Period Encounters":
["Encounter, Performed": "Ambulatory/ED Visit"] Encounter
where Encounter.relevantPeriod during "Measurement Period"
and "In Demographic"
define "Pharyngitis Encounters With Antibiotics":
"Measurement Period Encounters" Encounter
with "Pharyngitis" Pharyngitis
such that Common."Includes Or Starts During"(Pharyngitis, Encounter)
with "Antibiotics" Antibiotics
such that Antibiotics.authorDatetime 3 days or less after start of Encounter.relevantPeriod
Since the measure is counting encounters, we can return the list in the initial population:
define "Initial Population":
"Pharyngitis Encounters With Antibiotics"
Once we've identified the type of information the measure will be counting, we need to describe what information needs to be retrieved from the source in order to build the population criteria. QDM allows us to describe clinical information as Data Elements, which identify a Data Type and a Value Set. The Data Type combines a Category of clinical information, such as Encounter, Medication, or Procedure, with a context, such as Performed, Administered, or Ordered. The Data Type then determines the structure of the information. For example, the Medication, Administered Data Type has the following attributes:
- authorDatetime (DateTime)
- relevantPeriod (Interval)
- dosage (Quantity)
- supply (Quantity)
- frequency (Code)
- reason (Code)
- negationRationale (Code)
In addition to the Data Type, a QDM Data Element specifies a Value Set to indicate precisely what kinds of information should be retrieved. For example, the Inpatient Encounter Codes Value Set identifies encounters that take place in an in-patient setting. The QDM Data Element is then:
"Encounter, Performed: Inpatient Encounter Codes"
In CQL, this is expressed using a retrieve, which encloses the QDM Data Element information in square brackets ([]):
["Encounter, Performed": "Inpatient Encounter Codes"]
This retrieve expression results in only the highlighted encounters, because they have codes that match the "Inpatient Encounter Codes" Value Set:
Note that the quotation marks in this expression are important, as they are delineating the names of the constructs involved:
| Identifier | Description |
|---|---|
"Encounter, Performed" |
The name of the QDM Data Type |
"Inpatient Encounter Codes" |
The name of the Value Set |
The examples above used one of the central constructs of CQL, the query. Queries are a specific type of expression that allow relationships between data to be easily and precisely expressed. Queries in CQL are clause-based meaning that they have different types of clauses that can be used depending on what operations need to be performed on the data. Each clause in a query is introduced with a different keyword, and must appear in a particular location within the query in order to be valid CQL.
The general structure of a CQL query is:
<source> <alias>
<with or without clauses>
<where clause>
<return clause>
<sort clause>
All the clauses are optional, so the simplest query is just a source and an alias:
"Inpatient Encounters" Encounter
Here, the source is just a reference to Inpatient Encounters, which is an expression that returns a list of encounters. This source is given the alias Encounter. The alias allows the elements of the source to be referenced anywhere within the query. However, this simple query doesn't have any clauses, so it simply returns the same result as the source.
The where keyword introduces a where clause, which allows you to filter the results of the source:
"Inpatient Encounters" Encounter
where Encounter.relevantPeriod during "Measurement Period"
This query returns only those encounters from the source whose relevantPeriod occurred entirely during the measurement period.
For where versus such that, a where clause is only used as a direct clause in a query, and a such that is only used in a with or without clause. That's actually why CQL uses a different keyword, so that it would always be clear when you were providing a where clause, or when you were defining the conditions for a with or without clause.
If you're familiar with SQL, you can think of a with as a subquery with an exists, for example:
Encounters E with Medications M such that E.relevantPeriod includes M.relevantPeriod
is equivalent to
select *
from Encounters E
where exists (select * from Medications M where E.relevantPeriod includes M.relevantPeriod)
(Assuming SQL had the same temporal operators as CQL).
Similarly, a without is like a subquery with a not exists:
Encounters E without Medications M such that E.relevantPeriod includes M.relevantPeriod
is equivalent to
select *
from Encounters E
where not exists (select * from Medications M where E.relevantPeriod includes M.relevantPeriod)
Because with and without apply to the whole query, you can't combine them optionally in the same query. To do that, you can either:
-
Use a union to combine the results:
EncountersWithComfortMeasures union EncountersWithASpecificDischarge
-
Combine the logic within a single query using or:
Encounters E where exists (ComfortMeasures C where C.relevantPeriod during E.relevantPeriod) or E.dischargeStatus in ExpectedDischargeStatuses
["Encounter, Performed": "Encounter Inpatient" ] Encounter where "Encounter.dischargeDisposition" in "Patient Expired" and ( not "Newborn Hearing Screening Left" or not "Newborn Hearing Screening Right" )
["Encounter, Performed": "Encounter Inpatient" ] Encounter where ("Encounter.dischargeDisposition" in "Patient Expired" and not "Newborn Hearing Screening Left") or not "Newborn Hearing Screening Right"
behavior is additive
["Encounter, Performed": "Encounter Inpatient" ] Encounter
without "Newborn Hearing Screening Left" Left such that Left.relevantPeriod during Encounter.relevantPeriod
without "Newborn Hearing Screening Right" Right such that Right.relevantPeriod during Encounter.relevantPeriod
where Encounter.dischargeDisposition in "Patient Expired"
define "Encounters Without Left":
["Encounter, Performed": "Encounter Inpatient" ] Encounter
without "Newborn Hearing Screening Left" Left such that Left.relevantPeriod during Encounter.relevantPeriod
define "Encounters Without Right":
["Encounter, Performed": "Encounter Inpatient" ] Encounter
without "Newborn Hearing Screening Right" Right such that Right.relevantPeriod during Encounter.relevantPeriod
define "Encounters Without Screening":
"Encounters Without Left" union "Encounters Without Right"
To determine the length of time between two dates, CQL provides two different approaches. The first approach, calculating the duration, determines the number of whole periods that occur between the two dates. Conceptually, the calculation is performed by considering the two dates on a timeline, and counting the number of whole periods that fit on that timeline between the two dates. For example:
define Date1: @2012-03-10
define Date2: @2013-03-10
define DurationInYears: years between Date1 and Date2
This expression gives one year, because an entire year has passed between the two dates. Note that time is considered for the purposes of calculating the number of years:
define DateTime1: @2012-03-10T10:20:00
define DateTime2: @2013-03-10T09:20:00
define DurationInYears: years between DateTime1 and DateTime2
This expression gives zero years, because the year has not passed until 10:20:00 on the day in the following year. To calculate the number of years, ignoring the time, extract the date from the date/time value:
define DateTime1: @2012-03-10T10:20:00
define DateTime2: @2013-03-10T09:20:00
define DurationInYears: years between (date from DateTime1) and (date from DateTime2)
The second approach, calculating the difference, determines the number of boundaries crossed between two dates. To illustrate the difference, consider the following example:
define Date1: @2012-12-31
define Date2: @2013-01-01
define DurationInYears: years between Date1 and Date2
define DifferenceInYears: difference in years between Date1 and Date2
The DurationInYears expression returns zero because a full year has not passed between the two dates. However, the second expression returns 1 because a year boundary was crossed between the two dates.
In CQL, a year is defined as the duration of any time interval which starts at a certain time of day at a certain calendar date of the calendar year and ends at:
- The same time of at the same calendar date of the next calendar year, if it exists
- The same time of day at the immediately following calendar date of the ending calendar, if the same calendar date of the ending calendar year does not exist.
Note: When in the next calendar year the same calendar date does not exist, the ISO standard states that the ending calendar day has to be agreed upon. The above convention is used in CQL as a resolution to this issue.