oba_client 2.0.3

data/.gitignore

@@ -0,0 +1,6 @@
+doc
+pkg
+.yardoc
+.buildpath
+.project
+

data/History.md

@@ -0,0 +1,54 @@
+## 2.0.3 / 2010-07-17
+Quick fix in docs.
+
+## 2.0.2 / 2010-07-08
+Parse version and nbAnnotation for ontologies.
+
+## 2.0.1 / 2010-07-08
+
+Rubyforge doesn't allow "_", so we have "oba-client", not "oba_client".
+
+# 2.0.0 / 2010-07-08
+
+* Parse XML entirely. See README for more information on the return value.
+
+## 1.2.1 / 2010-07-08
+
+* Link correctly (problem with using markdown-ed URL in README.md).
+
+## 1.2.0 / 2010-07-08
+
+* Parse statistics.
+
+## 1.1.1 / 2010-07-08
+
+* Rake or Hoe bug workaround.
+
+## 1.1.0 / 2010-07-08
+
+* Fully parse MGREP mappings.
+
+## 1.0.5 / 2010-07-08
+
+* Modify docs slightly.
+
+## 1.0.4 / 2010-07-08
+
+* Add all possible parameter values for the Annotator.
+
+## 1.0.3 / 2010-07-07
+
+* Add more tests.
+
+## 1.0.2 / 2010-07-07
+
+* Oops, no release notes.
+
+## 1.0.1 / 2010-07-07
+
+* Oops, fix a symbol bug.
+
+# 1.0.0 / 2010-07-07
+
+* Initial release.
+* Does not yet parse statistics.

data/Manifest.txt

@@ -0,0 +1,6 @@
+History.md
+Manifest.txt
+README.md
+Rakefile
+lib/oba_client.rb
+test/test_oba_client.rb

data/README.md

@@ -0,0 +1,103 @@
+# oba-client
+
+* [RubyForge project](http://rubyforge.org/projects/oba-client "RubyForge project")
+
+## DESCRIPTION:
+
+A client for accessing the NCBO's Open Biomedical Annotator service.
+See [the Annotator documentation](http://www.bioontology.org/wiki/index.php/Annotator_User_Guide "Documentation") for much more information.
+
+## FEATURES:
+
+* Many
+
+## REQUIREMENTS:
+
+* None
+
+## INSTALL:
+
+    sudo gem install oba-client
+    gem install --user-install oba-client
+
+## USAGE:
+    
+    require "rubygems"
+    require "oba-client"
+    
+    client = OBAClient.new
+    # As XML.
+    result = client.execute("some text string") 
+
+    client2 = OBAClient.new({:parse_xml => true})
+    # Returns {:statistics  => {information about the annotation},
+    #          :annotations => [Array of annotations of text],
+    #          :ontologies  => [Array of ontologies used]}
+    # Like:
+    :statistics => {"MAPPING" => 1951, "MGREP" => 2319, "ISA_CLOSURE" => 30}
+    :annotations => [{
+      :score           => 199,
+      :id              => 203820,
+      :localConceptId  => "42877/CARO:0000013",
+      :localOntologyId => 42877,
+      :isTopLevel      => true,
+      :fullId          => "http://purl.obolibrary.org/obo/FBbt_00007002",
+      :preferredName   => "cell",
+      :synonyms        => ["body cell"],
+      :definitions     => ["a cell", "some other definition"],
+    	
+      :semanticTypes => [
+        {:id => 230820, :semanticType => "T043", :description => "desc"},
+        "etc..."
+      ]
+    	
+      :context => {
+        :contextName   => "MAPPING",
+        :isDirect      => false,
+        :from          => 10,
+        :to            => 20,
+        :mappedConcept => {
+          "has" => "the same information as other annotations, minus score"
+        }
+      }
+    	
+      :mappingType => "Automatic"
+    }, "more annotations..."]
+    	
+    :ontologies => [{
+      :localOntologyId   => 40404,
+      :name              => "Ontology Name",
+      :virtualOntologyId => 1042,
+      :version           => 1.1,
+      :nbAnnotation      => 40
+
+    }, "more ontologies..."]
+    	
+    client2.execute("another text string, maybe longer this time.")
+    client2.execute("this is the second query for this client!")
+    
+    # Or, parse some file you've already got lying about (pass as a string).
+    parsed = OBAClient::parse("<?xml version='1.0'>...</xml>")
+
+## LICENSE:
+ 
+Copyright (c) 2010 Rob Tirrell
+
+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/Rakefile

@@ -0,0 +1,74 @@
+require "rubygems"
+require File.dirname(__FILE__) + "/lib/oba_client.rb"
+#require "hoe"
+
+#Hoe.plugin :yard
+
+#Hoe.spec "oba-client" do
+#  self.developer "Rob Tirrell", "rpt@stanford.edu"
+#  self.url             = "http://rubyforge.org/projects/oba-client"
+#    
+#  self.yard_title      = "OBAClient Documentation"
+#  self.yard_options    = ["--default-return", "void"]
+#  self.yard_markup     = "markdown"
+#  self.remote_yard_dir = ""
+#
+#  self.rubyforge_name = "oba-client"
+#end
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "oba_client"
+    gem.summary = "A client for the Open Biomedical Annotator."
+    gem.description = "See above."
+    gem.email = "rpt@stanford.edu"
+    gem.homepage = "http://github.com/rtirrell/oba_client"
+    gem.authors = ["Rob Tirrell"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    gem.add_development_dependency "yard", ">= 0"
+    gem.version = OBAClient::VERSION
+
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/lib/oba_client.rb

@@ -0,0 +1,282 @@
+require "rubygems"
+require "nokogiri"
+require "cgi"
+require "net/http"
+require "uri"
+
+##
+# A class for interacting with the Open Biomedical Annotator. There are two
+# things we do: get text, and parse it. We can do both independently or 
+# serially.
+class OBAClient
+  VERSION = "2.0.3"
+
+  ##
+  # A high HTTP read timeout, as the service sometimes takes awhile to respond.
+  DEFAULT_TIMEOUT = 30
+
+  ##
+  # The endpoint URI for the production version of the Annotator service.
+  DEFAULT_URI = "http://rest.bioontology.org/obs/annotator"
+
+  ##
+  # The header for every request. There's no need to specify this per-instance.
+  HEADER = {"Content-Type" => "application/x-www-form-urlencoded"}
+
+  ##
+  # Parameters the annotator accepts. Any one not in this list (excluding
+  # textToAnnotate) is not valid.
+  ANNOTATOR_PARAMETERS = [
+    :email,
+    :filterNumber,
+    :format,
+    :isStopWordsCaseSensitive,
+    :isVirtualOntologyID,
+    :levelMax,
+    :longestOnly,
+    :ontologiesToExpand,
+    :ontologiesToKeepInResult,
+    :mappingTypes,
+    :minTermSize,
+    :scored,
+    :semanticTypes,
+    :stopWords,
+    :wholeWordOnly,
+    :withDefaultStopWords,
+    :withSynonyms,
+  ]
+
+  ##
+  # Instantiate the class with a set of reused options. Options used by the
+  # method are:
+  #
+  #   * {String} **uri**: the URI of the annotator service (default: 
+  #     {DEFAULT_URI}).
+  #   * {Fixnum} **timeout**: the length of the read timeout (default: 
+  #     {DEFAULT_TIMEOUT}).
+  #   * {Boolean} **parse_xml**: whether to parse the received text (default: 
+  #     false).
+  #   * {Array}<{String}> **ontologies**: a pseudo-parameter which sets both
+  #      ontologiesToExpand and ontologiesToKeepInResult.
+  # @param [Hash<String, String>] options Parameters for the annotation.
+  def initialize(options = {})
+    @uri         = URI.parse(options.delete(:uri) || DEFAULT_URI)
+    @timeout     = options.delete(:timeout)       || DEFAULT_TIMEOUT
+    @parse_xml   = options.delete(:parse_xml)
+
+    if ontologies = options.delete(:ontologies)
+      [:ontologiesToExpand, :ontologiesToKeepInResult].each do |k|
+        if options.include?(k)
+          puts "WARNING: specified both :ontologies and #{k}, ignoring #{k}."
+        end
+        options[k] = ontologies
+      end
+    end
+
+    @options = {}
+    options.each do |k, v|
+      if !ANNOTATOR_PARAMETERS.include?(k)
+        puts "WARNING: #{k} is not a valid annotator parameter."
+      end
+      if v.is_a? Array
+        @options[k] = v.join(",")
+      else
+        @options[k] = v
+      end
+    end
+
+    if !@options.include?(:email)
+      puts "TIP: as a courtesy, consider including your email in the " + 
+           "request (:email => 'a@b.com')"
+    end
+  end
+
+  ##
+  # Perform the annotation.
+  # @param [String] text The text to annotate.
+  # @return [Hash<Symbol, Array>, String, nil] A Hash representing the parsed
+  #   document, the raw XML if parsing is not requested, or nil if the
+  #   request times out.
+  def execute(text)
+    request = Net::HTTP::Post.new(@uri.path, initheader=HEADER)
+    request.body = {:textToAnnotate => text}.merge(@options).map do |k, v|
+      "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"
+    end.join("&")
+    puts request.body if $DEBUG
+
+    begin
+      response = Net::HTTP.new(@uri.host, @uri.port).start do |http|
+        http.read_timeout = @timeout
+        http.request(request)
+      end
+      @parse_xml ? self.class.parse(response.body) : response.body
+    rescue Timeout::Error
+      puts "Request for #{text[0..10]}... timed-out at #{@timeout} seconds."
+    end
+  end
+
+  
+  STATISTICS_BEANS_XPATH = "/success/data/annotatorResultBean/statistics/statisticsBean"
+  ANNOTATION_BEANS_XPATH = "/success/data/annotatorResultBean/annotations/annotationBean"
+  ONTOLOGY_BEANS_XPATH   = "/success/data/annotatorResultBean/ontologies/ontologyUsedBean"
+
+  ##
+  # Attributes for mapping concepts (only one type).
+  CONCEPT_ATTRIBUTES = {
+    :id              => lambda {|c| c.xpath("id").text.to_i},
+    :localConceptId  => lambda {|c| c.xpath("localConceptId").text},
+    :localOntologyId => lambda {|c| c.xpath("localOntologyId").text.to_i},
+    :isTopLevel      => lambda {|c| to_b(c.xpath("isTopLevel").text)},
+    :fullId          => lambda {|c| c.xpath("fullId").text},
+    :preferredName   => lambda {|c| c.xpath("preferredName").text},
+
+    :synonyms        => lambda do |c| 
+      c.xpath("synonyms/synonym").map do |s|
+        s.xpath("string").text
+      end
+    end,
+
+    :semanticTypes   => lambda do |c| 
+      c.xpath("semanticTypes/semanticTypeBean").map do |s|
+        {
+          :id           => s.xpath("id").text.to_i,
+          :semanticType => s.xpath("semanticType").text,
+          :description  => s.xpath("description").text
+        }
+      end
+    end
+  }
+  
+
+  ##
+  # Attributes for mapping and mgrep contexts (both will add 
+  # additional attributes).
+  CONTEXT_ATTRIBUTES = {
+    :contextName     => lambda {|c| c.xpath("contextName").text},
+    :isDirect        => lambda {|c| to_b(c.xpath("isDirect").text)},
+    :from            => lambda {|c| c.xpath("from").text.to_i},
+    :to              => lambda {|c| c.xpath("to").text.to_i},
+  }
+  
+  ##
+  #  Attributes for annotation contexts.
+  ANNOTATION_CONTEXT_ATTRIBUTES = {
+    :score   => lambda {|c| c.xpath("score").text.to_i},
+    :concept => lambda {|c| parse_concept(c.xpath("concept").first)},
+    :context => lambda {|c| parse_context(c.xpath("context").first)}
+  }
+
+  ##
+  # Attributes for mapping contexts.
+  MAPPED_CONTEXT_ATTRIBUTES = CONTEXT_ATTRIBUTES.merge(
+    :mappingType   => lambda {|c| c.xpath("mappingType").text},
+    :mappedConcept => lambda {|c| parse_concept(c.xpath("mappedConcept").first)}
+  )
+
+  ##
+  # Attributes for mgrep contexts.
+  MGREP_CONTEXT_ATTRIBUTES = CONTEXT_ATTRIBUTES.merge(
+    :name           => lambda {|c| c.xpath("term/name").text},
+    :localConceptId => lambda {|c| c.xpath("term/localConceptId").text},
+    :isPreferred    => lambda {|c| to_b(c.xpath("term/isPreferred").text)},
+    :dictionaryId   => lambda {|c| c.xpath("term/dictionaryId").text}
+  )
+
+  ## 
+  # Map the bean type to the set of attributes we parse from it.
+  CONTEXT_CLASSES = {
+    "annotationContextBean" => ANNOTATION_CONTEXT_ATTRIBUTES,
+    "mgrepContextBean"      => MGREP_CONTEXT_ATTRIBUTES,
+    "mappingContextBean"    => MAPPED_CONTEXT_ATTRIBUTES,
+  }
+
+  ##
+  # Parse a context: an annotation, or a mapping/mgrep context bean.
+  #
+  # @param [Nokgiri::XML::Node] context The root node of the context.
+  #
+  # @return [Hash<Symbol, Object>] The parsed context.
+  def self.parse_context(context)
+    # Annotations (annotationBeans) do not have a class, so we'll refer to them
+    # as annotationContextBeans. context_class will be one of the types in
+    # {CONTEXT_CLASSES}.
+    context_class = if context.attribute("class").nil?
+      "annotationContextBean"
+    else
+      context.attribute("class").value
+    end
+
+    Hash[CONTEXT_CLASSES[context_class].map do |k, v|
+      [k, v.call(context)]
+    end]
+  end
+
+  ##
+  # Parse a concept: a toplevel annotation concept, or an annotation's
+  # mapping concept.
+  #
+  # @param [Nokogiri::XML::Node] concept The root node of the concept.
+  #
+  # @return [Hash<Symbol, Object>] The parsed concept.
+  def self.parse_concept(concept)
+    Hash[CONCEPT_ATTRIBUTES.map do |k, v| 
+      [k, v.call(concept)]
+    end]
+  end
+
+  ##
+  # Parse raw XML, returning a Hash with three elements: statistics,
+  # annotations, and ontologies. Respectively, these represent the annotation
+  # statistics (annotations by mapping type, etc., as a Hash), an Array of
+  # each annotation (as a Hash), and an Array of ontologies used (also as
+  # a Hash).
+  #
+  # @param [String] xml The XML we'll be parsing.
+  #
+  # @return [Hash<Symbol, Object>] A Hash representation of the XML, as
+  #   described in the README.
+  def self.parse(xml)
+    puts "WARNING: text is empty!" if (xml.gsub(/\n/, "") == "")
+    doc = Nokogiri::XML.parse(xml)
+
+    statistics = Hash[doc.xpath(STATISTICS_BEANS_XPATH).map do |sb|
+      [sb.xpath("mapping").text, sb.xpath("nbAnnotation").text.to_i]
+    end]
+
+    annotations = doc.xpath(ANNOTATION_BEANS_XPATH).map do |annotation|
+      parse_context(annotation)
+    end
+
+    ontologies = doc.xpath(ONTOLOGY_BEANS_XPATH).map do |ontology|
+      {
+        :localOntologyId   => ontology.xpath("localOntologyId").text.to_i,
+        :virtualOntologyId => ontology.xpath("virtualOntologyId").text.to_i,
+        :name              => ontology.xpath("name").text,
+        :version           => ontology.xpath("version").text.to_f,
+        :nbAnnotation      => ontology.xpath("nbAnnotation").text.to_i
+      }
+    end
+
+    {
+      :statistics  => statistics,
+      :annotations => annotations,
+      :ontologies  => ontologies
+    }
+  end
+  
+  ##
+  # A little helper: convert a string true/false or 1/0 value to boolean.
+  # AFAIK, there's no better way to do this.
+  #
+  # @param [String] value The value to convert.
+  #
+  # @return [true, false]
+  def self.to_b(value)
+    case value
+    when "0"     then false
+    when "1"     then true
+    when "false" then false
+    when "true"  then true
+    end
+  end
+end

data/test/test_oba_client.rb

@@ -0,0 +1,91 @@
+require "test/unit"
+require "oba-client"
+
+TEST_TEXTS = [
+  "Mexico,, Disease Thing \o\r\m\n\t\v\l\rzebrafish !!! cancer of the thorax. large intestine thorax",
+  %Q{LOROE aonuhaso unseu anoeuhs aeuhsaonuh asoneuhason uaosenuh aosenuhaose
+  aoneuhasonuhaoenuh anoeuhasn euhasoneu haosneuhaosenuhaoesunahoeusnaoeuteeano
+  aot tt t t t t t t tae \n!!@)$@(#)%@\#!)@# asoeuaohsenutahoeusaheou
+  }
+]
+
+class TestOBAClient < Test::Unit::TestCase
+  def test_reuse_instance
+    ann = OBAClient.new
+    TEST_TEXTS.each do |text|
+      xml = ann.execute(text)
+      assert xml[0..4] == "<?xml"
+    end
+  end
+  
+  def test_reuse_instance_with_email
+    ann = OBAClient.new :email => "r.tirrell@gmail.com"
+    TEST_TEXTS.each do |text|
+      xml = ann.execute(text)
+      assert xml[0..4] == "<?xml"
+    end
+  end
+  
+  def test_annotation_no_parameters
+    TEST_TEXTS.each do |text|
+      ann = OBAClient.new 
+      xml = ann.execute(text)
+      assert xml[0..4] == "<?xml"
+    end
+  end
+  
+  def test_annotation_parse
+    TEST_TEXTS.each do |text|
+      ann = OBAClient.new :parse_xml => true
+      parsed = ann.execute(text)
+      assert parsed[:statistics].is_a?(Hash)
+      assert parsed[:annotations].is_a?(Array)
+      assert parsed[:ontologies].is_a?(Array)
+    end
+  end
+  
+  def test_annotation_keep_one_ontology
+    TEST_TEXTS.each do |text|
+      ann = OBAClient.new(
+        :ontologiesToKeepInResult => [42812],
+        :parse_xml => true
+      )
+      parsed = ann.execute(text)
+      assert parsed[:ontologies].all? {|o| o[:localOntologyId] == 42812}
+    end
+  end
+  
+  def test_annotation_invalid_parameters
+    TEST_TEXTS.each do |text|
+      ann = OBAClient.new(
+        :ontologiesToKeepInResult => [42812],
+        :parse_xml                => true,
+        :blah_blah                => true,
+        :hoho                     => ["merry", "christmas"]
+      )
+      parsed = ann.execute(text)
+      assert parsed[:statistics].is_a?(Hash)
+      assert parsed[:annotations].is_a?(Array)
+      assert parsed[:ontologies].is_a?(Array)
+    end
+  end
+  
+  def test_ontologies_pseudo_parameter
+    ann = OBAClient.new(:ontologies => [42812], :parse_xml => true)
+    TEST_TEXTS.each do |text|
+      parsed = ann.execute(text)
+      assert parsed[:ontologies].all? {|o| o[:localOntologyId] == 42812}
+    end
+  end
+  
+  def test_parse
+    parsed = OBAClient::parse("<?xml version='1.0'></xml>")
+  end
+  
+  def test_with_print
+    ann = OBAClient.new(:ontologies => [42838, 35686], :parse_xml => false)
+    ann = OBAClient.new(:ontologies => [42838, 35686], :parse_xml => true)
+  end
+    
+  
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: oba_client
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: false
+  segments: 
+  - 2
+  - 0
+  - 3
+  version: 2.0.3
+platform: ruby
+authors: 
+- Rob Tirrell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-16 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: See above.
+email: rpt@stanford.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- .gitignore
+- History.md
+- Manifest.txt
+- README.md
+- Rakefile
+- Rakefile-2
+- lib/oba_client.rb
+- test/test_oba_client.rb
+has_rdoc: true
+homepage: http://github.com/rtirrell/oba_client
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A client for the Open Biomedical Annotator.
+test_files: 
+- test/test_oba_client.rb