caruby-tissue 1.4.2 → 1.5.1

data/History.md

@@ -0,0 +1,53 @@
+This history lists major release themes. See the GitHub Commits (https://github.com/caruby/tissue)
+for change details.
+
+1.5.1 / 2011-06-15
+------------------
+* Annotation refactoring.
+
+1.4.2 / 2011-05-04
+------------------
+* Add registration and PCBIN examples.
+
+1.4.1 / 2011-05-03
+------------------
+* caTissue 1.2 support.
+
+1.3.6 / 2011-03-04
+------------------
+* Specify caruby-core gem version dependency.
+
+1.3.5 / 2011-03-04
+------------------
+* Annotation migration.
+
+1.3.4 / 2011-02-26
+------------------
+* Use caruby-core JRuby 1.5 bug work-around.
+
+1.3.3 / 2011-02-26
+------------------
+* JRuby 1.5 upgrade.
+
+1.3.2 / 2011-02-25
+------------------
+* Migration bug fixes.
+
+1.3.1 / 2011-02-18
+------------------
+* Prostate Spore PCBIN DE support.
+
+1.2.3 / 2011-02-18
+------------------
+* Dynamic Extensions Support.
+
+1.2.2 / 2010-11-30
+------------------
+* Galena example.
+
+1.2.1 / 2010-11-23
+------------------
+* Initial public release.
+
+* embed Java-caRuby bridge subproject.
+

data/bin/crtdump

@@ -5,12 +5,7 @@
 
 # load the caruby-tissue gem
 require 'rubygems'
-begin
-  gem 'caruby-tissue'
-rescue LoadError
-  # if the gem is not available, then try a local source
-  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
-end
+gem 'caruby-tissue'
 
 # the default log file
 DEF_LOG_FILE = 'log/catissue.log'

data/bin/crtexample

@@ -5,12 +5,7 @@
 
 # load the caruby-tissue gem
 require 'rubygems'
-begin
-  gem 'caruby-tissue'
-rescue LoadError
-  # if the gem is not available, then try a local source
-  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
-end
+gem 'caruby-tissue'
 
 require 'catissue/cli/example'
 

data/bin/crtmigrate

@@ -5,12 +5,7 @@
 
 # load the required gems
 require 'rubygems'
-begin
-  gem 'caruby-tissue'
-rescue LoadError
-  # if the gem is not available, then try a local source
-  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
-end
+gem 'caruby-tissue'
 
 require 'catissue/cli/migrate'
 

data/bin/crtsmoke

@@ -12,12 +12,7 @@ puts "Loading the caruby-tissue gem..." unless quiet
 
 # load the caruby-tissue gem
 require 'rubygems'
-begin
-  gem 'caruby-tissue'
-rescue LoadError
-  # if the gem is not available, then try a local source
-  $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
-end
+gem 'caruby-tissue'
 
 puts "Loading the caTissue client..." unless quiet
 

data/conf/migration/filter_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 MRN: ParticipantMedicalIdentifier.medical_record_number
 Initials: Participant.first_name, Participant.last_name
 Frozen?: TissueSpecimen.specimen_type

data/conf/migration/general_fields.yaml

@@ -1,7 +1,7 @@
 # This is the Galena general example migration field mapping file in the format:
 #   input field: caTissue property
 
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 
 Collection Site: Site.name
 

data/conf/migration/simple_fields.yaml

@@ -11,7 +11,7 @@
 # * the pre-defined Rubyized underscore form of the Java property, e.g. last_name
 
 # The collection protocol title for the specimen
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 
 # The input MRN field is used for the PMI MRN, CPR PPI and Participant last name.
 # Since the migration source is for a single collection site, the MRN is unique within the protocol.

data/conf/migration/small_fields.yaml

@@ -3,7 +3,7 @@
 # The example does not use a shim.
 
 # The collection protocol title for the specimen
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 
 # The input MRN field is used for the PMI MRN, CPR PPI and Participant last name
 MRN: ParticipantMedicalIdentifier.medical_record_number, Participant.last_name

data/examples/galena/README.md

@@ -45,14 +45,14 @@ Migrate the Galena `simple` example as follows:
 
 2. Run the following:
 
-      bin/seed
+   `bin/seed`
    
    This command initializes the administrative objects in the Galena test database,
    including the Galena collection protocol, site, cancer center, tissue bank and coordinator.
 
 3. Run the following:
 
-      crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv
+   `crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv`
 
    This command migrates the CSV record in the `simple.csv` input file into a caTissue
    `TissueSpecimen` based on the `simple_fields.yaml` mapping file.
@@ -65,20 +65,29 @@ Migrate the Galena `simple` example as follows:
 The other examples are run in a similar manner. Each example demonstrates different
 features of the caRuby Migration utility as follows:
 
-* `simple` - a good starting point with limited input fields
-   `crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv` 
+* <tt>simple</tt> - a good starting point with limited input fields
 
-* `general` - lots of input fields, no custom Ruby code
-   `crtmigrate --target TissueSpecimen --mapping conf/migration/general_fields.yaml data/general.csv`
+  `crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv`
 
-* `filter` - a smattering of custom Ruby shim code to convert input values to caTissue values
-   `crtmigrate --target TissueSpecimen --mapping conf/migration/filter_fields.yaml data/filter.csv`
+* <tt>general</tt> - lots of input fields, no custom Ruby code
 
-* `frozen` - an example demonstrating how to import storage locations
-   `crtmigrate --target TissueSpecimen --mapping conf/migration/frozen_fields.yaml --defaults conf/migration/frozen_defaults.yaml data/frozen.csv` 
+  `crtmigrate --target TissueSpecimen --mapping conf/migration/general_fields.yaml data/general.csv`
 
-* `annotation` - an example demonstrating how to import annotations
-   `crtmigrate --target TissueSpecimen --mapping conf/migration/annotation_fields.yaml --defaults conf/migration/annotation_defaults.yaml data/annotation.csv `
+* <tt>filter</tt> - a smattering of custom Ruby shim code to convert input values to caTissue values and reject an incomplete migration
+
+  `crtmigrate --target TissueSpecimen --mapping conf/migration/filter_fields.yaml --shims lib/galena/tissue/migration/filter_shims.rb --bad bad.csv data/filter.csv`
+
+* <tt>frozen</tt> - storage locations
+
+  `crtmigrate --target TissueSpecimen --mapping conf/migration/frozen_fields.yaml --defaults conf/migration/frozen_defaults.yaml --shims lib/galena/tissue/migration/frozen_shims.rb data/frozen.csv`
+
+* <tt>annotation</tt> - Dynamic Extension annotations
+
+  `crtmigrate --target TissueSpecimen --mapping conf/migration/annotation_fields.yaml --defaults conf/migration/annotation_defaults.yaml data/annotation.csv`
+
+* <tt>registration</tt> - register participants in a Collection Protocol without specimens
+
+  `crtmigrate --target SpecimenCollectionGroup --mapping conf/migration/registration_fields.yaml data/registration.csv`
 
 Try running an example with the `--debug` flag and look at the `log/migration.log` file to see
 what caRuby is up to behind the scenes (hint: a lot!).
@@ -88,17 +97,17 @@ Input data
 The sample Galena Tissue Bank CSV input files hold one row for each specimen.
 The following input fields are included in the examples:
 
-* `Protocol` - Collection Protocol title
-* `MRN` - Patient Medical Record Number
-* `Initials` - Patient name initials
-* `Frozen?` - Flag indicating whether the specimen is frozen
-* `SPN` - Surgical Pathology Number
-* `Collection Date` - Date the specimen was acquired by the tissue bank
-* `Received Date` - Date the specimen was donated by the participant
-* `Quantity` - Amount collected
-* `Box` - Tissue storage container
-* `X` - the tissue box column
-* `Y` - the tissue box row
-* `Gleason`: Specimen primary gleason score
-* `Grade`: Specimen histologic WHO grade
+* <tt>Protocol</tt> - Collection Protocol title
+* <tt>MRN</tt> - Patient Medical Record Number
+* <tt>Initials</tt> - Patient name initials
+* <tt>Frozen?</tt> - Flag indicating whether the specimen is frozen
+* <tt>SPN</tt> - Surgical Pathology Number
+* <tt>Collection Date</tt> - Date the specimen was acquired by the tissue bank
+* <tt>Received Date</tt> - Date the specimen was donated by the participant
+* <tt>Quantity</tt> - Amount collected
+* <tt>Box</tt> - Tissue storage container
+* <tt>X</tt> - the tissue box column
+* <tt>Y</tt> - the tissue box row
+* <tt>Gleason</tt>: Specimen primary gleason score
+* <tt>Grade</tt>: Specimen histologic WHO grade
 

data/examples/galena/bin/seed

@@ -5,12 +5,7 @@
 
 # load the caRuby Tissue gem
 require 'rubygems'
-begin
-  gem 'caruby-tissue'
-rescue LoadError
-  # if the gem is not available, then try a local source
-  $:.unshift File.join(File.dirname(__FILE__), '..', '..', '..', 'lib')
-end
+gem 'caruby-tissue'
 
 # add the Galena lib to the path
 $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
@@ -21,6 +16,6 @@ DEF_LOG_FILE = 'log/migration.log'
 require 'catissue'
 require 'catissue/cli/command'
 
-require 'galena/seed/defaults'
+require 'galena/tissue/seed/defaults'
 
 CaTissue::CLI::Command.new.start { Galena::Seed.defaults.ensure_exists }

data/examples/galena/conf/migration/annotation_fields.yaml

@@ -1,7 +1,7 @@
 # This is the Galena annotation example migration field mapping file.
 # This example extends the simple migration with annotation fields.
 
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 MRN: ParticipantMedicalIdentifier.medical_record_number, Participant.last_name
 SPN: SpecimenCollectionGroup.surgical_pathology_number
 Gleason: SpecimenCollectionGroup::Pathology::GleasonScore.primary_pattern_score

data/examples/galena/conf/migration/filter_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 MRN: ParticipantMedicalIdentifier.medical_record_number
 Initials: Participant.first_name, Participant.last_name
 Frozen?: TissueSpecimen.specimen_type

data/examples/galena/conf/migration/frozen_fields.yaml

@@ -2,11 +2,11 @@
 # This example extends the simple migration with storage fields
 # and the frozen defaults.
 
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 MRN: ParticipantMedicalIdentifier.medical_record_number, Participant.last_name
 SPN: SpecimenCollectionGroup.surgical_pathology_number
 Collection Date: ReceivedEventParameters.timestamp
 Quantity: TissueSpecimen.initial_quantity
-Box: SpecimenPosition.container.name
+Box: StorageContainer.name
 X: SpecimenPosition.position_dimension_one
 Y: SpecimenPosition.position_dimension_two

data/examples/galena/conf/migration/general_fields.yaml

@@ -1,7 +1,7 @@
 # This is the Galena general example migration field mapping file in the format:
 #   input field: caTissue property
 
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 
 Collection Site: Site.name
 

data/examples/galena/conf/migration/registration_fields.yaml

@@ -1,3 +1,4 @@
+Protocol: CollectionProtocol.title
 Patient: ParticipantMedicalIdentifier.medical_record_number
 Collection Point: CollectionProtocolEvent.collection_point_label
 Received: ReceivedEventParameters.timestamp

data/examples/galena/conf/migration/simple_fields.yaml

@@ -11,7 +11,7 @@
 # * the pre-defined Rubyized underscore form of the Java property, e.g. last_name
 
 # The collection protocol title for the specimen
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 
 # The input MRN field is used for the PMI MRN, CPR PPI and Participant last name.
 # Since the migration source is for a single collection site, the MRN is unique within the protocol.

data/examples/galena/data/frozen.csv

@@ -1 +1 @@
-Protocol,MRN,SPN,Collection Date,Quantity,Box,X,Y
+Protocol,MRN,SPN,Collection Date,Quantity,Box,X,Y

data/examples/galena/data/general.csv

@@ -1 +1 @@
-Protocol,Collection Site,MRN,First Name,Last Name,PPI,SPN,Collection Point,Receiver,Received Timestamp,Collector,Collected Timestamp,Diagnosis,Anatomic Site,Development,Label,Type,Quantity,Box,X,Y
+Protocol,Collection Site,MRN,First Name,Last Name,PPI,SPN,Collection Point,Receiver,Received Timestamp,Collector,Collected Timestamp,Diagnosis,Anatomic Site,Development,Label,Type,Quantity,Box,X,Y

data/examples/galena/data/registration.csv

@@ -1 +1 @@
-Patient,Collection Point,Received,SCG Name
+Protocol,Patient,Collection Point,Received,SCG Name

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

@@ -22,13 +22,17 @@ module CaTissue
     # @return [StorageContainer] the new box
     def create_galena_box
       defs = Galena::Seed.defaults
-      self.storage_type = defs.box_type
-      site = defs.tissue_bank
+      # the box container type
+      self.container_type = defs.box_type
+      # the required box site
+      self.site = defs.tissue_bank
       # A freezer with a slot 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.
+      # Add the box to the first open slot in the first unfilled rack in the freezer.
       frz << self
+      logger.debug { "Placed the tissue box #{self} in freezer #{frz}." }
+      logger.debug { "Creating the tissue box #{self}..." }
+      create
     end
   end
 end

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

@@ -21,7 +21,7 @@ module Galena
     #
     # 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')
+    #   pcl = CaTissue::CollectionProtocol.new(: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.
@@ -42,7 +42,11 @@ module Galena
         @protocols.each { |pcl| pcl.find(:create) }
         @hospital.find(:create)
         @surgeon.find(:create)
-        @box_type.find(:create)
+        unless @box.find then
+          frz = @freezer_type.find_available(@tissue_bank, :create)
+          frz << @box
+          @box.create
+        end
       end
       
       # @return [CaTissue::CollectionProtocol] the primary example protocol
@@ -87,7 +91,7 @@ module Galena
           :first_name => 'Serge', :last_name => 'On', :address => addr.copy,
           :institution => galena, :department => dept, :cancer_research_group => crg)
   
-        @protocols << pcl = CaTissue::CollectionProtocol.new(:short_title => 'Galena Migration', 
+        @protocols << pcl = CaTissue::CollectionProtocol.new(:title => 'Galena Migration', 
           :principal_investigator => pi, :sites => [@tissue_bank])
   
         # CPE has default 1.0 event point and label
@@ -97,23 +101,26 @@ module Galena
         # sets the CPE requirement inverse attribute in caRuby.
         CaTissue::TissueSpecimenRequirement.new(:collection_event => cpe, :specimen_type => 'Fixed Tissue')
   
-        @protocols << pcl2 = CaTissue::CollectionProtocol.new(:short_title => 'Galena Migration 2', 
+        @protocols << pcl2 = CaTissue::CollectionProtocol.new(:title => 'Galena Migration 2', 
           :principal_investigator => pi, :sites => [@tissue_bank])
         cpe2 = CaTissue::CollectionProtocolEvent.new(:collection_protocol => pcl2, :event_point => 2.0, :label => 'Galena Migration_2')
         CaTissue::TissueSpecimenRequirement.new(:collection_event => cpe2, :specimen_type => 'Frozen Tissue')
   
-        @protocols << pcl3 = CaTissue::CollectionProtocol.new(:short_title => 'Galena Migration 3', 
+        @protocols << pcl3 = CaTissue::CollectionProtocol.new(:title => 'Galena Migration 3', 
           :principal_investigator => pi, :sites => [@tissue_bank])
         cpe3 = CaTissue::CollectionProtocolEvent.new(:collection_protocol => pcl3, :event_point => 3.0, :label => 'Galena Migration_3')
         CaTissue::TissueSpecimenRequirement.new(:collection_event => cpe3, :specimen_type => 'Frozen 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 = CaTissue::StorageType.new(:name => 'Galena Freezer', :columns => 10, :rows => 1, :column_label => 'Rack')
+        rack_type = CaTissue::StorageType.new(:name => 'Galena Rack', :columns => 10, :rows => 10)
+        @box_type = CaTissue::StorageType.new(:name => 'Galena Box', :columns => 10, :rows => 10)
         @freezer_type << rack_type
-        rack_type << box_type
+        rack_type << @box_type
         @box_type << 'Tissue'
+        
+        # the example tissue box
+        @box = @box_type.new_container(:name => 'Galena Box 1')
       end
     end
   end

data/examples/pcbin/README.md

@@ -9,26 +9,26 @@ data elements. The official PCBIN import utility is a Java program which operate
 special-purpose input XML file and calls caRuby to create annotations. The example shown
 here is a caRuby Tissue Migrator import which operates on CSV files.
 
-The migration input files are in the +data+ directory. The input maps to +caTissue+ entities as follows:
+The migration input files are in the `data` directory. The input maps to caTissue entities as follows:
 
-* +patient+ => +Participant+
+* `patient` => `Participant`
 
-* +biopsy+ => prostate biopsy +SpecimenCollectionGroup+
+* `biopsy` => prostate biopsy `SpecimenCollectionGroup`
 
-* +surgery+ => prostatectomy +SpecimenCollectionGroup+
+* `surgery` => prostatectomy `SpecimenCollectionGroup`
 
-* +t_stage+ => the tumor stage as a lab annotation
+* `t_stage` => the tumor stage as a lab annotation
 
-* (+neo+)+adjuvant_hormone+ => (neo)adjuvant hormone therapy annotation
+* (`neo`)`adjuvant_hormone` => (neo)adjuvant hormone therapy annotation
 
-* (+neo+)+adjuvant_radiation+ => (neo)adjuvant radiation therapy annotation
+* (`neo`)`adjuvant_radiation` => (neo)adjuvant radiation therapy annotation
 
 Setup
 -----
 Configure caRuby and copy the PCBIN example as described in the Galena examples
 [Setup](https://github.com/caruby/tissue/blob/master/examples/galena/README.md).
 
-Create a simple +Prostate SPORE+ caTissue collection protocol in a test database.
+Create a simple `Prostate SPORE` caTissue collection protocol in a test database.
 
 Migration
 ---------