laika-developer Mailing List for LAIKA: EHR Testing Framework

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Hi,

I've been meaning to post an overview of the changes I've been making to
the Laika validator.  These changes aren't in the master branch yet, but
you can check them out in the generate-format-component-dsl branch of
the opensourcery/laika repo on Github:

http://github.com/opensourcery/laika/tree/generate-format-component-dsl

Originally I believe the validator logic was scattered through the Laika
Rails models themselves as a series of validate_c32() methods.  At some
point it was decided to begin separating that code into its own library.
The validate_c32 methods were moved into a series of modules which were
re-injected into the model classes at validation time and driven through
a main lib/validation.rb library that provided an abstraction for a
handle on a Validator object.

So to validate a GenerateAndFormatPlan you might:

test_plan = GenerateAndFormatPlan.find(1)
patient = test_plan.patient
document = test_plan.clinical_document.as_xml_document
validator = Validation.get_validator(clinical_document.doc_type)
errors = validator.validate(patient, document)

Under the hood, the validator would run a series of registered
validators for schema, schematron, content and umls validation.  The
content validator, which is the only one we're discussing atm, would
call the patient#validate_c32() method, which would in turn walk all of
its components (languages, medications, etc.) and call their
validate_c32() methods.  For an instance of Allergy this looks like
(from lib/validators/c32/allergy_c32_validation.rb)

def validate_c32(document)
  errors = []
  begin
    section =
XML::XPath.first(document,"//cda:section[cda:templateId[@root =
.16.840.1.113883.10.20.1.2']]", MatchHelper::DEFAULT_NAMESPACES)

...

    adverse_event = REXML::XPath.first(section, xpath,
tchHelper::DEFAULT_NAMESPACES, {"free_text_product" =>
lf.free_text_product})
    if adverse_event
      errors << match_value(adverse_event,
        "cda:effectiveTime/cda:low/@value",
        'start_event',
        self.start_event.try(:to_formatted_s, :brief)
      )
      errors << match_value(adverse_event,
        "cda:effectiveTime/cda:high/@value",
        'end_event',
        self.end_event.try(:to_formatted_s, :brief)
      )
...
    else
      errors << ContentError.new(:section => 'allergies',
        :error_message => "Unable to find product #{free_text_product}",
        :location => section.try(:xpath)
      )
    end
  rescue
    errors << ContentError.new(:section => 'Allergy',
      :error_message => 'Invalid, non-parsable XML for allergy data',
      :type=>'error',
      :location => document.xpath)
  end
  errors.compact
end

This uses REXML to find first the section, then the adverse_event
element of the section.  A helper method match_value() is then used to
check each field.  Each Laika model which validates has some variation
of the above method, a block of similar but unique code that handles all
of the xml identification, lookup, value comparison and ContentError
generation.

The main problem that this left us was that the validator code was still
dependent on the model classes and vice versa.  The laika models and the
validation library were still pretty tightly intertwined.  All of the
validation methods assumed that they could walk deeply into a model to
query dependent objects, and made direct use of the ContentError model
to record issues, for example.  This also had the potential to cause
class reloading issues which we had a lot of trouble with in the
beginning of the year.

So when Ben began discussing upgrades to the Generate and Format test
process, I started looking at ways to finish separating the validator
library.  One of the major requests Ben made had to do with error output
for matching sections.  When Laika failed to match a model section from
a choice of repeating document sections, Ben and Amit wanted to be able
to see the expected section values, and all of the provided sections and
their values.  To introduce this in the existing validator code would
have required touching each validate_c32 method that matched sections
and adding code to store the expected and provided values of the section
on failure.

Instead what I worked on was a new library which would have a general
set of validation routines that could be applied to a set of
descriptions mapping model elements to xml document sections.  Since the
hard work of studying the specifications for element requirements and
xpath expressions to locate the various subsections had already been
done for the most part, what I wanted to do was to extract that
information in as concise a manner as possible into a declaration of
component modules and their subsections and fields, which would provide
the framework around which a validator could iterate.

After a couple months and two main development passes, this is what I
came up with.  There are two new libraries:

lib/component_descriptors.rb
and
lib/validator/c32_validator.rb

The component_descriptors library does most of the work.  It has a
Mapping module which may be included in a specification module to
provide a simple domain language for describing components, sections and
fields of a particular document type.  You can then request a component
definition from your descriptor module (for C32 allergies say) and
attach either a C32 xml document to it or a reference model with
accessors or hash keys matching the fields, and the descriptor library
will extract all of the described values.

lib/validator/c32_descriptors.rb describes all of the currently mapped
C83 components*.  Here is the allergy descriptor:

component :allergies, :template_id => '2.16.840.1.113883.10.20.1.2' do
  repeating_section :allergy => %
q{cda:entry/cda:act[cda:templateId/@root='2.16.840.1.113883.10.20.1.27']/cda:entryRelationship[@typeCode='SUBJ']/cda:observation[cda:templateId/@root='2.16.840.1.113883.10.20.1.18']}, :matches_by => :free_text_product do
    field :free_text_product => %
q{cda:participant[@typeCode='CSM']/cda:participantRole[@classCode='MANU']/cda:playingEntity[@classCode='MMAT']/cda:name/text()}
    field :start_event => %q{cda:effectiveTime/cda:low/@value}
    field :end_event => %q{cda:effectiveTime/cda:high/@value}
    field :product_code => %
q{cda:participant[@typeCode='CSM']/cda:participantRole[@classCode='MANU']/cda:playingEntity[@classCode='MMAT']/cda:code[@codeSystem='2.16.840.1.113883.6.88']/@code}
  end
end

Each entry has a key value and an xpath expression.  The key value is
used to lookup a value in a reference model; the xpath expression is
used to lookup an element or attribute in the xml document.  So you can
do things like:

jpartlow@fook:~/dev/osourcery/elbe/laika$ script/console 
Loading development environment (Rails 2.3.5)

>> descriptors = Validators::C32Descriptors.get_component(:allergies)

>> allergy = Allergy.first  

=> #<Allergy id: 1018745150, start_event: "2005-06-30", end_event: nil,
adverse_event_type_id: 74884154, free_text_product: "iodine",
product_code: "5933", severity_term_id: 125997487, patient_id:
353184192, allergy_status_code_id: 186579971, allergy_type_code_id:
113267946, code_system_id: 150121693>

>> descriptors.model = [allergy]          

>> pp descriptors.to_field_hash

{:free_text_product=>"iodine",
 :start_event=>Thu, 30 Jun 2005,
 :end_event=>nil,
 :product_code=>"5933"}

You could get the same sort of field hash by attaching an xml document
with a C83 Allergy component module.

The c32_validator is a smaller library that handles the actual
validation of a Laika Patient instance with a C32 document.  For every
component module of a Patient, it looks up a Descriptor from
lib/validators/c32_descriptors.rb, and hands it off to a ComponentScope
class with a reference to the Patient model and the C32 xml document.
The ComponentScope validates the current section or field and then walks
down the descriptors descendents, generating new ComponentScope wrappers
for each repeating section, section or field.  If any errors are found,
a Laika::ValidationError is generated.  This set of errors is then given
back to Laika which translates them to ContentErrors and stores them in
the database just as it did with the old validator.

The main benefits I see are:

* The new library is completely decoupled from the Rails application.
All it requires is that it be given an object with accessors or a hash
with keys that honor the contract of section/field keys set up in the
descriptor mapping.
* There is a single path through the validator for any section or field.
If we need to fix something about how sections or fields are obtained or
validated, the code is in one spot.
* Use of an XML library like REXML is limited to a very few calls in
lib/component_descriptors.rb making it very simple to upgrade to a
better XML library like Nokogiri. 
* Additional decorators can be slipped more easily into the system.  The
new library, for example, has logging and can provide detailed logging
output of how it is extracting data, what it is comparing and any
problems it finds.
* Error output is uniform.  Each error condition flows through a single
function producing a SectionNotFound, NoMatchingSection, ComparisonError
or general ValidationError with uniform defaults and parameters.
* The actual mapping between models and xml is concisely described in a
descriptor mapping like c32_descriptors in what is hopefully a pretty
human readable format.
* We can describe other xml documents in addition to the C32; at it's
heart the descriptors are just :section_key =>
"xpath/expression".  :section_keys are the default accessor methods for
a model, but may be overriden with an :accessor => :foo parameter.
* Any component module can be output as a hash of {:field => 'value'},
whether from an attached model or xml document.
* API docs

The next step would be extending the library to handle export (for c32
this is currently a set of to_c32() methods embedded in the models) and
import (provided by Shauni's importer).  Then, with some work on the
configuration process we can move the entire
Laika/descriptor/validator/exporter/importer library into it's own
repository, which Laika can simple depend on and use.

This would provide an independent tool for operating on, validating and
potentially transforming medical documents between any formats the
library had descriptors for.  It should also go a long way towards
cleaning up the Laika application's loading process, helping us out with
class loading and resource issues.

A name for this library would be handy though; 'Laika medical document
import/export/validator thingy' is a bit unwieldy.

That's all I've got for now.  Please let me know if you have any
questions or thoughts about how to approach this.

thanks,
Josh

* Note that not all the C32 was mapped in the original validator, and
the new descriptors have translated most but not all of the old
validator mappings.  Support, information_source, advanced_directive and
telephone numbers in general remain to be done to match the old
validator.  And then whatever additional mapping is desired to capture
further data.

2007	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep	Oct (13)	Nov (18)	Dec (5)
2008	Jan (9)	Feb (5)	Mar (5)	Apr	May (1)	Jun (2)	Jul (2)	Aug	Sep (2)	Oct	Nov (3)	Dec (31)
2009	Jan (31)	Feb (58)	Mar (26)	Apr (16)	May (10)	Jun (13)	Jul (20)	Aug (30)	Sep (32)	Oct (48)	Nov (76)	Dec (16)
2010	Jan (11)	Feb (27)	Mar (14)	Apr (17)	May (6)	Jun (5)	Jul (3)	Aug	Sep	Oct	Nov	Dec

laika-developer Mailing List for LAIKA: EHR Testing Framework

laika-developer — Developer discussions about the Laika framework