caruby-tissue 1.2.1 → 1.2.2

data/History.txt

@@ -2,3 +2,7 @@
 
 * Initial public release
 
+=== 1.2.2 / 2010-11-30
+
+* Enable Galena example
+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Oregon Health & Science University Knight Cancer Institute
+Copyright (c) 2010 Oregon Health & Science University
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -1,44 +1,93 @@
-caRuby Tissue: caTissue API facade
-===================================
+Galena caRuby Tissue example
+============================
 
-**Home**:         [http://caruby.rubyforge.com](http://caruby.rubyforge.com) 
-**Git**:          [http://github.com/caruby/tissue](http://github.com/caruby/tissue)
-**Author**:       OHSU Knight Cancer Institute    
-**Copyright**:    2010    
-**License**:      MIT License    
-**Latest Version**: 1.2.1    
-**Release Date**: November 23rd 2010    
+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.
 
-caRuby presents a JRuby facade that simplifies interaction with caBIG applications.
+The Galena example demonstrates how to load the content of a custom tissue bank into caTissue.
+The use cases illustrate several common migration impediments:
 
-Feature List
-------------
+* 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
 
-1. caTissue API wrapper.
+Setup
+-----
+1. Run the `crtexample --list` command to display the Galena example location.
 
-2. Built on the caRuby Core.
+2. Copy the example into a location of your choosing.
 
-3. Migration utility.
+3. Configure a caTissue client to connect to a test caTissue instance, as described in the
+   caTissue Technical Guide.
 
-Installing
-----------
+4. Define the caRuby Tissue access property file as described in the configuration
+   [FAQ](how-do-i-configure-caruby-to-work-with-catissue).
 
-jgem install caruby-tissue
+Migration
+---------
+The example migration input data resides in the `data` directory.
+Each CSV input file holds one row for each specimen.
 
-Usage
------
+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.
 
-See the project [http://caruby.rubyforge.com](Home) Page for usage examples. 
+Migrate the Galena `simple` example as follows:
 
-Changelog
----------
+1. Open a console in the copied Galena example location.
 
-- **November.23.10**: 1.2.1 release
-    - Initial public release
+2. Run the following:
 
-Copyright
----------
+      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:
+
+* 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
+
+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!).
+
+Input data
+----------
+The sample Galena Tissue Bank CSV input files hold one row for each specimen.
+Common fields are as follows:
 
-caRuby © 2010 by [Oregon Health & Science University](mailto:loneyf@ohsu.edu).
-caRuby is licensed under the MIT license. Please see the LICENSE and LEGAL
-files for more information.
+* 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

data/bin/crtmigrate

@@ -12,6 +12,6 @@ rescue LoadError
   $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 end
 
-require 'catissue/migration/command'
+require 'catissue/cli/migrate'
 
-CaTissue::MigrateCommand.new.execute
+CaTissue::CLI::Migrate.new.start

data/bin/seed

@@ -0,0 +1,26 @@
+#!/usr/bin/env jruby
+#
+# seed: seeds the Galena example administrative objects in the database
+#
+
+# 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
+
+# add the Galena lib to the path
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+# the default log file
+DEF_LOG_FILE = 'log/migration.log'
+
+require 'catissue'
+require 'catissue/cli/command'
+
+require 'galena/seed/defaults'
+
+CaTissue::CLI::Command.new.start { Galena::Seed.defaults.ensure_exists }

data/bin/seed.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env jruby
+#
+# crtseed-galena: seeds the Galena example administrative objects in the database
+#
+# == Usage
+#
+# catissue-seed-galena.rb [options] file
+#
+# --help, -h:
+# print this help message and exit
+#
+# --log file, -l file:
+# log file (default ./log/migration.log)
+#
+# --debug, -d:
+# print debug messages to log (optional)
+#
+# == License
+#
+# This program is licensed under the terms of the +LEGAL+ file in
+# the source distribution.
+
+# 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
+
+# add the Galena lib to the path
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+# the default log file
+DEF_LOG_FILE = 'log/migration.log'
+
+require 'catissue'
+require 'catissue/cli/command'
+
+require 'galena/seed/defaults'
+
+CaTissue::Command.new.start { Galena::Seed.defaults.ensure_exists }

data/conf/extract/simple_fields.yaml

@@ -0,0 +1,4 @@
+MRN: specimen_collection_group.registration.participant_identifier
+SPN: specimen_collection_group.surgical_pathology_number
+Collection Date: specimen_collection_group.collection_event_parameters.timestamp
+Quantity: initial_quantity

data/conf/migration/filter_fields.yaml

@@ -0,0 +1,7 @@
+Protocol: CollectionProtocol.short_title
+MRN: ParticipantMedicalIdentifier.medical_record_number
+Initials: Participant.first_name, Participant.last_name
+Frozen?: TissueSpecimen.specimen_type
+SPN: SpecimenCollectionGroup.surgical_pathology_number
+Collection Date: ReceivedEventParameters.timestamp
+Quantity: TissueSpecimen.initial_quantity

data/conf/migration/frozen_fields.yaml

@@ -0,0 +1,11 @@
+# This is the Galena frozen example migration field mapping file.
+# This example extends the simple migration with storage fields
+# and the frozen defaults.
+
+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
+X: SpecimenPosition.position_dimension_one
+Y: SpecimenPosition.position_dimension_two

data/conf/migration/general_fields.yaml

@@ -0,0 +1,44 @@
+# This is the Galena general example migration field mapping file in the format:
+#   input field: caTissue property
+
+Protocol: CollectionProtocol.short_title
+
+Collection Site: Site.name
+
+SPN: SpecimenCollectionGroup.surgical_pathology_number
+
+PPI: CollectionProtocolRegistration.protocol_participant_identifier
+
+MRN: ParticipantMedicalIdentifier.medical_record_number
+
+First Name: Participant.first_name
+
+Last Name: Participant.last_name
+
+Collection Point: CollectionProtocolEvent.event_point
+
+Receiver: ReceivedEventParameters.user.login_name
+
+Received Timestamp: ReceivedEventParameters.timestamp
+
+Collector: CollectionEventParameters.user.login_name
+
+Collected Timestamp: CollectionEventParameters.timestamp
+
+Diagnosis: SpecimenCollectionGroup.clinical_diagnosis
+
+Anatomic Site: SpecimenCharacteristics.tissue_site
+
+Development: TissueSpecimen.pathological_status
+
+Label: TissueSpecimen.label
+
+Type: TissueSpecimen.specimen_type
+
+Quantity: TissueSpecimen.initial_quantity
+
+Box: SpecimenPosition.container.name
+
+X: SpecimenPosition.position_dimension_one
+
+Y: SpecimenPosition.position_dimension_two

data/conf/migration/simple_fields.yaml

@@ -0,0 +1,30 @@
+# This is the Galena simple example migration field mapping file.
+# Each entry is in the format:
+#   heading: paths
+# The heading is the CSV file label in the leading heading record.
+# The paths is a comma-separated list of CaTissue domain object attribute paths specifying
+# how the CSV heading maps to a CaTissue attribute value. Each attribute path is in the format:
+#   class.attribute[.attribute]
+# where class is a CaTissue class and attribute is a Ruby accessor method defined in the CaTissue class.
+# The accessor method can be one of the following:
+# * a Java property name, e.g. lastName
+# * 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
+
+# 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.
+# The simple input does not have a Participant name field. It is a useful practice to set the caTissue
+# name to some value, since caTissue uses the name for display and sorting. For want of a better
+# value, the name is set to the MRN.
+MRN: ParticipantMedicalIdentifier.medical_record_number, Participant.last_name
+
+# The input SPN field is the SCG SPN value.
+SPN: SpecimenCollectionGroup.surgical_pathology_number
+
+# The input Collection Date is the Specimen received timestamp.
+Collection Date: ReceivedEventParameters.timestamp
+
+# The input Quantity is the target Specimen initial quantity.
+Quantity: Specimen.initial_quantity

data/examples/galena/README.md

@@ -27,8 +27,8 @@ Setup
 3. Configure a caTissue client to connect to a test caTissue instance, as described in the
    caTissue Technical Guide.
 
-4. Define the caRuby Tissue access property file as described in
-   [http://caruby.tenderapp.com/faqs/getting-started/tissue_config](FAQ).
+4. Define the caRuby Tissue access property file as described in the configuration
+   [FAQ](how-do-i-configure-caruby-to-work-with-catissue).
 
 Migration
 ---------
@@ -45,9 +45,49 @@ Migrate the Galena `simple` example as follows:
 
 2. Run the following:
 
-      crtmigrate --file conf/migration/simple.yaml data/simple.yaml
+      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:
 
-3. Check the test database and verify that a there is a collection protocol
-   named `Galena CP.
+      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.
+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
+
+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!).
+
+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

data/examples/galena/bin/seed

@@ -0,0 +1,26 @@
+#!/usr/bin/env jruby
+#
+# seed: seeds the Galena example administrative objects in the database
+#
+
+# 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
+
+# add the Galena lib to the path
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+# the default log file
+DEF_LOG_FILE = 'log/migration.log'
+
+require 'catissue'
+require 'catissue/cli/command'
+
+require 'galena/seed/defaults'
+
+CaTissue::CLI::Command.new.start { Galena::Seed.defaults.ensure_exists }

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

@@ -2,6 +2,7 @@
 # This example extends the simple migration with storage fields
 # and the frozen defaults.
 
+Protocol: CollectionProtocol.short_title
 MRN: ParticipantMedicalIdentifier.medical_record_number, Participant.last_name
 SPN: SpecimenCollectionGroup.surgical_pathology_number
 Collection Date: ReceivedEventParameters.timestamp