CDSConnectCommons.cql

// CDS Connect Commons for FHIRv400

library CDSConnectCommons version '1.0.3'

using FHIR version '4.0.1'

// Include the FHIRHelpers library for simplifying interacton w/ the FHIR data model
include FHIRHelpers version '4.0.1'

codesystem "AIVERSTATUS": 'http://terminology.hl7.org/CodeSystem/allergyintolerance-verification'
codesystem "AICLINSTATUS": 'http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical'
codesystem "CONDVERSTATUS": 'http://terminology.hl7.org/CodeSystem/condition-ver-status'
codesystem "CONDCLINSTATUS": 'http://terminology.hl7.org/CodeSystem/condition-clinical'
code "AllergyIntolerance Confirmed code": 'confirmed' from "AIVERSTATUS" display 'Confirmed'
code "AllergyIntolerance Active code": 'active' from "AICLINSTATUS" display 'Active'
code "Condition Confirmed code": 'confirmed' from "CONDVERSTATUS" display 'Confirmed'
code "Condition Active code": 'active' from "CONDCLINSTATUS" display 'Active'
code "Condition Recurrence code": 'recurrence' from "CONDCLINSTATUS" display 'Recurrence'
code "Condition Relapse code": 'relapse' from "CONDCLINSTATUS" display 'Relapse'
//concept "AllergyIntolerance Confirmed": { "AllergyIntolerance Confirmed code" } display 'Confirmed'
//concept "AllergyIntolerance Active": { "AllergyIntolerance Active code" } display 'Active'
//concept "Condition Confirmed": { "Condition Confirmed code" } display 'Confirmed'
//concept "Condition Active": { "Condition Active code" } display 'Active'
//concept "Condition Recurrence": { "Condition Recurrence code" } display 'Recurrence'
//concept "Condition Relapse": { "Condition Relapse code" } display 'Relapse'

// -------------------------------------------------- GENERAL ---------------------------------------------------------

/**
 * Converts a FHIR Period to a CQL Interval.  FHIRHelpers provides a function for this, but
 * FHIRHelpers provides several overloads of the ToInterval function, and the JavaScript CQL
 * Execution Framework apparently does not handle this correctly.  Creating uniquely named
 * functions here ensures safe execution.
 * @param period - a FHIR Period
 * @returns {System.Interval} a CQL Interval or null if null was passed in
 */
define function PeriodToInterval(period FHIR.Period):
  if period is null then
    null
  else
    if period."start" is null then
      Interval(period."start".value, period."end".value]
    else
      Interval[period."start".value, period."end".value]

/**
 * Converts a FHIR Quantity to a CQL Interval.  FHIRHelpers provides a function for this, but
 * FHIRHelpers provides several overloads of the ToInterval function, and the JavaScript CQL
 * Execution Framework apparently does not handle this correctly.  Creating uniquely named
 * functions here ensures safe execution.
 * @param quantity - a FHIR Quantity
 * @returns {System.Interval} a CQL Interval or null if null was passed in
 */
/*
define function QuantityToInterval(quantity FHIR.Quantity):
  if quantity is null then null else
    case quantity.comparator.value
      when '<' then
        Interval[
          null,
          FHIRHelpers.ToQuantityIgnoringComparator(quantity)
        )
      when '<=' then
        Interval[
          null,
          FHIRHelpers.ToQuantityIgnoringComparator(quantity)
        ]
      when '>=' then
        Interval[
          FHIRHelpers.ToQuantityIgnoringComparator(quantity),
          null
        ]
      when '>' then
        Interval(
          FHIRHelpers.ToQuantityIgnoringComparator(quantity),
          null
        ]
      else
        Interval[FHIRHelpers.ToQuantity(quantity), FHIRHelpers.ToQuantity(quantity)]
    end
*/

/**
 * Converts a FHIR Range to a CQL Interval.  FHIRHelpers provides a function for this, but
 * FHIRHelpers provides several overloads of the ToInterval function, and the JavaScript CQL
 * Execution Framework apparently does not handle this correctly.  Creating uniquely named
 * functions here ensures safe execution.
 * @param range - a FHIR Range
 * @returns {System.Interval} a CQL Interval or null if null was passed in
 */
define function RangeToInterval(range FHIR.Range):
  if range is null then
    null
  else
    Interval[FHIRHelpers.ToQuantity(range.low), FHIRHelpers.ToQuantity(range.high)]

// -------------------------------------------------- OBSERVATIONS -----------------------------------------------------

/**
 * Filters Observations by a concept rather than by a ValueSet.  In CQL 1.3, this is built into the retrieve,
 * but for backwards compatibility, we keep this query where clause as an option.
 * @param Koncept - the concept to filter on (intentionally mispelled to avoid naming clashes)
 * @returns {List<Observation>} a list of Observations matching the concept, or null if null was passed in
 */
define function ObservationsByConcept(Koncept System.Concept):
  [Observation] O where FHIRHelpers.ToConcept(O.code) ~ Koncept

/**
 * Observations that are complete and verified. In FHIR R4, there are three statuses that indicate this state: 'final',
 * 'corrected', and 'amended'.
 * @see http://hl7.org/fhir/R4/valueset-observation-status.html
 * @param ObsList - a list of Observations
 * @returns {List<Observation>} a list of verified Observations, or null if null was passed in
 */
define function Verified(ObsList List<Observation>):
  ObsList O where O.status.value in {'final', 'corrected', 'amended'}

/**
 * Observations that have quantity values recorded in the requested unit.
 * @param ObsList - a list of Observations
 * @param Unit - the unit to require in the Observations quantity value
 * @returns {List<Observation>} a list of Observations with the required unit, or null if null was passed in
 */
define function WithUnit(ObsList List<Observation>, Unit String):
  ObsList O
    where (O.value as FHIR.Quantity).unit.value = Unit or (O.value as FHIR.Quantity).code.value = Unit

/**
 * Observations with an effective or issued date in the specified "look back" period.  For example, LDL-C Tests in the
 * last 6 years.
 * TODO: Rename to LookBack once the execution engine supports overloaded functions.
 * @param ObsList - a list of Observations
 * @returns {List<Observation>} a list of Observations with effective or issued date specified lookback period, or null
 * if null was passed in
 */
define function ObservationLookBack(ObsList List<Observation>, LookBack System.Quantity):
  ObsList O
    let LookBackInterval: Interval[Now() - LookBack, Now()]
    where (O.effective as FHIR.dateTime).value in LookBackInterval
      or (O.effective as FHIR.instant).value in LookBackInterval
      or PeriodToInterval(O.effective as FHIR.Period) overlaps LookBackInterval
      or O.issued.value in LookBackInterval

/**
 * The most recent observation.  For each Observation, this algorithm will use the Coalesce function, which uses the
 * first non-null date value from these fields: effectiveDateTime, effectiveInstant, effectivePeriod.end,
 * effectivePeriod.start, issued. The found date will be used to compare Observations and determine the most recent
 * one.  NOTE: We can't use FindDate because it appears that the execution engine may have problems sorting by the
 * result of a function.
 * @param ObsList - a list of Observations
 * @returns {Observation} the most recent Observation from the list, or null if null was passed in
 */
define function MostRecent(ObsList List<Observation>):
  Last(ObsList O sort by Coalesce(
    (effective as FHIR.dateTime).value,
    (effective as FHIR.instant).value,
    (effective as FHIR.Period)."end".value,
    (effective as FHIR.Period)."start".value,
    issued.value)
  )

/**
 * Extracts the quantity value from an Observation, returning it as a CQL Quantity
 * @param Obs - an observation
 * @returns {System.Quantity} the Observation's value as a quantity, or null if there is no quantity value
 */
define function QuantityValue(Obs Observation):
  case
  when Obs is null then null
  when Obs.value as FHIR.Quantity is null then null
  else
    FHIRHelpers.ToQuantity(Obs.value as FHIR.Quantity)
  end

/**
 * Extracts the CodeableConcept value from an Observation, returning it as a CQL Concept
 * @param Obs - an observation
 * @returns {System.Concept} the Observation's value as a concept, or null if there is no CodeabeConcept value
 */
define function ConceptValue(Obs Observation):
  FHIRHelpers.ToConcept(Obs.value as FHIR.CodeableConcept)

/**
 * Finds the first non-null meaningful date that can be associated with this Observation.  This will look through the
 * following fields in the following order: effectiveDateTime, effectiveInstant, effectivePeriod.end,
 * effectivePeriod.start, issued.
 * @param Obs - an Observation
 * @returns {System.DateTime} the first non-null meaningful date, or null if non is found
 */
define function FindDate(Obs Observation):
  Coalesce(
    (Obs.effective as FHIR.dateTime).value,
    (Obs.effective as FHIR.instant).value,
    (Obs.effective as FHIR.Period)."end".value,
    (Obs.effective as FHIR.Period)."start".value,
    Obs.issued.value
  )

/**
 * The highest observation.
 * The value will be used to compare Observations and determine the highest one.
 * @param ObsList - a list of Observations
 * @returns {System.Quantity} the quantity with the highest value from the list, or null if null was passed in
 */
define function HighestObservation(ObsList List<Observation>):
  Max(ObsList O return FHIRHelpers.ToQuantity(O.value as FHIR.Quantity))

/**
 * The lowest observation.
 * The value will be used to compare Observations and determine the lowest one.
 * @param ObsList - a list of Observations
 * @returns {System.Quantity} the quantity with the lowest value from the list, or null if null was passed in
 */
define function LowestObservation(ObsList List<Observation>):
  Min(ObsList O return FHIRHelpers.ToQuantity(O.value as FHIR.Quantity))


// -------------------------------------------------- CONDITIONS -------------------------------------------------------

/**
 * Filters Conditions by a concept rather than by a ValueSet.  In CQL 1.3, this is built into the retrieve,
 * but for backwards compatibility, we keep this query where clause as an option.
 * @param Koncept - the concept to filter on (intentionally mispelled to avoid naming clashes)
 * @returns {List<Observation>} a list of Conditions matching the concept, or null if null was passed in
 */
define function ConditionsByConcept(Koncept System.Concept):
  [Condition] C where FHIRHelpers.ToConcept(C.code) ~ Koncept

/**
 * Conditions that are confirmed. In FHIR R4, this is reflected by verificationStatus: 'confirmed'.
 * @see http://hl7.org/fhir/R4/valueset-condition-ver-status.html
 * @param CondList - a list of Conditions
 * @returns {List<Condition>} a list of confirmed Conditions, or null if null was passed in
 */
define function Confirmed(CondList List<Condition>):
  CondList C where C.verificationStatus ~ "Condition Confirmed code"

/**
 * Conditions that are active. In FHIR R4, this is reflected by clinicalStatus: 'active' and the absence of any
 * abatement information (i.e., if it abated, it is no longer active).
 * TODO: Rename to Active once the execution engine supports overloaded functions.
 * @see http://hl7.org/fhir/R4/valueset-condition-clinical.html
 * @param CondList - a list of Conditions
 * @returns {List<Condition>} a list of active Conditions, or null if null was passed in
 */
define function ActiveCondition(CondList List<Condition>):
  CondList C
    where C.clinicalStatus ~ "Condition Active code"
      and C.abatement is null

/**
 * Conditions that are active or recurring. In FHIR R4, this is reflected by clinicalStatus: 'active', 'recurrence', or
 * 'relapse'.  We do not check for null abatement information because it may have dates from when the now recurring
 * condition initially went into remission.
 * @see http://hl7.org/fhir/R4/valueset-condition-clinical.html
 * @param CondList - a list of Conditions
 * @returns {List<Condition>} a list of active or recurring Conditions, or null if null was passed in
 */
define function ActiveOrRecurring(CondList List<Condition>):
  CondList C
    where C.clinicalStatus ~ "Condition Active code"
      or C.clinicalStatus ~ "Condition Recurrence code"
      or C.clinicalStatus ~ "Condition Relapse code"

/**
 * Conditions with an onset or recorded date in the specified "look back" period.  For example, pregnancy in
 * the last 42 weeks.
 * TODO: Rename to LookBack once the execution engine supports overloaded functions.
 * @param CondList - a list of Conditions
 * @returns {List<Condition>} a list of Conditions with onset or recorded date specified lookback period, or null
 * if null was passed in
 */
define function ConditionLookBack(CondList List<Condition>, LookBack System.Quantity):
  CondList C
    let LookBackInterval: Interval[Now() - LookBack, Now()]
    where (C.onset as FHIR.dateTime).value in LookBackInterval
      or PeriodToInterval(C.onset as FHIR.Period) overlaps LookBackInterval
      or C.recordedDate.value in LookBackInterval

/**
 * The most recent condition.  For each Condition, this algorithm will use the Coalesce function, which uses the
 * first non-null result from these fields: onsetDateTime, onsetPeriod.end, onsetPeriod.start, assertedDate.
 * The found date will be used to compare Conditions and determine the most recent one.
 * @param CondList - a list of Conditions
 * @returns {Condition} the most recent Condition from the list, or null if null was passed in
 */
define function MostRecentCondition(CondList List<Condition>):
  Last(CondList C sort by Coalesce(
    (onset as FHIR.dateTime).value,
    (onset as FHIR.Period)."end".value,
    (onset as FHIR.Period)."start".value,
    recordedDate.value)
  )

 // -------------------------------------------------- PROCEDURES ------------------------------------------------------

 /**
  * Filters Procedures by a concept rather than by a ValueSet.  In CQL 1.3, this is built into the retrieve,
 * but for backwards compatibility, we keep this query where clause as an option.
  * @param Koncept - the concept to filter on (intentionally mispelled to avoid naming clashes)
  * @returns {List<Procedure>} a list of Procedures matching the concept, or null if null was passed in
  */
 define function ProceduresByConcept(Koncept System.Concept):
   [Procedure] P where FHIRHelpers.ToConcept(P.code) ~ Koncept

/**
 * Procedures that are completed. In FHIR R4, this is reflected by status: 'completed'.
 * @see http://hl7.org/fhir/R4/valueset-event-status.html
 * @param ProcList - a list of Procedures
 * @returns {List<Procedure>} a list of completed Procedures, or null if null was passed in
 */
define function Completed(ProcList List<Procedure>):
  ProcList P
    where P.status.value = 'completed'

/**
 * Procedures that are in progress. In FHIR R4, this is reflected by status: 'in-progress'.
 * @see http://hl7.org/fhir/R4/valueset-event-status.html
 * @param ProcList - a list of Procedures
 * @returns {List<Procedure>} a list of completed Procedures, or null if null was passed in
 */
define function ProcedureInProgress(ProcList List<Procedure>):
  ProcList P
    where P.status.value = 'in-progress'

/**
 * Procedures that actually happened or are happening. In FHIR R4, there are a few properties that negate the
 * procedure, most notably when status is 'preparation', 'not-done', 'entered-in-error', or 'unknown'.
 * @see http://hl7.org/fhir/R4/valueset-event-status.html
 * @param ProcList - a list of Procedures
 * @returns {List<Procedure>} a list of Procedures that actually happened or are happening, or null if null was passed in
 */
define function ProcedurePerformance(ProcList List<Procedure>):
  ProcList P
    where not (P.status.value in {'preparation', 'not-done', 'entered-in-error', 'unknown'})

/**
 * Procedures performed in the specified "look back" period.  For example, PCIs performed in the
 * past 2 weeks.
 * TODO: Rename to LookBack once the execution engine supports overloaded functions.
 * @param ProcList - a list of Procedures
 * @param LookBack - the lookback period for when the procedure was performed
 * @returns {List<Procedure>} a list of Procedures performed in the look back period, or null if null
 * was passed in
 */
define function ProcedureLookBack(ProcList List<Procedure>, LookBack System.Quantity):
  ProcList P
    let LookBackInterval: Interval[Now() - LookBack, Now()]
    where (P.performed as FHIR.dateTime).value in LookBackInterval
      or PeriodToInterval(P.performed as FHIR.Period) overlaps LookBackInterval

/**
 * The most recent procedure.  For each Procedure, this algorithm will use the Coalesce function, which returns the
 * first non-null result from these fields: performedDateTime, performedPeriod.end, performedPeriod.start.
 * The found date will be used to compare Procedures and determine the most recent one.
 * @param ProcList - a list of Procedures
 * @returns {Procedure} the most recent Procedure from the list, or null if null was passed in
 */
define function MostRecentProcedure(ProcList List<Procedure>):
  Last(ProcList P sort by Coalesce(
    (performed as FHIR.dateTime).value,
    (performed as FHIR.Period)."end".value,
    (performed as FHIR.Period)."start".value)
  )

// ----------------------------------------------- SERVICEREQUESTS -----------------------------------------------------

// NOTE: In FHIR R4, ProcedureRequest and ReferralRequest are replaced by ServiceRequest

/**
 * ServiceRequests that are active or completed. In FHIR R4, this is reflected by the corresponding
 * status values.
 * @see http://hl7.org/fhir/R4/valueset-request-status.html
 * @param ServiceRequestList - a list of ServiceRequests
 * @returns {List<ServiceRequest>} a list of accepted, in-progress, or completed ProcedureRequests,
 * or null if null was passed in
 */
define function ServiceRequestActiveOrCompleted(ServiceRequestList List<ServiceRequest>):
  ServiceRequestList S
    where S.status.value in List{'active', 'completed'}

/**
 * ServiceRequests ordered in the specified "look back" period.  For example, PCIs ordered in the
 * past 2 weeks.
 * TODO: Rename to LookBack once the execution engine supports overloaded functions.
 * @param ServiceRequestList - a list of ServiceRequests
 * @param LookBack - the lookback period for when the service was ordered
 * @returns {List<ServiceRequest>} a list of ServiceRequests ordered in the look back period, or null if null
 * was passed in
 */
define function ServiceRequestLookBack(ServiceRequestList List<ServiceRequest>, LookBack System.Quantity):
  ServiceRequestList S
    where S.authoredOn.value in Interval[Now() - LookBack, Now()]

// -------------------------------------------------- MEDICATIONS ------------------------------------------------------

/**
* Medication requests that are active.  In FHIR R4, this is reflected by MedicationRequest with status 'active'.
* Note that in R4, the MedicationRequest Boundaries and Relationships now says: "When reporting on the usage of
* a medication by a patient, the MedicationStatement resource should be used." It also indicates that:
* "A medication statement is not a part of the prescribe->dispense->administer sequence but is a report that
* such a sequence (or at least a part of it) did take place resulting in a belief that the patient has received
* a particular medication." In this regard, MedicationStatement is more appropriate as an indication of an actually
* active medication, although it's not clear if vendors really will automatically create MedicationStatements in
* these cases or not.  Until we know, MedicationRequest may be the best proxy we have for an active medication.
* TODO: Should the "intent" field be considered (e.g., is it still active if intent is "proposal" or "plan")?
* TODO: Rename to Active once the execution engine supports overloaded functions.
* @see http://hl7.org/fhir/R4/valueset-medicationrequest-status.html
* @param MedList - a list of MedicationRequests
* @returns {List<MedicationRequest>} a list of active medication requests, or null if null was passed in
*/
define function ActiveMedicationRequest(MedList List<MedicationRequest>):
  MedList M where M.status.value = 'active'

/**
* Medication requests that are active or completed, according to a prescription.  In FHIR R4, this is reflected by MedicationRequest
* with status 'active' or 'completed'.  See the note above (in ActiveMedicationRequest) for more nuance regarding MedicationRequest
* vs. MedicationStatement.
* @see http://hl7.org/fhir/R4/valueset-medicationrequest-status.html
* @param MedList - a list of MedicationRequests
* @returns {List<MedicationRequest>} a list of active medication requests, or null if null was passed in
*/
define function ActiveOrCompletedMedicationRequest(MedList List<MedicationRequest>):
  MedList M
    where M.status.value = 'active'
      or M.status.value = 'completed'

/**
* Medication requests that are active, completed, or stopped, according to a prescription.  In FHIR R4, this is
* reflected by MedicationRequest with status 'active', 'completed', or 'stopped'. See the note above
* (in ActiveMedicationRequest) for more nuance regarding MedicationRequest vs. MedicationStatement.
* @see http://hl7.org/fhir/R4/valueset-medicationrequest-status.html
* @param MedList - a list of MedicationOrders
* @returns {List<MedicationRequestr>} a list of active medication requests, or null if null was passed in
*/
define function ActiveCompletedOrStoppedMedicationRequest(MedList List<MedicationRequest>):
  MedList M
    where M.status.value = 'active'
      or M.status.value = 'completed'
      or M.status.value = 'stopped'

/**
* Medication requests that are issued in the specified "look back" period.
* TODO: Rename to LookBack once the execution engine supports overloaded functions.
* @param MedList - a list of Medications
* @param LookBack - the lookback period for when the medication was prescribed
* @returns {List<MedicationRequest>} a list of Medications prescribed in the look back period, or null if null
* was passed in
*/
define function MedicationRequestLookBack(MedList List<MedicationRequest>, LookBack System.Quantity):
  MedList M
    let LookBackInterval: Interval[Now() - LookBack, Now()]
    where M.authoredOn.value in LookBackInterval
    // DSTU2 also checked the dateEnded property of MedicationOrder, but this doesn't exist for MedicationRequest

// -------------------------------------------------- ENCOUNTERS ------------------------------------------------------

/**
 * Filters Encounters by a concept rather than by a ValueSet.  In CQL 1.3, this is built into the retrieve,
 * but for backwards compatibility, we keep this query where clause as an option.
 * @param Koncept - the concept to filter on (intentionally mispelled to avoid naming clashes)
 * @returns {List<Encounter>} a list of Encounters matching the concept, or null if null was passed in
 */
define function EncountersByConcept(Koncept System.Concept):
  [Encounter] E where exists( (E.type) ET where FHIRHelpers.ToConcept(ET) ~ Koncept )

/**
 * Encounters that are in progress. In FHIR R4, this is reflected by status: 'in-progress'.
 * @see http://hl7.org/fhir/R4/valueset-encounter-status.html
 * @param EncList - a list of Encounters
 * @returns {List<Encounter>} a list of in progress encounters, or null if null was passed in
 */
define function InProgress(EncList List<Encounter>):
  EncList E
    where E.status.value = 'in-progress'

// -------------------------------------------------- ALLERGY INTOLERANCES ------------------------------------------------------

/**
 * Filters AllergyIntolerances by a concept rather than by a ValueSet.  In CQL 1.3, this is built into the retrieve,
 * but for backwards compatibility, we keep this query where clause as an option.
 * @param Koncept - the concept to filter on (intentionally mispelled to avoid naming clashes)
 * @returns {List<AllergyIntolerance>} a list of Allergy Intolerances matching the concept, or null if null was passed in
 */
define function AllergyIntolerancesByConcept(Koncept System.Concept):
  [AllergyIntolerance] A where FHIRHelpers.ToConcept(A.code) ~ Koncept

/**
* AllergyIntolerances that are active or confirmed.  In FHIR STU3, this is reflected by AllergyIntolerance
* with clinicalStatus 'active' or verificationStatus 'confirmed'
* @see https://www.hl7.org/fhir/R4/valueset-allergy-clinical-status.html
* @see https://www.hl7.org/fhir/R4/valueset-allergy-verification-status.html
* @param AllergyIntolList - a list of AllergyIntolerances
* @returns {List<AllergyIntolerance>} a list of active or confirmed allergy intolerances, or null if null was passed in
*/
define function ActiveOrConfirmedAllergyIntolerance(AllergyIntolList List<AllergyIntolerance>):
  AllergyIntolList A
    where A.clinicalStatus ~ "AllergyIntolerance Active code"
      or A.verificationStatus ~ "AllergyIntolerance Confirmed code"

// -------------------------------------------------------- GOALS ------------------------------------------------------

/**
 * Goals with a start, target, or status date in the specified "look back" period.  For example, Pain Management Goals
 * in the last 2 years.
 * TODO: Rename to LookBack once the execution engine supports overloaded functions.
 * @param GoalList - a list of Goals
 * @returns {List<Goal>} a list of Goals with a start, target, or status date in the specified lookback period, or null
 * if null was passed in
 */
define function GoalLookBack(GoalList List<Goal>, LookBack System.Quantity):
  GoalList G
    let LookBackInterval: Interval[Now() - LookBack, Now()],
    StartDate: (G.start as FHIR.date).value,
    StatusDate: G.statusDate.value,
    TargetDates: (G.target) T return (T.due as FHIR.date).value,
    TargetQuantities: (G.target) T return FHIRHelpers.ToQuantity(T.due as FHIR.Duration)
    where StartDate in LookBackInterval
      or StatusDate in LookBackInterval
      or exists(TargetDates TD where TD in LookBackInterval)
      or exists(TargetQuantities TQ where (StartDate + TQ) in LookBackInterval)