caruby-scat 1.2.1

data/config.ru

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'bundler'
+Bundler.require
+
+require 'fileutils'
+require 'redis'
+require 'jinx/helpers/log'
+require 'scat'
+
+# the logger
+use Rack::CommonLogger, Jinx.logger(:app => 'Scat', :debug => true)
+
+# start the application
+run Scat::App
+

data/features/edit.feature

@@ -0,0 +1,29 @@
+Feature: Edit
+  In order to use Scat
+  As a biobank technician
+  I submit an edit
+  
+  Scenario: Visit edit
+    Given I am on the edit page
+    Then I should see the "Protocol" field
+    And I should see the "MRN" field
+    And I should see the "SPN" field
+    And I should see the "Diagnosis" field
+    And I should see the "Tissue Site" field
+    And I should see the "Quantity" field
+    And I should see the "Malignant" field
+
+  Scenario: Submit an edit
+    Given I am on the edit page
+    And the protocol "Scat" exists
+    When I fill in "Protocol" with "Scat"
+    And I fill in "MRN" with "123"
+    And I fill in "SPN" with "SP-123"
+    And I fill in "Diagnosis" with "[M]Adrenal cortical adenoma NOS"
+    And I fill in "Tissue Site" with "Adrenal gland, NOS"
+    And I fill in "Quantity" with "4"
+    And I check the "Malignant" checkbox
+    And I am authorized
+    And I click "Save"
+    Then the status should show the label
+    And the specimen should be saved 

data/features/step_definitions/scat_steps.rb

@@ -0,0 +1,50 @@
+World(Rack::Test::Methods)
+
+Given %r{I am on the (\w+) page} do |page|
+  visit("/#{page unless page =~ /^([Hh]ome|[Ee]dit)$/}")
+end
+
+# Authorization requires that the CaTissue API is configured with client
+# access properties as described in the caRuby Tissue +README.md+ file.
+Given %q{I am authorized} do
+  username = CaTissue.properties[:user].split('@').first
+  page.driver.browser.authorize(username, CaTissue.properties[:password])
+end
+
+Given %r{the protocol "([^"]*)" exists} do |title|
+  Scat::Seed.protocol_for(title).find(:create)
+end
+
+When %r{I fill in(?: the)? "([^"]*)"(?: field)? with "([^"]*)"} do |name, text|
+  fill_in Scat::Edit.instance.input_id(name), :with => text
+end
+
+When %r{I check(?: the)? "([^"]*)(?: checkbox)?"} do |name|
+  check Scat::Edit.instance.input_id(name)
+end
+
+When %r{I click "([^"]*)"} do |name|
+  click_on name
+end
+
+Then %r{I should see the "([^"]*)" field} do |name|
+  find_field(Scat::Edit.instance.input_id(name)).visible?.should be true
+end
+
+Then %q{the status should show the label} do
+  find(:status).text.should match /label \d+\.$/
+end
+
+Then %q{the specimen should be saved} do
+  lbl = /label (\d+)\.$/.match(find(:status).text).captures.first
+  lbl.should_not be nil
+  CaTissue::Specimen.new(:label => lbl).find.should_not be nil
+end
+
+Then %r{^I should see "([^"]*)"$} do |text|
+  page.should have_content text
+end
+
+After do |scenario|
+  save_and_open_page if scenario.failed?
+end

data/features/support/env.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:test, :development)
+
+require 'capybara/cucumber'
+require 'jinx/helpers/log'
+require 'scat'
+
+ENV['RACK_ENV'] = 'test'
+
+Capybara.app = Scat::App
+
+# Open the logger.
+Jinx.logger('test/results/log/scat.log', :debug)
+
+def app
+  Scat::App
+end

data/features/support/seed.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + '/../../test/fixtures/seed'
+    

data/lib/scat.rb

@@ -0,0 +1,56 @@
+require 'sinatra'
+require 'haml'
+require 'catissue'
+require 'casmall/authorization'
+require 'scat/autocomplete'
+require 'scat/edit'
+
+module Scat
+  # The standard Scat application error.
+  class ScatError < RuntimeError; end
+   
+  class App < Sinatra::Base
+    include CaSmall::Authorization, Autocomplete
+
+    set :root, File.dirname(__FILE__) + '/..'
+    
+    if development? then
+      # Don't generate fancy HTML for stack traces.
+      disable :show_exceptions
+      # Allow errors to get out of the app so Cucumber can display them.
+      enable :raise_errors
+    end
+      
+    # The authorization page name.
+    set :authorization_realm, 'Please enter your username and caTissue password'
+    
+    enable :sessions
+    
+    # Displays the edit form.
+    get '/' do
+      haml :edit
+    end
+    
+    # Saves the specimen specified in the specimen form.
+    post '/' do
+      # Save the specimen.
+      protect! { Edit.instance.save(params.merge(:user => current_user), session) }
+      # Return to the edit form.
+      redirect back
+    end
+
+    # Displays the CVs for the given property attribute which match the given input
+    # value term.
+    get '/autocomplete/*' do |pa|
+      protect! { autocomplete(pa.to_sym, params[:term]) }
+    end
+        
+    # Sets the status field to the error message.
+    error do
+      e = env['sinatra.error']
+      logger.error(e)
+      request.params[:status] = e.message
+      redirect back
+    end
+  end
+end

data/lib/scat/autocomplete.rb

@@ -0,0 +1,74 @@
+require 'jinx/helpers/inflector'
+require 'catissue/database/controlled_values'
+require 'scat/cache'
+
+module Scat
+  # Auto-completion mix-in.
+  module Autocomplete
+    # Fetches controlled caTissue values for the given attribute and value prefix.
+    # The supported attributes include the following:
+    # * +:clinical_diagnosis+ (+SpecimenCollectionGroup.clinical_diagnosis+)
+    # * +:tissue_site+ (+SpecimenCharacteristics.tissue_site+)
+    #
+    # @param [Symbol] attribute the CV attribute
+    # @param [String] prefix the leading value letters
+    # @return [String] the JSON representation of the matching values
+    def autocomplete(attribute, text)
+      # Start up the cache if necessary
+      @cache ||= Cache.new
+      # Compare lower case.
+      text_dc = text.downcase
+      # The search term is the first word in the text.
+      words = text_dc.split(' ')
+      term = words.first
+      logger.debug { "Scat is matching the cached #{attribute} values which contain #{term}..." }
+      # The hash key, e.g. dx:lymphoma.
+      key = KEY_PREFIX_HASH[attribute] + term
+      # The CVs which match the term.
+      cvs = @cache.get_all(key)
+      # Load the CVs if necessary.
+      cvs = load_controlled_values(attribute, term, key) if cvs.empty?
+      # The CVs which match the entire target.
+      matched = words.size == 1 ? cvs : cvs.select { |cv| cv.downcase[text_dc] }
+      logger.debug { "#{matched.empty? ? 'No' : matched.size} #{attribute} values match '#{text}'." }
+      matched.to_json
+    end
+    
+    private
+    
+    KEY_PREFIX_HASH = {
+       :clinical_diagnosis => 'dx:',
+       :tissue_site => 'ts:'
+    }
+    
+    # The template to fetch CVs matching a PID and key term.
+    # The SQL cheats a little, since it theoretically could return a CV with null PID
+    # whose parentage is not directly or indirectly in the PID. However, this problem
+    # does not occur in practice and is relatively benign if it should occur, since at
+    # worst it includes a few obviously extraneous matches.
+    CV_TMPL = "select value
+      from catissue_permissible_value pv
+      where (public_id = '%s' or (public_id is null and parent_identifier is not null))
+      and value like '%%%s%%'
+      and not exists (select 1 from catissue_permissible_value where parent_identifier = pv.identifier)"
+    
+    # @param (see #match)
+    # @param [Strimg] the cache key
+    # @return (see #match)
+    def load_controlled_values(attribute, term, key)
+      logger.debug { "Scat is loading the #{attribute} controlled values which match '#{term}'..." }
+      # The CV PID, e.g. the :tissue_site PID is Tissue_Site_PID.
+      pid = attribute.to_s.split('_').map { |s| s.capitalize_first }.join('_') << '_PID'
+      # The SQL is the template formatted with the PID and term.
+      sql = CV_TMPL % [pid, term]
+      # Cache each fetched CV.
+      cvs = CaTissue::Database.current.executor.query(sql).map do |rec|
+        cv = rec.first
+        @cache.add(key, cv)
+        cv
+      end
+      logger.debug { "Scat loaded #{cvs.size} #{attribute} #{term} controlled values." }
+      cvs
+    end
+  end
+end

data/lib/scat/cache.rb

@@ -0,0 +1,90 @@
+require 'redis'
+
+module Scat
+  # The session and global key => value cache wrapper.
+  class Cache
+    # @return [Redis] the Redis cache data store
+    # @raise [ScatError] if the cache could not be started
+    def datastore
+      @redis ||= discover
+    end
+    
+    # Sets the given value to the cache tag set as follows:
+    # * If the key is nil, then the cache entry is the tag.
+    # * Otherwise, the cache entry is the tag hash entry for the given key.
+    # * If the value is nil, then the entry is removed from the cache.
+    # * Otherwise, the value is converted to a string, if necessary, and
+    #   the cache entry is set to the value.
+    #
+    # @param [String, Symbol] tag the cache tag 
+    # @param value the value to set 
+    # @param [String, Symbol, nil] key the cache tag hash key
+    def set(tag, value, key=nil)
+      if value.nil? then
+        key ? datastore.hdel(tag, key) : datastore.rem(tag) 
+      else
+        key ? datastore.hset(tag, key, value) : datastore.set(tag, value)
+      end
+    end
+
+     # Adds the given value to the cache tag set. The value is converted to
+     # a string, if necessary.
+     #
+     # @param [String, Symbol] tag the cache tag 
+     # @param value the value to add 
+     def add(tag, value)
+       datastore.zadd(tag, 0, value)
+     end
+     
+    # @param [String, Symbol] tag the cache tag
+    # @param [Symbol, nil] the cached tag hash key
+    # @return [String, <String>] the matching value or values
+    def get(tag, key=nil)
+      key ? datastore.hget(tag, key) : datastore.get(tag)
+    end
+    
+    # @param [String, Symbol] tag the cache tag
+    # @return [<String>] the matching set
+    def get_all(tag)
+      datastore.zrange(tag, 0, -1)
+    end
+    
+    private
+    
+    REDIS_SERVER = File.expand_path('redis-server', File.dirname(__FILE__) + '/../../ext')
+    
+    REDIS_CONF = File.expand_path('redis.conf', File.dirname(__FILE__) + '/../../conf')
+                                      
+    # Locates the Redis server on the default Redis port.
+    #
+    # @return [Redis] the Redis client
+    # @raise (see #start)
+    def discover
+      redis = Redis.current
+      redis.ping rescue start(redis)
+      redis
+    end
+    
+    # Starts the Redis server on the default Redis port.
+    #
+    # @param [Redis] the Redis client
+    # @raise [ScatError] if the server command could not be executed
+    # @raise [Exception] if the server is not reachable
+    def start(redis)
+      logger.debug { "Scat is starting the Redis cache server..." }
+      unless system(REDIS_SERVER, REDIS_CONF) then
+        raise ScatError.new("Scat cannot start the Redis cache server.")
+      end
+      # Ping the server until loaded. 
+      3.times do |n|
+        begin
+          redis.ping
+          logger.debug { "Scat started the Redis cache server." }
+          return redis
+        rescue
+          n < 2 ? sleep(0.5) : raise
+        end
+      end
+    end
+  end
+end

data/lib/scat/configuration.rb

@@ -0,0 +1,79 @@
+require 'yaml'
+require 'jinx/helpers/hash'
+require 'scat/field'
+
+module Scat
+  # The Scat Configuration specifies the edit form fields. 
+  class Configuration
+    # @param [String] the configuration file path
+    def initialize(file)
+      # the field name => Field hash
+      @fld_hash = parse(YAML.load_file(file))
+      logger.info("Scat fields: #{@fld_hash.values.pp_s}")
+    end
+    
+    # @param [Symbol, String] name the field name or label           
+    # @return [Field] the corresponding field
+    def [](name_or_label)
+      # the standardized field name
+      key = case name_or_label
+      when Symbol then
+        name_or_label
+      when String then
+        Field.name_for(name_or_label).to_sym
+      else
+        raise ArgumentError.new("Scat field argument not supported: #{name_or_label.qp}")
+      end
+      @fld_hash[key]
+    end
+    
+    # Returns the edit form field specifications.
+    #
+    # @return [<Field>] the specimen edit field specifications
+    def fields
+      @fld_hash.values
+    end
+
+    # @param [{String => String}] params the request parameters
+    # @return [{Class => {CaRuby::Property => Object}}] the caTissue class => { property => value } hash
+    def slice(params)
+      hash = Jinx::LazyHash.new { Hash.new }
+      params.each do |name, value|
+        next if value.nil?
+        # Skip the param if it is not obtained from the request.
+        field = @fld_hash[name.to_sym] || next
+        field.properties.each do |klass, prop|
+          # Convert non-string values.
+          if prop.type <= Integer or prop.type <= Java::JavaLang::Integer then
+            value = value.to_i
+          elsif prop.type <= Date or prop.type <= Java::JavaUtil::Date then
+            value = DateTime.parse(value)
+          elsif prop.type <= Numeric or prop.type <= Java::JavaLang::Number then
+            value = value.to_f
+          end
+          # Generalize a Specimen subclass.
+          klass = CaTissue::Specimen if klass < CaTissue::Specimen
+          # Add the property value.
+          hash[klass][prop.to_sym] = value
+        end
+      end
+      hash
+    end    
+    
+    private
+    
+    # Parses the field configuration as described in {Field}.
+    #                      
+    # @param [{String => String}] config the field label => spec hash
+    # @return [{Symbol} => Field] the symbol => Field hash
+    def parse(config)
+      hash = {}
+      config.each do |label, spec|
+        field = Field.new(label, spec)
+        hash[field.name.to_sym] = field
+      end
+      hash
+    end
+  end
+end
+ 

data/lib/scat/edit.rb

@@ -0,0 +1,160 @@
+require 'singleton'
+require 'jinx/helpers/validation'
+require 'scat/configuration'
+require 'scat/authorization'
+require 'scat/cache'
+
+module Scat
+  # The Edit helper makes a +CaTissue::Specimen+ from the edit form parameters and creates
+  # the specimen in the database.
+  class Edit
+    include Singleton
+    
+    def initialize
+      super
+      @conf = Configuration.new(FIELD_CONFIG)
+    end
+    
+    # @return (see Configuration#fields)
+    def fields
+      # Delegate to the configuration.
+      @conf.fields
+    end
+    
+    # @param (see Configuration#[])           
+    # @return [String] the corresponding HTML input element id
+    def input_id(name_or_label)
+      field = @conf[name_or_label]
+      if field.nil? then raise ArgumentError.new("Scat field not found: #{name_or_label.qp}") end
+      field.input_id
+    end
+    
+    # Saves the +CaTissue::Specimen+ object specified in the request parameters.
+    #
+    # @param [{Symbol => String}] params the request parameters
+    # @param [{String => String}] session the current Sinatra session
+    # @return [CaTissue::Specimen] the saved specimen
+    # @raise [ScatError] if the parameters are insufficient to build a specimen
+    # @raise [CaRuby::DatabaseError] if the save is unsuccessful
+    def save(params, session)
+      logger.debug { "Scat is saving the specimen with parameters #{params.qp}..." }
+      pcl_id = session[:protocol_id] if session[:protocol] == params[:protocol]
+      site_id = session[:site_id] if pcl_id
+      cpr_id = session[:cpr_id] if pcl_id and session[:mrn] == params[:mrn]
+      scg_id = session[:scg_id] if cpr_id and session[:spn] == params[:spn]
+      # the caTissue class => { property => value } hash
+      ph = @conf.slice(params)
+      # the collection protocol
+      pcl = to_protocol(ph[CaTissue::CollectionProtocol].merge({:identifier => pcl_id}))
+      # the current user
+      user = params[:user]
+      # the collection site
+      site = site_id ? CaTissue::Site.new(:identifier => site_id) : to_site(pcl, user)
+      # the patient
+      pnt = CaTissue::Participant.new(ph[CaTissue::Participant])
+      # the CPR parameters
+      reg_params = ph[CaTissue::ParticipantMedicalIdentifier].merge(:participant => pnt, :site => site)
+      # the CPR
+      reg = to_registration(pcl, reg_params) 
+      reg.identifier = cpr_id
+      # the specimen parameters
+      spc_params = ph[CaTissue::Specimen].merge(ph[CaTissue::SpecimenCharacteristics])
+      # The current user is the biobank specimen receiver.
+      spc_params.merge!(:receiver => user)
+      # the specimen to save
+      spc = to_specimen(pcl, spc_params)
+      # the SCG parameters
+      scg_params = ph[CaTissue::SpecimenCollectionGroup].merge(:participant => pnt, :site => site)
+      # the SCG which contains the specimen
+      pcl.add_specimens(spc, scg_params)
+      # Save the specimen.
+      logger.debug { "Scat is saving #{spc} with content:\n#{spc.dump}" }
+      spc.save
+      # Format the status message.
+      session[:status] = "Created the specimen with label #{spc.label}."
+      # Capture the params in the session to refresh the form.
+      params.each { |a, v| session[a.to_sym] = v }
+      # Capture the ids.
+      scg = spc.specimen_collection_group
+      session[:scg_id] = scg.identifier
+      session[:site_id] = site.identifier
+      cpr = scg.registration
+      session[:cpr_id] = cpr.identifier
+      session[:protocol_id] = cpr.protocol.identifier
+      logger.debug { "Scat saved #{spc}." }
+      spc
+    end
+
+    private
+      
+    # The field configuration file name.
+    FIELD_CONFIG = File.dirname(__FILE__) + '/../../conf/fields.yaml'
+    
+    # Builds the registration object specified in the given parameters.
+    #
+    # @param [{Symbol => String}] params the registration parameters
+    # @return [CaTissue::CollectionProtocolRegistration] the SCG to save
+    def to_protocol(params)
+      pcl = CaTissue::CollectionProtocol.new(params)
+      unless pcl.find then
+        raise ScatError.new("Protocol not found: #{pcl.title}")
+      end
+      pcl
+    end
+    
+    # The collection site is the first match for the following criteria:
+    # * the first site of the current user
+    # * the first protocol site
+    # * the first protocol coordinator site
+    #              
+    # @param [CaTissue::CollectionProtocol] protocol the collection protocol
+    # @param [CaTissue::User] user the current user
+    # @return [CaTissue::Site] the collection site 
+    def to_site(protocol, user)
+      user.find unless user.fetched?
+      site = user.sites.first
+      return site if site
+      protocol.find unless protocol.fetched?
+      site = protocol.sites.first
+      return site if site
+      site = protocol.coordinators.detect_value { |coord| coord.sites.first } or
+        raise ScatError.new("Neither the user #{rcvr.email_address} nor the #{pcl.title} protocol administrators have an associated site.")
+    end
+    
+    # Builds the registration object specified in the given parameters.
+    #
+    # @param [CaTissue::CollectionProtocol] protocol the collection protocol
+    # @param [{Symbol => String}] params the registration parameters
+    # @return [CaTissue::CollectionProtocolRegistration] the SCG to save
+    def to_registration(protocol, params)
+      # If there is an MRN, then make a PMI
+      if params.has_key?(:medical_record_number) then
+        CaTissue::ParticipantMedicalIdentifier.new(params)
+      end
+      # the patient
+      pnt = params[:participant]
+      # Register the patient.
+      protocol.register(pnt)
+    end
+    
+    # Builds the +CaTissue::Specimen+ object specified in the given parameters.
+    #
+    # The default edit form pathological status checkbox value is 'Malignant'.
+    # If the user unchecked it, then there is no pathological status parameter.
+    # In that case, the pathological status is 'Non-Malignant'. 
+    #
+    # @param [CaTissue::CollectionProtocol] protocol the collection protocol
+    # @param [{Symbol => String}] params the Specimen parameters
+    # @return [CaTissue::Specimen] the specimen to save
+    def to_specimen(protocol, params)
+      params[:pathological_status] ||= 'Non-Malignant'
+      # The CPE is the sole protocol event.
+      cpe = protocol.events.first
+      # The specimen requirement is the sole event requirement.
+      rqmt = cpe.requirements.first
+      # Make the specimen.
+      CaTissue::Specimen.create_specimen(params.merge(:requirement => rqmt))
+    end
+  end
+end
+