health-data-standards 3.6.1 → 3.7.0

data/lib/hqmf-parser/2.0/data_criteria_helpers/dc_base_extract.rb

@@ -0,0 +1,80 @@
+module HQMF2
+  # Contains extraction methods which are self-contained (rely only on the xml and an xpath, no other instance
+  # variables)
+  class DataCriteriaBaseExtractions
+    include HQMF2::Utilities
+    CONJUNCTION_CODE_TO_DERIVATION_OP = {
+      'OR' => 'UNION',
+      'AND' => 'XPRODUCT'
+    }
+
+    def initialize(entry)
+      @entry = entry
+    end
+
+    # Extract the local variable name (held in the value of the localVariableName element)
+    def extract_local_variable_name
+      lvn = @entry.at_xpath('./cda:localVariableName')
+      lvn['value'] if lvn
+    end
+
+    # Generate a list of child criterias
+    def extract_child_criteria
+      @entry.xpath("./*/cda:outboundRelationship[@typeCode='COMP']/cda:criteriaReference/cda:id",
+                   HQMF2::Document::NAMESPACES).collect do |ref|
+        Reference.new(ref).id
+      end.compact
+    end
+
+    # Extracts the derivation operator to be used by the data criteria, and fails out if it finds more than one (should
+    # not be valid)
+    def extract_derivation_operator
+      codes = @entry.xpath("./*/cda:outboundRelationship[@typeCode='COMP']/cda:conjunctionCode/@code",
+                           HQMF2::Document::NAMESPACES)
+      codes.inject(nil) do |d_op, code|
+        if d_op && d_op != CONJUNCTION_CODE_TO_DERIVATION_OP[code.value]
+          fail 'More than one derivation operator in data criteria'
+        end
+        CONJUNCTION_CODE_TO_DERIVATION_OP[code.value]
+      end
+    end
+
+    def extract_temporal_references
+      @entry.xpath('./*/cda:temporallyRelatedInformation', HQMF2::Document::NAMESPACES).collect do |temporal_reference|
+        TemporalReference.new(temporal_reference)
+      end
+    end
+
+    # Filters all the subset operators to only include the ones of type 'UNION' and 'XPRODUCT'
+    def extract_subset_operators
+      all_subset_operators.select do |operator|
+        operator.type != 'UNION' && operator.type != 'XPRODUCT'
+      end
+    end
+
+    # Extracts all subset operators contained in the entry xml
+    def all_subset_operators
+      @entry.xpath('./*/cda:excerpt', HQMF2::Document::NAMESPACES).collect do |subset_operator|
+        SubsetOperator.new(subset_operator)
+      end
+    end
+
+    def extract_template_ids
+      @entry.xpath('./*/cda:templateId/cda:item', HQMF2::Document::NAMESPACES).collect do |template_def|
+        HQMF2::Utilities.attr_val(template_def, '@root')
+      end
+    end
+
+    # Extract the negation (and the negation_code_list_id if appropriate)
+    def extract_negation
+      negation = (attr_val('./*/@actionNegationInd') == 'true')
+      negation_code_list_id = nil
+      if negation
+        res = @entry.at_xpath('./*/cda:outboundRelationship/*/cda:code[@code="410666004"]/../cda:value/@valueSet',
+                              HQMF2::Document::NAMESPACES)
+        negation_code_list_id = res.value if res
+      end
+      [negation, negation_code_list_id]
+    end
+  end
+end

data/lib/hqmf-parser/2.0/data_criteria_helpers/dc_definition_from_template_or_type_extract.rb

@@ -0,0 +1,201 @@
+module HQMF2
+  # Extracts the type, and modifies the data criteria, based on the template id or definition
+  module DataCriteriaTypeAndDefinitionExtraction
+    VARIABLE_TEMPLATE = '0.1.2.3.4.5.6.7.8.9.1'
+    SATISFIES_ANY_TEMPLATE = '2.16.840.1.113883.10.20.28.3.108'
+    SATISFIES_ALL_TEMPLATE = '2.16.840.1.113883.10.20.28.3.109'
+    def extract_definition_from_template_or_type
+      # Try to determine what kind of data criteria we are dealing with
+      # First we look for a template id and if we find one just use the definition
+      # status and negation associated with that
+      # If no template id or not one we recognize then try to determine type from
+      # the definition element
+      extract_definition_from_type unless extract_definition_from_template_id
+    end
+
+    #  Given a template id, derive (if available) the definition for the template.
+    #  The definitions are stored in hqmf-model/data_criteria.json.
+    def extract_definition_from_template_id
+      found = false
+
+      @template_ids.each do |template_id|
+        defs = HQMF::DataCriteria.definition_for_template_id(template_id, 'r2')
+        if defs
+          @definition = defs['definition']
+          @status = defs['status'].length > 0 ? defs['status'] : nil
+          found ||= true
+        else
+          found ||= handle_known_template_id(template_id)
+        end
+      end
+
+      found
+    end
+
+    # Given a template id, modify the variables inside this data criteria to reflect the template
+    def handle_known_template_id(template_id)
+      case template_id
+      when VARIABLE_TEMPLATE
+        @derivation_operator = HQMF::DataCriteria::INTERSECT if @derivation_operator == HQMF::DataCriteria::XPRODUCT
+        @definition ||= 'derived'
+        @variable = true
+        @negation = false
+      when SATISFIES_ANY_TEMPLATE
+        @definition = HQMF::DataCriteria::SATISFIES_ANY
+        @negation = false
+      when SATISFIES_ALL_TEMPLATE
+        @definition = HQMF::DataCriteria::SATISFIES_ALL
+        @derivation_operator = HQMF::DataCriteria::INTERSECT
+        @negation = false
+      else
+        return false
+      end
+      true
+    end
+
+    # Extract the definition (sometimes status, sometimes other elements) of the data criteria based on the type
+    def extract_definition_from_type
+      # If we have a specific occurrence of a variable, pull attributes from the reference.
+      # IDEA set this up to be called from dc_specific_and_source_extract, the number of
+      #  fields changed by handle_specific_variable_ref may pose an issue.
+      extract_information_for_specific_variable if @variable && @specific_occurrence
+
+      if @entry.at_xpath('./cda:grouperCriteria')
+        @definition ||= 'derived'
+        return
+      end
+      # See if we can find a match for the entry definition value and status.
+      entry_type = attr_val('./*/cda:definition/*/cda:id/@extension')
+      handle_entry_type(entry_type)
+    end
+
+    # Extracts information from a reference for a specific
+    def extract_information_for_specific_variable
+      reference = @entry.at_xpath('./*/cda:outboundRelationship/cda:criteriaReference',
+                                  HQMF2::Document::NAMESPACES)
+      if reference
+        ref_id = strip_tokens(
+          "#{HQMF2::Utilities.attr_val(reference, 'cda:id/@extension')}_#{HQMF2::Utilities.attr_val(reference, 'cda:id/@root')}")
+      end
+      reference_criteria = @data_criteria_references[ref_id] if ref_id
+      # if the reference is derived, pull from the original variable
+      if reference_criteria && reference_criteria.definition == 'derived'
+        reference_criteria = @data_criteria_references["GROUP_#{ref_id}"]
+      end
+      return unless reference_criteria
+      handle_specific_variable_ref(reference_criteria)
+    end
+
+    # Apply additional information to a specific occurrence's elements from the criteria it references.
+    def handle_specific_variable_ref(reference_criteria)
+      # if there are no referenced children, then it's a variable representing
+      # a single data criteria, so just reference it
+      if reference_criteria.children_criteria.empty?
+        @children_criteria = [reference_criteria.id]
+      # otherwise pull all the data criteria info from the reference
+      else
+        @field_values = reference_criteria.field_values
+        @temporal_references = reference_criteria.temporal_references
+        @subset_operators = reference_criteria.subset_operators
+        @derivation_operator = reference_criteria.derivation_operator
+        @definition = reference_criteria.definition
+        @description = reference_criteria.description
+        @status = reference_criteria.status
+        @children_criteria = reference_criteria.children_criteria
+      end
+    end
+
+    # Generate the definition and/or status from the entry type in most cases.
+    # If the entry type is nil, and the value is a specific occurrence, more parsing may be necessary.
+    def handle_entry_type(entry_type)
+      # settings is required to trigger exceptions, which set the definition
+      HQMF::DataCriteria.get_settings_for_definition(entry_type, @status)
+      @definition = entry_type
+    rescue
+      # if no exact match then try a string match just using entry definition value
+      case entry_type
+      when 'Medication', 'Medications'
+        @definition = 'medication'
+        @status = 'active' unless @status
+      when 'RX'
+        @definition = 'medication'
+        @status = 'dispensed' unless @status
+      when nil
+        definition_for_nil_entry
+      else
+        @definition = extract_definition_from_entry_type(entry_type)
+      end
+    end
+
+    # If there is no entry type, extract the entry type from what it references, and extract additional information for
+    # specific occurrences. If there are no outbound references, print an error and mark it as variable.
+    def definition_for_nil_entry
+      reference = @entry.at_xpath('./*/cda:outboundRelationship/cda:criteriaReference', HQMF2::Document::NAMESPACES)
+      ref_id = nil
+      unless reference.nil?
+        ref_id = "#{HQMF2::Utilities.attr_val(reference, 'cda:id/@extension')}_#{HQMF2::Utilities.attr_val(reference, 'cda:id/@root')}"
+      end
+      reference_criteria = @data_criteria_references[strip_tokens(ref_id)] unless ref_id.nil?
+      if reference_criteria
+        # we only want to copy the reference criteria definition, status, and code_list_id if this is this is not a grouping criteria (i.e., there are no children)
+        if @children_criteria.blank?
+          @definition = reference_criteria.definition
+          @status = reference_criteria.status
+          if @specific_occurrence
+            @title = reference_criteria.title
+            @description = reference_criteria.description
+            @code_list_id = reference_criteria.code_list_id
+          end
+        else
+          # if this is a grouping data criteria (has children) mark it as derived and only pull title and description from the reference criteria
+          @definition = 'derived'
+          if @specific_occurrence
+            @title = reference_criteria.title
+            @description = reference_criteria.description
+          end
+        end
+      else
+        puts "MISSING_DC_REF: #{ref_id}" unless @variable
+        @definition = 'variable'
+      end
+    end
+
+    # Given an entry type (which describes the criteria's purpose) return the appropriate defintino
+    def extract_definition_from_entry_type(entry_type)
+      case entry_type
+      when 'Problem', 'Problems'
+        'diagnosis'
+      when 'Encounter', 'Encounters'
+        'encounter'
+      when 'LabResults', 'Results'
+        'laboratory_test'
+      when 'Procedure', 'Procedures'
+        'procedure'
+      when 'Demographics'
+        definition_for_demographic
+      when 'Derived'
+        'derived'
+      else
+        fail "Unknown data criteria template identifier [#{entry_type}]"
+      end
+    end
+
+    # Return the definition for a known subset of patient characteristics
+    def definition_for_demographic
+      demographic_type = attr_val('./cda:observationCriteria/cda:code/@code')
+      demographic_translation = {
+        '21112-8' => 'patient_characteristic_birthdate',
+        '424144002' => 'patient_characteristic_age',
+        '263495000' => 'patient_characteristic_gender',
+        '102902016' => 'patient_characteristic_languages',
+        '125680007' => 'patient_characteristic_marital_status',
+        '103579009' => 'patient_characteristic_race'
+      }
+      if demographic_translation[demographic_type]
+        demographic_translation[demographic_type]
+      else
+        fail "Unknown demographic identifier [#{demographic_type}]"
+      end
+    end
+  end
+end

data/lib/hqmf-parser/2.0/data_criteria_helpers/dc_post_processing.rb

@@ -0,0 +1,85 @@
+module HQMF2
+  # Processing on data criteria after the initial extractions have taken place
+  module DataCriteriaPostProcessing
+    # Handles settings values after (most) values have been setup
+    def post_processing
+      extract_code_list_path_and_result_value
+
+      # prefix ids that start with numerical values, and strip tokens from others
+      @id = strip_tokens(@id)
+      @children_criteria.map! { |cc| strip_tokens(cc) }
+
+      # append "_source" to the criteria since all the source criteria are separated from the non-source with the "_source" identifier
+      # "_source" is added to the SDC ids so that we are not duplicating ids between source and non source data criteria lists
+      # the derived source data criteria maintain their original ids since they are duplicated in the data criteria and source data criteria lists from the simple xml
+      @source_data_criteria = "#{@id}_source" unless (@definition == 'derived' || @definition == 'satisfies_all' || @definition == 'satisfies_any')
+      @source_data_criteria = strip_tokens(@source_data_criteria) unless @source_data_criteria.nil?
+      @specific_occurrence_const = strip_tokens(@specific_occurrence_const) unless @specific_occurrence_const.nil?
+      change_xproduct_to_intersection
+      handle_derived_specific_occurrences
+    end
+
+    # Extract the code_list_xpath and the criteria's value from either the location related to the specific occurrence,
+    # or from any of the template ids (if multiple exist)
+    def extract_code_list_path_and_result_value
+      if @template_ids.empty? && @specific_occurrence
+        template = @entry.document.at_xpath(
+          "//cda:id[@root='#{@source_data_criteria_root}' and @extension='#{@source_data_criteria_extension}']/../cda:templateId/cda:item/@root")
+        if template
+          mapping = ValueSetHelper.get_mapping_for_template(template.to_s)
+          handle_mapping_template(mapping)
+        end
+      end
+      @template_ids.each do |t|
+        mapping = ValueSetHelper.get_mapping_for_template(t)
+        handle_mapping_template(mapping)
+        break if mapping # quit if one template id with a mapping has set these values
+      end
+    end
+
+    # Set the value and code_list_xpath using the template mapping held in the ValueSetHelper class
+    def handle_mapping_template(mapping)
+      if mapping
+        if mapping[:valueset_path] && @entry.at_xpath(mapping[:valueset_path])
+          @code_list_xpath = mapping[:valueset_path]
+        end
+        @value = DataCriteriaMethods.parse_value(@entry, mapping[:result_path]) if mapping[:result_path]
+      end
+    end
+
+    # Changes XPRODUCT data criteria that has an associated tempalte(s) to an INTERSETION criteria.
+    # UNION is used for all other cases.
+    def change_xproduct_to_intersection
+      # Need to handle grouper criteria that do not have template ids -- these will be union of and intersection
+      # criteria
+      return unless @template_ids.empty?
+      # Change the XPRODUCT to an INTERSECT otherwise leave it as a UNION
+      @derivation_operator = HQMF::DataCriteria::INTERSECT if @derivation_operator == HQMF::DataCriteria::XPRODUCT
+      @description ||= (@derivation_operator == HQMF::DataCriteria::INTERSECT) ? 'Intersect' : 'Union'
+    end
+
+    # Apply some elements from the reference_criteria to the derived specific occurrence
+    def handle_derived_specific_occurrences
+      return unless @definition == 'derived'
+
+      # remove "_source" from source data critera. It gets added in in SpecificOccurrenceAndSource but
+      # when it gets added we have not yet determined the definition of the data criteria so we cannot
+      # skip adding it.  Determining the definition before SpecificOccurrenceAndSource processes doesn't
+      # work because we need to know if it is a specific occurrence to be able to figure out the definition
+      @source_data_criteria = @source_data_criteria.gsub("_source",'') if @source_data_criteria
+
+      # Adds a child if none exists (specifically the source criteria)
+      @children_criteria << @source_data_criteria if @children_criteria.empty?
+      return if @children_criteria.length != 1 ||
+                (@source_data_criteria.present? && @children_criteria.first != @source_data_criteria)
+      # if child.first is nil, it will be caught in the second statement
+      reference_criteria = @data_criteria_references[@children_criteria.first]
+      return if reference_criteria.nil?
+      @is_derived_specific_occurrence_variable = true # easier to track than all testing all features of these cases
+      @subset_operators ||= reference_criteria.subset_operators
+      @derivation_operator ||= reference_criteria.derivation_operator
+      @description = reference_criteria.description
+      @variable = reference_criteria.variable
+    end
+  end
+end

data/lib/hqmf-parser/2.0/data_criteria_helpers/dc_specific_occurrences_and_source_data_criteria_extract.rb

@@ -0,0 +1,117 @@
+module HQMF2
+  # Handles various tasks that the Data Criteria needs performed to obtain and
+  # modify secific occurrences
+  class SpecificOccurrenceAndSource
+    include HQMF2::Utilities
+
+    def initialize(entry, id, local_variable_name, data_criteria_references, occurrences_map)
+      @entry = entry
+      @id = id
+      @local_variable_name = local_variable_name
+      @occurrences_map = occurrences_map
+      @is_variable = DataCriteriaMethods.extract_variable(@local_variable_name, @id)
+      @data_criteria_references = data_criteria_references
+    end
+
+    # Retrieve the specific occurrence and source data criteria information (or just source if there is no specific)
+    def extract_specific_occurrences_and_source_data_criteria
+      specific_def = @entry.at_xpath('./*/cda:outboundRelationship[@typeCode="OCCR"]', HQMF2::Document::NAMESPACES)
+      source_def = @entry.at_xpath('./*/cda:outboundRelationship[cda:subsetCode/@code="SOURCE"]',
+                                   HQMF2::Document::NAMESPACES)
+      if specific_def
+        source_data_criteria_extension = HQMF2::Utilities.attr_val(specific_def,
+                                                                   './cda:criteriaReference/cda:id/@extension')
+        source_data_criteria_root = HQMF2::Utilities.attr_val(specific_def, './cda:criteriaReference/cda:id/@root')
+
+        occurrence_criteria = @data_criteria_references[strip_tokens("#{source_data_criteria_extension}_#{source_data_criteria_root}")]
+
+        return if occurrence_criteria.nil?
+        specific_occurrence_const = HQMF2::Utilities.attr_val(specific_def,
+                                                              './cda:localVariableName/@controlInformationRoot')
+        specific_occurrence = HQMF2::Utilities.attr_val(specific_def,
+                                                        './cda:localVariableName/@controlInformationExtension')
+
+        # FIXME: Remove debug statements after cleaning up occurrence handling
+        # build regex for extracting alpha-index of specific occurrences
+        occurrence_identifier = obtain_occurrence_identifier(strip_tokens(@id),
+                                                             strip_tokens(@local_variable_name) || '',
+                                                             strip_tokens(source_data_criteria_extension),
+                                                             @is_variable)
+
+        handle_specific_and_source(occurrence_identifier, source_data_criteria_extension, source_data_criteria_root,
+                                   specific_occurrence_const, specific_occurrence)
+
+      elsif source_def
+        extension = HQMF2::Utilities.attr_val(source_def, './cda:criteriaReference/cda:id/@extension')
+        root = HQMF2::Utilities.attr_val(source_def, './cda:criteriaReference/cda:id/@root')
+        ["#{extension}_#{root}_source", root, extension] # return the soruce data criteria itself, the rest will be blank
+      end
+    end
+
+    # Handle setting the specific and source instance variables with a given occurrence identifier
+    def handle_specific_and_source(occurrence_identifier, source_data_criteria_extension, source_data_criteria_root,
+                                   specific_occurrence_const, specific_occurrence)
+      source_data_criteria = "#{source_data_criteria_extension}_#{source_data_criteria_root}_source"
+      if !occurrence_identifier.blank?
+        # if it doesn't exist, add extracted occurrence to the map
+        # puts "\tSetting #{@source_data_criteria}-#{@source_data_criteria_root} to #{occurrence_identifier}"
+        @occurrences_map[strip_tokens(source_data_criteria)] ||= occurrence_identifier
+        specific_occurrence ||= occurrence_identifier
+        specific_occurrence_const = "#{source_data_criteria}".upcase
+      else
+        # create variable occurrences that do not already exist
+        if @is_variable
+          # puts "\tSetting #{@source_data_criteria}-#{@source_data_criteria_root} to #{occurrence_identifier}"
+          @occurrences_map[strip_tokens(source_data_criteria)] ||= occurrence_identifier
+        end
+        occurrence = @occurrences_map.try(:[], strip_tokens(source_data_criteria))
+        unless occurrence
+          fail "Could not find occurrence mapping for #{source_data_criteria}, #{source_data_criteria_root}"
+        end
+        # puts "\tUsing #{occurrence} for #{@id}"
+        specific_occurrence ||= occurrence
+      end
+
+      specific_occurrence = 'A' unless specific_occurrence
+      specific_occurrence_const = source_data_criteria.upcase unless specific_occurrence_const
+      [source_data_criteria, source_data_criteria_root, source_data_criteria_extension,
+       specific_occurrence, specific_occurrence_const]
+    end
+
+    # Using the id, source data criteria id, and local variable name (and whether or not it's a variable),
+    #  extract the occurrence identifiter (if one exists).
+    def obtain_occurrence_identifier(stripped_id, stripped_lvn, stripped_sdc, is_variable)
+      if is_variable || (stripped_sdc.include? 'qdm_var')
+        occurrence_lvn_regex = 'occ[A-Z]of_qdm_var'
+        occurrence_id_regex = 'occ[A-Z]of_qdm_var'
+        occ_index = 3
+        return handle_occurrence_var(stripped_id, stripped_lvn, stripped_sdc, occurrence_id_regex, occurrence_lvn_regex, occ_index)
+      else
+        occurrence_lvn_regex = 'Occurrence[A-Z]of'
+        occurrence_id_regex = 'Occurrence[A-Z]_'
+        occ_index = 10
+
+        occurrence_identifier = handle_occurrence_var(
+          stripped_id, stripped_lvn, stripped_sdc,
+          "#{occurrence_id_regex}#{stripped_sdc}", "#{occurrence_lvn_regex}#{stripped_sdc}",
+          occ_index)
+        return occurrence_identifier if occurrence_identifier.present?
+
+        stripped_sdc[occ_index] if stripped_sdc.match(
+          /(^#{occurrence_id_regex}| ^#{occurrence_id_regex}qdm_var_| ^#{occurrence_lvn_regex})| ^#{occurrence_lvn_regex}qdm_var_/)
+      end
+    end
+
+    # If the occurrence is a variable, extract the occurrence identifier (if present)
+    def handle_occurrence_var(stripped_id, stripped_lvn, stripped_sdc, occurrence_id_compare, occurrence_lvn_compare, occ_index)
+      # TODO: Handle specific occurrences of variables that don't self-reference?
+      if stripped_id.match(/^#{occurrence_id_compare}/)
+        return stripped_id[occ_index]
+      elsif stripped_lvn.match(/^#{occurrence_lvn_compare}/)
+        return stripped_lvn[occ_index]
+      elsif stripped_sdc.match(/^#{occurrence_id_compare}/)
+        return stripped_sdc[occ_index]
+      end
+    end
+  end
+end