caruby-tissue 1.2.1

data/History.txt

@@ -0,0 +1,4 @@
+=== 1.2.1 / 2010-11-23
+
+* Initial public release
+

data/LEGAL

@@ -0,0 +1,5 @@
+LEGAL NOTICE INFORMATION
+------------------------
+
+All the files in this distribution are covered under either the MIT
+license (see the file LICENSE).

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Oregon Health & Science University Knight Cancer Institute
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,44 @@
+caRuby Tissue: caTissue API facade
+===================================
+
+**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    
+
+caRuby presents a JRuby facade that simplifies interaction with caBIG applications.
+
+Feature List
+------------
+
+1. caTissue API wrapper.
+
+2. Built on the caRuby Core.
+
+3. Migration utility.
+
+Installing
+----------
+
+jgem install caruby-tissue
+
+Usage
+-----
+
+See the project [http://caruby.rubyforge.com](Home) Page for usage examples. 
+
+Changelog
+---------
+
+- **November.23.10**: 1.2.1 release
+    - Initial public release
+
+Copyright
+---------
+
+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.

data/bin/crtdump

@@ -0,0 +1,31 @@
+#!/usr/bin/env jruby
+#
+# crtdump: Dumps the content of a caTissue object to stdout
+#
+
+# 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
+
+# the default log file
+DEF_LOG_FILE = 'log/catissue.log'
+
+require 'catissue/cli/command'
+
+# run the command
+CaTissue::Command.new(:class, :id).execute do |opts, class_name, id|
+  # the search template
+  obj = CaTissue.const_get(class_name).new(:identifier=>id.to_i)
+  unless obj.find then
+    print("#{class_name} with identifier #{id} not found") and exit(-1)
+  end
+  # fetch the references
+  obj.references
+  # print the object graph
+  puts obj.dump
+end

data/bin/crtexample

@@ -0,0 +1,18 @@
+#!/usr/bin/env jruby
+#
+# crtexample: list and run caRuby Tissue examples
+#
+
+# 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
+
+require 'catissue/cli/example'
+
+# run the command
+CaTissue::CLI::Example.new.start

data/bin/crtextract

@@ -0,0 +1,47 @@
+#!/usr/bin/env jruby
+#
+# crtextract: extracts caTissue records which changed during a time interval
+#
+# == Usage
+#
+# catissue-extract.rb [options]
+#
+# --help, -h:
+#    print this help message and exit
+# --target, -t class:
+#    target class to extract (default Specimen)
+# --log file, -l file:
+#    log file (default ./log/migration.log)
+# --since date, -s date:
+#    earliest change date selection condition (optional)
+# --before date, -b date:
+#    latest change date selection condition (optional)
+# --on date, -b date:
+#    change date selection condition (optional)
+# --debug, -d:
+#    print debug messages to log (optional)
+#
+# See the ohsu distribution doc/extract.html file for more information.
+#
+# == License
+#
+# This program is licensed under the terms of the +LEGAL+ file in
+# the source distribution.
+#
+# load the required gems
+require 'rubygems'
+gem 'caruby-tissue'
+
+require 'catissue/cli/command'
+require 'catissue/extract/delta'
+require 'catissue/extract/extractor'
+
+# the command line specification
+spec = [
+  [:version, "--version", "prints the version of caRuby Tissue and the supported caTissue releases"],
+]
+
+# run the command
+CaRuby::Command.new(spec).execute do |opts|
+  if opts[:version] then puts "#{CaTissue::VERSION} for caTissue v#{CaTissue::CATISSUE_VERSIONS}" end
+end

data/bin/crtmigrate

@@ -0,0 +1,17 @@
+#!/usr/bin/env jruby
+#
+# crtmigrate: migrates a source file to caTissue
+#
+
+# 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
+
+require 'catissue/migration/command'
+
+CaTissue::MigrateCommand.new.execute

data/bin/crtsmoke

@@ -0,0 +1,27 @@
+#!/usr/bin/env jruby
+#
+# crtsmoke: Verifies a caTissue connection
+#
+
+# Don't print messages if the help or version option is set.
+quiet = ARGV.include?('--help') || ARGV.include?('--version')
+
+puts "Starting the smoke test..." unless quiet
+
+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
+
+puts "Loading the caTissue client..." unless quiet
+
+require 'catissue/cli/smoke'
+
+# run the command
+CaTissue::CLI::Smoke.new.start

data/examples/galena/README.md

@@ -0,0 +1,53 @@
+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 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.
+
+4. Define the caRuby Tissue access property file as described in
+   [http://caruby.tenderapp.com/faqs/getting-started/tissue_config](FAQ).
+
+Migration
+---------
+The example migration input data resides in the `data` directory.
+Each CSV input file holds one row for each specimen.
+
+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.
+
+Migrate the Galena `simple` example as follows:
+
+1. Open a console in the copied Galena example location.
+
+2. Run the following:
+
+      crtmigrate --file conf/migration/simple.yaml data/simple.yaml
+
+3. Check the test database and verify that a there is a collection protocol
+   named `Galena CP.
+   
+The other examples are run in a similar manner.

data/examples/galena/bin/migrate.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env jruby
+#
+# == Synopsis
+#
+# catissue-migrate-galena: migrates the Galena example to caTissue
+#
+# == Usage
+#
+# catissue-migrate-galena.rb [options] file
+#
+# See catissue-migrate.rb for the argments
+#
+# == License
+#
+# This program is licensed under the terms of the +LEGAL+ file in
+# the source distribution.
+
+# 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 example library to the Ruby class load path. 
+$:.unshift File.join(File.dirname(__FILE__), '..', 'examples', 'galena', 'lib')
+
+# the default log file
+DEF_LOG_FILE = 'log/migration.log'
+
+# Load the caRuby classes.
+require 'catissue'
+require 'catissue/migration/command'
+require 'galena/seed/defaults'
+
+# Seed the database, if necessary.
+Galena.seed
+
+# Migrate the example input using the command line arguments.
+CaTissue::CLI::Migrate.new.start

data/examples/galena/bin/seed.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env jruby
+#
+# == Synopsis
+#
+# catissue-seed-galena.rb: 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')
+  $:.unshift File.join(File.dirname(__FILE__), '..', 'examples', 'galena', 'lib')
+end
+
+# 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/examples/galena/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/examples/galena/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/examples/galena/conf/migration/filter_migration.yaml

@@ -0,0 +1,9 @@
+# This is the Galena filter example migration configuration file.
+
+# The field heading => CaTissue mapping file.
+mapping: examples/galena/conf/migration/filter_fields.yaml
+
+# The filter code.
+shims: examples/galena/lib/galena/migration/filter_shims.rb
+
+target: TissueSpecimen

data/examples/galena/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/examples/galena/conf/migration/frozen_migration.yaml

@@ -0,0 +1,9 @@
+# This is the Galena frozen example migration configuration file.
+# The frozen example extends the simple example with storage fields
+# and shims.
+
+mapping: examples/galena/conf/migration/frozen_fields.yaml
+
+shims: examples/galena/lib/galena/migration/frozen_shims.rb
+
+target: TissueSpecimen

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

@@ -0,0 +1,42 @@
+# 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
+
+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