This page is part of the Quality Improvement Core Framework (v4.1.0: STU 4) based on FHIR R4. The current version which supercedes this version is 4.1.1. For a full list of available versions, see the Directory of published versions

QI-Core Patterns

The patterns described here have been developed through usage of QI-Core profiles in the development of CQL-based quality measures and decision support.

FHIR and CQL

Clinical Quality Language (CQL) is a high-level, domain-specific language focused on clinical quality and targeted at clinical knowledge artifact authors such as quality measure and decision support artifact developers. In addition, the CQL specification provides a machine-readable canonical representation called Expression Logical Model (ELM) targeted at implementations and designed to enable automated sharing of clinical knowledge.

To use CQL with FHIR, model information must be provided to the implementation environment. The CQF Common IG provides a FHIR-ModelInfo library that provides this information for the base FHIR specification, as well as FHIRHelpers and FHIRCommon libraries that provide commonly used functions and declarations for clinical knowledge artifact development. To use FHIR directly, follow the documentation provided in that implementation guide.

However, this implementation guide includes a QICore-ModelInfo library that provides model information for the profiles and extensions defined in QI-Core. To use this model, include a using declaration as shown in the example below:

using QICore version '4.1.0'

Although not required by CQL, current best-practice is to include the version of the QICore model. For more information about how this library is constructed, refer to the ModelInfo topic.

Primitives

Primitive elements in FHIR, such as String, Integer, DateTime, and so on, may have extensions, and so have more complex structure than primitive elements typically have in other models. This means that when accessing a FHIR primitive element directly, a .value accessor must be used to get at the CQL primitive value:

define "Completed Encounter":
  ["Encounter"] E
    where E.status.value = 'finished'

To avoid this need, a FHIRHelpers library has been defined (and is included by default in the CQL-to-ELM translator). To use this library, add the following include:

include FHIRHelpers version '4.0.1'

Note that the FHIRHelpers version must match the FHIR version being used.

With this include, the above simplifies to:

define "Completed Encounter":
  ["Encounter"] E
    where E.status = 'finished'

Note that the additional .value is no longer required. In addition, the QICore model info represents FHIR primitive elements using the system types directly, so when using QICore, no .value accessor is required.

Extensions

Extensions in FHIR provide a standard mechanism to describe additional content that is not part of the base FHIR resources. By defining extensions in a uniform way as part of the base specification, FHIR enables extension-based functionality to be introduced through the use of profiles and implementation guidance. QI-Core includes several extensions related to quality improvement applications.

When using FHIR directly, these extensions must be accessed explicitly, using functions such as the following:

define function "Extensions"(domainResource DomainResource, url String):
  domainResource.extension E
	  where E.url = ('http://hl7.org/fhir/us/qicore/StructureDefinition/' + url)
		return E

define function "Extension"(domainResource DomainResource, url String):
  singleton from "Extensions"(domainResource, url)

define function "Extensions"(element Element, url String):
  element.extension E
	  where E.url = url
		return E

define function "Extension"(element Element, url String):
  singleton from "Extensions"(element, url)

However, when using QICore, extensions and slices defined in profiles are represented directly as elements in the types. For example:

define TestSlices:
  ["observation-bp"] BP
    where BP.SystolicBP.value < 140 'mm[Hg]'
      and BP.DiastolicBP.value < 90 'mm[Hg]'

define TestSimpleExtensions:
  Patient P
    where P.birthsex = 'M'

define TestComplexExtensions:
  Patient P
    where P.race.ombCategory contains "American Indian or Alaska Native"
      and P.race.detailed contains "Alaska Native"

Choice Types

FHIR includes the notion of Choice Types, or elements that can be of any of a number of types. For example, the Patient.deceased element can be specified as a Boolean or as a DateTime. Since CQL also supports choice types, these are manifest directly as Choice Types within the Model Info.

Where appropriate, the QICoreProfiles restrict choice types to those that are appropriate for the quality improvement use case. For example, The QICoreCondition profile removes String as a possible type for the onset element, to communicate the expectation that a computable representation of onset is required for quality improvement applications.

However, because systems may communicate instances contain any of these types, quality improvement logic must be prepared to deal with choice elements of any of the available types. To support the most common usages of choice types (for timing elements), the following functions have been defined:

define function "Normalize Onset"(onset Choice<FHIR.dateTime, FHIR.Age, FHIR.Period, FHIR.Range, FHIR.string>):
  if onset is FHIR.dateTime then
      Interval[FHIRHelpers.ToDateTime(onset as FHIR.dateTime), FHIRHelpers.ToDateTime(onset as FHIR.dateTime)]
  else if onset is FHIR.Period then
    FHIRHelpers.ToInterval(onset as FHIR.Period)
  else if onset is FHIR.string then
    Message(null as Interval<DateTime>, true, '1', 'Error', 'Cannot compute an interval from a String value')
  else if onset is FHIR.Age then
    Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(onset as FHIR.Age),
      FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(onset as FHIR.Age) + 1 year)
  else if onset is FHIR.Range then
    Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((onset as FHIR.Range).low),
      FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((onset as FHIR.Range).high) + 1 year)
  else
    null

define function "Normalize Abatement"(condition Condition):
  if condition.abatement is FHIR.dateTime then
    Interval[FHIRHelpers.ToDateTime(condition.abatement as FHIR.dateTime), FHIRHelpers.ToDateTime(condition.abatement as FHIR.dateTime)]
  else if condition.abatement is FHIR.Period then
    FHIRHelpers.ToInterval(condition.abatement as FHIR.Period)
  else if condition.abatement is FHIR.string then
    Message(null as Interval<DateTime>, true, '1', 'Error', 'Cannot compute an interval from a String value')
  else if condition.abatement is FHIR.Age then
    Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(condition.abatement as FHIR.Age),
      FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(condition.abatement as FHIR.Age) + 1 year)
  else if condition.abatement is FHIR.Range then
    Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((condition.abatement as FHIR.Range).low),
      FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((condition.abatement as FHIR.Range).high) + 1 year)
  else if condition.abatement is FHIR.boolean then
    Interval[end of "Normalize Onset"(condition.onset), condition.recordedDate)
  else
    null

define function "Prevalence Period"(condition Condition):
  Interval[start of "Normalize Onset"(condition.onset), end of "Normalize Abatement"(condition))

define function "Normalize Interval"(choice Choice<FHIR.dateTime, FHIR.Period, FHIR.Timing, FHIR.instant, FHIR.string, FHIR.Age, FHIR.Range>):
  case
    when choice is FHIR.dateTime then
      Interval[FHIRHelpers.ToDateTime(choice as FHIR.dateTime), FHIRHelpers.ToDateTime(choice as FHIR.dateTime)]
    when choice is FHIR.Period then
      FHIRHelpers.ToInterval(choice as FHIR.Period)
    when choice is FHIR.instant then
      Interval[FHIRHelpers.ToDateTime(choice as FHIR.instant), FHIRHelpers.ToDateTime(choice as FHIR.instant)]
    when choice is FHIR.Age then
      Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(choice as FHIR.Age),
        FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity(choice as FHIR.Age) + 1 year )
    when choice is FHIR.Range then
      Interval[FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((choice as FHIR.Range).low),
        FHIRHelpers.ToDate(Patient.birthDate) + FHIRHelpers.ToQuantity((choice as FHIR.Range).high) + 1 year )
    when choice is FHIR.Timing then
      Message(null as Interval<DateTime>, true, '1', 'Error', 'Cannot compute a single interval from a Timing type')
    when choice is FHIR.string then
      Message(null as Interval<DateTime>, true, '1', 'Error', 'Cannot compute an interval from a String value')
    else
      null as Interval<DateTime>
  end

Note that these functions make use of the FHIRHelpers library to ensure correct processing.

NOTE: The examples throughout this topic have been simplified to illustrate specific usage. Refer to the originating context for complete expressions.

Observations

For observations that have established profiles in US-Core, QI-Core uses those profiles:

Profile	Description
Vital Signs Profile	The FHIR Vital Signs profile sets minimum expectations for the Observation resource to record, search and fetch the vital signs associated with a patient that include the primary vital signs plus additional measurements such as height, weight and BMI.
Smoking Status Profile	This profile sets minimum expectations for the Observation resource to record, search and fetch smoking status data associated with a patient.
Laboratory Result Profile	This profile sets minimum expectations for the Observation resource resource to record, search and fetch laboratory test results associated with a patient.
Pediatric BMI For Age Profile	This profile sets minimum expectations for the Observation resource to record, search and fetch pediatric body mass index (BMI) per age and gender observations associated with a patient.
Pediatric Weight For Height Profile	This profile sets minimum expectations for the Observation resource to record, search and fetch pediatric weight for height and age observations associated with a patient.
Pulse Oximetry Profile	This profile sets minimum expectations for the Observation resource to record, search, and fetch pulse oximetry and inspired oxygen observations associated with a patient.

For all other observations, use the QICore-Observation profile.

For any observations not done, including the observations identified in the profiles above, use the Observation Not Done Profile.

Encounter Examples

Inpatient Encounter Example

Example source: MATGlobalCommonFunctions

define "Inpatient Encounter":
  [Encounter: "Encounter Inpatient"] EncounterInpatient
    where EncounterInpatient.status = 'finished'
      and "LengthInDays"(EncounterInpatient.period) <= 120
      and EncounterInpatient.period ends during "Measurement Period"

Inpatient Encounter with Principal Diagnosis

Example source: EXM105

define "Inpatient Encounter with Principal Diagnosis of Ischemic Stroke":
  "Inpatient Encounter" Encounter
    let PrincipalDiagnosis:
      (singleton from (Encounter.diagnosis D where D.use ~ ToConcept("Billing") and D.rank = 1)) PD
        return singleton from ([Condition: id in Last(Split(PD.condition.reference, '/'))])
    where PrincipalDiagnosis.code in "Ischemic Stroke"

Note that the FHIRHelpers.ToConcept usage is intended to be implicit and will be unnecessary once QUICK is fully supported.

Inpatient Encounter with Principal Procedure

Example source: VTE-1

define "Inpatient Encounter With Principal Procedure of SCIP VTE Selected Surgery":
  "Inpatient Encounter" Encounter
	  let PrincipalProcedure:
		  singleton from (
			  Encounter.extension E
				  where E.url = 'http://hl7.org/fhir/us/qicore/StructureDefinition/qicore-encounter-procedure'
					  and exists (E.extension I where I.url = 'type' and I.value ~ "Primary procedure")
					return singleton from (
							E.extension I where I.url = 'procedure' return GetProcedure(I.value)
						)
			)
		where PrincipalProcedure.code in "SCIP VTE Selected Surgery"

define function GetProcedure(reference Reference):
  singleton from ["Procedure": id in GetId(reference.reference))]

define function GetId(uri String):
  Last(Split(uri, '/'))

Diagnosis Examples

Example source: EXM72_FHIR-8.1.0_TJC.cql

define "Condition of Intravenous or Intra arterial Thrombolytic (tPA) Therapy Prior to Arrival":
  Condition: "Intravenous or Intra arterial Thrombolytic (tPA) Therapy Prior to Arrival"] PriorTPA
    where clinicalStatus in { 'active', 'recurrence', 'relapse' }

Note that verificationStatus is not being checked due to feedback received that it may be difficult for implementers to retrieve the element.

Medications

Example source: EXM108_FHIR

define "VTE Prophylaxis by Medication Administered":
  ["MedicationAdministration": medication in "Low Dose Unfractionated Heparin for VTE Prophylaxis"] VTEMedication
    where VTEMedication.status = 'completed'
      and VTEMedication.dosage.route in "Subcutaneous route"

Medications at discharge

Example source: EXM104_FHIR-8.1.000_TJC.cql

define "Antithrombotic Therapy at Discharge":
  ["MedicationRequest": "Antithrombotic Therapy"] Antithrombotic
    where exists (Antithrombotic.category C where FHIRHelpers.ToConcept(C) ~ "Discharge")
      and Antithrombotic.intent = 'order'

Note that the FHIRHelpers.ToConcept usage is intended to be implicit and will be unnecessary once QUICK is fully supported.

Medication not discharged

define "Antithrombotic Not Given at Discharge":
  ["MedicationRequest": "Antithrombotic Therapy"] NoAntithromboticDischarge
    where NoAntithromboticDischarge.doNotPerform is true
      and (singleton from NoAntithromboticDischarge.reasonCode in "Medical Reason"
        or singleton from NoAntithromboticDischarge.reasonCode in "Patient Refusal")

Medication not administered

Example source: EXM108_FHIR

define "No VTE Prophylaxis Medication Administered":
  ["MedicationAdministration": medication in "Low Dose Unfractionated Heparin for VTE Prophylaxis"] MedicationAdm
    where MedicationAdm.status = 'not-done'

Medication not ordered

Example source: EXM108_FHIR

define "No VTE Prophylaxis Medication Ordered":
  ["MedicationRequest": medication in "Low Dose Unfractionated Heparin for VTE Prophylaxis"] MedicationOrder
    where MedicationOrder.intent = 'order'
      and MedicationOrder.doNotPerform is true

Ballot-note: Note that the MedicationRequest status element is not being checked here. What is the status element expected to be for a MedicationRequest with doNotPerform set to true?

Procedures/Interventions

Example source: EXM108_FHIR

define "Intervention Comfort Measures":
  (["ServiceRequest": "Comfort Measures"] P
    where P.intent = 'order'
  )
    union (["Procedure": "Comfort Measures"] InterventionPerformed
      where InterventionPerformed.status in {'completed', 'in-progress'}
    )

Device Use

Example source: EXM108_FHIR

define "VTE Prophylaxis by Device Applied":
  ["Procedure": "Device Application"] DeviceApplied
    where DeviceApplied.status = 'complete'
      and (DeviceApplied.usedCode in "Intermittent pneumatic compression devices (IPC)"
        or DeviceApplied.usedCode in"Venous foot pumps (VFP)"
        or DeviceApplied.usedCode in "Graduated compression stockings (GCS)"
)

Device Not Used

Example source: EXM108_FHIR

define "No VTE Prophylaxis Device Applied":
  ["Procedure": "Device Application"] DeviceApplied
    let DeviceNotDoneTiming: Global.GetExtension(DeviceApplied, 'qicore-recorded').value
    where (DeviceApplied.usedCode in "Intermittent pneumatic compression devices (IPC)"
      or DeviceApplied.usedCode in "Venous foot pumps (VFP)"
      or DeviceApplied.usedCode in "Graduated compression stockings (GCS)"
    )
      and  DeviceApplied.status = 'not-done'
    return {id: DeviceApplied.id, requestStatusReason: DeviceApplied.statusReason, authoredOn: DeviceNotDoneTiming}

Device Not Ordered

Example source: EXM108_FHIR

define "No VTE Prophylaxis Device Order":
  (["ServiceRequest": "Venous foot pumps (VFP)"]
    union ["ServiceRequest": "Intermittent pneumatic compression devices (IPC)"]
    union ["ServiceRequest": "Graduated compression stockings (GCS)"]
  ) DeviceOrder
    where DeviceOrder.status = 'completed'
      and DeviceOrder.doNotPerform is true