caruby-tissue 1.2.1 → 1.2.2

data/examples/galena/doc/index.html

@@ -70,8 +70,8 @@ The use cases illustrate several common migration impediments:</p>
 <li><p>Copy the example into a location of your choosing.</p></li>
 <li><p>Configure a caTissue client to connect to a test caTissue instance, as described in the
 caTissue Technical Guide.</p></li>
-<li><p>Define the caRuby Tissue access property file as described in
-<a href="FAQ">http://caruby.tenderapp.com/faqs/getting-started/tissue_config</a>.</p></li>
+<li><p>Define the caRuby Tissue access property file as described in the configuration
+<a href="how-do-i-configure-caruby-to-work-with-catissue">FAQ</a>.</p></li>
 </ol>
 
 
@@ -90,16 +90,61 @@ For example, the <code>simple.csv</code> input file is migrated into caTissue us
 <li><p>Open a console in the copied Galena example location.</p></li>
 <li><p>Run the following:</p>
 
-<p>   crtmigrate --file conf/migration/simple.yaml data/simple.yaml</p></li>
-<li><p>Check the test database and verify that a there is a collection protocol
-named `Galena CP.</p></li>
+<p>   bin/seed</p>
+
+<p>This command initializes the administrative objects in the Galena test database,
+including the Galena collection protocol, site, cancer center, tissue bank and coordinator.</p></li>
+<li><p>Run the following:</p>
+
+<p>   crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv</p>
+
+<p>This command migrates the CSV record in the <code>simple.csv</code> input file into a caTissue
+<code>TissueSpecimen</code> based on the <code>simple_fields.yaml</code> mapping file.
+The command will take a couple of minutes to finish, since the less information
+you provide caRuby the more it works to fill in the missing bits. In the meantime,
+peruse the configuration and data files to see which data are migrated and
+where this data ends up in caTissue.</p></li>
+<li><p>Open the caTissue application on the test server and verify the content of the
+Galena CP collection protocol.</p></li>
 </ol>
 
 
-<p>The other examples are run in a similar manner.</p></div></div>
+<p>The other examples are run in a similar manner. Each example demonstrates different
+features of the caRuby Migration utility as follows:</p>
+
+<ul>
+<li>simple - a good starting point with limited input fields</li>
+<li>minimal - the fewest possible input fields without writing custom Ruby shim code</li>
+<li>general - lots of input fields, no custom Ruby code</li>
+<li>filter - a smattering of custom Ruby shim code to convert input values to caTissue values</li>
+<li>frozen - an example demonstrating how to import storage locations</li>
+</ul>
+
+
+<p>Try running an example with the <code>--debug</code> flag and look at the <code>log/migration.log</code> file to see
+what caRuby is up to behind the scenes (hint: a lot!).</p>
+
+<h2>Input data</h2>
+
+<p>The sample Galena Tissue Bank CSV input files hold one row for each specimen.
+Common fields are as follows:</p>
+
+<ul>
+<li>MRN - Patient Medical Record Number</li>
+<li>Initials - Patient name initials</li>
+<li>Frozen? - Flag indicating whether the specimen is frozen</li>
+<li>SPN - Surgical Pathology Number</li>
+<li>Collection Date - Date the specimen was acquired by the tissue bank</li>
+<li>Received Date - Date the specimen was donated by the participant</li>
+<li>Quantity - Amount collected</li>
+<li>Box - Tissue storage container</li>
+<li>X - the tissue box column</li>
+<li>Y - the tissue box row</li>
+</ul>
+</div></div>
     
     <div id="footer">
-  Generated on Tue Nov 23 11:38:42 2010 by 
+  Generated on Tue Nov 30 11:09:42 2010 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.6.1 (ruby-1.8.6).
 </div>

data/examples/galena/doc/method_list.html

@@ -77,14 +77,6 @@
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="CaTissue/TissueSpecimen.html#migrate-instance_method" title="CaTissue::TissueSpecimen#migrate (method)">#migrate</a></span> 
-    
-      <small>CaTissue::TissueSpecimen</small>
-    
-  </li>
-  
-
-  <li class="r2 ">
     <span class='object_link'><a href="CaTissue/StorageContainer.html#migrate-instance_method" title="CaTissue::StorageContainer#migrate (method)">#migrate</a></span> 
     
       <small>CaTissue::StorageContainer</small>
@@ -92,15 +84,15 @@
   </li>
   
 
-  <li class="r1 ">
-    <span class='object_link'><a href="CaTissue/CollectionProtocolRegistration.html#migrate-instance_method" title="CaTissue::CollectionProtocolRegistration#migrate (method)">#migrate</a></span> 
+  <li class="r2 ">
+    <span class='object_link'><a href="CaTissue/TissueSpecimen.html#migrate-instance_method" title="CaTissue::TissueSpecimen#migrate (method)">#migrate</a></span> 
     
-      <small>CaTissue::CollectionProtocolRegistration</small>
+      <small>CaTissue::TissueSpecimen</small>
     
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="CaTissue/Participant.html#migrate_first_name-instance_method" title="CaTissue::Participant#migrate_first_name (method)">#migrate_first_name</a></span> 
     
       <small>CaTissue::Participant</small>
@@ -108,7 +100,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="CaTissue/TissueSpecimen.html#migrate_initial_quantity-instance_method" title="CaTissue::TissueSpecimen#migrate_initial_quantity (method)">#migrate_initial_quantity</a></span> 
     
       <small>CaTissue::TissueSpecimen</small>
@@ -116,7 +108,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="CaTissue/Participant.html#migrate_last_name-instance_method" title="CaTissue::Participant#migrate_last_name (method)">#migrate_last_name</a></span> 
     
       <small>CaTissue::Participant</small>
@@ -124,7 +116,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="CaTissue/TissueSpecimen.html#migrate_specimen_type-instance_method" title="CaTissue::TissueSpecimen#migrate_specimen_type (method)">#migrate_specimen_type</a></span> 
     
       <small>CaTissue::TissueSpecimen</small>
@@ -132,7 +124,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="CaTissue/SpecimenCollectionGroup.html#migration_valid%3F-instance_method" title="CaTissue::SpecimenCollectionGroup#migration_valid? (method)">#migration_valid?</a></span> 
     
       <small>CaTissue::SpecimenCollectionGroup</small>
@@ -140,7 +132,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="Galena/Seed/Defaults.html#protocol-instance_method" title="Galena::Seed::Defaults#protocol (method)">#protocol</a></span> 
     
       <small>Galena::Seed::Defaults</small>
@@ -148,14 +140,6 @@
   </li>
   
 
-  <li class="r2 ">
-    <span class='object_link'><a href="Galena.html#resource-class_method" title="Galena.resource (method)">resource</a></span> 
-    
-      <small>Galena</small>
-    
-  </li>
-  
-
   <li class="r1 ">
     <span class='object_link'><a href="Galena.html#seed-class_method" title="Galena.seed (method)">seed</a></span> 
     

data/examples/galena/doc/top-level-namespace.html

@@ -103,7 +103,7 @@ the default log file
 </div>
     
     <div id="footer">
-  Generated on Tue Nov 23 11:38:43 2010 by 
+  Generated on Tue Nov 30 11:09:43 2010 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.6.1 (ruby-1.8.6).
 </div>

data/examples/galena/lib/galena/migration/frozen_shims.rb

@@ -1,7 +1,7 @@
-require 'galena/seed/defaults'
+# 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 
 
@@ -14,16 +14,6 @@ module CaTissue
       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.
@@ -36,14 +26,13 @@ module CaTissue
     
     private
     
-    # Creates a new box of type {Galena::Migration::Defaults#box_type} in a
-    # freezer of type {Galena::Migration::Defaults#freezer_type}.
+    # 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
-      self.site = defs.tissue_bank
       # 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

data/examples/galena/lib/galena/seed/defaults.rb

@@ -23,7 +23,8 @@ module Galena
     # 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.
+    # 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
   
@@ -39,7 +40,8 @@ module Galena
       def ensure_exists
         @protocol.find(:create)
         @hospital.find(:create)
-        @freezer_type.find(:create)
+        @surgeon.find(:create)
+        @box.find(:create)
       end
   
       private
@@ -74,7 +76,12 @@ module Galena
           :last_name => 'Gator', :first_name => 'Vesta', :address => addr.copy,
           :institution => galena, :department => dept, :cancer_research_group => crg)
   
-        @protocol = CaTissue::CollectionProtocol.new(:short_title => 'Galena CP', 
+        @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
@@ -84,13 +91,18 @@ module Galena
         # sets the CPE requirement inverse attribute in caRuby.
         CaTissue::TissueSpecimenRequirement.new(:collection_event => cpe, :specimen_type => 'Fixed Tissue')
   
-        # a storage container
+        # 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

data/lib/catissue/cli/command.rb

@@ -18,19 +18,22 @@ module CaTissue
     # Augments {CaRuby::CLI::Command} with caTissue-specific command line option handlers.
     class Command < CaRuby::CLI::Command
       # @see {CaRuby::CLI::Command#initialize}
-      def initialize(specs=[], &executor)
+      def initialize(specs=[])
         specs << VERSION_OPT
-        super { |opts| handle_catissue_options(opts, &executor) }
+        super
       end
       
       private
       
+      VERSION_OPT = [:version, "--version", "Prints the version of caRuby Tissue and the supported caTissue releases and exits"]
+
       # If the version option is set, then prints the version and exits.
       # Otherwise, extracts the connection command line options, adds them
       # to {CaTissue.access_properties}, and yields to the executor block.
       #
       # @param [{Symbol => Object}] opts the command line argument and option symbol => value hash
-      def handle_catissue_options(opts)
+      def handle_options(opts)
+        super
         if opts[:version] then
           puts "#{CaTissue::VERSION} for caTissue v#{CaTissue::CATISSUE_VERSIONS}"
         else
@@ -38,14 +41,8 @@ module CaTissue
             value = opts.delete(opt)
             CaTissue.access_properties[opt] = value if value
           end
-          yield(opts)
         end
       end
-      
-      private
-      
-      VERSION_OPT = [:version, "--version", "Prints the version of caRuby Tissue and the supported caTissue releases and exits"]
-
     end
   end
 end

data/lib/catissue/cli/migrate.rb

@@ -26,24 +26,25 @@ module CaTissue
       # as well as the {SPECS} command line specifications.
       #
       # @param (see CaRuby::CLI::Command#initialize)
-      def initialize(specs={}, &factory)
-        super(specs.merge(SPECS)) { |opts| migrate(opts, &factory) }
+      # @yield [opts] optional migrator factory
+      # @yieldparam [{Symbol => Object}] the {CaTissue::Migrator#initialize} creation options
+      # @see CaRuby::Command#run
+      def initialize(&factory)
+        super(SPECS) { |opts| migrate(opts, &factory) }
       end
   
+      private
+      
       # Starts a Migrator with the command-line options.
       #
       # @yield [target] operation on the migration target
       # @yieldparam [CaRuby::Resource] the migrated domain object 
       # @see CaRuby::Command#run
-      def migrate(opts, &factory)
-        super do |opts|
-          validate(opts)
-          migrator = block_given ? yield(opts) : Migrator.new(opts)
-          migrator.migrate
-        end
+      def migrate(opts)
+        validate(opts)
+        migrator = block_given? ? yield(opts) : CaTissue::Migrator.new(opts)
+        migrator.migrate_to_database
       end
-  
-      private
       
       def validate(opts)
         tgt = opts[:target]

data/lib/catissue/cli/smoke.rb

@@ -6,12 +6,12 @@ module CaTissue
     class Smoke < Command
       # Creates a new Smoke command.
       def initialize
-        super { |opts| execute(opts) }
+        super { |opts| execute }
       end
       
       private
       
-      DB_MSG = "Verifying database access by searching for the pre-defined 'In Transit' Site..."
+      DB_MSG = "Verifying database access by searching for the pre-defined #{CaTissue::Site::DEF_SITE_NAME} Site..."
       
       # Runs the smoke test.
       def execute
@@ -23,7 +23,7 @@ module CaTissue
       
       def find_in_transit_site
         begin
-          site = CaTissue::Site.new(:name => 'In Transit').find
+          site = CaTissue::Site.new(:name => CaTissue::Site::DEF_SITE_NAME).find
         rescue Exception => e
           logger.error("caTissue database access was unsuccessful - #{e}:\n#{e.backtrace.qp}")
           puts "caTissue database access was unsuccessful - #{e}."
@@ -31,11 +31,11 @@ module CaTissue
         end
         
         if site then
-          puts "The 'In Transit' Site was found with identifier #{site.identifier}."
+          puts "The #{CaTissue::Site::DEF_SITE_NAME} Site was found with identifier #{site.identifier}."
           puts "Smoke test successful."
           exit 0
         else
-          puts "The 'In Transit' Site was not found."
+          puts "The #{CaTissue::Site::DEF_SITE_NAME} Site was not found."
           puts "Smoke test unsuccessful."
           exit 69 # service unavailable error status
         end

data/lib/catissue/database.rb

@@ -270,14 +270,20 @@ module CaTissue
     # * caTissue alert - Bug #161: Specimen API disposal not reflected in result activity status.
     #   DisposalEventParameters create sets the owner Specimen activity_status to +Closed+ as a side-effect.
     #   Reflect this side-effect in the submitted DisposalEventParameters owner Specimen object.
+    # * Ensure that a {CaTissue::Participant} obj registrations reference an existing protocol.
+    #   This compensates for a hole in the storable template logic which does not recognize the
+    #   CPR CP references as a pre-requisite. TODO - isolate, report and fix.
     def create_object(obj)
 #      if CaTissue::SCGEventParameters === obj and obj.specimen_collection_group then
 #        return create_scg_event_parameters(obj) { super }
 #      elsif CaTissue::Specimen === obj and obj.is_available == false then
-      if CaTissue::Specimen === obj and not obj.available? then
-        # Note that the obj.is_available == false test is required as opposed to obj.is_available?,
-        # since a nil is_available flag does not imply an unavailable specimen.
-        return create_unavailable_specimen(obj) { super }
+      if CaTissue::Specimen === obj then
+        obj.add_defaults
+        if obj.is_available == false or obj.available_quantity.zero? then
+          # Note that the obj.is_available == false test is required as opposed to obj.is_available?,
+          # since a nil is_available flag does not imply an unavailable specimen.
+          return create_unavailable_specimen(obj) { super }
+        end
       end
       
       # standard create
@@ -418,11 +424,28 @@ module CaTissue
     end
 
     def fetch_participant_using_mrn(pnt)
-      mid = pnt.medical_identifiers.first
-      return if mid.nil?
+      pmi = pnt.medical_identifiers.first
+      return if pmi.nil?
       logger.debug { "Using alternative Participant fetch strategy to find Participant by medical record number..." }
-      return unless exists?(mid)
-      candidates = query(mid.copy, :participant)
+      
+      #
+      # TODO - hack to work around intricate add_default logic; ties in with the create participant hack in this class.
+      # FIX THIS!!
+      #
+      if pmi.site.nil? then
+        # fetch Participant CPR protocols if necessary
+        pnt.registrations.each do |reg|
+          pcl = reg.protocol || next
+          pcl.find unless pcl.identifier
+          reg.add_defaults
+        end
+        pnt.add_defaults
+      end
+      
+      # END OF HACK
+      
+      return unless exists?(pmi)
+      candidates = query(pmi.copy, :participant)
       candidates.first if candidates.size == 1
     end