caruby-tissue 1.2.1 → 1.2.2

data/lib/catissue/domain/abstract_specimen.rb

@@ -39,7 +39,7 @@ module CaTissue
     add_dependent_attribute(:specimen_characteristics, :autogenerated, :no_cascade_update_to_create)
 
     add_dependent_attribute(:specimen_events, :create_only, :disjoint, :no_cascade_update_to_create)
-    
+   
     set_attribute_inverse(:parent_specimen, :child_specimens)
     
     # caTissue alert - SCG specimens query result does not set the Specimen children and parent, even though they are

data/lib/catissue/domain/collection_protocol.rb

@@ -93,25 +93,27 @@ module CaTissue
       reg.nil? ? Array::EMPTY_ARRAY : reg.specimens
     end
 
-    # Adds specimens to this protocol. Arguments:
-    # * participant - the Participant from whom the specimen is collected
-    # * biospecimens - the collected top-level underived specimens
-    # * params - additional SCG parameters as described in {SpecimenCollectionGroup#merge} method
-    # If params does not include a :collectionProtocolEvent parameter, then the SCG is assigned
+    # Adds specimens to this protocol. The following parameter options are supported:
+    # * :participant - the Participant from whom the specimen is collected
+    # * :biospecimens - the collected top-level underived specimens
+    # * additional SCG parameters as described in {SpecimenCollectionGroup#merge}.
+    #
+    # If the options does not include a :collection_protocol_event, then the SCG is assigned
     # to the first collection event in this protocol.
-    # If params does not include a :specimen_collection_site parameter, then the SCG is assigned
-    # to the participant's collection site as determined by {Participant#collection_site}, if that
-    # can be uniquely determined.
+    # If the options does not include a :specimen_collection_site, then the SCG is assigned
+    # to the participant's collection site as determined by {Participant#collection_site},
+    # if that can be uniquely determined.
     #
-    # This add_specimens method adds the following association to params before calling the
-    # SpecimenCollectionGroup constructor:
+    # This add_specimens method adds the following parameter options before calling the
+    # {SpecimenCollectionGroup} constructor:
     # * :registration => a new CollectionProtocolRegistration for this protocol and the specified participant
     # If there is no :name parameter, then this method builds a new unique SCG name as this
     # CollectionProtocol's name followed by a unique suffix.
     #
-    # Returns a new SpecimenCollectionGroup for the given participant containing the specimens.
-    #
-    # Raises ArgumentError if the SpecimenCollectionGroup does not include all required attributes.
+    # @param [(<Specimen>, {Symbol => Object})] specimens_and_params the specimens to add followed
+    #   by the required parameter hash
+    # @return [SpecimenCollectionGroup] a new SCG for the given participant containing the specimens
+    # @raise [ArgumentError] if the {SpecimenCollectionGroup} does not include all required attributes
     def add_specimens(*specimens_and_params)
       params = specimens_and_params.pop
       spcs = specimens_and_params
@@ -136,6 +138,20 @@ module CaTissue
       spcs.each { |spc| spc.specimen_collection_group = scg }
       scg
     end
+    
+    # Returns the default protocol site, determined as follows:
+    # * If there is exactly one authorized site for this protocol, then that is the default site.
+    # * If there is exactly two authorized sites for this protocol, then the site other than the
+    #   {CaTissue::Site::DEF_SITE_NAME} is returned.
+    # * Otherwise, this method returns nil.
+    #
+    # @return [CaTissue::Site, nil] the default site
+    def default_site
+     case sites.size
+      when 1 then sites.first
+      when 2 then sites.select { |site| site.name != CaTissue::Site::DEF_SITE_NAME }
+      end
+    end
 
     private
 

data/lib/catissue/domain/participant_medical_identifier.rb

@@ -32,7 +32,7 @@ module CaTissue
     def default_site
       cprs = participant.registrations if participant
       cp = cprs.first.protocol if cprs and cprs.size == 1
-      cp.sites.first if cp and cp.sites.size == 1
+      cp.default_site if cp
     end
   end
 end

data/lib/catissue/domain/site.rb

@@ -5,6 +5,9 @@ module CaTissue
   # The Site domain class.
   class Site
     include Resource
+    
+    # The default pre-defined caTissue site name.
+    DEF_SITE_NAME = 'In Transit'
 
     # caTissue alert - the Site SCG collection is ignored, since it is not fetched with the Site,
     # the caCORE query builder doesn't support abstract types, and even if it worked it would

data/lib/catissue/domain/specimen.rb

@@ -91,10 +91,6 @@ module CaTissue
     # argument.
     qualify_attribute(:available_quantity, :autogenerated)
 
-    MERGEABLE_RQMT_ATTRS = nondomain_java_attributes - primary_key_attributes
-
-    MERGEABLE_SPC_CHR_ATTRS = SpecimenCharacteristics.nondomain_java_attributes - SpecimenCharacteristics.primary_key_attributes
-
     # Specimen storage is constrained on the basis of the +specimen_class+.
     alias :storable_type :specimen_class
 
@@ -181,20 +177,21 @@ module CaTissue
         raise ValidationError.new("#{self} available quantity #{available_quantity} cannot exceed initial quantity #{initial_quantity}")
       end
       if available? and available_quantity.zero? then
-        raise ValidationError.new("#{self} availablility flag cannot be set when the avaialble quantity is zero.")
+        raise ValidationError.new("#{self} availablility flag cannot be set when the avaialble quantity is zero")
       end
       if collected? then
         unless event_parameters.detect { |ep| CaTissue::CollectionEventParameters === ep } then
-          raise ValidationError.new("#{self} is missing CollectionEventParameters.")
+          raise ValidationError.new("#{self} is missing CollectionEventParameters")
         end
         unless event_parameters.detect { |ep| CaTissue::ReceivedEventParameters === ep } then
-          raise ValidationError.new("#{self} is missing ReceivedEventParameters.")
+          raise ValidationError.new("#{self} is missing ReceivedEventParameters")
         end
       end
     end
 
     # Returns the Specimen in others which matches this Specimen in the scope of an owner SCG.
-    # This method relaxes {CaRuby::Resource#match_in_owner_scope} to include a match on at least one external identifier.
+    # This method relaxes {CaRuby::Resource#match_in_owner_scope} to include a match on at least
+    # one external identifier.
     def match_in_owner_scope(others)
       super or others.detect do |other|
          external_identifiers.any? do |eid|
@@ -302,9 +299,9 @@ module CaTissue
       elsif specimen_collection_group.consent_tier_statuses.size == 1 then
         statuses.first
       elsif specimen_collection_group.consent_tier_statuses.size == 0 then
-        raise ValidationError.new("Specimen #{self} SCG does not have a consent tier status.")
+        raise ValidationError.new("Specimen #{self} SCG does not have a consent tier status")
       else
-        raise ValidationError.new("Specimen #{self} SCG consent tier is ambiguous:#{consent_tier_statuses.select { |cts| "\n  #{cts.statement}" }.to_series('or')}.")
+        raise ValidationError.new("Specimen #{self} SCG consent tier is ambiguous:#{consent_tier_statuses.select { |cts| "\n  #{cts.statement}" }.to_series('or')}")
       end
       ct = status.consent_tier
       cts = consent_tier_statuses.detect { |item| item.consent_tier == ct }
@@ -334,6 +331,10 @@ module CaTissue
 
     private
 
+    MERGEABLE_RQMT_ATTRS = nondomain_java_attributes - primary_key_attributes
+
+    MERGEABLE_SPC_CHR_ATTRS = SpecimenCharacteristics.nondomain_java_attributes - SpecimenCharacteristics.primary_key_attributes
+
     # Adds this Specimen's defaults, as follows:
     # * The default specimen_collection_group is the parent specimen_collection_group.
     # * Add default collection and received event parameters if this Specimen is collected.
@@ -358,10 +359,12 @@ module CaTissue
       self.specimen_collection_group ||= parent.specimen_collection_group if parent
       add_default_event_parameters
       
-      # The default available quantity is 0 if the is_available flag is false,
-      # otherwise the initial quantity.
-      self.available_quantity ||= is_available == false ? 0.0 : initial_quantity
-
+      # The default available quantity is the initial quantity.
+      aq = available_quantity
+      if aq.nil? or aq.zero? then
+        self.available_quantity = is_available == false ? 0.0 : initial_quantity
+      end
+      
       # The specimen is available by default if there is a positive available quantity.
       # If is_available is set to false, then set it to nil to work around a caTissue bug.
       self.is_available ||= available_quantity.zero? ? nil : true

data/lib/catissue/domain/specimen_collection_group.rb

@@ -271,14 +271,11 @@ module CaTissue
       each_dependent { |dep| yield dep unless ReceivedEventParameters === dep }
     end
 
-    # The default In Transit collection site.
-    DEF_SITE = Site.new(:name => 'In Transit')
-
     # Adds defaults as follows:
     # * the default collection event is the first event in the protocol registered with this SCG.
     # * the default collection status is 'Complete' if there is a received event, 'Pending' otherwise.
     # * the default collection site is the CP site, if this SCG is {#received?} and there is only CP one,
-    #   otherwise the 'In Transit' site.
+    #   otherwise the {CaTissue::Site::DEF_SITE_NAME} site.
     # * the default conset tier status is 'Complete' if there is a received event, 'Pending' otherwise.
     # * a default ReceivedEventParameters is added to this SCG if the collection status is
     #   'Complete' and there is no other ReceivedEventParameters. The receiver is an arbitrary
@@ -334,7 +331,7 @@ module CaTissue
 
     def default_site
       cp = collection_event.protocol if collection_event
-      cp && cp.sites.size == 1 ? cp.sites.first : DEF_SITE
+      cp.default_site if cp
     end
 
     # Returns the first event in the protocol registered with this SCG.

data/lib/catissue/extract/delta.rb

@@ -10,12 +10,6 @@ module CaTissue
   class Delta
     include Enumerable
 
-    private
-
-    SQL_FILE = File.join(File.dirname(__FILE__), '..', '..', '..', 'sql', 'delta.sql')
-
-    public
-
     # Creates a new Delta for objects of the given target type which changed
     # at or after the since Date and earlier but not at the before Date.
     # The default before Date is now.
@@ -36,6 +30,8 @@ module CaTissue
 
     private
 
+    SQL_FILE = File.join(File.dirname(__FILE__), '..', '..', '..', 'sql', 'delta.sql')
+
     # Returns the result of running the delta SQL on the target CaTissue domain class.
     def execute_query
       sql = File.open(SQL_FILE) { |file| file.read }

data/lib/catissue/migration/migrator.rb

@@ -33,6 +33,12 @@ module CaTissue
     # database or the migration must build a Participant and a CollectionProtocol.
     # 
     # @option (see CaRuby::Migrator#initialize)
+    # @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
+    # @option opts [String] :bad write each invalid record to the given file and continue migration
+    # @option opts [String] :offset zero-based starting source record number to process (default 0)
     def initialize(opts={})
       # if there is a configuration file, then add config options into the parameter options
       conf_file = opts.delete(:file)

data/lib/catissue/resource.rb

@@ -8,10 +8,13 @@ module CaTissue
   module Resource
     include 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'.
+    #
     # @param [Resource] other the domain object to compare
     # @param [<Symbol>] attributes the  attributes to compare
-    # @return [Boolean} whether each of the given attribute values either equals the
-    #   respective other attribute value or one of the values is nil or 'Not Specified'
+    # @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)) }
     end

data/lib/catissue/util/log.rb

@@ -12,15 +12,15 @@ module CaTissue
     # caTissue alert - avoid caTissue error by creating log subdirectory
     if File.directory?('log') then
       unless File.writable?('log') then
-        raise StandardError.new("caTissue log subdirectory #{File.expand_path('log')} is not writable.")
+        raise StandardError.new("caTissue log subdirectory #{File.expand_path('log')} is not writable")
       end
     elsif File.exists?('log') then
-      raise StandardError.new("Existing file #{File.expand_path('log')} prevents creation of the required caTissue log subdirectory.")
+      raise StandardError.new("Existing file #{File.expand_path('log')} prevents creation of the required caTissue log subdirectory")
     else
       begin
         Dir.mkdir('log')
       rescue Exception => e
-        raise StandardError.new("Cannot create the log subdirectory required by the caTissue client: #{File.expand_path('log')}.")
+        raise StandardError.new("Cannot create the log subdirectory required by the caTissue client: #{File.expand_path('log')}")
       end
     end
   end

data/lib/catissue/version.rb

@@ -1,6 +1,6 @@
 module CaTissue
   # The version of this caRuby Tissue release.
-  VERSION = "1.2.1"
+  VERSION = "1.2.2"
   
   # The supported caTissue release versions.
   CATISSUE_VERSIONS = "1.1.2"

data/{examples/galena/bin → lib/galena/cli}/seed.rb

@@ -40,4 +40,4 @@ require 'catissue/cli/command'
 
 require 'galena/seed/defaults'
 
-CaTissue::Command.new.start { Galena::Seed.defaults.ensure_exists }
+CaTissue::Command.new.execute { Galena::Seed.defaults.ensure_exists }

data/lib/galena/migration/filter_shims.rb

@@ -0,0 +1,43 @@
+require 'uom'
+
+module CaTissue
+
+  # Declares the classes modified for migration.
+  shims Participant, TissueSpecimen, SpecimenCollectionGroup
+
+  class Participant
+    # Extracts the Participant first name from the +Initials+ input field.
+    def migrate_first_name(value, row)
+      self.first_name = value[0, 1]
+    end
+
+    # Extracts the Participant last name from the +Initials+ input field.
+    def migrate_last_name(value, row)
+      self.last_name = value[-1, 1]
+    end
+  end
+
+  class TissueSpecimen
+    # Transforms the +Frozen?+ flag input field to the caTissue specimen type +Frozen Tissue+ value.
+    def migrate_specimen_type(value, row)
+      'Frozen Tissue' if value =~ /TRUE/i
+    end
+
+    # Parses the source field as a UOM::Measurement if it is a string.
+    # Otherwises, returns the source value.
+    def migrate_initial_quantity(value, row)
+      # 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 SpecimenCollectionGroup
+    # Returns whether this SCG has a SPN.
+    def migration_valid?
+      surgical_pathology_number
+    end
+  end
+end

data/lib/galena/migration/frozen_shims.rb

@@ -0,0 +1,53 @@
+# load the defaults file in the seed directory
+require File.join(File.dirname(__FILE__), '..', 'seed', 'defaults')
+
+module CaTissue
+  # Declares the classes modified for migration.
+  shims TissueSpecimen, CollectionProtocolRegistration, StorageContainer 
+
+  class TissueSpecimen
+    # Sets the specimen type to +Frozen Tissue+.
+    #
+    # @param (see CaRuby::Migratable#migrate)
+    def migrate(row, migrated)
+      super
+      self.specimen_type = 'Frozen Tissue'
+    end
+  end
+  
+  class CollectionProtocolRegistration
+    # Sets this CPR's protocol to the pre-defined {Galena::Migration::Defaults#protocol}.
+    #
+    # @param (see CaRuby::Migratable#migrate)
+    def migrate(row, migrated)
+      super
+      self.protocol = Galena::Seed.defaults.protocol
+    end
+  end
+
+  class StorageContainer
+    # Creates the migrated box in the database, if necessary.
+    #
+    # @param (see CaRuby::Migratable#migrate)
+    def migrate(row, migrated)
+      super
+      find or create_box
+    end
+    
+    private
+    
+    # Creates a new box of type {Galena::Seed::Defaults#box_type} in a freezer of type
+    # {Galena::Seed::Defaults#freezer_type}.
+    # 
+    # @return [StorageContainer] the new box
+    def create_box
+      defs = Galena::Seed.defaults
+      self.storage_type = defs.box_type
+      # A freezer with a spot for the box
+      frz = defs.freezer_type.find_available(site, :create)
+      if frz.nil? then raise CaRuby::MigrationError.new("Freezer not available to place #{self}") end
+      # Add this box to the first open slot in the first unfilled rack in the freezer.
+      frz << self
+    end
+  end
+end

data/lib/galena/seed/defaults.rb

@@ -0,0 +1,109 @@
+require 'singleton'
+require 'catissue'
+
+module Galena
+  # Creates the {Galena::Seed::Defaults} administrative objects as necessary.
+  def self.seed
+    Seed.defaults.ensure_exists
+  end
+  
+  # Galena example utility module to populate the database with pre-defined administrative objects.
+  module Seed
+    # @return [Defaults] the defaults instance
+    def self.defaults
+      Defaults.instance
+    end
+  
+    # Pre-defined Galena example administrative objects. If the Galena example is already set up
+    # in the caTissue database, then the default object secondary key attributes can be used as a
+    # {CaRuby::Persistable#find} template to retrieve the existing objects. Otherwise, the Defaults
+    # attributes can be created by calling {CaRuby::Persistable#create}.
+    #
+    # In a real-world use case, the administrative objects are typically built in the UI before-hand.
+    # In that case, it is only necessary to define the object secondary key rather than content, e.g.:
+    #   pcl = CaTissue::CollectionProtocol.new(:short_title => 'Galena CP')
+    # The complete definitions are included in this method for convenience in order to seed the
+    # example in a test database. A real-world migration might find it useful to create a similar
+    # defaults file in order to rapidly seed an empty test or staging database.
+    class Defaults
+      include Singleton
+  
+      attr_reader :protocol, :hospital, :tissue_bank, :freezer_type, :box_type
+  
+      # Creates the Galena example Defaults singleton and populates the attributes.
+      def initialize
+        super
+        populate
+      end
+      
+      # Creates the Galena example administrative objects as necessary.
+      def ensure_exists
+        @protocol.find(:create)
+        @hospital.find(:create)
+        @surgeon.find(:create)
+        @box.find(:create)
+      end
+  
+      private
+  
+      # Sets the Galena example Defaults attributes to new objects.
+      def populate
+        galena = CaTissue::Institution.new(:name => 'Galena University')
+  
+        addr = CaTissue::Address.new(
+          :city => 'Galena', :state => 'Illinois', :country => 'United States', :zipCode => '37544',
+          :street => '411 Basin St', :phoneNumber => '311-555-5555')
+  
+        dept = CaTissue::Department.new(:name => 'Pathology')
+  
+        crg = CaTissue::CancerResearchGroup.new(:name => 'Don Thomas Cancer Center')
+  
+        coord = CaTissue::User.new(
+          :email_address => 'corey.nator@galena.edu',
+          :last_name => 'Nator', :first_name => 'Corey', :address => addr.copy,
+          :institution => galena, :department => dept, :cancer_research_group => crg)
+  
+        @hospital = CaTissue::Site.new(
+            :site_type => CaTissue::Site::SiteType::COLLECTION, :name => 'Galena Hospital', 
+            :address => addr, :coordinator => coord)
+  
+        @tissue_bank = CaTissue::Site.new(
+            :site_type => CaTissue::Site::SiteType::REPOSITORY, :name => 'Galena Tissue Bank', 
+            :address => addr, :coordinator => coord)
+  
+        pi = CaTissue::User.new(
+          :email_address => 'vesta.gator@galena.edu',
+          :last_name => 'Gator', :first_name => 'Vesta', :address => addr.copy,
+          :institution => galena, :department => dept, :cancer_research_group => crg)
+  
+        @surgeon = CaTissue::User.new(
+          :email_address => 'serge.on@galena.edu',
+          :first_name => 'Serge', :last_name => 'On', :address => addr.copy,
+          :institution => galena, :department => dept, :cancer_research_group => crg)
+  
+        @protocol = CaTissue::CollectionProtocol.new(:short_title => 'Galena Migration', 
+          :principal_investigator => pi, :sites => [@tissue_bank])
+  
+        # CPE has default 1.0 event point and label
+        cpe = CaTissue::CollectionProtocolEvent.new(:collection_protocol => @protocol)
+        
+        # the sole specimen requirement. Setting the requirement collection_event attribute to a CPE automatically
+        # sets the CPE requirement inverse attribute in caRuby.
+        CaTissue::TissueSpecimenRequirement.new(:collection_event => cpe, :specimen_type => 'Fixed Tissue')
+  
+        # the storage container type hierarchy
+        @freezer_type = CaTissue::StorageType.new(:name => 'GTB Freezer', :columns => 10, :rows => 1, :column_label => 'Rack')
+        rack_type = CaTissue::StorageType.new(:name => 'GTB Rack', :columns => 10, :rows => 10)
+        @box_type = CaTissue::StorageType.new(:name => 'GTB Box', :columns => 10, :rows => 10)
+        @freezer_type << rack_type
+        rack_type << box_type
+        @box_type << 'Tissue'
+        
+        # a sample freezer and box
+        frz = CaTissue::StorageContainer.new(:name => 'GTB Freezer 1', :storage_type=>@freezer_type, :site=>@tissue_bank)
+        @box = CaTissue::StorageContainer.new(:name => 'GTB Box 1', :storage_type=>@box_type)
+        frz << @box
+      end
+    end
+  end
+end