ncs_mdes 0.2.0

data/lib/ncs_navigator/mdes/source_documents.rb

@@ -0,0 +1,103 @@
+require 'ncs_navigator/mdes'
+
+require 'forwardable'
+
+module NcsNavigator::Mdes
+  ##
+  # Implements the mechanism for determining where the MDES documents
+  # are stored on a particular system.
+  class SourceDocuments
+    BASE_ENV_VAR = 'NCS_MDES_DOCS_DIR'
+
+    extend Forwardable
+
+    ##
+    # The base path for all paths that are not explicitly
+    # configured. It defaults to `'documents'` within this gem and may
+    # be globally overridden by setting `NCS_MDES_DOCS_DIR` in the
+    # runtime environment.
+    #
+    # There's probably no reason to change this in the current version
+    # of the gem.
+    #
+    # @return [String]
+    attr_accessor :base
+
+    ##
+    # The MDES version this set of documents describes.
+    #
+    # @return [String]
+    attr_accessor :version
+
+    ##
+    # Instance-level alias for {.xmlns}.
+    # @method xmlns
+    # @return [Hash]
+    def_delegator self, :xmlns
+
+    class << self
+      ##
+      # Constructs an appropriate instance for the given version.
+      #
+      # @return [SourceDocuments]
+      def get(version)
+        case version
+        when '1.2'
+          create('1.2', '1.2/Data_Transmission_Schema_V1.2.xsd')
+        when '2.0'
+          create('2.0', '2.0/NCS_Transmission_Schema_2.0.01.02.xml')
+        else
+          raise "MDES #{version} is not supported by this version of ncs_mdes"
+        end
+      end
+
+      def create(version, schema)
+        self.new.tap do |sd|
+          sd.version = version
+          sd.schema = schema
+        end
+      end
+      private :create
+
+      ##
+      # A mapping of prefixes to XML namespaces for use with
+      # Nokogiri XPath.
+      #
+      # @return [Hash<String, String>]
+      def xmlns
+        {
+          'xs'     => 'http://www.w3.org/2001/XMLSchema',
+          'ncs'    => 'http://www.nationalchildrensstudy.gov',
+          'ncsdoc' => 'http://www.nationalchildrensstudy.gov/doc'
+        }
+      end
+    end
+
+    def base
+      @base ||= (
+        ENV[BASE_ENV_VAR] ||
+        File.expand_path(File.join('..', '..', '..', '..', 'documents'), __FILE__)
+        )
+    end
+
+    ##
+    # The absolute path to the XML Schema describing the MDES
+    # transmission structure for this instance.
+    #
+    # @return [String]
+    def schema
+      @schema[0, 1] == '/' ? @schema : File.join(base, @schema)
+    end
+
+    ##
+    # Set the path to the MDES transmission structure XML Schema.
+    # If the path is relative (i.e., it does not begin with `/`), it
+    # will be interpreted relative to {#base}.
+    #
+    # @param [String] path
+    # @return [String] the provided path
+    def schema=(path)
+      @schema = path
+    end
+  end
+end

data/lib/ncs_navigator/mdes/specification.rb

@@ -0,0 +1,86 @@
+require 'ncs_navigator/mdes'
+
+require 'forwardable'
+require 'logger'
+require 'nokogiri'
+
+module NcsNavigator::Mdes
+  class Specification
+    extend Forwardable
+
+    ##
+    # @return [SourceDocuments] the source documents this reader is
+    #   working from.
+    attr_accessor :source_documents
+
+    ##
+    # @method version
+    # @return [String] the version of the MDES to which this instance refers.
+    def_delegator :@source_documents, :version
+
+    ##
+    # @param [String,SourceDocuments] version either the string
+    #   version of the MDES metadata you would like to read, or a
+    #   {SourceDocuments} instance pointing to the appropriate files.
+    # @param [Hash] options
+    # @option options :log a logger to use while reading the specification. If
+    #   not specified, a logger pointing to standard error will be used.
+    def initialize(version, options={})
+      @source_documents = case version
+                          when SourceDocuments
+                            version
+                          else
+                            SourceDocuments.get(version)
+                          end
+      @log = options[:log] || NcsNavigator::Mdes.default_logger
+    end
+
+    ##
+    # @return [Nokogiri::XML::Document] the parsed version of the VDR
+    #   XML schema for this version of the MDES.
+    def xsd
+      @xsd ||= Nokogiri::XML(File.read source_documents.schema)
+    end
+
+    ##
+    # @return [Array<TransmissionTable>] all the transmission tables
+    #   in this version of the MDES.
+    def transmission_tables
+      @transmission_tables ||= read_transmission_tables
+    end
+
+    def read_transmission_tables
+      xsd.xpath(
+        '//xs:element[@name="transmission_tables"]/xs:complexType/xs:sequence/xs:element',
+        source_documents.xmlns
+      ).collect { |table_elt|
+        TransmissionTable.from_element(table_elt, :log => @log)
+      }.tap { |tables|
+        tables.each { |t| t.variables.each { |v| v.resolve_type!(types, :log => @log) } }
+      }
+    end
+    private :read_transmission_tables
+
+    ##
+    # @return [Array<VariableType>] all the named types in the
+    #   MDES. This includes all the code lists.
+    def types
+      @types ||= read_types
+    end
+
+    def read_types
+      xsd.xpath('//xs:simpleType[@name]', source_documents.xmlns).collect do |type_elt|
+        VariableType.from_xsd_simple_type(type_elt, :log => @log)
+      end
+    end
+    private :read_types
+
+    ##
+    # A briefer inspection for nicer IRB sessions.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class} version=#{version.inspect}>"
+    end
+  end
+end

data/lib/ncs_navigator/mdes/transmission_table.rb

@@ -0,0 +1,53 @@
+require 'ncs_navigator/mdes'
+
+module NcsNavigator::Mdes
+  ##
+  # One table in the MDES.
+  class TransmissionTable
+    ##
+    # Creates a new instance from an `xs:element` describing the table.
+    #
+    # @return [TransmissionTable] the created instance.
+    def self.from_element(element, options={})
+      log = options[:log] || NcsNavigator::Mdes.default_logger
+
+      new(element['name']).tap do |table|
+        table.variables = element.
+          xpath('xs:complexType/xs:sequence/xs:element', SourceDocuments.xmlns).
+          collect { |col_elt| Variable.from_element(col_elt, options) }
+      end
+    end
+
+    ##
+    # @return [String] the machine name of the table. This is also the name of the XML
+    #  element in the VDR export.
+    attr_reader :name
+
+    ##
+    # @return [Array<Variable>] the variables that make up this
+    #  table. (A relational model might call these the columns of this
+    #  table.)
+    attr_accessor :variables
+
+    def initialize(name)
+      @name = name
+    end
+
+    ##
+    # Search for a variable by name.
+    #
+    # @param variable_name [String] the name of the variable to look for.
+    # @return [Variable] the variable with the given name, if any
+    def [](variable_name)
+      variables.find { |c| c.name == variable_name }
+    end
+
+    ##
+    # Provides a briefer inspection for cleaner IRB use.
+    #
+    # @return [String]
+    def inspect
+      "\#<#{self.class} name=#{name.inspect}>"
+    end
+  end
+end

data/lib/ncs_navigator/mdes/variable.rb

@@ -0,0 +1,119 @@
+require 'ncs_navigator/mdes'
+
+module NcsNavigator::Mdes
+  ##
+  # A single field in the MDES. A relational model might also call
+  # this a column, but "variable" is what it's called in the MDES.
+  class Variable
+    ##
+    # @return [String] the name of the variable
+    attr_reader :name
+
+    ##
+    # @return [Boolean,:possible,:unknown,String] the PII category
+    #   for the variable. `true` if it is definitely PII, `false` if
+    #   it definitely is not, `:possible` if it was marked in the MDES
+    #   as requiring manual review, `:unknown` if the MDES does not
+    #   specify, or a string if the parsed value was not mappable to
+    #   one of the above. Note that this value will always be truthy
+    #   unless the MDES explicitly says that the variable is not PII.
+    attr_accessor :pii
+
+    ##
+    # @return [:active,:new,:modified,:retired,String] the status of
+    #   the variable in this version of the MDES. A String is returned
+    #   if the source value doesn't match any of the expected values
+    #   in the MDES.
+    attr_accessor :status
+
+    ##
+    # @return [VariableType] the type of this variable.
+    attr_accessor :type
+
+    ##
+    # Is the variable mandatory for a valid submission?
+    #
+    # @return [Boolean]
+    attr_accessor :required
+    alias :required? :required
+
+    class << self
+      ##
+      # Examines the given parsed element and creates a new
+      # variable. The resulting variable has all the attributes set
+      # which can be set without reference to any other parts of the
+      # MDES outside of this one variable definition.
+      #
+      # @param [Nokogiri::Element] element the source xs:element
+      # @return [Variable] a new variable instance
+      def from_element(element, options={})
+        log = options[:log] || NcsNavigator::Mdes.default_logger
+
+        new(element['name']).tap do |var|
+          var.required = (element['nillable'] == 'false')
+          var.pii =
+            case element['pii']
+            when 'Y'; true;
+            when 'P'; :possible;
+            when nil; :unknown;
+            when '';  false;
+            else element['pii'];
+            end
+          var.status =
+            case element['status']
+            when '1'; :active;
+            when '2'; :new;
+            when '3'; :modified;
+            when '4'; :retired;
+            else element['status'];
+            end
+          var.type =
+            if element['type']
+              if element['type'] =~ /^xs:/
+                VariableType.xml_schema_type(element['type'].sub(/^xs:/, ''))
+              else
+                VariableType.reference(element['type'])
+              end
+            elsif element.elements.collect { |e| e.name } == %w(simpleType)
+              VariableType.from_xsd_simple_type(element.elements.first, options)
+            else
+              log.warn("Could not determine a type for variable #{var.name.inspect} on line #{element.line}")
+              nil
+            end
+        end
+      end
+    end
+
+    def initialize(name)
+      @name = name
+    end
+
+    def constraints
+      @constraints ||= []
+    end
+
+    ##
+    # If the {#type} of this instance is a reference to an NCS type,
+    # attempts to replace it with the full version from the given list
+    # of types.
+    #
+    # @param [Array<VariableType>] types
+    # @return [void]
+    def resolve_type!(types, options={})
+      log = options[:log] || NcsNavigator::Mdes.default_logger
+
+      return unless type && type.reference?
+      unless type.name =~ /^ncs:/
+        log.warn("Unknown reference namespace in type #{type.name.inspect} for #{name}")
+      end
+
+      ncs_type_name = type.name.sub(/^ncs:/, '')
+      match = types.find { |t| t.name == ncs_type_name }
+      if match
+        self.type = match
+      else
+        log.warn("Undefined type #{type.name} for #{name}.") if log
+      end
+    end
+  end
+end

data/lib/ncs_navigator/mdes/variable_type.rb

@@ -0,0 +1,196 @@
+require 'ncs_navigator/mdes'
+
+module NcsNavigator::Mdes
+  ##
+  # Encapsulates restrictions on the content of a {Variable}.
+  class VariableType
+    attr_reader :name
+
+    ##
+    # @return [Symbol, nil] the XML Schema base type that this
+    #   variable type is based on.
+    attr_accessor :base_type
+
+    ##
+    # @return [Regexp, nil] a regular expression that valid values of this
+    #   type must match.
+    attr_accessor :pattern
+
+    ##
+    # @return [Fixnum, nil] the maximum length of a valid value of
+    #   this type.
+    attr_accessor :max_length
+
+    ##
+    # @return [Fixnum, nil] the minimum length of a valid value of
+    #   this type.
+    attr_accessor :min_length
+
+    ##
+    # @return [CodeList<CodeListEntry>, nil] the fixed list of values
+    #   that are valid for this type.
+    attr_accessor :code_list
+
+    ##
+    # @return [Boolean] whether this is a fully fleshed-out type or
+    #   just a reference. If it is a reference, all fields except for
+    #   {#name} should be ignored.
+    attr_accessor :reference
+    alias :reference? :reference
+
+    class << self
+      ##
+      # @param [Nokogiri::XML::Element] st the `xs:simpleType` element
+      #   from which to build the instance
+      # @param [Hash] options
+      # @option options [#warn] :log the logger to which to direct warnings
+      #
+      # @return [VariableType] a new instance based on the provided
+      #   simple type.
+      def from_xsd_simple_type(st, options={})
+        log = options[:log] || NcsNavigator::Mdes.default_logger
+
+        restriction = st.xpath('xs:restriction[@base="xs:string"]', SourceDocuments.xmlns).first
+        unless restriction
+          log.warn "Unsupported restriction base in simpleType on line #{st.line}"
+          return
+        end
+
+        new(st['name']).tap do |vt|
+          vt.base_type = :string
+          restriction.elements.each do |elt|
+            case elt.name
+            when 'pattern'
+              p = elt['value']
+              vt.pattern =
+                begin
+                  Regexp.new(p)
+                rescue RegexpError
+                  log.warn("Uncompilable pattern #{p.inspect} in simpleType#{(' ' + vt.name.inspect) if vt.name} on line #{elt.line}")
+                  nil
+                end
+            when 'maxLength'
+              vt.max_length = elt['value'].to_i
+            when 'minLength'
+              vt.min_length = elt['value'].to_i
+            when 'enumeration'
+              (vt.code_list ||= CodeList.new) << CodeListEntry.from_xsd_enumeration(elt)
+              if elt['desc'] =~ /\S/
+                if vt.code_list.description.nil?
+                  vt.code_list.description = elt['desc']
+                elsif vt.code_list.description != elt['desc']
+                  log.warn("Code list entry on line #{elt.line} unexpectedly has a different desc from the first entry")
+                end
+              end
+            else
+              log.warn "Unsupported restriction element #{elt.name.inspect} on line #{elt.line}"
+            end
+          end
+        end
+      end
+
+      ##
+      # Creates an instance that represents a reference with the given
+      # name.
+      #
+      # @return [VariableType] a new instance
+      def reference(name)
+        new(name).tap do |vt|
+          vt.reference = true
+        end
+      end
+
+      ##
+      # Creates an instance corresponding to the given XML Schema
+      # simple base type.
+      #
+      # @return [VariableType] a new instance
+      def xml_schema_type(type_name)
+        new.tap do |vt|
+          vt.base_type = type_name.to_sym
+        end
+      end
+    end
+
+    def initialize(name=nil)
+      @name = name
+    end
+
+    def inspect
+      attrs = [
+        [:name, name.inspect],
+        [:base_type, base_type.inspect],
+        [:reference, reference.inspect],
+        [:code_list, code_list ? "<#{code_list.size} entries>" : nil]
+      ].reject { |k, v| v.nil? }.
+        collect { |k, v| "#{k}=#{v}" }
+      "#<#{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']).tap do |cle|
+            cle.label = enum['label']
+            cle.global_value = enum['global_value']
+            cle.master_cl = enum['master_cl']
+          end
+        end
+      end
+
+      def initialize(value)
+        @value = value
+      end
+
+      alias :to_s :value
+    end
+  end
+end

data/lib/ncs_navigator/mdes/version.rb

@@ -0,0 +1,5 @@
+module NcsNavigator
+  module Mdes
+    VERSION = "0.2.0"
+  end
+end

data/lib/ncs_navigator/mdes.rb

@@ -0,0 +1,27 @@
+require 'logger'
+
+module NcsNavigator
+  module Mdes
+    autoload :VERSION, 'ncs_navigator/mdes/version'
+
+    autoload :SourceDocuments,   'ncs_navigator/mdes/source_documents'
+    autoload :Specification,     'ncs_navigator/mdes/specification'
+    autoload :TransmissionTable, 'ncs_navigator/mdes/transmission_table'
+    autoload :Variable,          'ncs_navigator/mdes/variable'
+    autoload :VariableType,      'ncs_navigator/mdes/variable_type'
+
+    ##
+    # @return the default logger for this module when no other one is
+    #   specified. It logs to standard error.
+    def self.default_logger
+      @default_logger ||= Logger.new($stderr)
+    end
+  end
+
+  ##
+  # @return [Mdes::Specification] a new {Mdes::Specification} for the given
+  #   version.
+  def self.Mdes(version)
+    Mdes::Specification.new(version)
+  end
+end

data/ncs_mdes.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "ncs_navigator/mdes/version"
+
+Gem::Specification.new do |s|
+  s.name        = "ncs_mdes"
+  s.version     = NcsNavigator::Mdes::VERSION
+  s.authors     = ["Rhett Sutphin"]
+  s.email       = ["r-sutphin@northwestern.edu"]
+  s.homepage    = ""
+  s.summary     = %q{A ruby API for various versions of the NCS MDES.}
+  s.description = %q{
+Provides a consistent ruby interface to the project metainformation in the
+National Children's Study's Master Data Element Specification.
+}
+
+  s.files         = `git ls-files`.split("\n") - ['irb']
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'nokogiri', '~> 1.4'
+
+  s.add_development_dependency 'rspec', '~> 2.6'
+  s.add_development_dependency 'rake', '~> 0.9.2'
+  s.add_development_dependency 'yard', '~> 0.7.2'
+end