cql_qdm_patientapi 1.0.0

data/app/assets/javascripts/cqlpatient.js.coffee

@@ -0,0 +1,232 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+
+###
+Represents a patient. The interface aligns with QDM. The internals are
+HDS mapped to the QDM representation.
+
+Typical flow of usage:
+1.  Bonnie takes one of its patient records and creates a CQL_QDM.CQLPatient
+    for it.
+1a. This class takes that patient record and checks for data criteria that
+    exist on it.
+1b. When it finds a data criteria record, it creates an equivalent
+    CQL_QDM.QDMDatatype instance of that data criteria, and attaches it to
+    the instance of this patient. This process happens in the 'buildDatatypes'
+    method.
+2.  When the CQL execution engine comes across a retrieve statement (e.g.
+    ["Encounter Performed"]), it will call 'findRecords' on this class with
+    the name of that profile. The 'findRecords' method will do some parsing,
+    and eventually return an array of CQL_QDM.QDMDatatype(s) that both
+    match that profile and exist on the instance of this patient.
+3.  The CQL_QDM.QDMDatatype directly represents a QDM datatype. The classes
+    that subclass this class (e.g. CQL_QDM.EncounterActive) provide methods
+    that represent the relevant QDM datatypes attributes (e.g.
+    CQL_QDM.EncounterActive.relevantPeriod).
+4.  When a CQL statement takes a data criteria and wants to check an attribute
+    of it, it calls the 'get' method of the CQL_QDM.QDMDatatype superclass with
+    the name of that attribute. This 'get' method takes that attribute and
+    calls the relevant attribute method on that data criteria.
+5.  Each attribute method of a CQL_QDM.QDMDatatype correctly converts the
+    Bonnie value for something into a form that the CQL execution engine
+    can understand.
+###
+class CQL_QDM.CQLPatient
+  constructor: (patient) ->
+    @_patient = patient
+    @_datatypes = @buildDatatypes()
+
+  ###
+  @returns {String}
+  ###
+  id: ->
+    @_patient.id
+
+  ###
+  This method is called by the CQL execution engine on a CQLPatient when
+  the execution engine wants information on a record. A record could be patient
+  characteristic information about the patient, or it could be data criteria
+  that currently exist on this patient (data criteria you drag on a patient
+  in Bonnie's patient builder).
+
+  @param {String} profile - the data criteria requested by the execution engine
+  @returns {Object}
+  ###
+  findRecords: (profile) ->
+    if profile == 'Patient'
+      # Requested generic patient info
+      @getPatientMetadata()
+    else if /PatientCharacteristic/.test profile
+      # Requested a patient characteristic
+      @getPatientCharacteristic(profile)
+    else if profile?
+      # Requested something else (probably a QDM data type).
+
+      # Strip model details from request. The requested profile string contains
+      # a lot of things we don't need or care about. Example, we might see
+      # something like:
+      # "{urn:healthit-gov:qdm:v5_0_draft}PatientCharacteristicEthnicity"
+      # Where we only care about: "PatientCharacteristicEthnicity".
+      profile = profile.replace(/ *\{[^)]*\} */g, '')
+
+      # Check and handle negation status
+      if /Positive/.test profile
+        profile = profile.replace /Positive/, ''
+        # Since the data criteria is 'Positive', it is not negated.
+        return @getNegatableDataCriteria(profile, false)
+      else if /Negative/.test profile
+        profile = profile.replace /Negative/, ''
+        # Since the data criteria is 'Negative', it is negated.
+        return @getNegatableDataCriteria(profile, true)
+      else
+        # No negation status, proceed normally
+        if @_datatypes[profile]? then return @_datatypes[profile] else []
+    else
+      []
+
+  ###
+  Handles requests for patient characteristic information (e.g. birthdate).
+
+  @param {String} profile - the data criteria requested by the execution engine
+  @returns {Array of Objects}
+  ###
+  getPatientCharacteristic: (profile) ->
+    if /PatientCharacteristicSex/.test profile
+      # Requested sex
+      [new CQL_QDM.PatientCharacteristicSex(@_patient)]
+    else if /PatientCharacteristicBirthdate/.test profile
+      # Requested birthdate
+      [new CQL_QDM.PatientCharacteristicBirthdate(@_patient)]
+    else if /PatientCharacteristicExpired/.test profile
+      # Requested deathdate
+      [new CQL_QDM.PatientCharacteristicExpired(@_patient)]
+    else
+      # Check if there are PatientCharateristic qdm datatypes that can be returned
+      profile = profile.replace(/ *\{[^)]*\} */g, '')
+      @_datatypes[profile] || []
+
+  ###
+  Searches the patient's history for data criteria that match the given
+  profile (keeping in mind negated status). Specifically, if we wanted
+  something that was negated, and we only have an instance of that thing
+  without a negation, we would not include it.
+
+  @param {String} profile - the data criteria requested by the execution engine
+  @param {Boolean} isNegated - the negated type of data criteria to look for
+  @returns {Array}
+  ###
+  getNegatableDataCriteria: (profile, isNegated) ->
+    results = []
+    if @_datatypes[profile]?
+      for dataCriteria in @_datatypes[profile]
+        if isNegated
+          if dataCriteria._negationRationale != null && dataCriteria._negationRationale != undefined
+            results.push dataCriteria
+        else
+          if dataCriteria._negationRationale == null || dataCriteria._negationRationale == undefined
+            results.push dataCriteria
+    results
+
+  ###
+  This method searches through the Bonnie patient for data criteria (i.e. the
+  data criteria that have been dragged on a patient in Bonnie's patient
+  builder). It then takes what it finds and creates CQL_QDM.QDMDatatype
+  versions of them for future lookups by the execution engine.
+
+  @returns {Object}
+  ###
+  buildDatatypes: ->
+    # TODO: this datatypes scheme needs to be made more robust. It is too dependent
+    # on matching strings that don't always match.
+
+    # HDS based list that describe various QDM concepts.
+    # See lib/health-data-standards/models/record.rb in HDS for the origin
+    # of these types.
+    types = [
+      'adverse_events',
+      'assessments',
+      'allergies',
+      'care_goals',
+      'conditions',
+      'encounters',
+      'communications',
+      'family_history',
+      'immunizations',
+      'medical_equipment',
+      'medications',
+      'procedures',
+      'results',
+      'social_history',
+      'vital_signs',
+      'devices',
+      'diagnostic_studies',
+      'functional_statuses',
+      'interventions',
+      'laboratory_tests',
+      'physical_exams',
+      'risk_category_assessments',
+      'care_experiences',
+      'preferences',
+      'provider_characteristics',
+      'substances',
+      'system_characteristics',
+      'transfers'
+    ]
+    data_types = {}
+    for type in types
+      data_criteria = @_patient.get(type)
+      if data_criteria
+        # Looks like this patient has at least one instance of this type of
+        # data criteria; loop over them and create CQL_QDM.QDMDatatype of them.
+        for dc in data_criteria
+          # Construct a classname from the data criteria
+          # e.g. "Encounter, Performed: Face-to-Face Interaction" becomes
+          # EncounterPerformed
+          # TODO: this needs to be modified to look at the HQMF template OID instead of the description
+          classname = dc.description.substr(0, dc.description.lastIndexOf(':'))
+          # remove commas, slashes, and colons
+          classname = classname.replace(/,/g, '').replace(/\//g, '').replace(/:/g, '')
+          # make all words start upper case
+          classname = classname.replace(/\w\S*/g, (txt) ->
+            txt.charAt(0).toUpperCase() + txt.substr(1))
+          # both 'discharge' and 'order' are present tense when positive and past tense when negative.
+          # need to make consistently present tense (this is what is in the model-info file).
+          classname = classname.replace(/Ordered$/g, "Order")
+          classname = classname.replace(/Discharged$/g, "Discharge")
+          # remove spaces
+          classname = classname.replace(/ /g, '')
+          unless data_types[classname]?
+            data_types[classname] = []
+          # Checks that the key 'classname' exists in the CQL_QDM object
+          # confirming that a QDM datatype profile has been selected.
+          if classname of CQL_QDM
+            cql_dc = new CQL_QDM[classname](dc)
+            # Keep track of the 'bonnie' type for use in the 'Learn CQL' tool
+            cql_dc['bonnie_type'] = type
+            data_types[classname].push cql_dc
+    data_types
+
+  ###
+  Returns metadata information about this patient.
+  This metadata is composed of:
+    - birthDatetime (the birth date and time of the patient)
+    - gender (the sex of the patient)
+
+  @returns {Object}
+  ###
+  getPatientMetadata: ->
+    # Note about 'gender' key:
+    # If the execution engine wants an attribute of the patient
+    # directly, it calls findRecord with a profile of Patient, and
+    # looks at that object for things. Other times CQL might treat
+    # things like gender/sex as a data criteria (i.e. PatientPatientCharacteristicSex),
+    # and calls things like getCode on them. The info['gender'] is for the
+    # former case.
+    info = {}
+    info['birthDatetime'] = CQL_QDM.Helpers.convertDateTime(@_patient.get('birthdate'))
+    info['gender'] = @_patient.get('gender')
+    [info]

data/app/assets/javascripts/datatypes/adverseevent.js.coffee

@@ -0,0 +1,70 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+###
+Data elements that meet criteria using this datatype should document the Adverse
+Event and its corresponding value set.
+###
+class CQL_QDM.AdverseEvent extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    @_facilityLocation = @entry.facility
+    @_relevantPeriodLow = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    if @entry.end_time
+      @_relevantPeriodHigh = CQL_QDM.Helpers.convertDateTime(@entry.end_time)
+    else
+      # No end time; high is set to infinity
+      @_relevantPeriodHigh = CQL_QDM.Helpers.infinityDateTime()
+    @_severity = @entry.severity
+    @_type = @entry.type
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime
+
+  ###
+  @returns {FacilityLocation}
+  ###
+  facilityLocation: ->
+    if @_facilityLocation?.values?[0]?
+      new CQL_QDM.FacilityLocation(@_facilityLocation.values[0])
+    else
+      null
+
+  ###
+  @returns {Interval<Date>}
+  ###
+  relevantPeriod: ->
+    low = @_relevantPeriodLow
+    high = @_relevantPeriodHigh
+    if low?
+      new cql.Interval(low, high)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  severity: ->
+    if @_severity?
+      new cql.Code(@_severity.code, @_severity.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  type: ->
+    if @_type?
+      new cql.Code(@_type.code, @_type.code_system)
+    else
+      null

data/app/assets/javascripts/datatypes/allergyintolerance.js.coffee

@@ -0,0 +1,63 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+###
+Data elements that meet criteria using this datatype should document the Allergy
+or Intolerance and its corresponding value set.
+
+Timing: The Prevalence Period references the time from the onset date to the
+abatement date.
+###
+class CQL_QDM.AllergyIntolerance extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    @_prevalencePeriodLow = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    if @entry.end_time
+      @_prevalencePeriodHigh = CQL_QDM.Helpers.convertDateTime(@entry.end_time)
+    else
+      # No end time; high is set to infinity
+      @_prevalencePeriodHigh = CQL_QDM.Helpers.infinityDateTime()
+    @_severity = @entry.severity
+    @_type = @entry.type
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime
+
+  ###
+  @returns {Interval<Date>}
+  ###
+  prevalencePeriod: ->
+    low = @_prevalencePeriodLow
+    high = @_prevalencePeriodHigh
+    if low?
+      new cql.Interval(low, high)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  severity: ->
+    if @_severity?
+      new cql.Code(@_severity.code, @_severity.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  type: ->
+    if @_type?
+      new cql.Code(@_type.code, @_type.code_system)
+    else
+      null

data/app/assets/javascripts/datatypes/assessment.js.coffee

@@ -0,0 +1,159 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+
+###
+Data elements that meet criteria using this datatype should document completion
+of the assessment indicated by the QDM category and its corresponding value set.
+
+Timing: The time the assessment is completed; author time.
+###
+class CQL_QDM.AssessmentPerformed extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    @_method = @entry.method
+    @_negationRationale = @entry.negationReason
+    @_reason = @entry.reason
+    if @entry.values? && @entry.values.length > 0
+      @_result = @entry.values?[0]
+    @_relatedTo = @entry.references
+    @_components = @entry.components
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime
+
+  ###
+  @returns {Code}
+  ###
+  method: ->
+    if @_method?
+      new cql.Code(@_method.code, @_method.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  negationRationale: ->
+    if @_negationRationale?
+      new cql.Code(@_negationRationale.code, @_negationRationale.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  reason: ->
+    if @_reason?
+      new cql.Code(@_reason.code, @_reason.code_system)
+    else
+      null
+
+  ###
+  The model_info_file also lists Integer, Decimal, DateTime, Time, and Ratio.
+  Decimal and Integer are covered under Quantity with a nil unit.
+  Ratio is not yet supported with CQL although it appears in the QDM model.
+  Time and Datetime are covered by Date
+  @returns {Code|Quantity|Date}
+  ###
+  result: ->
+    if @_result
+      # A PhysicalQuantity with unit UnixTime is a TimeStamp, set in bonnie /lib/measures/patient_builder.rb
+      if @_result.units == 'UnixTime'
+        CQL_QDM.Helpers.convertDateTime(@_result.scalar)
+      else
+        CQL_QDM.Helpers.formatResult(@_result)
+    else
+      null
+
+  ###
+  @returns {Array}
+  ###
+  relatedTo: ->
+    CQL_QDM.Helpers.relatedTo(@_relatedTo)
+
+  ###
+  @returns {Array}
+  ###
+  components: ->
+    CQL_QDM.Helpers.components(@_components)
+
+
+###
+Data elements that meet this criteria using this datatype should document a
+recommendation for a request by a clinician or appropriately licensed care
+provider to a patient or an appropriate provider or organization to perform an
+assessment indicated by the QDM category and its corresponding value set.
+Timing: The time the recommendation is authored (i.e., provided to the patient).
+
+NOTE: Recommendations address the time that the recommendation occurs, a single
+point in time. Vendors have expressed concerns that recommendations are not
+necessarily captured or managed in a standard manner as part of structured data
+capture in clinical workflow; many are documented as part of assessments in
+narrative text. Measure developers should address feasibility of clinical
+workflow to capture recommendations when evaluating measures.
+###
+class CQL_QDM.AssessmentRecommended extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    @_method = @entry.method
+    @_negationRationale = @entry.negationReasonv
+    @_reason = @entry.reason
+    if @entry.values? && @entry.values.length > 0
+      @_result = @entry.values?[0]
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime
+
+  ###
+  @returns {Code}
+  ###
+  method: ->
+    if @_method?
+      new cql.Code(@_method.code, @_method.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  negationRationale: ->
+    if @_negationRationale?
+      new cql.Code(@_negationRationale.code, @_negationRationale.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  reason: ->
+    if @_reason?
+      new cql.Code(@_reason.code, @_reason.code_system)
+    else
+      null
+
+  ###
+  @returns {Code}
+  ###
+  method: ->
+    if @_method?
+      new cql.Code(@_method.code, @_method.code_system)
+    else
+      null

data/app/assets/javascripts/datatypes/careexperience.js.coffee

@@ -0,0 +1,47 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+
+###
+Data elements that meet this criterion indicate the patient’s care experience,
+usually measured with a validated survey tool. The most common tool is the
+Consumer Assessment of Healthcare Providers and Systems.
+###
+class CQL_QDM.PatientCareExperience extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime
+
+
+###
+Data elements that meet this criterion indicate the provider's experience
+with availability of resources (e.g., scheduling, equipment, space, and
+such consumables as medications). Provider care experience gauges provider
+satisfaction with key structures, processes, and outcomes in the healthcare
+delivery system.
+###
+class CQL_QDM.ProviderCareExperience extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+
+  ###
+  @returns {Date}
+  ###
+  authorDatetime: ->
+    @_authorDatetime

data/app/assets/javascripts/datatypes/caregoal.js.coffee

@@ -0,0 +1,60 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+
+###
+Unlike other QDM datatypes, the Care Goal datatype does not indicate a
+specific context of use. Instead, to meet this criterion, there must be
+documentation of a care goal as defined by the Care Goal QDM category and
+its corresponding value set.
+###
+class CQL_QDM.CareGoal extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} entry - the HDS data criteria object to convert
+  ###
+  constructor: (@entry) ->
+    super @entry
+    @_authorDatetime = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    @_relevantPeriodLow = CQL_QDM.Helpers.convertDateTime(@entry.start_time)
+    if @entry.end_time
+      @_relevantPeriodHigh = CQL_QDM.Helpers.convertDateTime(@entry.end_time)
+    else
+      # No end time; high is set to infinity
+      @_relevantPeriodHigh = CQL_QDM.Helpers.infinityDateTime()
+    @_relatedTo = @entry.references
+    @_targetOutcome = @entry.targetOutcome
+
+  ###
+  @returns {Interval<Date>}
+  ###
+  relevantPeriod: ->
+    low = @_relevantPeriodLow
+    high = @_relevantPeriodHigh
+    if low?
+      new cql.Interval(low, high)
+    else
+      null
+
+  ###
+  @returns {Array}
+  ###
+  relatedTo: ->
+    CQL_QDM.Helpers.relatedTo(@_relatedTo)
+
+  ###
+  The model_info_file also lists Integer, Decimal, and Ratio.
+  Decimal and Integer are covered under Quantity with a nil unit.
+  Ratio is not yet supported with CQL although it appears in the QDM model.
+  @returns {Quantity | Code}
+  ###
+  targetOutcome: ->
+    if @_targetOutcome?
+      if @_targetOutcome?['unit']?
+        new cql.Quantity({unit: @_targetOutcome['unit'], value: @_targetOutcome['value']})
+      else
+        new cql.Code(@_targetOutcome.code, @_targetOutcome.code_system)
+    else
+      null

data/app/assets/javascripts/datatypes/characteristic_birthdate.js.coffee

@@ -0,0 +1,28 @@
+###
+@namespace scoping into the CQL_QDM namespace (all classes and
+their methods will be accessable through the CQL_QDM namespace)
+###
+@CQL_QDM ||= {}
+
+
+###
+Used to represent a birthdate.
+###
+class CQL_QDM.PatientCharacteristicBirthdate extends CQL_QDM.QDMDatatype
+  ###
+  @param {Object} patient - the HDS patient object to use
+  ###
+  constructor: (@patient) ->
+    @_patient = @patient
+
+  ###
+  @returns {Object}
+  ###
+  getCode: ->
+    '21112-8' # LOINC code for birthdate
+
+  ###
+  @returns {DateTime}
+  ###
+  birthDatetime: ->
+    CQL_QDM.Helpers.convertDateTime(@_patient.get('birthdate'))