/* \n Author: CMS Alliance to Modernize Healthcare, operated by THE MITRE Corporation.\n\n (C) 2024 The MITRE Corporation. All Rights Reserved. \n Approved for Public Release: 24-2711. \n Distribution Unlimited.\n\n Unless otherwise noted, this work is available under an Apache 2.0 license. \n It was produced by the MITRE Corporation for the Division of Cancer Prevention \n and Control, Centers for Disease Control and Prevention in accordance with the \n Statement of Work, contract number 75FCMC18D0047, task order number 75D30123F17931.\n*/\n\nlibrary CSMCommonFunctions version '1.0.0'\n\nusing FHIR version '4.0.1'\n\ninclude CDSConnectCommonsforFHIRv401 version '1.0.0' called C3F\ninclude FHIRHelpers version '4.0.1' called FHIRHelpers\n\ncodesystem "CONDVERSTATUS": 'http://terminology.hl7.org/CodeSystem/condition-ver-status'\n\ncode "Condition Refuted code": 'refuted' from "CONDVERSTATUS" display 'Refuted'\ncode "Condition Entered in Error code": 'entered-in-error' from "CONDVERSTATUS" display 'Entered in Error'\n\nconcept "Condition Refuted": { "Condition Refuted code" } display 'Refuted'\nconcept "Condition Entered in Error": { "Condition Entered in Error code" } display 'Entered in Error'\n\n/*******************************************************************************\n * NOTICE: This following code has been adapted from "Factors to Consider in \n * Managing Chronic Pain: A Pain Management Summary," available at:\n * https://cds.ahrq.gov/cdsconnect/artifact/factors-consider-managing-chronic-pain-pain-management-summary\n * It is made available via an Apache 2.0 license.\n*******************************************************************************/\n\n// Returns the first-found display text for a CodeableConcept, looking first at the `text` attribute, then the\n// `display` on each `coding` until it finds a non-null value. Some PEG codes are normalized due to length.\n// @param c - a FHIR CodeableConcept to get text from\n// @returns {System.String} the display text or null if none is found\ndefine function ConceptText(c FHIR.CodeableConcept):\n Coalesce(c.text.value, Coalesce((c.coding) c2 return c2.display.value))\n\n// Returns a text representation of a date using the CQL `ToString` function.\n// @param d - a FHIR date to get text for\n// @returns {System.String} the text representation of the date\ndefine function DateText(d FHIR.date):\n ToString(d.value)\n\n// Returns a text representation of a dateTime using the CQL `ToString` function.\n// @param d - a FHIR dateTime to get text for\n// @returns {System.String} the text representation of the date portion of the dateTime\ndefine function DateTimeText(d FHIR.dateTime):\n First(SplitOnMatches(ToString(d.value), 'T'))\n\n// Returns a text representation of an instant using the CQL `ToString` function.\n// @param i - a FHIR instant to get text for\n// @returns {System.String} the text representation of the instant\ndefine function InstantText(i FHIR.instant):\n ToString(i.value)\n\n// Returns a text representation of a Quantity with the Quantity's value and unit.\n// If the unit is {score}, then omit it (as it is not useful to display)\n// @param q - a FHIR Quantity to get text for\n// @returns {System.String} the text representation of the Quantity\ndefine function QuantityText(q FHIR.Quantity):\n if (q is null) then null\n else if (q.unit is not null) then ToString(q.value.value) + ' ' + q.unit.value\n else if (q.code is not null) then ToString(q.value.value) + ' ' + q.code.value\n else ToString(q.value.value)\n\n// Returns a tuple containing a Period's start and end as text representations.\n// @param p - a FHIR Period to get a tuple for\n// @returns {Tuple<Start System.String, End System.String>} the tuple representation of the Period\ndefine function PeriodObject(p FHIR.Period):\n if p is null then null\n else\n {\n Start: DateTimeText(p."start"),\n End: DateTimeText(p."end")\n }\n\n// Returns a tuple containing a Range's low and high as text representations.\n// @param r - a FHIR Range to get a tuple for\n// @returns {Tuple<Low System.String, High System.String>} the tuple representation of the Range\ndefine function RangeObject(r FHIR.Range):\n if r is null then null\n else\n {\n Low: QuantityText(r.low),\n High: QuantityText(r.high)\n }\n\ndefine function ObservationDate(o FHIR.Observation):\n Coalesce(\n (o.effective as FHIR.dateTime).value,\n (o.effective as FHIR.instant).value,\n (o.effective as FHIR.Period)."end".value,\n (o.effective as FHIR.Period)."start".value,\n (o.issued as FHIR.instant).value\n )\n\n// Returns a text representation of a date associated with an Observation, preferring `effectiveDateTime`, then\n// `effectivePeriod.start`, then `issued`.\n// @param o - a FHIR Observation to get the text date from\n// @returns {System.String} the text representation of a relevant date from the Observation\ndefine function ObservationDateString(o FHIR.Observation):\n Coalesce(\n DateTimeText(o.effective as FHIR.dateTime),\n InstantText(o.effective as FHIR.instant),\n DateTimeText((o.effective as FHIR.Period)."end"),\n DateTimeText((o.effective as FHIR.Period)."start"),\n InstantText(o.issued)\n )\n\n// Returns a text representation of a date associated with a MedicationStatement, preferring `effectiveDateTime`, then\n// `.start`.\n// @param s - a FHIR MedicationStatement to get the text date from\n// @returns {System.String} the text representation of a relevant date from the MedicationStatement\ndefine function MedicationStatementDate(s FHIR.MedicationStatement):\n Coalesce(\n DateTimeText(s.effective as FHIR.dateTime),\n DateTimeText((s.effective as FHIR.Period)."end"),\n DateTimeText((s.effective as FHIR.Period)."start")\n )\n\n// Returns a text representation of a Condition's onset, whether represented as a dateTime, Period, Quantity (Age),\n// Range (Age), or string.\n// @param c - a FHIR Condition to get the text representation of the onset from\n// @returns {System.String} the text representation of the Condition's onset\ndefine function Onset(c FHIR.Condition):\n Coalesce( List{\n DateTimeText(c.onset as FHIR.dateTime),\n QuantityText(c.onset as FHIR.Age),\n PeriodObject(c.onset as FHIR.Period),\n RangeObject(c.onset as FHIR.Range),\n (c.onset as FHIR.string).value\n })\n\n// Returns a text representation of a Condition's abatement, whether represented as a dateTime, Period, Quantity (Age),\n// Range (Age), string, or boolean.\n// @param c - a FHIR Condition to get the text representation of the abatement from\n// @returns {System.String} the text representation of the Condition's abatement\ndefine function Abatement(c FHIR.Condition):\n Coalesce( List{\n DateTimeText(c.abatement as FHIR.dateTime),\n // QuantityText(c.abatement as FHIR.Age),\n PeriodObject(c.abatement as FHIR.Period),\n RangeObject(c.abatement as FHIR.Range),\n (c.abatement as FHIR.string).value\n })\n\n/*******************************************************************************\n * END: Code adapted from "Factors to Consider in Managing Chronic Pain: A Pain \n * Management Summary"\n*******************************************************************************/\n\n/*******************************************************************************\n* Condition Functions\n*******************************************************************************/\n\ndefine function ConditionDate(C Condition):\n Coalesce(\n (C.onset as FHIR.dateTime).value,\n (C.onset as FHIR.Period)."end".value,\n (C.onset as FHIR.Period)."start".value,\n C.recordedDate.value\n )\n\n/**\n * The oldest condition. For each Condition, this algorithm will use the Coalesce function, which uses the\n * first non-null result from these fields: onsetDateTime, onsetPeriod.start, assertedDate, onsetPeriod.end.\n * The found date will be used to compare Conditions and determine the oldest one.\n * @param CondList - a list of Conditions\n * @returns {Condition} the oldest Condition from the list, or null if null was passed in\n */\ndefine function OldestCondition(CondList List<Condition>):\n First(CondList C sort by Coalesce(\n (onset as FHIR.dateTime).value,\n (onset as FHIR.Period)."start".value,\n recordedDate.value,\n (onset as FHIR.Period)."end".value)\n )\n\n/**\n * Date of the oldest condition in a list. For each Condition, this algorithm will use the Coalesce function, which uses the\n * first non-null result from these fields: onsetDateTime, onsetPeriod.start, assertedDate, onsetPeriod.end.\n * The found date will be used to compare Conditions and determine the oldest one. The date of the oldest Condition\n * will be returned.\n * @param CondList - a list of Conditions\n * @returns {System.String} the text representation of the Condition's date\n */\ndefine function DateOfFirstCondition(CondList List<Condition>):\n ConditionDate(\n OldestCondition(\n CondList\n )\n )\n\n/**\n * Conditions that are valid. This is reflected by a Condition that does not have a verificationStatus of 'refuted' or `entered-in-error`.\n * @see http://hl7.org/fhir/R4/valueset-condition-ver-status.html\n * @param CondList - a list of Conditions\n * @returns {List<Condition>} a list of valid Conditions, or null if null was passed in\n */\ndefine function ValidCondition(CondList List<Condition>):\n CondList C where C.verificationStatus !~ "Condition Refuted"\n and C.verificationStatus !~ "Condition Entered in Error"\n\n/*******************************************************************************\n* DiagnosticReport Functions\n*******************************************************************************/\n\n// Returns a text representation of a date associated with a DiagnosticReport, preferring `effectiveDateTime`, then\n// `.start`.\n// @param s - a FHIR DiagnosticReport to get the text date from\n// @returns {System.String} the text representation of a relevant date from the DiagnosticReport\ndefine function DiagnosticReportDateString(d FHIR.DiagnosticReport):\n Coalesce(\n DateTimeText((d.effective as FHIR.Period)."end" as FHIR.dateTime),\n DateTimeText(d.effective as FHIR.dateTime),\n DateTimeText((d.effective as FHIR.Period)."start" as FHIR.dateTime)\n )\n\ndefine function DiagnosticReportDate(d FHIR.DiagnosticReport):\n Coalesce(\n (d.effective as FHIR.Period)."end".value,\n (d.effective as FHIR.dateTime).value,\n (d.effective as FHIR.Period)."start".value\n )\n\ndefine function SortedDiagnosticReports(ReportList List<FHIR.DiagnosticReport>):\n ReportList R sort by Coalesce(\n (effective as FHIR.Period)."end".value,\n (effective as FHIR.dateTime).value,\n (effective as FHIR.Period)."start".value\n )\n\ndefine function MostRecentDiagnosticReport(ReportList List<FHIR.DiagnosticReport>):\n Last(\n SortedDiagnosticReports(\n ReportList\n )\n )\n\n/**\n* Diagnostic Reports that are issued in the specified "look back" period.\n* TODO: Rename to LookBack once the execution engine supports overloaded functions.\n* @param DiagnosticReportList - a list of DiagnosticReports\n* @param LookBack - the lookback period for when the DiagnosticReport specimen was collected\n* @returns {List<DiagnosticReport>} a list of DiagnosticReports in the look back period, or null if null\n* was passed in\n*/\ndefine function LookBack(DiagnosticReportList List<DiagnosticReport>, LookBack System.Quantity):\n DiagnosticReportList D\n let LookBackInterval: Interval[Now() - LookBack, Now()]\n where (D.effective as FHIR.dateTime).value in LookBackInterval\n or C3F.PeriodToInterval(D.effective as FHIR.Period) overlaps LookBackInterval\n\n /**\n* Diagnostic Reports that are issued in the specified "look back" period and after a specified "look back" date\n* @param DiagnosticReportList - a list of DiagnosticReports\n* @param LookBack - the lookback period for when the DiagnosticReport specimen was collected\n* @param LookBackDate - the date that the DiagnosticReport test must fall after\n* @returns {List<DiagnosticReport>} a list of DiagnosticReports in the look back period and after the\n* look back date, or null if null was passed in\n*/\ndefine function LookBack(DiagnosticReportList List<DiagnosticReport>, LookBack System.Quantity, LookBackDate System.DateTime):\n DiagnosticReportList D\n let LookBackInterval: Interval[Now() - LookBack, Now()]\n where ( ((D.effective as FHIR.dateTime).value in LookBackInterval) and ((D.effective as FHIR.dateTime).value after LookBackDate) )\n or ( (C3F.PeriodToInterval(D.effective as FHIR.Period) overlaps LookBackInterval) and (C3F.PeriodToInterval(D.effective as FHIR.Period) starts after LookBackDate) )\n\n// TODO: Parameterize by association window (currently hard-coded to 1 day)\ndefine function AssociateDiagnosticReports(d1 FHIR.DiagnosticReport, d2 FHIR.DiagnosticReport):\n if (\n (d1.effective as FHIR.dateTime).value within 1 day of (d2.effective as FHIR.dateTime).value or\n (d1.effective as FHIR.dateTime).value within 1 day of (d2.effective as FHIR.Period)."start".value or \n (d1.effective as FHIR.dateTime).value within 1 day of (d2.effective as FHIR.Period)."end".value or\n (d2.effective as FHIR.dateTime).value within 1 day of (d1.effective as FHIR.Period)."start".value or \n (d2.effective as FHIR.dateTime).value within 1 day of (d1.effective as FHIR.Period)."end".value or\n (d1.effective as FHIR.Period) overlaps (d2.effective as FHIR.Period)\n ) then\n true\n else\n false\n\ndefine function CoincidentDiagnosticReports(d1 FHIR.DiagnosticReport, d2 FHIR.DiagnosticReport):\n if (\n AssociateDiagnosticReports(d1, d2) or\n d1.encounter = d2.encounter or\n (\n Coalesce((d1.basedOn) R where R.type = 'ServiceRequest' return R.reference) =\n Coalesce((d2.basedOn) R where R.type = 'ServiceRequest' return R.reference)\n )\n ) then\n true\n else\n false\n\n\n/*******************************************************************************\n* Encounter Functions\n*******************************************************************************/\n\n/**\n * Encounters that are triaged, in-progress or completed.\n * @see http://hl7.org/fhir/R4/valueset-encounter-status.html\n * @param EncList - a list of Encounters\n * @returns {List<Encounter>} a list of encounters, or null if null was passed in\n */\ndefine function RelevantEncounterStatus(EncList List<Encounter>):\n EncList E\n where E.status.value = 'triaged'\n or E.status.value = 'in-progress'\n or E.status.value = 'finished'\n\n\n/*******************************************************************************\n* Medication Functions\n*******************************************************************************/\n\n// Returns a text representation of a date associated with a MedicationAdministration, preferring `effectiveDateTime`, then\n// `.start`.\n// @param s - a FHIR MedicationAdministration to get the text date from\n// @returns {System.String} the text representation of a relevant date from the MedicationAdministration\ndefine function MedicationAdministrationDate(a FHIR.MedicationAdministration):\n Coalesce(\n DateTimeText(a.effective as FHIR.dateTime),\n DateTimeText((a.effective as FHIR.Period)."end"),\n DateTimeText((a.effective as FHIR.Period)."start")\n )\n\n/**\n* Medication administrations that are completed, according to a prescription.\n* @see https://www.hl7.org/fhir/valueset-medication-admin-status.html\n* @param MedList - a list of MedicationAdministrations\n* @returns {List<MedicationAdministration>} a list of completed medication administrations, or null if null was passed in\n*/\ndefine function CompletedMedicationAdministration(MedList List<MedicationAdministration>):\n MedList M\n where M.status.value = 'completed'\n\ndefine function CompletedMedicationDispense(MedList List<MedicationDispense>):\n MedList M\n where M.status.value = 'completed'\n\n/**\n* Diagnostic reports that are completed.\n* @see https://www.hl7.org/fhir/valueset-diagnostic-report-status.html\n* @param DiagnosticReportList - a list of DiagnosticReports\n* @returns {List<DiagnosticReport>} a list of completed diagnostic reports, or null if null was passed in\n*/\ndefine function CompletedDiagnosticReport(DiagnosticReportList List<DiagnosticReport>):\n DiagnosticReportList D\n where D.status.value in List{'final', 'amended', 'corrected', 'appended'}\n\n/**\n* Medication Administrations that are issued in the specified "look back" period.\n* TODO: Rename to LookBack once the execution engine supports overloaded functions.\n* @param MedList - a list of MedicationAdministrations\n* @param LookBack - the lookback period for when the medication was prescribed\n* @returns {List<MedicationAdministration>} a list of MedicationAdministrations prescribed in the look back period, or null if null\n* was passed in\n*/\ndefine function LookBack(MedList List<MedicationAdministration>, LookBack System.Quantity):\n MedList M\n let LookBackInterval: Interval[Now() - LookBack, Now()]\n where (M.effective as FHIR.dateTime).value in LookBackInterval\n or C3F.PeriodToInterval(M.effective as FHIR.Period) overlaps LookBackInterval\n\n/**\n* Medication requests that are completed, according to a prescription.\n* @see http://hl7.org/fhir/R4/valueset-medicationrequest-status.html\n* @param MedList - a list of MedicationRequests\n* @returns {List<MedicationRequest>} a list of completed medication requests, or null if null was passed in\n*/\ndefine function CompletedMedicationRequest(MedList List<MedicationRequest>):\n MedList M\n where M.status.value = 'completed'\n\n/**\n* Medication requests with an intent of 'order', or one of the sub-categories of 'order'.\n* @see http://hl7.org/fhir/R4/valueset-medicationrequest-intent.html\n* @param MedList - a list of MedicationRequests\n* @returns {List<MedicationRequest>} a list of medication requests with an intent of 'order', or null if null was passed in\n*/\ndefine function MedicationRequestsWithOrderIntent(MedList List<MedicationRequest>):\n MedList M\n where M.intent.value = 'order'\n or M.intent.value = 'original-order'\n or M.intent.value = 'reflex-order'\n or M.intent.value = 'filler-order'\n or M.intent.value = 'instance-order'\n\n/*******************************************************************************\n* Observation Functions\n*******************************************************************************/\n\n\n/*******************************************************************************\n* Procedure Functions\n*******************************************************************************/\n\ndefine function ProcedureDate(p FHIR.Procedure):\n Coalesce(\n (p.performed as FHIR.dateTime).value,\n (p.performed as FHIR.Period)."end".value,\n (p.performed as FHIR.Period)."start".value\n )\n\n// TODO: Can replace this with an overloaded function\n// Returns a text representation of a date associated with a Procedure, preferring `effectiveDateTime`, then\n// `.start`.\n// @param s - a FHIR Procedure to get the text date from\n// @returns {System.String} the text representation of a relevant date from the Procedure\ndefine function ProcedureDateString(p FHIR.Procedure):\n Coalesce(\n DateTimeText(p.performed as FHIR.dateTime),\n DateTimeText((p.performed as FHIR.Period)."end"),\n DateTimeText((p.performed as FHIR.Period)."start")\n )\n\n /**\n * The oldest procedure. For each Procedure, this algorithm will use the Coalesce function, which returns the\n * first non-null result from these fields: performedDateTime, performedPeriod.start, performedPeriod.end.\n * The found date will be used to compare Procedures and determine the oldest one.\n * @param ProcList - a list of Procedures\n * @returns {Procedure} the oldest Procedure from the list, or null if null was passed in\n */\ndefine function OldestProcedure(ProcList List<Procedure>):\n First(ProcList P sort by Coalesce(\n (performed as FHIR.dateTime).value,\n (performed as FHIR.Period)."start".value,\n (performed as FHIR.Period)."end".value)\n )\n\n/**\n * Date of the oldest procedure in a list. For each Procedure, this algorithm will use the Coalesce function, which returns the\n * first non-null result from these fields: performedDateTime, performedPeriod.end, performedPeriod.start.\n * The found date will be used to compare Procedures and determine the oldest one. The date of the oldest Procedure\n * will be returned.\n * @param ProcList - a list of Procedures\n * @returns {System.String} the text representation of the Procedure's date\n */\ndefine function DateOfFirstProcedure(ProcList List<Procedure>):\n ProcedureDate(\n OldestProcedure(\n ProcList\n )\n )\n\n/*******************************************************************************\n* Immunization Functions\n*******************************************************************************/\n\n/**\n* Immunizations that are completed.\n* @see http://hl7.org/fhir/R4/valueset-immunization-status.html\n* @param ImmunizationList - a list of Immunizations\n* @returns {List<Immunization>} a list of completed immunizations, or null if null was passed in\n*/\ndefine function CompletedImmunization(ImmunizationList List<Immunization>):\n ImmunizationList I\n where I.status.value = 'completed'
|
\n