eutils 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Joon Lee
+
+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.rdoc

@@ -0,0 +1,17 @@
+= eutils
+
+Description goes here.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Joon Lee. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "eutils"
+    gem.summary = %Q{Lightweight Ruby API for NCBI Eutils}
+    gem.description = %Q{This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.}
+    gem.email = "seouri@gmail.com"
+    gem.homepage = "http://github.com/seouri/eutils"
+    gem.authors = ["Joon Lee"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_dependency "nokogiri"
+    # 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
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "eutils #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/eutils.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{eutils}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Joon Lee"]
+  s.date = %q{2010-08-25}
+  s.description = %q{This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.}
+  s.email = %q{seouri@gmail.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "eutils.gemspec",
+     "lib/eutils.rb",
+     "test/helper.rb",
+     "test/test_eutils.rb"
+  ]
+  s.homepage = %q{http://github.com/seouri/eutils}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Lightweight Ruby API for NCBI Eutils}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_eutils.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<nokogiri>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<nokogiri>, [">= 0"])
+  end
+end
+

data/lib/eutils.rb

@@ -0,0 +1,172 @@
+require 'cgi'
+require 'net/http'
+require 'uri'
+require 'active_support/core_ext/hash/conversions'
+# Synopsis
+# eutils = Eutils.new("medvane", "joon@medvane.org")
+# eutils.einfo
+class Eutils
+  # Global constants
+  # * host: http://http://eutils.ncbi.nlm.nih.gov
+  # * EUTILS_INTERVAL
+  EUTILS_HOST = "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/"
+  EUTILS_INTERVAL = 1.0 / 3.0
+  @@last_access = nil
+  @@last_access_mutex = nil
+  attr_accessor :tool, :email
+  ActiveSupport::XmlMini.backend = "LibXMLSAX" # or "NokogiriSAX"
+
+  def initialize(tool = nil, email = nil)
+    @tool, @email = tool, email
+  end
+
+  # EInfo: Provides field index term counts, last update, and available links for each database.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/einfo_help.html
+  def einfo(db = nil)
+    db.strip! if db.class == String
+    server = EUTILS_HOST + "einfo.fcgi"
+    params = {"db" => db}
+    response = post_eutils(server, params)
+    if db.nil? || db.empty?
+      return response.scan(/<DbName>(\w+)<\/DbName>/).flatten
+    else
+      return Hash.from_xml(response)
+    end
+  end
+
+  # ESearch: Searches and retrieves primary IDs (for use in EFetch, ELink, and ESummary) and term translations and optionally retains results for future use in the user's environment.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/esearch_help.html
+  # eutils.esearch("autism")
+  def esearch(term, db = "pubmed", params = {})
+    term.strip! if term.class == String
+    params["term"] = term
+    params["db"] = db
+    params["usehistory"] ||= "y"
+    server = EUTILS_HOST + "esearch.fcgi"
+    response = post_eutils(server, params)
+    return Hash.from_xml(response)
+  end
+
+  # EPost: Posts a file containing a list of primary IDs for future use in the user's environment to use with subsequent search strategies.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/epost_help.html
+  # returns: webenv, querykey. Both nil for invalid epost.
+  def epost(ids, db = "pubmed", params = {})
+    params["id"] = ids.join(",")
+    params["db"] = db
+    server = EUTILS_HOST + "epost.fcgi"
+    response = post_eutils(server, params)
+    querykey = response.scan(/<QueryKey>(\d+)<\/QueryKey>/).flatten.first.to_i
+    querykey = nil if querykey == 0
+    webenv = response.scan(/<WebEnv>(\S+)<\/WebEnv>/).flatten.first
+    return webenv, querykey
+  end
+
+  # ESummary: Retrieves document summaries from a list of primary IDs or from the user's environment.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/esummary_help.html
+  def esummary(ids, db = "pubmed", params = {})
+    params["id"] = ids.join(",")
+    params["db"] = db
+    server = EUTILS_HOST + "esummary.fcgi"
+    response = post_eutils(server, params)
+    return Hash.from_xml(response)
+  end
+
+  # EFetch: Retrieves records in the requested format from a list of one or more primary IDs or from the user's environment.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/efetch_help.html
+  def efetch(db, webenv, query_key, params = {})
+    params["db"] = db
+    params["WebEnv"] = webenv
+    params["query_key"] = query_key
+    params["retmode"] ||= "xml"
+    params["retstart"] ||= 0
+    params["retmax"] ||= 10
+    server = EUTILS_HOST + "efetch.fcgi"
+    response = post_eutils(server, params)
+    if params["retmode"] == "xml"
+      return Hash.from_xml(response)
+    else
+      return response
+    end
+  end
+
+  # ELink: Checks for the existence of an external or Related Articles link from a list of one or more primary IDs.  Retrieves primary IDs and relevancy scores for links to Entrez databases or Related Articles;  creates a hyperlink to the primary LinkOut provider for a specific ID and database, or lists LinkOut URLs and Attributes for multiple IDs.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/elink_help.html
+  def elink
+    
+  end
+
+  # EGQuery: Provides Entrez database counts in XML for a single search using Global Query.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/egquery_help.html
+  def egquery(term)
+    term.strip! if term.class == String
+    server = EUTILS_HOST + "egquery.fcgi"
+    params = {"term" => term}
+    response = post_eutils(server, params)
+    return Hash.from_xml(response)
+  end
+
+  # ESpell: Retrieves spelling suggestions.
+  # See also: http://eutils.ncbi.nlm.nih.gov/corehtml/query/static/espell_help.html
+  def espell(term)
+    term.strip! if term.class == String
+    server = EUTILS_HOST + "espell.fcgi"
+    params = {"db" => "pubmed", "term" => term}
+    response = post_eutils(server, params)
+    corrected = response.scan(/<CorrectedQuery>(.+)<\/CorrectedQuery>/).flatten.first.to_s
+    corrected = term if corrected.empty?
+    return corrected
+  end
+
+  private
+
+  def post_eutils(server, params)
+    check_tool_and_email
+    ncbi_access_wait
+    params["tool"] = tool
+    params["email"] = email
+    response = Net::HTTP.post_form(URI.parse(server), params)
+    return response.body
+  end
+
+  # (Private) Sleeps until allowed to access. Adapted from BioRuby
+  # ---
+  # *Arguments*:
+  # * (required) _wait_: wait unit time
+  # *Returns*:: (undefined)
+  def ncbi_access_wait(wait = EUTILS_INTERVAL)
+    @@last_access_mutex ||= Mutex.new
+    @@last_access_mutex.synchronize {
+      if @@last_access
+        duration = Time.now - @@last_access
+        if wait > duration
+          sleep wait - duration
+        end
+      end
+      @@last_access = Time.now
+    }
+    nil
+  end
+
+  # (Private) Checks parameters as NCBI requires. Adapted from BioRuby
+  # If no email or tool parameter, raises an error.
+  #
+  # NCBI announces that "Effective on
+  # June 1, 2010, all E-utility requests, either using standard URLs or
+  # SOAP, must contain non-null values for both the &tool and &email
+  # parameters. Any E-utility request made after June 1, 2010 that does
+  # not contain values for both parameters will return an error explaining
+  # that these parameters must be included in E-utility requests."
+  # ---
+  # *Arguments*:
+  # * (required) _opts_: Hash containing parameters
+  # *Returns*:: (undefined)
+  def check_tool_and_email
+    if @email.to_s.empty? then
+      raise 'Set email parameter for the query, or set eutils.email = "(your email address)"'
+    end
+    if @tool.to_s.empty? then
+      raise 'Set tool parameter for the query, or set eutils.tool = "(your tool name)"'
+    end
+    nil
+  end
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'eutils'
+
+class Test::Unit::TestCase
+end

data/test/test_eutils.rb

@@ -0,0 +1,87 @@
+require 'helper'
+
+class TestEutils < Test::Unit::TestCase
+  tool = "eutilstest"
+  email = "seouri@gmail.com"
+  eutils = Eutils.new(tool, email)
+  should "set tool and email at instance creation" do
+    assert_equal eutils.tool, tool
+    assert_equal eutils.email, email
+  end
+
+  should "set tool and email after instance creation" do
+    eutils_no_tool_email = Eutils.new
+    eutils_no_tool_email.tool = tool
+    eutils_no_tool_email.email = email
+    assert_equal eutils_no_tool_email.tool, tool
+    assert_equal eutils_no_tool_email.email, email
+  end
+
+  should "raise runtime error without tool or email" do
+    eutils_no = Eutils.new
+    assert_raise RuntimeError do
+      eutils_no.einfo
+    end
+  end
+
+  should "get array of db names from EInfo with no parameter" do
+    db = eutils.einfo
+    assert_equal Array, db.class
+    assert_equal true, db.include?("pubmed")
+    assert_equal Array, eutils.einfo("").class
+    assert_equal Array, eutils.einfo("  ").class
+  end
+
+  should "get a hash from EInfo with db parameter" do
+    i = eutils.einfo("pubmed")
+    assert_equal Hash, i.class
+    assert_equal "eInfoResult", i.keys.first
+    assert_equal "pubmed", i['eInfoResult']['DbInfo']['DbName']
+  end
+
+  should "get a hash from ESearch for a term" do
+    r = eutils.esearch("cancer")
+    assert_equal Hash, r.class
+    assert_equal "cancer", r["eSearchResult"]["TranslationSet"]["Translation"]["From"]
+    assert_equal Array, r["eSearchResult"]["IdList"]["Id"].class
+  end
+
+  should "get webenv and querykey from EPost for posted ids" do
+    ids = [11877539, 11822933, 11871444]
+    webenv, querykey = eutils.epost(ids)
+    assert_equal 1, querykey
+    assert_equal "NCID", webenv.scan(/^(\w{4})/).flatten.first
+    webenv, querykey = eutils.epost(ids, "invalid")
+    assert_nil querykey
+    assert_nil webenv
+  end
+
+  should "get a hash from ESummary for posted ids" do
+    ids = [11850928, 11482001]
+    i = eutils.esummary(ids)
+    assert_equal Hash, i.class
+    assert_equal ids[0], i['eSummaryResult']['DocSum'][0]['Id'].to_i
+  end
+
+  should "get a hash from EFetch for ESearch result" do
+    s = eutils.esearch("cancer")
+    webenv = s["eSearchResult"]["WebEnv"]
+    query_key = s["eSearchResult"]["QueryKey"]
+    r = eutils.efetch("pubmed", webenv, query_key)
+    assert_equal Hash, r.class
+    assert_equal "PubmedArticleSet", r.keys.first
+  end
+
+  should "get spelling suggestion for a term" do
+    assert_equal "breast cancer", eutils.espell("brest cancr")
+    assert_equal "breast cancer", eutils.espell("brest cancer")
+    assert_equal "", eutils.espell(" ")
+  end
+
+  should "get hash from EGQuery" do
+    i = eutils.egquery("autism")
+    assert_equal Hash, i.class
+    assert_equal "Result", i.keys.first
+    assert_equal "autism", i["Result"]["Term"]
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: eutils
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Joon Lee
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-25 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: This gem only provides API for NCBI Eutils. If you need full access to other NCBI databases, try BioRuby (bio gem) instead.
+email: seouri@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- eutils.gemspec
+- lib/eutils.rb
+- test/helper.rb
+- test/test_eutils.rb
+has_rdoc: true
+homepage: http://github.com/seouri/eutils
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Lightweight Ruby API for NCBI Eutils
+test_files: 
+- test/helper.rb
+- test/test_eutils.rb