entrez 0.3.0 → 0.4.0

data/README.rdoc

@@ -13,20 +13,39 @@ or if you use Bundler:
 
 It requires httparty.
 
+See 'Email & Tool' section below for setup.
+
 == Usage
 
-Entrez.EFetch(<database>, parameters)
+(You can copy/paste the resulting following request URLs into a browser to see what the response would be.)
+
+=== EFetch, ESummary
+
+args:
+* database
+* params hash
+
+  Entrez.EFetch('snp', id: 123, retmode: :xml)
+  #=> makes request to http://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=snp&id=9268480&retmode=xml
+  #=> returns XML document with SNP rs9268480 data.
+
+ESummary takes the same arguments.
 
-== Example
+=== ESearch
 
-  Entrez.EFetch('snp', {id: '9268480', retmode: 'xml'})
+args:
+* database
+* term hash
+* params hash
 
-will return an HTTParty response with a body of the xml document with information about rs9268480.
-It's up to you to parse the document.
+  Entrez.ESearch('genomeprj', {WORD: 'hapmap', SEQS: 'inprogress'}, retmode: :xml)
+  #=> makes request to http://http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=genomeprj&term=hapmap[WORD]+AND+inprogress[SEQS]&retmode=xml
+  #=> returns XML document with list of Ids of genome projects that match the searc term criteria
+  #=> i.e. genome projects that have 'hapmap' in the description and whose sequencing status is 'inprogress'.
 
 == Email & Tool
 
-NCBI requests that you supply the tool you are using and your email.
+NCBI asks that you supply the tool you are using and your email.
 The Entrez gem uses 'ruby' as the tool.
 Email is obtained from an environment variable ENTREZ_EMAIL on your computer.
 I set mine in my ~/.bash_profile:
@@ -42,8 +61,9 @@ The amount of delay time is no more than what is necessary to make the next requ
 
 * EFetch
 * ESummary
+* ESearch
 
-Not yet implemented: EInfo, EPost, ESearch, ELink, EGQuery, ESpell.
+Not yet implemented: EInfo, EPost, ELink, EGQuery, ESpell.
 
 == Compatibility
 

data/lib/entrez.rb

@@ -1,10 +1,12 @@
 require 'httparty'
+require 'query_string_normalizer'
 
 class Entrez
 
   include HTTParty
   base_uri 'http://eutils.ncbi.nlm.nih.gov/entrez/eutils'
   default_params tool: 'ruby', email: (ENV['ENTREZ_EMAIL'] || raise('please set ENTREZ_EMAIL environment variable'))
+  query_string_normalizer QueryStringNormalizer
 
   class << self
 
@@ -16,6 +18,11 @@ class Entrez
       perform '/esummary.fcgi', db, params
     end
 
+    def ESearch(db, search_terms = {}, params = {})
+      params[:term] = convert_search_term_hash(search_terms)
+      perform '/esearch.fcgi', db, params
+    end
+
     def perform(utility_path, db, params = {})
       respect_query_limit
       request_times << Time.now.to_f
@@ -40,6 +47,15 @@ class Entrez
       @request_times ||= []
     end
 
+    # Take a ruby hash and convert it to an ENTREZ search term.
+    # E.g. convert_search_term_hash {WORD: 'low coverage', SEQS: 'inprogress'}
+    # #=> 'low coverage[WORD]+AND+inprogress[SEQS]'
+    def convert_search_term_hash(hash)
+      hash.map do |field, value|
+        "#{value}[#{field}]"
+      end.join('+AND+')
+    end
+
   end
 
 end

data/lib/entrez/version.rb

@@ -1,3 +1,3 @@
 module Entrez
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/query_string_normalizer.rb

@@ -0,0 +1,12 @@
+# We need a simple normalizer that will not URI escape []s.
+QueryStringNormalizer = proc do |query_hash|
+  query_hash.map do |key, value|
+    value_string = case value
+    when Array
+      value.join(',')
+    else
+      value
+    end
+    "#{key}=#{value_string}"
+  end.join('&')
+end

data/spec/entrez_spec.rb

@@ -8,17 +8,22 @@ describe Entrez do
   end
 
   it '#EFetch retrieves results' do
-    response = Entrez.EFetch('snp', {id: 9268480})
-    response.code.should == 200
+    response = Entrez.EFetch('taxonomy', id: 9606, retmode: :xml)
+    response.body.should include('Homo sapiens')
   end
 
   it '#ESummary retrieves results' do
-    response = Entrez.ESummary('genomeprj', {id: 62343})
-    response.code.should == 200
+    response = Entrez.ESummary('genomeprj', id: 28911)
+    response.body.should include('Hapmap')
+  end
+
+  it '#ESearch retrieves results' do
+    response = Entrez.ESearch('genomeprj', {WORD: 'hapmap', SEQS: 'inprogress'}, retmode: :xml)
+    response.body.should include('28911')
   end
 
   it 'should respect query limit' do
-    requests = proc { 4.times { Entrez.EFetch('snp', id: 9268480) } }
+    requests = proc { 4.times { Entrez.EFetch('taxonomy', id: 9606) } }
     requests.should take_longer_than(1.0)
   end
 

data/spec/query_string_normalizer_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe QueryStringNormalizer do
+
+  it 'does not escape' do
+    query = {term: '[asdf]', db: 'snp'}
+    QueryStringNormalizer.call(query).should == 'term=[asdf]&db=snp'
+  end
+
+end

metadata

@@ -2,7 +2,7 @@
 name: entrez
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Jared Ning
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-14 00:00:00 -05:00
+date: 2011-05-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -54,7 +54,9 @@ files:
 - entrez.gemspec
 - lib/entrez.rb
 - lib/entrez/version.rb
+- lib/query_string_normalizer.rb
 - spec/entrez_spec.rb
+- spec/query_string_normalizer_spec.rb
 - spec/spec_helper.rb
 - spec/support/macros.rb
 - spec/support/matchers.rb
@@ -88,6 +90,7 @@ specification_version: 3
 summary: HTTP requests to Entrez E-utilities
 test_files: 
 - spec/entrez_spec.rb
+- spec/query_string_normalizer_spec.rb
 - spec/spec_helper.rb
 - spec/support/macros.rb
 - spec/support/matchers.rb