qa 0.0.1

data/LICENSE

@@ -0,0 +1,15 @@
+##########################################################################
+# Copyright 2013 Rock and Roll Hall of Fame and Museum
+# Additional copyright may be held by others, as reflected in the commit log
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/README.md

@@ -0,0 +1,174 @@
+# Questioning Authority
+
+[![Build Status](https://travis-ci.org/projecthydra/questioning_authority.png?branch=master)](https://travis-ci.org/projecthydra/questioning_authority)
+
+You should question your authorities.
+
+## What does this do?
+
+Provides a set of uniform RESTful routes to query any controlled vocabulary of set of authority terms.
+Results are returned in JSON, to be used in the context of a Rails application.  Primary examples would
+include providing auto-complete functionality via Javascript or populating a dropdown menu with a set
+of terms.
+
+## How does it work?
+
+Authorities are defined as classes, each implementing a set of methods allowing a controller to return
+results from a given vocabulary in the JSON format.  The controller does three things:
+
+* provide a list of all terms (if allowed by the class)
+* return a set of terms matching a given query
+* return the complete information for a specific term given its identifier
+
+### Sub-Authorities
+
+Some authorities, such as Library of Congress, allow sub-authorities which is an additional parameter that
+further defines the kind of authority to use with the context of a larger one.
+
+## How do use this?
+
+Add the gem to your Gemfile
+
+    gem 'qa'
+
+Add the engine to your config/routes.rb file
+
+    mount Qa::Engine => '/qa'
+
+Start questioning your authorities!
+
+### Examples
+
+Return a complete list of terms:
+
+    /qa/terms/:vocab
+    /qa/terms/:vocab/:sub_authority
+
+Return a set of terms matching a given query
+
+    /qa/search/:vocab?q=search_term
+    /qa/search/:vocab/:sub_authority?q=search_term
+
+Return the complete information for a specific term given its identifier
+
+    /qa/show/:vocab/:id
+    /qa/show/:vocab/:sub_authority/:id
+
+### JSON Results
+
+Results are returned in JSON in this format:
+
+    [
+        {"id" : "subject_id_1", "label" : "First labels"},
+        {"id" : "subject_id_2", "label" : "Printing labels"},
+        {"id" : "", "label" : "This term has no id number"},
+        {"id" : "", "label" : "Neither does this"}
+    ]
+
+Results for specific terms may vary according to the term.  For example:
+
+    /qa/show/mesh/D000001
+
+Might return:
+
+    { "id" : "D000001",
+      "label" : "Calcimycin",
+      "tree_numbers" : ["D03.438.221.173"],
+      "synonyms" : ["A-23187", "A23187", "Antibiotic A23187", "A 23187", "A23187, Antibiotic"]
+    }
+
+This is due to the varying nature of each authority source.  However, results for multiple terms, such as a search, we
+should always use the above id and label structure to ensure interoperability at the GUI level.
+
+# Authority Sources information
+
+### Library of Congress (example uses language):
+
+Base url: http://id.loc.gov/search/
+
+Example search (html): http://id.loc.gov/search/?q=eng&q=cs%3Ahttp%3A%2F%2Fid.loc.gov%2Fvocabulary%2Fiso639-2
+
+Example search (json): http://id.loc.gov/search/?q=eng&q=cs%3Ahttp%3A%2F%2Fid.loc.gov%2Fvocabulary%2Fiso639-2&format=json
+
+Example search (json, second page): http://id.loc.gov/search/?q=a*%20cs:http://id.loc.gov/vocabulary/countries&start=21&format=json
+
+# Local Authority Files
+
+### YAML file of terms
+
+#### Location and Naming Convention
+
+Local authorities are specified in YAML files, one for each sub-authority.  By default, local
+authority YAML files are located in config/authorities/ .  This location can be changed by editing
+the :local_path entry in config/authorities.yml.  Relative paths are assumed to be relative to
+Rails.root.
+
+Local authority YAML files are named for the sub-authority they represent.  For example, a YAML file
+for the "states" sub-authority would be named states.yml.
+
+#### Supported formats
+
+##### List of terms
+
+	:terms:
+		- Term 1
+		- Term 2
+		
+##### List of id and term keys and, optionally, active key
+
+	:terms:
+		- :id: id1
+		  :term: Term 1
+		  :active: true
+		- :id: id2
+		  :term: Term 2
+		  :active: false
+
+# Medical Subject Headings (MeSH)
+
+Provides autocompletion of [MeSH terms](http://www.nlm.nih.gov/mesh/introduction.html). This
+implementation is simple, and only provides *descriptors* and does not implement *qualifiers* (in
+the technical MeSH sense of these terms). The terms are stored in a local database, which is then
+queried to provide the suggestions.
+
+## Loading Terms
+
+To import the mesh terms into the local database, first download the MeSH descriptor dump in ASCII
+format  (see [http://www.nlm.nih.gov/mesh/filelist.html][]). Once you have this file, the rake task
+`mesh:import` will load the entire file of terms into the database. It does not do an update (yet!).
+
+    MESH_FILE=path/to/mesh.txt rake mesh:import
+
+This may take a few minutes to finish.
+
+# TODOs
+
+* Provide show method to TermsController to return individual terms
+
+check the issue list for more...
+
+# Developer Notes
+
+To develop this gem, clone the repository, then run:
+
+    bundle install
+    rake
+
+This will install the gems, create a dummy application under spec/internal and run the tests.  After you've made changes, remove the entire spec/internal
+directory so that further tests and run against a new dummy application.
+
+# Authors
+
+* [Stephen Anderson](https://github.com/scande3)
+* [Don Brower](https://github.com/dbrower)
+* [Jim Coble](https://github.com/coblej)
+* [Mike Durbin](https://github.com/mikedurbin)
+* [Randall Floyd](https://github.com/stormfin)
+* [Eric James](https://github.com/yulgit1)
+* [Mike Stroming](https://github.com/mstroming)
+* [Adam Wead](https://github.com/awead)
+
+### Special thanks to...
+
+[Jeremy Friesen](https://github.com/jeremyf) who gave us the name for our gem.
+

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+Dir.glob('tasks/*.rake').each { |r| import r }
+
+ENV["RAILS_ROOT"] ||= 'spec/internal'
+
+require 'rspec/core/rake_task'
+
+task :default => [:spec]

data/app/assets/javascripts/qa/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/stylesheets/qa/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/controllers/qa/application_controller.rb

@@ -0,0 +1,4 @@
+module Qa
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/qa/terms_controller.rb

@@ -0,0 +1,76 @@
+# This controller is used for all requests to all authorities. It will verify params and figure out
+# which class to instantiate based on the "vocab" param. All the authotirty classes inherit from a
+# super class so they implement the same methods.
+
+class Qa::TermsController < ApplicationController
+
+  before_action :check_search_params, only:[:search]
+  before_action :check_vocab_param, :check_authority, :check_sub_authority
+  
+  #search that returns all results
+  def index
+    #initialize the authority and run the search. if there's a sub-authority and it's valid, include that param
+    @authority = authority_class.constantize.new(params[:q], params[:sub_authority])
+    
+    #parse the results
+    @authority.parse_authority_response
+    
+    respond_to do |format|
+      format.html { render :layout => false, :text => @authority.results }
+      format.json { render :layout => false, :text => @authority.results }
+      format.js   { render :layout => false, :text => @authority.results }
+    end
+  end
+  
+  def search
+    
+    #convert wildcard to be URI encoded
+    params[:q].gsub!("*", "%2A")
+   
+    #initialize the authority and run the search. if there's a sub-authority and it's valid, include that param
+    @authority = authority_class.constantize.new(params[:q], params[:sub_authority])
+    
+    #parse the results
+    @authority.parse_authority_response
+    
+    respond_to do |format|
+      format.html { render :layout => false, :text => @authority.results }
+      format.json { render :layout => false, :text => @authority.results }
+      format.js   { render :layout => false, :text => @authority.results }
+    end
+
+  end
+
+  def check_vocab_param
+    unless params[:vocab].present?
+      redirect_to :status => 400
+    end
+  end
+  
+  def check_search_params
+    unless params[:q].present? && params[:vocab].present?
+      redirect_to :status => 400
+    end
+  end
+
+  def check_authority
+    begin
+      authority_class.constantize
+    rescue
+      redirect_to :status => 400
+    end 
+  end
+
+  def check_sub_authority
+    unless params[:sub_authority].nil?
+      redirect_to :status => 400 unless authority_class.constantize.authority_valid?(params[:sub_authority])
+    end
+  end
+
+  private
+
+  def authority_class
+    "Qa::Authorities::"+params[:vocab].capitalize
+  end
+
+end

data/app/helpers/qa/application_helper.rb

@@ -0,0 +1,2 @@
+module Qa::ApplicationHelper
+end

data/app/models/qa/mesh_tree.rb

@@ -0,0 +1,37 @@
+class Qa::MeshTree < ActiveRecord::Base
+  belongs_to :subject_mesh_term , :foreign_key => "term_id"
+
+  def self.classify_all_trees
+    MeshTreeStructure.find_each do |mts|
+      mts.classify_tree!
+    end
+  end
+
+  def eval_tree_path
+    trees = read_attribute(:eval_tree_path) || write_attribute(:eval_tree_path, "")
+    if trees
+      trees.split("|")
+    else
+      []
+    end
+  end
+
+  def classify_tree
+    tree_levels = initial_segements_of(tree_structure)
+    tree_levels.map &method(:lookup_tree_term)
+  end
+
+  def classify_tree!
+    unless classify_tree.empty?
+      tree_path = classify_tree.join('|')
+      puts "After Join #{tree_path.inspect}"
+      update_attribute(:eval_tree_path, tree_path)
+    end
+  end
+
+  # given a tree id, return the main subject term
+  # e.g. 'C03.752.530' returns 'Malaria'
+  def lookup_tree_term(tree_id)
+    self.class.get_term(tree_id).first.term
+  end
+end

data/app/models/qa/subject_mesh_term.rb

@@ -0,0 +1,45 @@
+class Qa::SubjectMeshTerm < ActiveRecord::Base
+  has_many :mesh_trees, :foreign_key => "term_id"
+
+  def self.from_tree_number(tree_id)
+    Qa::SubjectMeshTerm.joins('INNER JOIN qa_mesh_trees ON qa_subject_mesh_terms.term_id = qa_mesh_trees.term_id').where('qa_mesh_trees.tree_number = ?', tree_id)
+  end
+
+  def trees
+    Qa::MeshTree.where(term_id: self.term_id).map { |t| t.tree_number }
+  end
+
+  def synonyms
+    s = read_attribute(:synonyms)
+    s.nil? ? [] : s.split("|")
+  end
+
+  def synonyms=(syn_list)
+    write_attribute(:synonyms,
+                    if syn_list.respond_to?(:join)
+                      syn_list.join('|')
+                    else
+                      syn_list
+                    end)
+  end
+
+  def parents
+    t = self.trees
+    t.map { |tn| initial_segements_of(tn) }.flatten.uniq.map { |tn| Qa::SubjectMeshTerm.from_tree_number(tn) }
+  end
+
+  private
+  # Return all of the intial segements of our tree number,
+  # from most general to most specific
+  # e.g. 'D03.456.23.789' returns ['D03', 'D03.456', 'D03.456.23', 'D03.456.23.789']
+  def initial_segements_of(s)
+    result = []
+    loop do
+      result << s
+      s = s.rpartition('.').first
+      break if s.empty?
+    end
+    result.reverse
+  end
+
+end

data/app/views/layouts/qa/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Qa</title>
+  <%= stylesheet_link_tag    "qa/application", media: "all" %>
+  <%= javascript_include_tag "qa/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/authorities.yml

@@ -0,0 +1 @@
+:local_path: "config/authorities"

data/config/authorities/states.yml

@@ -0,0 +1,101 @@
+:terms:
+    - :id: AL
+      :term: Alabama
+    - :id: AK
+      :term: Alaska
+    - :id: AZ
+      :term: Arizona
+    - :id: AR
+      :term: Arkansas
+    - :id: CA
+      :term: California
+    - :id: CO
+      :term: Colorado
+    - :id: CT
+      :term: Connecticut
+    - :id: DE
+      :term: Delaware
+    - :id: FL
+      :term: Florida
+    - :id: GA
+      :term: Georgia
+    - :id: HI
+      :term: Hawaii
+    - :id: ID
+      :term: Idaho
+    - :id: IL
+      :term: Illinois
+    - :id: IN
+      :term: Indiana
+    - :id: IA
+      :term: Iowa
+    - :id: KS
+      :term: Kansas
+    - :id: KY
+      :term: Kentucky
+    - :id: LA
+      :term: Louisana
+    - :id: ME
+      :term: Maine
+    - :id: MD
+      :term: Maryland
+    - :id: MA
+      :term: Massachusetts
+    - :id: MI
+      :term: Michigan
+    - :id: MN
+      :term: Minnesota
+    - :id: MS
+      :term: Mississippi
+    - :id: MO
+      :term: Missouri
+    - :id: MT
+      :term: Montana
+    - :id: NE
+      :term: Nebraska
+    - :id: NV
+      :term: Nevada
+    - :id: NH
+      :term: New Hampshire
+    - :id: NJ
+      :term: New Jersey
+    - :id: NM
+      :term: New Mexico
+    - :id: NY
+      :term: New York
+    - :id: NC
+      :term: North Carolina
+    - :id: ND
+      :term: North Dakota
+    - :id: OH
+      :term: Ohio
+    - :id: OK
+      :term: Oklahoma
+    - :id: OR
+      :term: Oregon
+    - :id: PA
+      :term: Pennsylvania
+    - :id: RI
+      :term: Rhode Island
+    - :id: SC
+      :term: Sourth Carolina
+    - :id: SD
+      :term: South Dakota
+    - :id: TN
+      :term: Tennessee
+    - :id: TX
+      :term: Texas
+    - :id: UT
+      :term: Utah
+    - :id: VT
+      :term: Vermont
+    - :id: VA
+      :term: Virginia
+    - :id: WA
+      :term: Washington
+    - :id: WV
+      :term: West Virginia
+    - :id: WI
+      :term: Wisconsin
+    - :id: WY
+      :term: Wyoming