health-data-standards 0.3.0 → 0.5.0

data/lib/health-data-standards/import/c32/patient_importer.rb

@@ -0,0 +1,139 @@
+module HealthDataStandards
+  module Import
+    module C32
+
+      # This class is the central location for taking a HITSP C32 XML document and converting it
+      # into the processed form we store in MongoDB. The class does this by running each measure
+      # independently on the XML document
+      #
+      # This class is a Singleton. It should be accessed by calling PatientImporter.instance
+      class PatientImporter
+
+        include Singleton
+        include HealthDataStandards::Util
+
+        # Creates a new PatientImporter with the following XPath expressions used to find content in 
+        # a HITSP C32:
+        #
+        # Encounter entries
+        #    //cda:section[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.127']/cda:entry/cda:encounter
+        #
+        # Procedure entries
+        #    //cda:procedure[cda:templateId/@root='2.16.840.1.113883.10.20.1.29']
+        #
+        # Result entries - There seems to be some confusion around the correct templateId, so the code checks for both
+        #    //cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.15.1'] | //cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.15']
+        #
+        # Vital sign entries
+        #    //cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.14']
+        #
+        # Medication entries
+        #    //cda:section[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.112']/cda:entry/cda:substanceAdministration
+        #
+        # Codes for medications are found in the substanceAdministration with the following relative XPath
+        #    ./cda:consumable/cda:manufacturedProduct/cda:manufacturedMaterial/cda:code
+        #
+        # Condition entries
+        #    //cda:section[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.103']/cda:entry/cda:act/cda:entryRelationship/cda:observation
+        #
+        # Codes for conditions are determined by examining the value child element as opposed to the code child element
+        #
+        # Social History entries (non-C32 section, specified in the HL7 CCD)
+        #    //cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.19']
+        #
+        # Care Goal entries(non-C32 section, specified in the HL7 CCD)
+        #    //cda:observation[cda:templateId/@root='2.16.840.1.113883.10.20.1.25']
+        #
+        # Allergy entries
+        #    //cda:observation[cda:templateId/@root='2.16.840.1.113883.10.20.1.18']
+        #
+        # Immunization entries
+        #    //cda:substanceAdministration[cda:templateId/@root='2.16.840.1.113883.10.20.1.24']
+        #
+        # Codes for immunizations are found in the substanceAdministration with the following relative XPath
+        #    ./cda:consumable/cda:manufacturedProduct/cda:manufacturedMaterial/cda:code
+        def initialize(check_usable = true)
+          @section_importers = {}
+          @section_importers[:encounters] = EncounterImporter.new
+          @section_importers[:procedures] = ProcedureImporter.new
+          @section_importers[:results] = ResultImporter.new
+          @section_importers[:vital_signs] = VitalSignImporter.new
+          @section_importers[:medications] = MedicationImporter.new
+          @section_importers[:conditions] = SectionImporter.new("//cda:section[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.103']/cda:entry/cda:act/cda:entryRelationship/cda:observation",
+          "./cda:value",
+          "./cda:entryRelationship/cda:observation[cda:templateId/@root='2.16.840.1.1 13883.10.20.1.50']/cda:value",
+          "./cda:text/cda:reference[@value]")
+          @section_importers[:social_history] = SectionImporter.new("//cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.19']")
+          @section_importers[:care_goals] = SectionImporter.new("//cda:observation[cda:templateId/@root='2.16.840.1.113883.10.20.1.25']")
+          @section_importers[:medical_equipment] = SectionImporter.new("//cda:section[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.128']/cda:entry/cda:supply",
+          "./cda:participant/cda:participantRole/cda:playingDevice/cda:code")
+          @section_importers[:allergies] = AllergyImporter.new
+          @section_importers[:immunizations] = ImmunizationImporter.new
+        end
+
+        def build_id_map(doc)
+          id_map = {}
+          path = "//*[@ID]"
+          ids = doc.xpath(path)
+          ids.each do |id|
+            tag = id['ID']
+            value = id.content
+            id_map[tag] = value
+          end
+
+          id_map
+        end
+
+        # @param [boolean] value for check_usable_entries...importer uses true, stats uses false 
+        def check_usable(check_usable_entries)
+          @section_importers.each_pair do |section, importer|
+            importer.check_for_usable = check_usable_entries
+          end
+        end
+
+        # Parses a HITSP C32 document and returns a Hash of of the patient.
+        #
+        # @param [Nokogiri::XML::Document] doc It is expected that the root node of this document
+        #        will have the "cda" namespace registered to "urn:hl7-org:v3"
+        # @return [Record] a Mongoid model representing the patient
+        def parse_c32(doc)
+          c32_patient = Record.new
+          get_demographics(c32_patient, doc)
+          create_c32_hash(c32_patient, doc)
+          
+          c32_patient
+        end
+
+        # Create a simple representation of the patient from a HITSP C32
+        # @param [Record] record Mongoid model to append the Entry objects to
+        # @param [Nokogiri::XML::Document] doc It is expected that the root node of this document
+        #        will have the "cda" namespace registered to "urn:hl7-org:v3"
+        # @return [Hash] a represnetation of the patient with symbols as keys for each section
+        def create_c32_hash(record, doc)
+          id_map = build_id_map(doc)
+          @section_importers.each_pair do |section, importer|
+            record.send(section.to_setter, importer.create_entries(doc, id_map))
+          end
+        end
+
+        # Inspects a C32 document and populates the patient Hash with first name, last name
+        # birth date and gender.
+        #
+        # @param [Hash] patient A hash that is used to represent the patient
+        # @param [Nokogiri::XML::Node] doc The C32 document parsed by Nokogiri
+        def get_demographics(patient, doc)
+          patient_element = doc.at_xpath('/cda:ClinicalDocument/cda:recordTarget/cda:patientRole/cda:patient')
+          patient.first = patient_element.at_xpath('cda:name/cda:given').text
+          patient.last = patient_element.at_xpath('cda:name/cda:family').text
+          birthdate_in_hl7ts_node = patient_element.at_xpath('cda:birthTime')
+          birthdate_in_hl7ts = birthdate_in_hl7ts_node['value']
+          patient.birthdate = HL7Helper.timestamp_to_integer(birthdate_in_hl7ts)
+          gender_node = patient_element.at_xpath('cda:administrativeGenderCode')
+          patient.gender = gender_node['code']
+          id_node = doc.at_xpath('/cda:ClinicalDocument/cda:recordTarget/cda:patientRole/cda:id')
+          patient.medical_record_number = id_node['extension']
+        end
+      end
+    end
+  end
+end

data/lib/health-data-standards/import/c32/procedure_importer.rb

@@ -0,0 +1,55 @@
+module HealthDataStandards
+  module Import
+    module C32
+
+      # TODO Extract Discharge Disposition
+      class ProcedureImporter < SectionImporter
+
+        def initialize
+          @entry_xpath = "//cda:procedure[cda:templateId/@root='2.16.840.1.113883.10.20.1.29']"
+          @code_xpath = "./cda:code"
+          @status_xpath = "./cda:statusCode"
+          @description_xpath = "./cda:code/cda:originalText/cda:reference[@value] | ./cda:text/cda:reference[@value] "
+          @check_for_usable = true               # Pilot tools will set this to false
+        end
+
+        # Traverses that HITSP C32 document passed in using XPath and creates an Array of Entry
+        # objects based on what it finds                          
+        # @param [Nokogiri::XML::Document] doc It is expected that the root node of this document
+        #        will have the "cda" namespace registered to "urn:hl7-org:v3"
+        #        measure definition
+        # @return [Array] will be a list of Entry objects
+        def create_entries(doc,id_map = {})
+          procedure_list = []
+          entry_elements = doc.xpath(@entry_xpath)
+          entry_elements.each do |entry_element|
+            procedure = Procedure.new
+            extract_codes(entry_element, procedure)
+            extract_dates(entry_element, procedure)
+            extract_description(entry_element, procedure, id_map)
+            if @check_for_usable
+              procedure_list << procedure if procedure.usable?
+            else
+              procedure_list << procedure
+            end
+            extract_performer(entry_element, procedure)
+            extract_site(entry_element, procedure)
+          end
+          procedure_list
+        end
+
+        private
+
+        def extract_performer(parent_element, procedure)
+          performer_element = parent_element.at_xpath("./cda:performer")
+          procedure.performer = import_actor(performer_element) if performer_element
+        end
+
+        def extract_site(parent_element, procedure)
+          procedure.site = extract_code(parent_element, "./cda:targetSiteCode")
+        end
+
+      end
+    end
+  end
+end

data/lib/health-data-standards/import/c32/result_importer.rb

@@ -0,0 +1,58 @@
+module HealthDataStandards
+  module Import
+    module C32
+      class ResultImporter < SectionImporter
+        def initialize
+          @entry_xpath = "//cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.15.1'] | //cda:observation[cda:templateId/@root='2.16.840.1.113883.3.88.11.83.15']"
+          @code_xpath = "./cda:code"
+          @status_xpath = "./cda:statusCode"
+          @description_xpath = "./cda:code/cda:originalText/cda:reference[@value] | ./cda:text/cda:reference[@value] "
+          @check_for_usable = true               # Pilot tools will set this to false
+        end
+    
+        # Traverses that HITSP C32 document passed in using XPath and creates an Array of Entry
+        # objects based on what it finds                          
+        # @param [Nokogiri::XML::Document] doc It is expected that the root node of this document
+        #        will have the "cda" namespace registered to "urn:hl7-org:v3"
+        #        measure definition
+        # @return [Array] will be a list of Entry objects
+        def create_entries(doc,id_map = {})
+          result_list = []
+          entry_elements = doc.xpath(@entry_xpath)
+          entry_elements.each do |entry_element|
+            result = LabResult.new
+            extract_codes(entry_element, result)
+            extract_dates(entry_element, result)
+            extract_value(entry_element, result)
+            extract_status(entry_element, result)
+            extract_description(entry_element, result, id_map)
+            extract_interpretation(entry_element, result)
+            if @check_for_usable
+              result_list << result if result.usable?
+            else
+              result_list << result
+            end
+          end
+          result_list
+        end
+    
+        private
+        def extract_interpretation(parent_element, result)
+          interpretation_element = parent_element.at_xpath("./cda:interpretationCode")
+          if interpretation_element
+            code = interpretation_element['code']
+            code_system = CodeSystemHelper.code_system_for(interpretation_element['codeSystem'])
+            result.interpretation = {'code' => code, 'codeSystem' => code_system}
+          end
+        end
+    
+        def extract_status(parent_element, result)
+          status_code_element = parent_element.at_xpath(@status_xpath)
+          if status_code_element
+            result.status = status_code_element['code']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/health-data-standards/import/c32/section_importer.rb

@@ -0,0 +1,214 @@
+module HealthDataStandards
+  module Import
+    module C32
+      # Class that can be used to create an importer for a section of a HITSP C32 document. It usually
+      # operates by selecting all CDA entries in a section and then creates entries for them.
+      class SectionImporter
+        include HealthDataStandards::Util
+        
+        attr_accessor :check_for_usable
+        # Creates a new SectionImporter
+        # @param [Hash] id_map A hash of all ID tags to values for the enclosing document.  Used to look up descriptions.
+        # @param [String] entry_xpath An XPath expression that can be used to find the desired entries
+        # @param [String] code_xpath XPath expression to find the code element as a child of the desired CDA entry.
+        #        Defaults to "./cda:code"
+        # @param [String] status_xpath XPath expression to find the status element as a child of the desired CDA
+        #        entry. Defaults to nil. If not provided, a status will not be checked for since it is not applicable
+        #        to all enrty types
+        def initialize(entry_xpath, code_xpath="./cda:code", status_xpath=nil, description_xpath="./cda:code/cda:originalText/cda:reference[@value] | ./cda:text/cda:reference[@value] ")
+          @entry_xpath = entry_xpath
+          @code_xpath = code_xpath
+          @status_xpath = status_xpath
+          @description_xpath = description_xpath
+          @check_for_usable = true               # Pilot tools will set this to false
+        end
+
+        # @param [String] tag
+        # @param [Hash] id_map A map of ids to all tagged text in the narrative portion of a document
+        # @return [String] text description of tag
+        def lookup_tag(tag, id_map)
+           value = id_map[tag]
+           # Not sure why, but sometimes the reference is #<Reference> and the ID value is <Reference>, and 
+           # sometimes it is #<Reference>.  We look for both.
+           if !value and tag[0] == '#'  
+             tag = tag[1,tag.length]
+             value = id_map[tag]
+           end
+
+           value
+         end
+
+        # Traverses that HITSP C32 document passed in using XPath and creates an Array of Entry
+        # objects based on what it finds                          
+        # @param [Nokogiri::XML::Document] doc It is expected that the root node of this document
+        #        will have the "cda" namespace registered to "urn:hl7-org:v3"
+        #        measure definition
+        # @return [Array] will be a list of Entry objects
+        def create_entries(doc,id_map = {})
+          entry_list = []
+          entry_elements = doc.xpath(@entry_xpath)
+          entry_elements.each do |entry_element|
+            entry = Entry.new
+            extract_codes(entry_element, entry)
+            extract_dates(entry_element, entry)
+            extract_value(entry_element, entry)
+            if @status_xpath
+              extract_status(entry_element, entry)
+            end
+            if @description_xpath
+              extract_description(entry_element, entry, id_map)
+            end
+            if @check_for_usable
+              entry_list << entry if entry.usable?
+            else
+              entry_list << entry
+            end
+          end
+          entry_list
+        end
+
+        private
+
+        def extract_status(parent_element, entry)
+          status_element = parent_element.at_xpath(@status_xpath)
+          if status_element
+            case status_element['code']
+            when '55561003'
+              entry.status = :active
+            when '73425007'
+              entry.status = :inactive
+            when '413322009'      
+              entry.status = :resolved
+            end
+          end
+        end
+
+        def extract_description(parent_element, entry, id_map)
+          code_elements = parent_element.xpath(@description_xpath)
+          code_elements.each do |code_element|
+            tag = code_element['value']
+            entry.description = lookup_tag(tag, id_map)
+          end
+        end
+
+        def extract_codes(parent_element, entry)
+          code_elements = parent_element.xpath(@code_xpath)
+          code_elements.each do |code_element|
+            add_code_if_present(code_element, entry)
+            translations = code_element.xpath('cda:translation')
+            translations.each do |translation|
+              add_code_if_present(translation, entry)
+            end
+          end
+        end
+
+        def add_code_if_present(code_element, entry)
+          if code_element['codeSystem'] && code_element['code']
+            entry.add_code(code_element['code'], CodeSystemHelper.code_system_for(code_element['codeSystem']))
+          end
+        end
+
+        def extract_dates(parent_element, entry)
+          if parent_element.at_xpath('cda:effectiveTime')
+            entry.time = HL7Helper.timestamp_to_integer(parent_element.at_xpath('cda:effectiveTime')['value'])
+          end
+          if parent_element.at_xpath('cda:effectiveTime/cda:low')
+            entry.start_time = HL7Helper.timestamp_to_integer(parent_element.at_xpath('cda:effectiveTime/cda:low')['value'])
+          end
+          if parent_element.at_xpath('cda:effectiveTime/cda:high')
+            entry.end_time = HL7Helper.timestamp_to_integer(parent_element.at_xpath('cda:effectiveTime/cda:high')['value'])
+          end
+          if parent_element.at_xpath('cda:effectiveTime/cda:center')
+            entry.time = HL7Helper.timestamp_to_integer(parent_element.at_xpath('cda:effectiveTime/cda:center')['value'])
+          end
+        end
+
+        def extract_value(parent_element, entry)
+          value_element = parent_element.at_xpath('cda:value')
+          if value_element
+            value = value_element['value']
+            unit = value_element['unit']
+            if value
+              entry.set_value(value, unit)
+            end
+          end
+        end
+        
+        def import_actor(actor_element)
+          actor_hash = {}
+          addresses = actor_element.xpath("./cda:assignedEntity/cda:addr").try(:map) {|ae| import_address(ae)}
+          telecoms = actor_element.xpath("./cda:assignedEntity/cda:telecom").try(:map) {|te| import_telecom(te)}
+          person_element = actor_element.at_xpath("./cda:assignedEntity/cda:assignedPerson")
+          if person_element
+            actor_hash['person'] = import_person(person_element)
+            actor_hash['person']['addresses'] = addresses
+            actor_hash['person']['telecoms'] = telecoms
+          end
+          organization_element = actor_element.at_xpath("./cda:assignedEntity/cda:assignedOrganization")
+          if organization_element
+            actor_hash['organization'] = import_organization(organization_element)
+          end
+
+          actor_hash
+        end
+
+        def import_person(person_element)
+          person_hash = {}
+          name_element = person_element.at_xpath("./cda:name")
+          person_hash['name'] = name_element.try(:text)
+          person_hash['first'] = name_element.at_xpath("./cda:given").try(:text)
+          person_hash['last'] = name_element.at_xpath("./cda:family").try(:text)
+          person_hash
+        end
+
+        def import_address(address_element)
+          address_hash = {}
+          address_hash['streetAddress'] = [address_element.at_xpath("./cda:streetAddressLine").try(:text)]
+          address_hash['city'] = address_element.at_xpath("./cda:city").try(:text)
+          address_hash['stateOrProvince'] = address_element.at_xpath("./cda:state").try(:text)
+          address_hash['zip'] = address_element.at_xpath("./cda:postalCode").try(:text)
+          address_hash['country'] = address_element.at_xpath("./cda:country").try(:text)
+          address_hash
+        end
+
+        def import_telecom(telecom_element)
+          telecom_hash = {}
+          telecom_hash['value'] = telecom_element['value']
+          telecom_hash['use'] = telecom_element['use']
+          telecom_hash
+        end
+
+        def import_organization
+          # TODO: Implement when the Patient API has an implementation of
+          # organization
+        end
+
+        def extract_code(parent_element, code_xpath, code_system=nil)
+          code_element = parent_element.at_xpath(code_xpath)
+          code_hash = nil
+          if code_element
+            code_hash = {'code' => code_element['code']}
+            if code_system
+              code_hash['codeSystem'] = code_system
+            else
+              code_hash['codeSystemOid'] = code_element['codeSystem']
+              code_hash['codeSystem'] = CodeSystemHelper.code_system_for(code_hash['codeSystemOid'])
+            end
+          end
+
+          code_hash
+        end
+
+        def extract_scalar(parent_element, scalar_xpath)
+          scalar_element = parent_element.at_xpath(scalar_xpath)
+          if scalar_element
+            {'unit' => scalar_element['unit'], 'value' => scalar_element['value'].to_i}
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end
+