caruby-tissue 1.3.6 → 1.4.2

data/History.txt

@@ -1,22 +1,25 @@
+This history lists major release themes. See the GitHub source (https://github.com/caruby/tissue)
+for change details.
+
 === 1.2.1 / 2010-11-23
 
 * Initial public release.
 
 === 1.2.2 / 2010-11-30
 
-* Enable Galena example.
+* Galena example.
 
 === 1.2.3 / 2011-02-18
 
-* Support Dynamic Extensions.
+* Dynamic Extensions Support.
 
 === 1.3.1 / 2011-02-18
 
-* Full PCBIN DE support.
+* Prostate Spore PCBIN DE support.
 
 === 1.3.2 / 2011-02-25
 
-* Minor migration bug fixes.
+* Migration bug fixes.
 
 === 1.3.3 / 2011-02-26
 
@@ -28,10 +31,20 @@
 
 === 1.3.5 / 2011-03-04
 
-* Support annotation migration.
-
+* Annotation migration.
 
 === 1.3.6 / 2011-03-04
 
-* Specify caruby-core version dependency.
+* Specify caruby-core gem version dependency.
+
+=== 1.4.1 / 2011-05-03
+
+* caTissue 1.2 support.
+
+* embed Java-caRuby bridge subproject.
+
+=== 1.4.2 / 2011-05-04
+
+* Add registration and PCBIN examples.
+
 

data/README.md

@@ -1,99 +1,46 @@
-Galena caRuby Tissue example
-============================
+caRuby Tissue: Simplifying caTissue
+===================================
+
+**Home**:         [http://caruby.rubyforge.org/catissue.html](http://caruby.rubyforge.org/catissue.html)    
+**Git**:          [http://github.com/caruby/tissue](http://github.com/caruby/tissue)       
+**Author**:       OHSU Knight Cancer Institute    
+**Copyright**:    2010, 2011    
+**License**:      MIT License    
 
 Synopsis
 --------
-This directory contains the caRuby Tissue example for the hypothetical Galena Cancer Center.
-The example files are a useful template for building your own migrator.
-
-The Galena example demonstrates how to load the content of a custom tissue bank into caTissue.
-The use cases illustrate several common migration impediments:
-
-* Different terminology than caTissue
-* Different associations than caTissue
-* Incomplete input for caTissue
-* Denormalized input
-* Inconsistent input
-* Input data scrubbing
-* Aliquot inference
-* Pre-defined caTissue protocol
-
-Setup
------
-1. Run the `crtexample --list` command to display the Galena example location.
-
-2. Copy the example into a location of your choosing.
 
-3. Configure a caTissue client to connect to a test caTissue instance, as described in the
-   caTissue Technical Guide.
+caRuby Tissue presents a JRuby facade that simplifies interaction with the
+[caTissue](https://cabig-kc.nci.nih.gov/Biospecimen/KC/index.php/CaTissue_Suite) application.
 
-4. Define the caRuby Tissue access property file as described in the configuration
-   [FAQ](how-do-i-configure-caruby-to-work-with-catissue).
-
-Migration
----------
-The example migration input data resides in the `data` directory.
-Each CSV input file holds one row for each specimen.
+Feature List
+------------
 
-Each example has a field mapping configuration in the `conf/migration` directory.
-For example, the `simple.csv` input file is migrated into caTissue using the
-`simple_migration.yaml` configuration file.
+1. Declarative JRuby API that reduces caTissue API complexity.
 
-Migrate the Galena `simple` example as follows:
+2. Data migration and extraction.
 
-1. Open a console in the copied Galena example location.
+See the project [Home](http://caruby.rubyforge.org/catissue.html) Page for a more complete feature list.
 
-2. Run the following:
-
-      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
-
-   This command migrates the CSV record in the `simple.csv` input file into a caTissue
-   `TissueSpecimen` based on the `simple_fields.yaml` 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.
-   
-4. Open the caTissue application on the test server and verify the content of the
-   Galena CP collection protocol.
-   
-The other examples are run in a similar manner. Each example demonstrates different
-features of the caRuby Migration utility as follows:
+Installing
+----------
+caRuby Tissue is installed as a JRuby gem:
+    sudo jgem install caruby-tissue
 
-* simple - a good starting point with limited input fields
-* minimal - the fewest possible input fields without writing custom Ruby shim code
-* general - lots of input fields, no custom Ruby code
-* filter - a smattering of custom Ruby shim code to convert input values to caTissue values
-* frozen - an example demonstrating how to import storage locations
+The caRuby Tissue [FAQ](https://caruby.tenderapp.com/dashboard/sections/tissue) describes how to
+configure caRuby to access your caTissue instance.
 
-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!).
+Usage
+-----
 
-Input data
-----------
-The sample Galena Tissue Bank CSV input files hold one row for each specimen.
-Common fields are as follows:
+The [Galena Example](https://github.com/caruby/tissue/blob/master/examples/galena/README.md) presents
+a migration use case.
 
-* 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
+The caRuby Tissue [FAQ](https://caruby.tenderapp.com/dashboard/sections/tissue) contains caRuby Tissue API examples.
 
 Copyright
 ---------
 
 caRuby © 2010, 2011 by [Oregon Health & Science University](http://www.ohsu.edu/xd/health/services/cancer/index.cfm).
-caRuby is licensed under the MIT license. Please see the LICENSE and LEGAL files for more information.
+caRuby is licensed under the MIT license. Please see the LICENSE and LEGAL
+files for more information.

data/conf/wustl/log4j.properties

@@ -0,0 +1,40 @@
+log4j.rootLogger==ERROR, clientLog, catissuecoreclientLog
+
+log4j.appender.clientLog=org.apache.log4j.FileAppender
+log4j.appender.clientLog.File=./log/client.log
+log4j.appender.clientLog.layout=org.apache.log4j.PatternLayout
+log4j.appender.clientLog.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n
+
+log4j.appender.catissuecoreclientLog=org.apache.log4j.FileAppender
+log4j.appender.catissuecoreclientLog.File=./log/catissuecoreclient.log
+log4j.appender.catissuecoreclientLog.layout=org.apache.log4j.PatternLayout
+log4j.appender.catissuecoreclientLog.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1} - %m%n
+
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n
+
+### set log levels - for more verbose logging change 'info' to 'debug' ###
+
+log4j.rootLogger=warn, clientLog
+
+log4j.logger.org.hibernate=info
+
+## log the SQL
+log4j.logger.org.hibernate.SQL=debug
+
+### log JDBC bind parameters ###
+log4j.logger.org.hibernate.type=info
+
+### log schema export/update ###
+log4j.logger.org.hibernate.tool.hbm2ddl=debug
+
+### log cache activity ###
+#log4j.logger.org.hibernate.cache=debug
+
+### log JDBC resource acquisition
+#log4j.logger.org.hibernate.jdbc=debug
+
+### enable the following line if you want to track down connection ###
+### leakages when using DriverManagerConnectionProvider ###
+#log4j.logger.org.hibernate.connection.DriverManagerConnectionProvider=trace

data/examples/galena/README.md

@@ -4,9 +4,9 @@ Galena caRuby Tissue example
 Synopsis
 --------
 This directory contains the caRuby Tissue example for the hypothetical Galena Cancer Center.
-The example files are a useful template for building your own migrator.
+The example files are a useful starting point for configuring your own migration.
 
-The Galena example demonstrates how to load the content of a custom tissue bank into caTissue.
+The Galena example demonstrates how to load the content of a source tissue bank into caTissue.
 The use cases illustrate several common migration impediments:
 
 * Different terminology than caTissue
@@ -15,8 +15,8 @@ The use cases illustrate several common migration impediments:
 * Denormalized input
 * Inconsistent input
 * Input data scrubbing
+* Specimen annotations
 * Aliquot inference
-* Pre-defined caTissue protocol
 
 Setup
 -----
@@ -56,9 +56,7 @@ Migrate the Galena `simple` example as follows:
 
    This command migrates the CSV record in the `simple.csv` input file into a caTissue
    `TissueSpecimen` based on the `simple_fields.yaml` 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
+   Peruse the configuration and data files to see which data are migrated and
    where this data ends up in caTissue.
    
 4. Open the caTissue application on the test server and verify the content of the
@@ -67,11 +65,20 @@ 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
-* minimal - the fewest possible input fields without writing custom Ruby shim code
-* general - lots of input fields, no custom Ruby code
-* filter - a smattering of custom Ruby shim code to convert input values to caTissue values
-* frozen - an example demonstrating how to import storage locations
+* `simple` - a good starting point with limited input fields
+   `crtmigrate --target TissueSpecimen --mapping conf/migration/simple_fields.yaml data/simple.csv` 
+
+* `general` - lots of input fields, no custom Ruby code
+   `crtmigrate --target TissueSpecimen --mapping conf/migration/general_fields.yaml data/general.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`
+
+* `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` 
+
+* `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 `
 
 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!).
@@ -79,15 +86,19 @@ what caRuby is up to behind the scenes (hint: a lot!).
 Input data
 ----------
 The sample Galena Tissue Bank CSV input files hold one row for each specimen.
-Common fields are as follows:
-
-* 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
+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
+

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

@@ -0,0 +1,2 @@
+SpecimenCollectionGroup::Pathology::RadicalProstatectomyPathologyAnnotation.comment: Imported annotation
+SpecimenCollectionGroup::Pathology::HistologicGrade.grading_system_name: WHO Grade I

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

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

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

@@ -0,0 +1 @@
+TissueSpecimen.specimen_type: Frozen Tissue

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

@@ -0,0 +1,4 @@
+SSN: Participant.social_security_number
+First: Participant.first_name
+Middle: Participant.middle_name
+Last: Participant.last_name

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

@@ -0,0 +1,4 @@
+Patient: ParticipantMedicalIdentifier.medical_record_number
+Collection Point: CollectionProtocolEvent.collection_point_label
+Received: ReceivedEventParameters.timestamp
+SCG Name: SpecimenCollectionGroup.name

data/examples/galena/data/annotation.csv

@@ -0,0 +1 @@
+Protocol,MRN,SPN,Gleason,Grade

data/examples/galena/data/participant.csv

@@ -0,0 +1 @@
+SSN,First,Middle,Last

data/examples/galena/data/registration.csv

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

data/examples/galena/lib/galena/{migration → tissue/migration}/filter_shims.rb

@@ -1,19 +1,18 @@
 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]
+      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]
+      value[-1, 1]
     end
   end
 

data/examples/galena/lib/galena/{migration → tissue/migration}/frozen_shims.rb

@@ -4,16 +4,6 @@ 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 StorageContainer
     # Creates the migrated box in the database, if necessary.

data/examples/galena/lib/galena/{seed → tissue/seed}/defaults.rb

@@ -28,20 +28,26 @@ module Galena
     class Defaults
       include Singleton
   
-      attr_reader :protocol, :hospital, :tissue_bank, :freezer_type, :box_type
+      attr_reader :protocols, :hospital, :tissue_bank, :freezer_type, :box_type
   
       # Creates the Galena example Defaults singleton and populates the attributes.
       def initialize
         super
+        @protocols = []
         populate
       end
       
       # Creates the Galena example administrative objects as necessary.
       def ensure_exists
-        @protocol.find(:create)
+        @protocols.each { |pcl| pcl.find(:create) }
         @hospital.find(:create)
         @surgeon.find(:create)
-        @box.find(:create)
+        @box_type.find(:create)
+      end
+      
+      # @return [CaTissue::CollectionProtocol] the primary example protocol
+      def protocol
+        @protocols.first
       end
   
       private
@@ -65,11 +71,11 @@ module Galena
   
         @hospital = CaTissue::Site.new(
             :site_type => CaTissue::Site::SiteType::COLLECTION, :name => 'Galena Hospital', 
-            :address => addr, :coordinator => coord)
+            :address => addr.copy, :coordinator => coord)
   
         @tissue_bank = CaTissue::Site.new(
             :site_type => CaTissue::Site::SiteType::REPOSITORY, :name => 'Galena Tissue Bank', 
-            :address => addr, :coordinator => coord)
+            :address => addr.copy, :coordinator => coord)
   
         pi = CaTissue::User.new(
           :email_address => 'vesta.gator@galena.edu',
@@ -81,16 +87,26 @@ module Galena
           :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', 
+        @protocols << pcl = 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)
+        cpe = CaTissue::CollectionProtocolEvent.new(:collection_protocol => pcl, :event_point => 1.0, :label => 'Galena Migration_1')
         
-        # the sole specimen requirement. Setting the requirement collection_event attribute to a CPE automatically
+        # 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')
   
+        @protocols << pcl2 = CaTissue::CollectionProtocol.new(:short_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', 
+          :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)