caruby-tissue 1.5.2 → 1.5.3

data/History.md

@@ -1,6 +1,10 @@
 This history lists major release themes. See the GitHub Commits (https://github.com/caruby/tissue)
 for change details.
 
+1.5.3 / 2011-07-08
+------------------
+* Clean up documentation.
+
 1.5.2 / 2011-07-06
 ------------------
 * Update embed to use the annotation hook attribute.
@@ -11,7 +15,7 @@ for change details.
 
 1.4.2 / 2011-05-04
 ------------------
-* Add registration and PCBIN examples.
+* Add registration and PSBIN examples.
 
 1.4.1 / 2011-05-03
 ------------------
@@ -39,7 +43,7 @@ for change details.
 
 1.3.1 / 2011-02-18
 ------------------
-* Prostate Spore PCBIN DE support.
+* Prostate Spore PSBIN DE support.
 
 1.2.3 / 2011-02-18
 ------------------

data/examples/galena/README.md

@@ -39,6 +39,14 @@ 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.
 
+You can browse the source repository [example files](https://github.com/caruby/tissue/tree/master/examples/galena), where:
+
+* `conf/migration` has the mapping configuration files
+
+* `data` has the sample data
+
+* `lib/galena/tissue/migration` has the shim code
+
 Migrate the Galena `simple` example as follows:
 
 1. Open a console in the copied Galena example location.
@@ -111,3 +119,4 @@ The following input fields are included in the examples:
 * <tt>Gleason</tt>: Specimen primary gleason score
 * <tt>Grade</tt>: Specimen histologic WHO grade
 
+The fields listed are those used in the examples. caTissue supports any caTissue domain object.

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

@@ -1,29 +1,40 @@
 require 'uom'
 
 module CaTissue
-  # Declares the classes modified for migration.
+  # Declare 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)
+      # The first initial is the first "name".
       value[0, 1]
     end
 
     # Extracts the Participant last name from the +Initials+ input field.
+    #
+    # @param [String] value the input initials field
+    # @param @param [{Symbol => Object}] row the input row field => value hash
     def migrate_last_name(value, row)
+      # The last initial is the last "name".
       value[-1, 1]
     end
   end
 
   class TissueSpecimen
     # Transforms the +Frozen?+ flag input field to the caTissue specimen type +Frozen Tissue+ value.
+    #
+    # @param [String] value the input specimen type field
+    # @param @param [{Symbol => Object}] row the input row field => value hash
     def migrate_specimen_type(value, row)
       value =~ /TRUE/i ? 'Frozen Tissue' : 'Fixed Tissue'
     end
 
     # Parses the source field as a UOM::Measurement if it is a string.
     # Otherwises, returns the source value.
+    #
+    # @param [String, Numeric] value the input quantity field
+    # @param @param [{Symbol => Object}] row the input row field => value hash
     def migrate_initial_quantity(value, row)
       # if value is not a string, then use it as is
       return value unless value.is_a?(String)
@@ -34,9 +45,9 @@ module CaTissue
   end
 
   class SpecimenCollectionGroup
-    # Returns whether this SCG has a SPN.
+    # @return [Boolean] whether this SCG has a SPN
     def migration_valid?
-      surgical_pathology_number
+      not surgical_pathology_number.nil?
     end
   end
 end

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

@@ -2,15 +2,18 @@
 require File.join(File.dirname(__FILE__), '..', 'seed', 'defaults')
 
 module CaTissue
-  # Declares the classes modified for migration.
+  # Declare the classes modified for migration.
   shims TissueSpecimen, CollectionProtocolRegistration, StorageContainer 
   
   class StorageContainer
     # Creates the migrated box in the database, if necessary.
     #
-    # @param (see CaRuby::Migratable#migrate)
+    # @param [{Symbol => Object}] row the input row field => value hash
+    # @param [<Resource>] migrated the migrated instances
     def migrate(row, migrated)
       super
+      # Fetch the box from the database, if it exists.
+      # Otherwise, create the box.
       find or create_galena_box
     end
     
@@ -31,7 +34,7 @@ module CaTissue
       # 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}..." }
+      logger.debug { "Creating the tissue box #{self} in the database..." }
       create
     end
   end

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

@@ -16,8 +16,8 @@ module Galena
   
     # Pre-defined Galena example administrative objects. If the Galena example is already set up
     # in the caTissue database, then the default object secondary key attributes can be used as a
-    # {CaRuby::Persistable#find} template to retrieve the existing objects. Otherwise, the Defaults
-    # attributes can be created by calling {CaRuby::Persistable#create}.
+    # +CaRuby::Persistable.find+ template to retrieve the existing objects. Otherwise, the Defaults
+    # attributes can be created by calling +CaRuby::Persistable.create+.
     #
     # 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.:

data/examples/{pcbin → psbin}/README.md

@@ -1,11 +1,12 @@
-PCBIN caRuby Tissue example
+PSBIN caRuby Tissue example
 ============================
 
 Synopsis
 --------
-This directory contains the caRuby Tissue example for the Prostate SPORE PCBIN initiative.
-The PCBIN initiative shares participant cancer center data in caTissue instances with common
-data elements. The official PCBIN import utility is a Java program which operates on a
+This directory contains the caRuby Tissue example for the **P**rostate **S**PORE **B**io**I**nformatics **N**etwork
+(PSBIN) initiative.
+The PSBIN initiative shares participant cancer center data in caTissue instances with common
+data elements. The official PSBIN import utility is a Java program which operates on a
 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.
 
@@ -25,7 +26,7 @@ The migration input files are in the `data` directory. The input maps to caTissu
 
 Setup
 -----
-Configure caRuby and copy the PCBIN example as described in the Galena examples
+Configure caRuby and copy the PSBIN 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.

data/examples/psbin/conf/adjuvant_hormone_defaults.yaml

@@ -0,0 +1,2 @@
+Participant::Clinical::TreatmentAnnotation.agent: NOT SPECIFIED
+Participant::Clinical::TreatmentAnnotation.other_agent: adjuvant Hormone Therapy; Not Specified

data/examples/psbin/conf/adjuvant_radiation_defaults.yaml

@@ -0,0 +1,3 @@
+Participant::Clinical::RadRXAnnotation.agent: NOT SPECIFIED
+Participant::Clinical::RadRXAnnotation.other_agent: adjuvant Radiation Therapy
+Participant::Clinical::RadRXAnnotation.dose_units: Gy

data/examples/{pcbin → psbin}/conf/biopsy_defaults.yaml

@@ -1,3 +1,3 @@
-Participant::Clinical::NewDiagnosisHealthAnnotation.name_of_procedure: Biopsy of Prostate
+Participant::Clinical::NewDiagnosisHealthAnnotation.name_of_procedure: Needle Biopsy of prostate
 SpecimenCollectionGroup.clinical_status: New Diagnosis
 SpecimenCollectionGroup.collection_status: Complete

data/examples/{pcbin → psbin}/conf/neoadjuvant_hormone_defaults.yaml

@@ -1 +1,2 @@
+Participant::Clinical::TreatmentAnnotation.agent: NOT SPECIFIED
 Participant::Clinical::TreatmentAnnotation.other_agent: Neoadjuvant Hormone Therapy

data/examples/{pcbin → psbin}/conf/neoadjuvant_radiation_defaults.yaml

@@ -1,2 +1,3 @@
+Participant::Clinical::RadRXAnnotation.agent: NOT SPECIFIED
 Participant::Clinical::RadRXAnnotation.other_agent: Neoadjuvant Radiation Therapy
 Participant::Clinical::RadRXAnnotation.dose_units: Gy

data/examples/psbin/conf/patient_defaults.yaml

@@ -0,0 +1,3 @@
+Participant::Clinical::LabAnnotation.lab_test_name: 2857-1 ~ Prostate specific Ag - Serum/Plasma - Quantitative - Mass Concentration - Point in time
+Participant::Clinical::LabAnnotation.other_lab_test_name: Pre-Treatment PSA
+Participant::Clinical::LabAnnotation.result_units: ng/ml

data/examples/{pcbin → psbin}/conf/surgery_defaults.yaml

@@ -1,3 +1,4 @@
+Participant::Clinical::TreatmentAnnotation.agent: NOT SPECIFIED
 Participant::Clinical::TreatmentAnnotation.other_agent: Radical Prostatectomy
 SpecimenCollectionGroup.clinical_status: Operative
 SpecimenCollectionGroup.collection_status: Complete

data/lib/catissue/annotation/annotatable_class.rb

@@ -11,12 +11,12 @@ module CaTissue
     #   annotation objects, or nil if this is not a primary annotation class
     attr_reader :entity_id
       
-    # @return [Class] the {DEIntegration} proxy class (nil for 1.1 caTissue)
+    # @return [Class] the {Annotation::DEIntegration} proxy class (nil for 1.1 caTissue)
     def de_integration_proxy_class
       @de_integration_proxy_class or (superclass.de_integration_proxy_class if superclass < Annotatable)
     end
     
-    # Adds {CaRuby::Domain::Metadata} and {AnnotatableClass} functionality to the given class.
+    # Adds +CaRuby::Domain::Metadata+ and {AnnotatableClass} functionality to the given class.
     #
     # @param [Class] the domain class to extend
     def self.extend_class(klass)
@@ -61,7 +61,7 @@ module CaTissue
       annotation_defined?(symbol)
     end
 
-    # Refines the {CaRuby::Domain::Attributes#toxic_attributes} to exclude annotation attributes.
+    # Refines the +CaRuby::Domain::Attributes.toxic_attributes+ to exclude annotation attributes.
     #
     # @return [<Symbol>] the non-annotation unfetched attributes
     def toxic_attributes
@@ -90,7 +90,7 @@ module CaTissue
       end
     end
 
-    # Filters {CaRuby::Domain::Attributes#loadable_attributes} to exclude the {#annotation_attributes}
+    # Filters +CaRuby::Domain::Attributes.loadable_attributes+ to exclude the {#annotation_attributes}
     # since annotation lazy-loading is not supported.
     #
     # @return (see CaRuby::Domain::Attributes#loadable_attributes)

data/lib/catissue/annotation/annotation_class.rb

@@ -52,7 +52,7 @@ module CaTissue
       @ann_attrs ||= domain_attributes.compose { |attr_md| attr_md.type < Annotation }
     end
 
-    # Filters {CaRuby::Domain::Attributes#loadable_attributes} to exclude all references,
+    # Filters +CaRuby::Domain::Attributes.loadable_attributes+ to exclude all references,
     # since annotation lazy-loading is not supported.
     #
     # @return [Array] an empty array
@@ -73,7 +73,7 @@ module CaTissue
       not ref.nil?
     end
     
-    # @return [Boolean] whether this annotation is neither a {#primary?} nor a #{secondary} annotation
+    # @return [Boolean] whether this annotation is neither a {#primary?} nor a {#secondary?} annotation
     def tertiary_annotation
       not (primary? or secondary?)
     end

data/lib/catissue/annotation/annotation_module.rb

@@ -15,7 +15,7 @@ module CaTissue
     # @return [Class] the hook-annotation association class, or nil for 1.1.x caTissue
     attr_reader :record_entry_class
       
-    # @return [Symbol] the {#de_integration_proxy_class} hook writer method, or nil for 1.1.x caTissue
+    # @return [Symbol] the {Annotation::ProxyClass} hook writer method, or nil for 1.1.x caTissue
     attr_reader :record_entry_hook_writer
 
     # @param [AnnotationModule] mod the annotation module to build

data/lib/catissue/cli/command.rb

@@ -6,7 +6,7 @@ begin
 rescue Exception => e
   logger.error("caTissue client load was unsuccessful - #{e}:\n#{e.backtrace.qp}")
   puts "caTissue client load was unsuccessful - #{e}."
-  puts "See the log at #{CaRuby::Log.instance.file} for more information."
+  puts "See the log at #+CaRuby::Log.instance.file+ for more information."
   exit 1
 end
 
@@ -15,9 +15,9 @@ require 'catissue/version'
 
 module CaTissue
   module CLI
-    # Augments {CaRuby::CLI::Command} with caTissue-specific command line option handlers.
+    # Augments +CaRuby::CLI::Command+ with caTissue-specific command line option handlers.
     class Command < CaRuby::CLI::Command
-      # @see {CaRuby::CLI::Command#initialize}
+      # @see +CaRuby::CLI::Command.initialize+
       def initialize(specs=[])
         specs << VERSION_OPT
         super

data/lib/catissue/database.rb

@@ -7,17 +7,20 @@ require 'catissue/database/annotation/annotator'
 require 'catissue/util/collectible_event_parameters'
 
 module CaTissue
-  # A CaTissue::Database mediates access to the caTissue database.
-  # The CaRuby::Database functionality is preserved and not expanded, but this CaTissue::Database overrides
-  # several base class private methods to enable alternate CaTissue-specific search strategies and work
-  # around caTissue and caCORE bugs.
+  # A CaTissue: Database mediates access to the caTissue database.
+  # The superclass +CaRuby::Database+ functionality is preserved and not expanded, but this CaTissue
+  # Database implementation overrides several base class private methods to enable alternate
+  # caTissue-specific search strategies and work-arounds.
   class Database < CaRuby::Database
     include Singleton
     
-    # return [CaRuby::SQLExecutor] a utility SQL executor
-    attr_reader :executor, :access_properties
+    # @return [CaRuby::SQLExecutor] a utility SQL executor
+    attr_reader :executor
+    
+    # @return [{Symbol => Object}] the server access properties
+    attr_reader :access_properties
 
-    # Creates a new Database with the +catissuecore+ service and {CaTissue.access_properties}.
+    # Creates a new Database with the +catissuecore+ service.
     def initialize
       @access_properties = CaTissue.access_properties
       super(SVC_NAME, @access_properties)
@@ -29,7 +32,7 @@ module CaTissue
       @annotator ||= Annotator.new(self)
     end
 
-    # If the given domain object is an {Annotation}, then this method returns the {AnnotationService}
+    # If the given domain object is an {Annotation}, then this method returns the {Annotation::AnnotationService}
     # for the object {AnnotationModule}, otherwise this method returns the standard {CaTissue::Database}
     # service.
     #
@@ -39,7 +42,7 @@ module CaTissue
       klass < Annotation ? klass.annotation_module.persistence_service : super
     end
     
-    # Augments {CaRuby::Database#ensure_exists} to ensure that an {Annotation::Proxy} reference identifier
+    # Augments +CaRuby::Database.ensure_exists+ to ensure that an {Annotation::Proxy} reference identifier
     # reflects the hook identifier.
     #
     # @param (see CaRuby::Database::Writer#ensure_exists)
@@ -59,7 +62,7 @@ module CaTissue
     
     UPD_CTR_SQL = 'update catissue_consent_tier_response set response = ? where identifier = ?'
 
-    # Overrides #{CaRuby::Database::Writer#recursive_save?} to support the update work-around
+    # Overrides #+CaRuby::Database::Writer.recursive_save?+ to support the update work-around
     # described in {#update_object}. A recursive SCG update is allowed if the nested
     # transaction sequence is:
     # * Update SCG
@@ -192,7 +195,7 @@ module CaTissue
       penultimate and penultimate.subject == obj
     end
       
-    # Augments {CaRuby::Database#save_with_template} to work around the following caTissue anomalies:
+    # Augments +CaRuby::Database.save_with_template+ to work around the following caTissue anomalies:
     #
     # @quirk caTissue Bug #149: API update TissueSpecimen position validation incorrect.
     #   The Specimen update argument must reference the old position, even though the position is not
@@ -203,21 +206,21 @@ module CaTissue
     #   position in the caTissue service update argument. A Specimen position is altered as a side-effect
     #   by creating a proxy save {CaTissue::TransferEventParameters}. The changed position is not reflected
     #   in the Specimen position, which must be refetched to reflect the database state. This fetch is
-    #   done automatically by {CaRuby::Database} as part of the save proxy mechanism. The Specimen update
+    #   done automatically by +CaRuby::Database+ as part of the save proxy mechanism. The Specimen update
     #   template must include a reference to the former position but not the changed position.
     #
-    #   However, the Specimen {CaRuby::Writer#update} argument will include the changed position, not the
-    #   former position. The template built {CaRuby::Writer#update} for submission to the caTissue app
+    #   However, the Specimen +CaRuby::Writer.update+ argument will include the changed position, not the
+    #   former position. The template built +CaRuby::Writer.update+ for submission to the caTissue app
     #   does not include a position reference, since the position has a save proxy which handles position
-    #   change as part of the {CaRuby::Writer} update dependent propagation.
+    #   change as part of the +CaRuby::Writer+ update dependent propagation.
     #
     #   Thus, updating a Specimen which includes a position change is performed as follows:
     #   * reconstitute the former position from the Position snapshot taken as part of the
-    #      {CaRuby::Persistable} change tracker.
-    #   * add the former position to the template (which will now differ from the {CaRuby::Writer#update}
+    #      +CaRuby::Persistable+ change tracker.
+    #   * add the former position to the template (which will now differ from the +CaRuby::Writer.update+
     #     argument).
     #   * submit the adjusted Specimen template to the caTissue app updateObject.
-    #   * {CaRuby::Writer#update} will propagate the Specimen update to the changed position dependent,
+    #   * +CaRuby::Writer.update+ will propagate the Specimen update to the changed position dependent,
     #     which in turn saves via the {CaTissue::TransferEventParameters} proxy.
     #   * The proxy save will in turn refetch the proxied Specimen position to obtain the identifier
     #     and merge this into the Specimen position.
@@ -291,7 +294,7 @@ module CaTissue
         logger.debug { "caTissue #{ctr} update work-around completed." }
     end
 
-    # Overrides {CaRuby::Database::Writer#save_changed_dependents} to handle the following anomalies:
+    # Overrides +CaRuby::Database::Writer.save_changed_dependents+ to handle the following anomalies:
     # * create Specimen disposal event last, as described in {#save_changed_specimen_dependents}
     #
     # @param (see CaRuby::Writer#save_dependents)
@@ -302,7 +305,7 @@ module CaTissue
       end   
     end
     
-    # Overrides {CaRuby::Database::Writer#save_changed_dependents} on a Specimen to correct the
+    # Overrides +CaRuby::Database::Writer.save_changed_dependents+ on a Specimen to correct the
     # following problem:
     #
     # @quirk caTissue DisposalEventParameters must be created after all other Specimen SEPs.
@@ -321,7 +324,7 @@ module CaTissue
     # for the subtle interaction required between these two work-arounds.
     #
     # @param [CaTissue::Specimen] the specimen whose dependents are to be saved
-    # @yield [dependent] calls the base {CaRuby::Writer#save_changed_dependents} 
+    # @yield [dependent] calls the base +CaRuby::Writer.save_changed_dependents+ 
     # @yieldparam [Resource] dependent the dependent to save
     def save_changed_specimen_dependents(specimen)
       dsp = specimen.specimen_events.detect { |ep| CaTissue::DisposalEventParameters === ep }
@@ -343,7 +346,7 @@ module CaTissue
       end
     end
     
-    # Overrides {CaRuby::Database#build_save_template} to return obj itself if
+    # Overrides +CaRuby::Database.build_save_template+ to return obj itself if
     # obj is an {Annotation}, since annotations do not employ a separate template.
     #
     # @param (see CaRuby::Database#build_save_template)
@@ -369,7 +372,7 @@ module CaTissue
       annotation
     end
 
-    # Overrides {CaRuby::Database::Writer#save_with_template} to work around caTissue bugs.
+    # Overrides +CaRuby::Database::Writer.save_with_template+ to work around caTissue bugs.
     # @quirk caTissue  Bug #63: a SpecimenCollectionGroup update requires the referenced CollectionProtocolRegistration
     #   with an identifier to hold extraneous CollectionProtocolRegistration content, including the CPR
     #   collection protocol and PPI.
@@ -479,7 +482,7 @@ module CaTissue
       template.send(wtr, pxy)
     end
 
-    # Augment {CaRuby::Database::Writer#create_object} to work around caTissue bugs.
+    # Augment +CaRuby::Database::Writer.create_object+ to work around caTissue bugs.
     # @quirk caTissue Bug #124: SCG SpecimenEventParameters save fails validation.
     #   Work-around is to create the SEP by updating the SCG.
     # @quirk If obj is a CaTissue::Specimen with the is_available flag set to false, then work around the bug
@@ -514,7 +517,7 @@ module CaTissue
       obj
     end
     
-    # Overrides {CaRuby::Database#create_from_template} as follows:
+    # Overrides +CaRuby::Database.create_from_template+ as follows:
     # * Surrogate {Annotation::Proxy} is "created" by setting the identifier to its hook owner.
     #   The create operation then creates referenced uncreated dependents.
     #
@@ -596,7 +599,7 @@ module CaTissue
       specimen
     end
 
-    # Overrides {CaRuby::Database::Reader#fetch_object} to circumvent {Annotation} fetch, since an annotation
+    # Overrides +CaRuby::Database::Reader.fetch_object+ to circumvent {Annotation} fetch, since an annotation
     # does not have a key.
     def fetch_object(obj)
       super or fetch_alternative(obj)
@@ -609,7 +612,7 @@ module CaTissue
       end
     end
       
-    # Override {CaRuby::Database#query_safe} to work around the following +caTissue+ bugs:
+    # Override +CaRuby::Database.query_safe+ to work around the following +caTissue+ bugs:
     # * @quirk caTissue Specimen auto-generates blank ExternalIdentifier.
     #     cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
     # * @quirk caTissue Specimen auto-generates blank PMI. 
@@ -690,7 +693,7 @@ module CaTissue
       annotator.integrator.find(proxy)
     end
     
-    # @quirk caCORE Override {CaRuby::Database::Reader#invertible_query?} to enable the Bug #147 work
+    # @quirk caCORE Override +CaRuby::Database::Reader.invertible_query?+ to enable the Bug #147 work
     #   around in {#query_object}. Invertible queries are performed to work around Bug #79. However, this
     #   work-around induces Bug #147, so we disable the Bug #79 work-around here for the special case of
     #   a CPE in order to enable the Bug #147 work-around. And so it goes....