ncs_mdes 0.11.0 → 0.12.0

data/lib/ncs_navigator/mdes/transmission_table.rb

@@ -29,10 +29,19 @@ module NcsNavigator::Mdes
     #  table.)
     attr_accessor :variables
 
+    ##
+    # @see #child_instrument_table?
+    # @return [void]
+    attr_writer :child_instrument_table
+
     def initialize(name)
       @name = name
     end
 
+    def variables
+      @variables ||= []
+    end
+
     ##
     # Search for a variable by name.
     #
@@ -110,5 +119,57 @@ module NcsNavigator::Mdes
     def operational_table?
       !instrument_table?
     end
+
+    ##
+    # Is this a child instrument data table? (As opposed to a parent instrument
+    # data table or neither.)
+    #
+    # This reports the type of participant whose p_id should go in this table's
+    # p_id variable.
+    #
+    # Return values:
+    #
+    # * `true`: The p_id should be a child's p_id.
+    # * `false`: The p_id should be a parent's p_id.
+    # * `nil`: The table isn't an instrument data table, or it doesn't have a p_id
+    #   variable, or the childness of the p_id isn't known.
+    #
+    # @return [true,false,nil]
+    def child_instrument_table?
+      @child_instrument_table
+    end
+
+    ##
+    # Is this a parent instrument data table? (As opposed to a child instrument
+    # data table or neither.)
+    #
+    # This reports the type of participant whose p_id should go in this table's
+    # p_id variable.
+    #
+    # Return values:
+    #
+    # * `true`: The p_id should be a parent's p_id.
+    # * `false`: The p_id should be a child's p_id.
+    # * `nil`: The table isn't an instrument data table, or it doesn't have a p_id
+    #   variable, or the childness of the p_id isn't known.
+    #
+    # @return [true,false,nil]
+    def parent_instrument_table?
+      child_instrument_table?.nil? ? nil : !child_instrument_table?
+    end
+
+    # @private
+    DIFF_CRITERIA = {
+      :name => Differences::ValueCriterion.new,
+      :variables => Differences::CollectionCriterion.new(:name)
+    }
+
+    ##
+    # Computes the differences between this table and the other.
+    #
+    # @return [Differences::Entry,nil]
+    def diff(other_table, options={})
+      Differences::Entry.compute(self, other_table, DIFF_CRITERIA, options)
+    end
   end
 end

data/lib/ncs_navigator/mdes/variable.rb

@@ -111,10 +111,6 @@ module NcsNavigator::Mdes
       @name = name
     end
 
-    def constraints
-      @constraints ||= []
-    end
-
     ##
     # Is a value for the variable mandatory for a valid submission?
     #
@@ -205,5 +201,63 @@ module NcsNavigator::Mdes
         end
       end
     end
+
+    # @private
+    class EmbeddedVariableTypeCriterion
+      def apply(vt1, vt2, diff_options)
+        cvt1 = vt1 || VariableType.new
+        cvt2 = vt2 || VariableType.new
+
+
+        if cvt1.name && cvt2.name && cvt1.name == cvt2.name
+          # If they are named and have the same name, the differences will
+          # be reported once under the specification's entry for the named type.
+          nil
+        else
+          cvt1.diff(cvt2, diff_options)
+        end
+      end
+    end
+
+    def diff_criteria(diff_options={})
+      base = {
+        :name       => Differences::ValueCriterion.new,
+        :type       => EmbeddedVariableTypeCriterion.new,
+        :pii        => Differences::ValueCriterion.new,
+        :omittable? => Differences::ValueCriterion.new(:comparator => :predicate),
+        :nillable?  => Differences::ValueCriterion.new(:comparator => :predicate),
+        :table_reference => Differences::ValueCriterion.new(
+          :value_extractor => lambda { |o| o ? o.name : nil }
+        )
+      }
+
+      if diff_options[:strict]
+        base[:status] = Differences::ValueCriterion.new
+      else
+        base[:status] = Differences::ValueCriterion.new(
+          :comparator => lambda { |left, right|
+            no_change_changes = [
+              [:new, :active],
+              [:new, :modified],
+              [:active, :modified],
+              [:modified, :active]
+            ]
+
+            no_change_changes.include?([left, right]) || (left == right)
+          }
+        )
+      end
+
+      base
+    end
+    protected :diff_criteria
+
+    ##
+    # Computes the differences between this variable and the other.
+    #
+    # @return [Differences::Entry,nil]
+    def diff(other_variable, options={})
+      Differences::Entry.compute(self, other_variable, diff_criteria(options), options)
+    end
   end
 end

data/lib/ncs_navigator/mdes/variable_type.rb

@@ -127,70 +127,35 @@ module NcsNavigator::Mdes
       "#<#{self.class} #{attrs.join(' ')}>"
     end
 
-    ##
-    # A specialization of `Array` for code lists.
-    #
-    # @see VariableType#code_list
-    # @see CodeListEntry
-    class CodeList < Array
-      ##
-      # @return [String,nil] the description of the code list if any.
-      attr_accessor :description
-    end
-
-    ##
-    # A single entry in a code list.
-    #
-    # @see VariableType#code_list
-    # @see CodeList
-    class CodeListEntry
-      ##
-      # @return [String] the local code value for the entry.
-      attr_reader :value
-
-      ##
-      # @return [String] the human-readable label for the entry.
-      attr_accessor :label
-
-      ##
-      # @return [String] the MDES's globally-unique identifier for
-      #   this coded value.
-      attr_accessor :global_value
-
-      ##
-      # @return [String] the name of MDES's master code list from
-      #   which this value is derived.
-      attr_accessor :master_cl
-
-      class << self
-        ##
-        # Creates a new instance from a `xs:enumeration` simple type
-        # restriction subelement.
-        #
-        # @param [Nokogiri::XML::Element] enum the `xs:enumeration`
-        #   element.
-        # @param [Hash] options
-        # @option options [#warn] :log the logger to which to direct warnings
-        #
-        # @return [CodeListEntry]
-        def from_xsd_enumeration(enum, options={})
-          log = options[:log] || NcsNavigator::Mdes.default_logger
-
-          log.warn("Missing value for code list entry on line #{enum.line}") unless enum['value']
-
-          new(enum['value'] && enum['value'].strip).tap do |cle|
-            cle.label = enum['ncsdoc:label']
-            cle.global_value = enum['ncsdoc:global_value']
-            cle.master_cl = enum['ncsdoc:master_cl']
-          end
-        end
-      end
-
-      def initialize(value)
-        @value = value
+    def diff_criteria(diff_options={})
+      base = {
+        :name       => Differences::ValueCriterion.new,
+        :base_type  => Differences::ValueCriterion.new,
+        :pattern    => Differences::ValueCriterion.new,
+        :max_length => Differences::ValueCriterion.new,
+        :min_length => Differences::ValueCriterion.new,
+      }
+
+      if diff_options[:strict]
+        base.merge(
+          :code_list_by_value => Differences::CollectionCriterion.new(
+            :value, :collection => :code_list),
+          :code_list_by_label => Differences::CollectionCriterion.new(
+            :label, :collection => :code_list)
+        )
+      else
+        base.merge(
+          :code_list_by_value => Differences::CollectionCriterion.new(
+            :value, :collection => :code_list),
+          :code_list_by_label => Differences::CollectionCriterion.new(
+            :label, :collection => :code_list, :value_extractor => :word_chars_downcase)
+        )
       end
+    end
+    protected :diff_criteria
 
-      alias :to_s :value
+    def diff(other_type, options={})
+      Differences::Entry.compute(self, other_type, diff_criteria(options), options)
     end
   end
 end

data/lib/ncs_navigator/mdes/version.rb

@@ -1,5 +1,5 @@
 module NcsNavigator
   module Mdes
-    VERSION = '0.11.0'
+    VERSION = '0.12.0'
   end
 end

data/lib/ncs_navigator/mdes.rb

@@ -4,6 +4,8 @@ module NcsNavigator
   module Mdes
     autoload :VERSION, 'ncs_navigator/mdes/version'
 
+    autoload :CodeList,          'ncs_navigator/mdes/code_list'
+    autoload :CodeListEntry,     'ncs_navigator/mdes/code_list'
     autoload :SourceDocuments,   'ncs_navigator/mdes/source_documents'
     autoload :Specification,     'ncs_navigator/mdes/specification'
     autoload :TransmissionTable, 'ncs_navigator/mdes/transmission_table'
@@ -12,6 +14,8 @@ module NcsNavigator
 
     autoload :DispositionCode,   'ncs_navigator/mdes/disposition_code'
 
+    autoload :Differences,       'ncs_navigator/mdes/differences'
+
     ##
     # @return the default logger for this module when no other one is
     #   specified. It logs to standard error.
@@ -22,7 +26,7 @@ module NcsNavigator
 
   ##
   # @return [Mdes::Specification] a new {Mdes::Specification} for the given
-  #   version. See {Specification#initialize} for accepted options.
+  #   version. See {Mdes::Specification#initialize} for accepted options.
   def self.Mdes(version, options={})
     Mdes::Specification.new(version, options)
   end

data/spec/differences_matchers.rb

@@ -0,0 +1,40 @@
+require 'rspec/expectations'
+
+module NcsNavigator::Mdes::Spec::Matchers
+  class ValueDiffMatcher
+    attr_reader :left, :right, :actual
+
+    def initialize(left, right)
+      @left = left
+      @right = right
+    end
+
+    def left_matches?(actual)
+      left == actual.left
+    end
+
+    def right_matches?(actual)
+      right == actual.right
+    end
+
+    def matches?(actual)
+      @actual = actual
+      actual && left_matches?(actual) && right_matches?(actual)
+    end
+
+    def failure_message_for_should
+      if (!actual)
+        "expected a difference but got none"
+      else
+        [
+          ("expected left=#{left.inspect} but was #{actual.left.inspect}" unless left_matches?(actual)),
+          ("expected right=#{right.inspect} but was #{actual.right.inspect}" unless right_matches?(actual))
+        ].compact.join(' and ')
+      end
+    end
+  end
+
+  def be_a_value_diff(left, right)
+    ValueDiffMatcher.new(left, right)
+  end
+end

data/spec/ncs_navigator/mdes/code_list_spec.rb

@@ -0,0 +1,178 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+require 'nokogiri'
+
+module NcsNavigator::Mdes
+  describe CodeListEntry do
+    describe '.from_xsd_enumeration' do
+      def code_list_entry(xml_s)
+        CodeListEntry.from_xsd_enumeration(schema_element(xml_s), :log => logger)
+      end
+
+      let(:missing) {
+        code_list_entry(<<-XSD)
+          <xs:enumeration value="-4" ncsdoc:label="Missing in Error" ncsdoc:desc="" ncsdoc:global_value="99-4" ncsdoc:master_cl="missing_data"/>
+        XSD
+      }
+
+      describe '#value' do
+        it 'is set' do
+          missing.value.should == "-4"
+        end
+
+        it 'warns when missing' do
+          code_list_entry('<xs:enumeration ncsdoc:label="Foo"/>')
+          logger[:warn].first.should == 'Missing value for code list entry on line 2'
+        end
+
+        describe 'with external whitespace on the value' do
+          let(:missing) {
+            code_list_entry(<<-XSD)
+              <xs:enumeration value="  -4 " ncsdoc:label="Missing in Error" ncsdoc:desc="" ncsdoc:global_value="99-4" ncsdoc:master_cl="missing_data"/>
+            XSD
+          }
+
+          it 'removes the whitespace' do
+            missing.value.should == '-4'
+          end
+        end
+      end
+
+      describe "#label" do
+        it 'is set' do
+          missing.label.should == "Missing in Error"
+        end
+      end
+
+      describe '#global_value' do
+        it 'is set' do
+          missing.global_value.should == '99-4'
+        end
+      end
+
+      describe '#master_cl' do
+        it 'is set' do
+          missing.master_cl.should == 'missing_data'
+        end
+      end
+    end
+
+    describe '#to_s' do
+      it 'is the value' do
+        CodeListEntry.new('14').to_s.should == '14'
+      end
+    end
+
+    describe '#diff' do
+      let(:a) { CodeListEntry.new('A') }
+      let(:aprime) { CodeListEntry.new('A') }
+
+      let(:diff)        { a.diff(aprime) }
+      let(:strict_diff) { a.diff(aprime, :strict => true) }
+
+      it 'reports nothing for no differences' do
+        diff.should be_nil
+      end
+
+      describe 'value' do
+        let(:b) { CodeListEntry.new('B') }
+
+        it 'reports a difference' do
+          b.diff(a)[:value].should be_a_value_diff('B', 'A')
+        end
+      end
+
+      describe 'label' do
+        describe 'with a text difference' do
+          before do
+            a.label = 'Aleph'
+            aprime.label = 'Alpha'
+          end
+
+          it 'when not strict, it reports the normalized difference' do
+            diff[:label].should be_a_value_diff('aleph', 'alpha')
+          end
+
+          it 'when strict, it reports the literal difference' do
+            strict_diff[:label].should be_a_value_diff('Aleph', 'Alpha')
+          end
+        end
+
+        describe 'with a whitespace-only difference' do
+          before do
+            a.label = " a\t\tb   "
+            aprime.label = 'a   b'
+          end
+
+          it 'reports a difference in strict mode' do
+            strict_diff[:label].should be_a_value_diff(a.label, aprime.label)
+          end
+
+          it 'does not report a difference when not strict' do
+            diff.should be_nil
+          end
+        end
+
+        describe 'with a case-only difference' do
+          before do
+            a.label = 'AbcdEf'
+            aprime.label = 'aBCDeF'
+          end
+
+          it 'reports a difference in strict mode' do
+            strict_diff[:label].should be_a_value_diff(a.label, aprime.label)
+          end
+
+          it 'does not report a difference when not strict' do
+            diff.should be_nil
+          end
+        end
+
+        describe 'with a punctuation-only difference' do
+          before do
+            a.label = 'a,b,|c[at+]-'
+            aprime.label = 'a!b*&c$#at'
+          end
+
+          it 'reports a difference in strict mode' do
+            strict_diff[:label].should be_a_value_diff(a.label, aprime.label)
+          end
+
+          it 'does not report a difference when not strict' do
+            diff.should be_nil
+          end
+        end
+      end
+
+      describe 'global_value' do
+        before do
+          a.global_value = '0'
+          aprime.global_value = '-0'
+        end
+
+        it 'reports a difference in strict mode' do
+          strict_diff[:global_value].should be_a_value_diff('0', '-0')
+        end
+
+        it 'does not report a difference otherwise' do
+          diff.should be_nil
+        end
+      end
+
+      describe 'master_cl' do
+        before do
+          a.master_cl = 'C'
+          aprime.master_cl = 'Cprime'
+        end
+
+        it 'reports a difference in strict mode' do
+          strict_diff[:master_cl].should be_a_value_diff('C', 'Cprime')
+        end
+
+        it 'does not report a difference otherwise' do
+          diff.should be_nil
+        end
+      end
+    end
+  end
+end

data/spec/ncs_navigator/mdes/source_documents_spec.rb

@@ -71,6 +71,16 @@ module NcsNavigator::Mdes
       end
     end
 
+    describe '#child_or_parent_instrument_tables' do
+      let(:property) { :child_or_parent_instrument_tables }
+
+      it_behaves_like 'an absolutizing path accessor'
+
+      it 'is optional' do
+        SourceDocuments.new.child_or_parent_instrument_tables.should be_nil
+      end
+    end
+
     describe '.get' do
       shared_examples 'version docs' do
         subject { SourceDocuments.get(version) }
@@ -83,6 +93,10 @@ module NcsNavigator::Mdes
           subject.disposition_codes.should =~ %r{#{version}/disposition_codes.yml$}
         end
 
+        it 'has the correct path for the parent-child instrument tables list' do
+          subject.child_or_parent_instrument_tables.should =~ %r{#{version}/child_or_parent_instrument_tables.yml$}
+        end
+
         it 'is of the specified version' do
           subject.version.should == version
         end

data/spec/ncs_navigator/mdes/specification_spec.rb

@@ -53,6 +53,18 @@ module NcsNavigator::Mdes
             lambda { table.instrument_table? }.should_not raise_error
           end
         end
+
+        it 'knows the mother-childness of all p_id-bearing instrument tables' do
+          p_id_instrument_tables = tables.select { |t| t.instrument_table? && t.variables.collect(&:name).include?('p_id') }
+          p_id_instrument_tables.
+            reject { |t| [true, false].include?(t.child_instrument_table?) }.
+            collect { |t| t.name }.should == []
+        end
+
+        it 'has some child and some parent instrument data tables' do
+          index = tables.each_with_object(Hash.new(0)) { |t, acc| acc[t.child_instrument_table?] += 1 }
+          index.keys.sort_by { |k| k.inspect }.should == [false, nil, true]
+        end
       end
 
       context 'in version 1.2' do
@@ -275,5 +287,23 @@ module NcsNavigator::Mdes
         include_examples 'types fully resolved'
       end
     end
+
+    describe '#diff' do
+      let(:diff) {
+        Specification.new('2.0').diff(Specification.new('2.1'))
+      }
+
+      it 'finds different spec versions' do
+        diff[:specification_version].should be_a_value_diff('2.0.01.02', '2.1.00.00')
+      end
+
+      it 'finds different tables' do
+        diff[:transmission_tables].right_only.should include('preg_visit_1_saq_3')
+      end
+
+      it 'finds different types' do
+        diff[:types].right_only.should include('person_partcpnt_reltnshp_cl5')
+      end
+    end
   end
 end

data/spec/ncs_navigator/mdes/transmission_table_spec.rb

@@ -179,5 +179,82 @@ XSD
         end
       end
     end
+
+    describe 'parent or child instrument table accessors' do
+      let(:t) { TransmissionTable.new('T') }
+
+      it 'is not a parent table when it is a child table' do
+        t.child_instrument_table = true
+        t.should_not be_a_parent_instrument_table
+      end
+
+      it 'is a parent table when it is definitely not a child table' do
+        t.child_instrument_table = false
+        t.should be_a_parent_instrument_table
+      end
+
+      it 'is not known whether it is a parent instrument table when it is not known whether it is a child instrument table' do
+        t.child_instrument_table = nil
+        t.parent_instrument_table?.should be_nil
+      end
+    end
+
+    describe '#diff' do
+      let(:a) { TransmissionTable.new('A') }
+      let(:aprime) { TransmissionTable.new('A') }
+
+      describe 'name' do
+        let(:b) { TransmissionTable.new('B') }
+
+        it 'reports a difference when they are different' do
+          a.diff(b)[:name].should be_a_value_diff('A', 'B')
+        end
+
+        it 'reports nothing when they are the same' do
+          a.diff(aprime).should be_nil
+        end
+      end
+
+      describe 'variables' do
+        let(:v1) { Variable.new('V1') }
+        let(:v1prime) { Variable.new('V1') }
+        let(:v2) { Variable.new('V2') }
+        let(:v3) { Variable.new('V3') }
+
+        let(:diff) { a.diff(aprime) }
+
+        before do
+          a.variables << v1
+          aprime.variables << v1prime
+        end
+
+        it 'lists variables which are in the lefthand side only' do
+          a.variables << v2 << v3
+          aprime.variables << v3
+
+          diff[:variables].left_only.should == ['V2']
+        end
+
+        it 'lists variables which are in the righthand side only' do
+          aprime.variables << v3
+
+          diff[:variables].right_only.should == ['V3']
+        end
+
+        it 'provides detailed differences for variables which are different' do
+          v1.pii = :possible
+          a.variables << v1
+
+          v1prime.pii = true
+          aprime.variables << v1prime
+
+          diff[:variables].entry_differences['V1'][:pii].should be_a_value_diff(:possible, true)
+        end
+
+        it 'does not list variables which are the same' do
+          diff.should be_nil
+        end
+      end
+    end
   end
 end