caruby-tissue 1.5.6 → 2.1.1

data/lib/catissue/migration/migratable.rb

@@ -1,87 +1,136 @@
-require 'caruby/migration/migrator'
+require 'uom'
+require 'jinx/migration/migrator'
+require 'catissue/database/controlled_values'
+require 'catissue/database/controlled_value_finder'
 require 'catissue/annotation/proxy'
 
 module CaTissue
-  shims SpecimenCollectionGroup, CollectionProtocolRegistration, SpecimenCharacteristics,
-    SpecimenEventParameters, CollectionEventParameters, ReceivedEventParameters
+  shims SpecimenCollectionGroup, TissueSpecimen, SpecimenCharacteristics,
+    SpecimenEventParameters, CollectibleEventParameters
 
   class SpecimenCollectionGroup
-    @@diagnosis_cv_finder = nil
-
-    # Sets this SpecimenCollectionGroup diagnosis ControlledValueFinder.
-    def self.diagnosis_cv_finder=(finder)
-      @@diagnosis_cv_finder = finder
+    # @return [String] the diagnosis controlled value
+    # @raise [Jinx::MigrationError] if the value is not supported
+    def migrate_clinical_diagnosis(value, row)
+      cv = standard_cv_diagnosis(value)
+      if cv.nil? then
+        cv = variant_cv_diagnosis(value)
+        if cv then 
+          logger.warn("Migrator substituted diagnosis #{cv} for #{value}.")
+        else
+          raise Jinx::MigrationError.new("#{cv} is not a recognized controlled value.")
+        end
+      end
+      cv
+    end
+    
+    # Enables diagnosis controlled value lookup.
+    def self.enable_cv_finder
+      @diagnosis_cv_finder ||= ControlledValueFinder.new(:clinical_diagnosis)
     end
+    
+    private
 
     # Returns the diagnosis controlled value as follows:
     # * If CV lookup is disabled, then this method returns value.
-    # * Otherwise, if the value is remapped via a configuration remap file,
-    #   then this method returns the remapped CV.
-    # * Otherwise, if the value is a valid CV, then this method returns value.
-    # * Otherwise, this method returns nil.
+    # * Otherwise, delegate to the CV finder.
     #
     # @param [String] value the input diagnosis
     # @return [String] the mapped CV
     def self.diagnosis_controlled_value(value)
-      @@diagnosis_cv_finder.nil? ? value : @@diagnosis_cv_finder.controlled_value(value)
+      @diagnosis_cv_finder.nil? ? value : @diagnosis_cv_finder.controlled_value(value)
     end
 
-    # @return [String] the {diagnosis_controlled_value}
-    def migrate_clinical_diagnosis(value, row)
-      SpecimenCollectionGroup.diagnosis_controlled_value(value)
+    # @return [String, nil] the caTissue diagnosis permissible value, or nil if not found
+    def standard_cv_diagnosis(value)
+      SpecimenCollectionGroup.diagnosis_controlled_value(value) rescue nil
+    end
+
+    # Returns the tissue site which adds the 'NOS' suffix to a value without one or removes
+    # 'NOS' from a value with the suffix.
+    #
+    # @return [String, nil] a supported variant of the input value, or nil if none
+    # @raise (see ControlledValueFinder#controlled_value)
+    def variant_cv_diagnosise(value)
+      # try an NOS suffix variation
+      variation = value =~ /, NOS$/ ? value[0...-', NOS'.length] : value + ', NOS'
+      SpecimenCollectionGroup.diagnosis_controlled_value(variation) rescue nil
+    end
+  end
+
+  class Specimen
+    # Parses the source field as a UOM::Measurement if it is a string.
+    # Otherwises, returns the source value.
+    def migrate_initial_quantity(value, row)
+      standardize_quantity(value)
+    end
+    
+    private
+    
+    # Parses the source field as a UOM::Measurement if it is a string.
+    # Otherwises, returns the source value.
+    def standardize_quantity(value)
+      # if value is not a string, then use it as is
+      return value unless value.is_a?(String)
+      # the value has a unit qualifier; parse the measurement.
+      # the unit is normalized to the Specimen standard unit.
+      value.to_measurement_quantity(standard_unit)
     end
   end
 
   class SpecimenCharacteristics
-    @@tissue_site_cv_finder = nil
+    # Enables tissue site controlled value lookup.
+    def self.enable_cv_finder
+      @site_finder ||= ControlledValueFinder.new(:tissue_site)
+    end
 
-    # Sets this SpecimenCharacteristics tissue site ControlledValueFinder.
-    def self.tissue_site_cv_finder=(finder)
-      @@tissue_site_cv_finder = finder
+    # @return [String] the tissue site controlled value
+    # @raise [Jinx::MigrationError] if the value is not supported
+    def migrate_tissue_site(value, row)
+      cv = standard_cv_tissue_site(value)
+      if cv.nil? then
+        cv = variant_cv_tissue_site(value)
+        if cv then 
+          logger.warn("Migrator substituted tissue site #{cv} for #{value}.")
+        else
+          raise Jinx::MigrationError.new("#{cv} is not a recognized controlled value.")
+        end
+      end
+      cv
     end
 
+    private
+
     # Returns the tissue site controlled value as follows:
     # * If CV lookup is disabled, then this method returns value.
-    # * Otherwise, if the value is remapped via a configuration remap file,
-    #   then this method returns the remapped CV.
-    # * Otherwise, if the value is a valid CV, then this method returns value.
-    # * Otherwise, this method returns nil.
+    # * Otherwise, delegate to the CV finder.
     #
     # @return [String] the caTissue tissue site permissible value
     def self.tissue_site_controlled_value(value)
-      @@tissue_site_cv_finder.nil? ? value : @@tissue_site_cv_finder.controlled_value(value)
-    end
-
-    # @return [String] the {tissue_site_controlled_value}
-    def migrate_tissue_site(value, row)
-      standard_cv_tissue_site(value) or variant_cv_tissue_site(value)
+      @site_finder.nil? ? value : @site_finder.controlled_value(value)
     end
 
-    private
-
-    # Returns the {tissue_site_controlled_value}.
-    #
-    # @return the caTissue tissue site permissible value
+    # @return [String, nil] the caTissue tissue site permissible value,
+    #   or nil if not found
     def standard_cv_tissue_site(value)
-      SpecimenCharacteristics.tissue_site_controlled_value(value)
+      SpecimenCharacteristics.tissue_site_controlled_value(value) rescue nil
     end
 
-    # Returns the {tissue_site_controlled_value} which adds the 'NOS' suffix to a value
-    # without one or removes 'NOS' from a value with the suffix.
+    # Returns the tissue site which adds the 'NOS' suffix to a value without one
+    # or removes 'NOS' from a value with the suffix.
     #
-    # @return the caTissue tissue site permissible value
+    # @return [String, nil] a supported variant of the input value, or nil if none
     def variant_cv_tissue_site(value)
       # try an NOS suffix variation
       variation = value =~ /, NOS$/ ? value[0...-', NOS'.length] : value + ', NOS'
-      cv = SpecimenCharacteristics.tissue_site_controlled_value(variation)
-      logger.warn("Migrator substituted tissue site #{cv} for #{value}.") if cv
-      cv
+      SpecimenCharacteristics.tissue_site_controlled_value(variation) rescue nil
     end
   end
 
   class SpecimenEventParameters
     # Returns nil by default, since only CollectibleEventParameters have a SCG owner.
-    # {CollectibleEventParameters#migrate_specimen_collection_group} overrides this method.
+    # {CollectibleEventParameters#migrate_specimen_collection_group} overrides this
+    # method.
     #
     # @return nil
     def migrate_specimen_collection_group(scg, row)
@@ -103,7 +152,7 @@ module CaTissue
     # A CollectibleEventParameters is preferentially set to a migrated SCG rather than a migrated
     # Specimen.
     #
-    # Overrides {CaRuby::Migratable#migratable__target_value} to confer precedence to
+    # Overrides +Jinx::Migratable.migratable__target_value+ to confer precedence to
     # a SCG over a Specimen when setting this event parameters' owner. If the migrated
     # collection includes both a Specimen and a SCG, then this event parameters
     # +specimen+ reference is ambiguous, but the +specimen_collection_group+ reference

data/lib/catissue/migration/migrator.rb

@@ -1,15 +1,12 @@
-require 'caruby/util/properties'
-require 'caruby/migration/migrator'
-require 'catissue/resource'
-require 'catissue/database/controlled_values'
-require 'catissue/database/controlled_value_finder'
+require 'jinx/helpers/log'
+require 'jinx/migration/migrator'
 
 module CaTissue
   # Migrates a CSV extract to caTissue. See the {#initialize} documentation for usage options.
   #
-  # See the Galena Cancer Center Tissue Bank Migration Example for further information
-  # about how the options tailor migration, esp. the use of the field mappings and shims.
-  class Migrator < CaRuby::Migrator
+  # See the Galena migration example for further information about to tailor the migration,
+  # esp. the use of the field mappings and shims.
+  class Migrator < Jinx::Migrator
     # Creates a new Migrator with the given options.
     #
     # This migrator must include sufficient information to build a well-formed migration target object.
@@ -17,10 +14,9 @@ module CaTissue
     # able to build that SCG's CollectionProtocolRegistration. The CPR in turn must either exist in the
     # database or the migration must build a Participant and a CollectionProtocol.
     # 
-    # @option (see CaRuby::Migrator#initialize)
-    # @option opts [String] :tissue_sites the tissue site mapping file
-    # @option opts [String] :diagnoses the diagnosis mapping file
-    # @option opts [String] :database target application {CaRuby::Database}
+    # @option (see Jinx::Migrator#initialize)
+    # @option opts [String] :controlled_values enable controlled value lookup
+    # @option opts [String] :database target application +CaRuby::Database+
     # @option opts [String] :target required target domain class
     # @option opts [String] :input required source file to migrate
     # @option opts [String] :shims optional array of shim files to load
@@ -36,14 +32,9 @@ module CaTissue
         # add config options but don't override the parameter options
         opts.merge!(conf, :deep) { |key, oldval, newval| oldval }
       end
-      # open the log file before building structure
-      log_file = opts[:log]
-      CaRuby::Log.instance.open(log_file, :debug => opts[:debug]) if log_file
-
       # tailor the options
       opts[:name] ||= NAME
       opts[:database] ||= CaTissue::Database.instance
-      
       # the shims file(s)
       opts[:shims] ||= []
       shims = opts[:shims] ||= []
@@ -51,52 +42,45 @@ module CaTissue
       shims = opts[:shims] = [shims] unless shims.collection?
       # prepend this migrator's shims
       shims.unshift(MIGRATABLE_SHIM)
-
-      # If the unique option is set, then append the CaTissue-specific uniquifier shim.
+      # If the unique option is set, then prepend the CaTissue-specific uniquifier shim.
       if opts[:unique] then
-        # add the uniquify shim
-        shims << UNIQUIFY_SHIM
+        shims.unshift(UNIQUIFY_SHIM)
         logger.debug { "Migrator added uniquification shim #{UNIQUIFY_SHIM}." }
       end
 
-      # call the CaRuby::Migrator initializer with the augmented options
+      # call the Jinx::Migrator initializer with the augmented options
       super
 
       # The remaining options are handled by this CaTissue::Migrator subclass.
 
-      # The tissue site CV look-up option.
-      tissue_sites = opts[:tissue_sites]
-      if tissue_sites then
-        CaTissue::SpecimenCharacteristics.tissue_site_cv_finder = ControlledValueFinder.new(:tissue_site, tissue_sites)
-        logger.info("Migrator enabled tissue site controlled value lookup.")
-      end
-
-      # The clinical diagnosis CV look-up option.
-      diagnoses = opts[:diagnoses]
-      if diagnoses then
-        CaTissue::SpecimenCollectionGroup.diagnosis_cv_finder = ControlledValueFinder.new(:clinical_diagnosis, diagnoses)
-        logger.info("Migrator enabled clinical diagnosis controlled value lookup.")
+      # The CV look-up option.
+      if opts[:controlled_values] then
+        CaTissue::SpecimenCharacteristics.enable_cv_finder
+        CaTissue::SpecimenCollectionGroup.enable_cv_finder
+        logger.info("Migrator enabled tissue site and clinical diagnosis controlled value lookup.")
       end
     end
 
     private
+    
     # The default name of this migrator.
     NAME = 'caTissue Migrator'
 
     # The built-in caTissue migration shims.
-    MIGRATABLE_SHIM = File.join(File.dirname(__FILE__), 'migratable.rb')
+    MIGRATABLE_SHIM = File.expand_path('migratable.rb', File.dirname(__FILE__))
     
-    UNIQUIFY_SHIM = File.join(File.dirname(__FILE__), 'uniquify')
+    UNIQUIFY_SHIM = File.expand_path('unique.rb', File.dirname(__FILE__))
         
     # The context module is determined as follows:
-    # * For an {Annotation} target class, the context module is the annotated class's domain_module.
-    # * Otherwise, delegate to +CaRuby::Migrator+.
-    # * For an {Annotation} target class, the context module is the annotated class's {ResourceClass#domain_module}.
-    # * Otherwise, delegate to {CaRuby::Migrator}.
+    # * For an {Annotation} target class, the context module is the {Annotation::Metadata#annotation_module}.
+    # * Otherwise, delegate to +Jinx::Migrator+.
+    # * For an {Annotation} target class, the context module is the annotated class's
+    #   +CaRuby::Metadata.annotation_module+.
+    # * Otherwise, delegate to +Jinx::Migrator+.
     #
-    # @return (see CaRuby::Migrator#context_module)
+    # @return (see Jinx::Migrator#context_module)
     def context_module
-      @target_class < Annotation ? @target_class.hook.domain_module : super
+      @target_class < Annotation ? @target_class.annotation_module : super
     end
     
     # Clears the migration protocol CPR and SCG references.

data/lib/catissue/migration/shims.rb

@@ -1,4 +1,4 @@
-require 'caruby/migration/migrator'
+require 'jinx/migration/migrator'
 
 module CaTissue
   shims SpecimenCollectionGroup, CollectionProtocolRegistration, SpecimenCharacteristics,

data/lib/catissue/migration/unique.rb

@@ -0,0 +1,76 @@
+require 'jinx/resource/unique'
+
+module CaTissue
+  shims CollectionProtocol, CollectionProtocolEvent, Container, ContainerType, StorageType,
+    ParticipantMedicalIdentifier, CollectionProtocolRegistration, SpecimenCollectionGroup,
+    ExternalIdentifier, User
+  
+  class CollectionProtocol
+    include Jinx::Unique
+    
+    # Makes this CP's short and long title unique.
+    def uniquify
+      super
+      self.short_title = title
+    end
+  end
+
+  class CollectionProtocolEvent
+    include Jinx::Unique
+  end
+
+  class Container
+    include Jinx::Unique
+    
+    # Makes this Container and all of its subcontainers unique.
+    def uniquify
+      super
+      subcontainers.each { |ctr| ctr.uniquify }
+    end
+  end
+
+  class ContainerType
+    include Jinx::Unique
+  end
+
+  class StorageType
+    def uniquify
+      super
+      child_container_types.each { |type| type.uniquify } 
+    end
+  end
+
+  class ParticipantMedicalIdentifier
+    include Jinx::Unique
+  end
+
+  class CollectionProtocolRegistration
+    include Jinx::Unique
+  end
+
+  class SpecimenCollectionGroup
+    include Jinx::Unique
+  end
+
+  class Specimen
+    include Jinx::Unique
+  end
+
+  class ExternalIdentifier
+    include Jinx::Unique
+  end
+
+  class User
+    include Jinx::Unique
+    
+    # Makes this User's login id and email address unique.
+    # The result is in the form _name___suffix_+@test.com+
+    # where:
+    # * _name_ is the name prefix portion of the original email address
+    # * _suffix_ is a unique number
+    def uniquify
+      email = email_address ||= self.login_name || return
+      self.login_name = self.email_address = uniquify_value(email[/[^@]+/]) + '@test.com'
+    end
+  end
+end

data/lib/catissue/resource.rb

@@ -1,17 +1,12 @@
+require 'jinx/metadata/id_alias'
 require 'caruby/resource'
-require 'catissue/annotation/annotatable'
+require 'catissue/database'
 
+# The caTissue-specific Resource mix-in.
 module CaTissue
-  # The module included by all CaTissue domain classes.
-  #
-  # A Resource class is extended to support an attribute -> value hash argument
-  # to the initialize method. Subclasses which override the initialize method
-  # should not include the hash argument, since it is defined by a class
-  # instance new method override rather than initialize to work around a JRuby
-  # bug. 
   module Resource
-    include CaRuby::Resource, CaRuby::IdAlias, Annotatable
-    
+    include Jinx::IdAlias, CaRuby::Resource
+
     # Returns whether each of the given attribute values either equals the
     # respective other attribute value or one of the values is nil or 'Not Specified'.
     #
@@ -20,18 +15,18 @@ module CaTissue
     # @return [Boolean} whether this domain object is a tolerant match with the other
     #   domain object on the given attributes
     def tolerant_match?(other, attributes)
-      attributes.all? { |attr| Resource.tolerant_value_match?(send(attr), other.send(attr)) }
+      attributes.all? { |pa| Resource.tolerant_value_match?(send(pa), other.send(pa)) }
     end
 
-    # Returns the CaTissue::Database which stores this object.
+    # @return [Database] the database which stores this object
     def database
-      CaTissue::Database.instance
+      Database.instance
     end
 
     protected
 
     # Returns the required attributes which are nil for this domain object.
-    # Overrides the CaRuby::Resource method to handle the following bug:
+    # Overrides the Jinx::Resource method to handle the following bug:
     #
     # @quirk caTissue Bug #67:  AbstractSpecimen.setActivityStatus
     #   is a no-op. The Specimen activityStatus property is incorrectly pulled
@@ -51,16 +46,17 @@ module CaTissue
     end
 
     private
-    
-    # The unspecified value.
+
+    # The unspecified default value.
+    # @private
     UNSPECIFIED = 'Not Specified'
-    
-    # @return whether the given value equals the other value or one of the values is nil or 'Not Specified'
+
+    # @return [Boolean] whether the given value equals the other value or one of the values is nil or 'Not Specified'
     def self.tolerant_value_match?(value, other)
       value == other or unpsecified_value?(value) or unpsecified_value?(other)
     end
-    
-    # @return whether the given value equals nil or {Resource.UNSPECIFIED}
+
+    # @return [Boolean] whether the given value equals nil or {Resource.UNSPECIFIED}
     def self.unpsecified_value?(value)
       value.nil? or value == UNSPECIFIED
     end