pubmed_search 0.2.0

data/.document

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

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ryan Schenk
+
+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,49 @@
+= pubmed_search
+
+PubmedSearch is PubMed search wrapper. It provides more (obscure) features than BioRuby's.
+
+If all you need is a list of PubMed IDs, then use BioRuby. If you need more information from the eSearchResponse, then check this out.
+
+== Features
+
+In addition to returning the list of PubMed IDs, it will give you more information about your eSearch Response:
+
+* list of Exploded MeSH terms ({More Info about MeSH Term Explosion}[http://www.pubmedcentral.nih.gov/articlerender.fcgi?artid=2651214#id443777])
+* list of PhraseNotFound terms
+* the Count field
+
+Additionally, PubmedSearch can automatically fetch more results if the list of PubMed IDs is less than the Count. For instance, PubMed automatically caps your retmax to 100,000. However, a search for "Mus musculus" will return over 950,000 results. In this situation, PubmedSearch will automatically perform the 10 eSearches required to load the entire set of PubMed IDs, and return it to you as a single result set. This functionality is _disabled_ by default, but can be turned on via an option.
+
+== Synopsis
+
+=== Without the +load_all_pmids+ functionality (default)
+
+  results = PubmedSearch.search "Mus musculus"
+  
+  results.pmids.length
+  #=> 100000
+  
+  results.count
+  #=> 951134
+  
+  results.exploded_mesh_terms
+  #=> #<Set: {"mice"}>
+  
+=== With the +load_all_pmids+ functionality
+
+  results = PubmedSearch.search "Mus musculus", :load_all_pmids => true
+  
+  results.pmids.length
+  #=> 951134
+  
+  results.count
+  #=> 951134
+
+== Requirements
+
+* libxml-ruby - sudo gem install libxml-ruby
+* simple_uri_template - sudo gem install rschenk-simple_uri_template
+
+== Copyright
+
+Copyright (c) 2009 Ryan Schenk. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "pubmed_search"
+    gem.summary = %Q{A PubMed searching library with more features than BioRuby}
+    gem.email = "rschenk@gmail.com"
+    gem.homepage = "http://github.com/rschenk/pubmed_search"
+    gem.authors = ["Ryan Schenk"]
+    gem.add_dependency 'rschenk-simple_uri_template'
+    gem.add_dependency 'nokogiri'
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "pubmed_search #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/pubmed_search.rb

@@ -0,0 +1,106 @@
+require 'set'
+require 'open-uri'
+
+require 'rubygems'
+require 'nokogiri'
+require 'simple_uri_template'   # sudo gem install rschenk-simple_uri_template
+
+
+class PubmedSearch
+  # List of Pubmed IDs returned by your search
+  attr_accessor :pmids
+  
+  # The Count field returned by your search. If pmids < count, then you need to look at your retmax or try load_all_pmids
+  attr_accessor :count
+  
+  # See exploded_mesh_terms for a description.
+  attr_accessor :exploded_mesh_terms
+  
+  # The PhraseNotFound elements returned by your search
+  attr_accessor :phrases_not_found
+  
+  WAIT_TIME = 1 # seconds
+  DEFAULT_OPTIONS = {:retmax => 100000,
+                     :retstart => 0,
+                     :load_all_pmids => false }
+                     
+  @uri_template = SimpleURITemplate.new('http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmax={retmax}&retstart={retstart}&term={term}')
+  
+  class << self
+    # Performs a search to PubMed via eUtils with the given term +String+, and returns a +PubmedSearch+ object modeling the response.
+    #
+    # Accepts a +Hash+ of options. Valid options are 
+    # * :retmax - Defaults to 100,000 which is the largest retmax that PubMed will honor.
+    # * :retstart - Defaults to 0. Set higher if you need to page through results. You shouldn't need to do that manually, because of the +load_all_pmids+ option
+    # * :load_all_pmids - Defaults to +false+. If this is set +true+, then search will continue sending eSearches with an increasing retstart until the list of pmids == count. For instance, an eSearch for "Mus musculus" will return ~951134 results, but the highest retmax allowable is 100000. With +load_all_pmids+ set +true+, search will automatically perform 10 eSearches and return the entire list of pmids in one go.
+    def search(term, options={})
+      options = DEFAULT_OPTIONS.merge(options)
+    
+      results = do_search(new, term, options)
+    
+      if options[:load_all_pmids]
+        # Send off subsequent requests to load all the PMIDs, add them to the results
+        (options[:retmax]..results.count).step(options[:retmax]) do |step|
+          do_search(results, term, options.merge({:retstart => step}))
+        end 
+      end
+    
+      results
+    end
+    
+    # As of May 2009, PubMed requires a 300ms pause between eUtils calls. It used to be 3 seconds.
+    # PubmedSearch pauses for 1 second just to be on the safe side.
+    def wait
+      sleep WAIT_TIME unless @skip_wait
+    end
+    
+    # Setting this to true will prevent PubmedSearch from pausing before sending requests to PubMed. This is a fantastic way to get yourself banned from eUtils.
+    #
+    # I only use this for testing.
+    def skip_wait=(setting)
+      @skip_wait = setting
+    end
+    
+    private
+    
+    # Performs the HTTP request and parses the response
+    def do_search(results, term, options)
+      wait
+      
+      esearch_url = @uri_template.expand(options.merge({:term => term}))
+      doc = Nokogiri::XML( open esearch_url )
+
+      results.count = doc.xpath('/eSearchResult/Count').first.content.to_i
+      
+      doc.xpath('/eSearchResult/IdList/Id').each {|n| results.pmids << n.content.to_i}
+            
+      doc.xpath('/eSearchResult/TranslationStack/TermSet/Term').each do |n|
+        if n.content =~ /"(.*)"\[MeSH Terms\]/
+          results.exploded_mesh_terms << $1
+        end
+      end
+      
+      doc.xpath('/eSearchResult/ErrorList/PhraseNotFound').each {|n| results.phrases_not_found << n.content }
+
+      results
+    end
+  end
+  
+  
+  # Get the list of Pubmed IDs returned by this esearch as an +Array+ of +Numbers+
+  def pmids 
+    @pmids ||= []
+  end
+  
+  # Get the list of MeSH terms that PubMed exploded. 
+  # For more information on MeSH term explosion, see http://www.pubmedcentral.nih.gov/articlerender.fcgi?artid=2651214#id443777
+  def exploded_mesh_terms
+    @exploded_mesh_terms ||= Set.new
+  end
+  
+  # Get the list of PhraseNotFound terms returned by your search
+  def phrases_not_found
+    @phrases_not_found ||= Set.new
+  end
+  
+end

data/pubmed_search.gemspec

@@ -0,0 +1,62 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{pubmed_search}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Ryan Schenk"]
+  s.date = %q{2010-01-30}
+  s.email = %q{rschenk@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/pubmed_search.rb",
+     "pubmed_search.gemspec",
+     "spec/pubmed_search_spec.rb",
+     "spec/responses/bangana_tonkinensis_cranksection.xml",
+     "spec/responses/biodiversity_informatics.xml",
+     "spec/responses/e_coli_0.xml",
+     "spec/responses/e_coli_1.xml",
+     "spec/responses/e_coli_2.xml",
+     "spec/responses/mus_musculus.xml",
+     "spec/spec_helper.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/rschenk/pubmed_search}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{A PubMed searching library with more features than BioRuby}
+  s.test_files = [
+    "spec/pubmed_search_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rschenk-simple_uri_template>, [">= 0"])
+      s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
+    else
+      s.add_dependency(%q<rschenk-simple_uri_template>, [">= 0"])
+      s.add_dependency(%q<nokogiri>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rschenk-simple_uri_template>, [">= 0"])
+    s.add_dependency(%q<nokogiri>, [">= 0"])
+  end
+end

data/spec/pubmed_search_spec.rb

@@ -0,0 +1,68 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'benchmark'
+
+fake_esearch_response "Mus musculus"
+fake_esearch_response "biodiversity informatics"
+fake_esearch_response "Bangana tonkinensis cranksection"
+
+describe PubmedSearch do
+  before(:each) do
+    PubmedSearch.skip_wait = true
+  end
+  
+  it "should have attributes count, pmids, exploded_mesh_terms, and phrases_not_found" do
+    result = PubmedSearch.new
+    result.should respond_to :count
+    result.should respond_to :pmids
+    result.should respond_to :exploded_mesh_terms
+    result.should respond_to :phrases_not_found
+  end
+  
+  describe "::search" do
+    it "should pause before sending a subsequent request to eUtils" do
+      PubmedSearch.skip_wait = false
+      Benchmark.realtime{ PubmedSearch.search "biodiversity informatics" }.should > PubmedSearch::WAIT_TIME
+    end
+    
+    it "should build a PubmedSearch object for the results" do
+      result = PubmedSearch.search("biodiversity informatics")
+      result.should be_an_instance_of PubmedSearch
+      
+      result.count.should == result.pmids.length
+      
+      result.pmids.should include 19129210, 18784790, 18483570
+            
+      result.exploded_mesh_terms.should only_include 'biodiversity', 'informatics'
+      
+      result.phrases_not_found.should be_empty
+    end
+    
+    it "should allow the user to specify retmax" do
+      FakeWeb.allow_net_connect = true
+      result = PubmedSearch.search "Mr T", :retmax => 5
+      result.pmids.length.should == 5
+      FakeWeb.allow_net_connect = false
+    end
+    
+    it "should allow multiple requests to NLM if Count > Retmax if desired" do
+      FakeWeb.register_uri(:any, "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmax=100000&retstart=0&term=e%20coli",      :body => File.dirname(__FILE__) + '/responses/e_coli_0.xml')
+      FakeWeb.register_uri(:any, "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmax=100000&retstart=100000&term=e%20coli", :body => File.dirname(__FILE__) + '/responses/e_coli_1.xml')
+      FakeWeb.register_uri(:any, "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&retmax=100000&retstart=200000&term=e%20coli", :body => File.dirname(__FILE__) + '/responses/e_coli_2.xml')
+            
+      result = PubmedSearch.search("e coli", :load_all_pmids => true)
+      
+      result.pmids.length.should == result.count
+      
+      result.pmids.should include 19464251, 9737856, 6319486 # One PMID from each of the three e_coli_n.xml files
+      
+      result.exploded_mesh_terms.should only_include 'escherichia coli'
+    end
+    
+    it "should record any PhraseNotFound elements" do
+      result = PubmedSearch.search "Bangana tonkinensis cranksection"
+      
+      result.phrases_not_found.should only_include 'Bangana', 'cranksection'
+    end
+  end
+  
+end

data/spec/responses/bangana_tonkinensis_cranksection.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" ?>
+<!DOCTYPE eSearchResult PUBLIC "-//NLM//DTD eSearchResult, 11 May 2002//EN" "http://www.ncbi.nlm.nih.gov/entrez/query/DTD/eSearch_020511.dtd">
+<eSearchResult><Count>45</Count><RetMax>45</RetMax><RetStart>0</RetStart><IdList>
+		<Id>19445149</Id>
+		<Id>19260293</Id>
+		<Id>19209761</Id>
+		<Id>19196409</Id>
+		<Id>19170963</Id>
+		<Id>18615626</Id>
+		<Id>18161942</Id>
+		<Id>17450758</Id>
+		<Id>17427256</Id>
+		<Id>17365189</Id>
+		<Id>16904915</Id>
+		<Id>16810764</Id>
+		<Id>16783704</Id>
+		<Id>16753795</Id>
+		<Id>16724846</Id>
+		<Id>16355802</Id>
+		<Id>16308206</Id>
+		<Id>16289147</Id>
+		<Id>16273300</Id>
+		<Id>16042151</Id>
+		<Id>16012772</Id>
+		<Id>15934237</Id>
+		<Id>15787740</Id>
+		<Id>15744101</Id>
+		<Id>15658812</Id>
+		<Id>15461276</Id>
+		<Id>15351108</Id>
+		<Id>15256715</Id>
+		<Id>15224417</Id>
+		<Id>15125577</Id>
+		<Id>15015265</Id>
+		<Id>14510600</Id>
+		<Id>12872400</Id>
+		<Id>12785735</Id>
+		<Id>12774385</Id>
+		<Id>12736462</Id>
+		<Id>12151076</Id>
+		<Id>10536849</Id>
+		<Id>9000883</Id>
+		<Id>7765437</Id>
+		<Id>8427879</Id>
+		<Id>1479025</Id>
+		<Id>1442048</Id>
+		<Id>1758366</Id>
+		<Id>2512948</Id>
+	</IdList><TranslationSet/><TranslationStack>   <TermSet>    <Term>tonkinensis[All Fields]</Term>    <Field>All Fields</Field>    <Count>46</Count>    <Explode>Y</Explode>   </TermSet>   <OP>GROUP</OP>  </TranslationStack><QueryTranslation>tonkinensis[All Fields]</QueryTranslation><ErrorList><PhraseNotFound>Bangana</PhraseNotFound><PhraseNotFound>cranksection</PhraseNotFound></ErrorList></eSearchResult>

data/spec/responses/biodiversity_informatics.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" ?>
+<!DOCTYPE eSearchResult PUBLIC "-//NLM//DTD eSearchResult, 11 May 2002//EN" "http://www.ncbi.nlm.nih.gov/entrez/query/DTD/eSearch_020511.dtd">
+<eSearchResult><Count>18</Count><RetMax>18</RetMax><RetStart>0</RetStart><IdList>
+		<Id>19129210</Id>
+		<Id>18784790</Id>
+		<Id>18483570</Id>
+		<Id>18445641</Id>
+		<Id>18335319</Id>
+		<Id>17704120</Id>
+		<Id>17597923</Id>
+		<Id>17594421</Id>
+		<Id>16956323</Id>
+		<Id>16701313</Id>
+		<Id>16680511</Id>
+		<Id>19455221</Id>
+		<Id>19455206</Id>
+		<Id>15253354</Id>
+		<Id>15192219</Id>
+		<Id>15063059</Id>
+		<Id>12376687</Id>
+		<Id>11009408</Id>
+	</IdList><TranslationSet><Translation>     <From>biodiversity</From>     <To>"biodiversity"[MeSH Terms] OR "biodiversity"[All Fields]</To>    </Translation><Translation>     <From>informatics</From>     <To>"informatics"[MeSH Terms] OR "informatics"[All Fields]</To>    </Translation></TranslationSet><TranslationStack>   <TermSet>    <Term>"biodiversity"[MeSH Terms]</Term>    <Field>MeSH Terms</Field>    <Count>5512</Count>    <Explode>Y</Explode>   </TermSet>   <TermSet>    <Term>"biodiversity"[All Fields]</Term>    <Field>All Fields</Field>    <Count>9741</Count>    <Explode>Y</Explode>   </TermSet>   <OP>OR</OP>   <OP>GROUP</OP>   <TermSet>    <Term>"informatics"[MeSH Terms]</Term>    <Field>MeSH Terms</Field>    <Count>6441</Count>    <Explode>Y</Explode>   </TermSet>   <TermSet>    <Term>"informatics"[All Fields]</Term>    <Field>All Fields</Field>    <Count>21168</Count>    <Explode>Y</Explode>   </TermSet>   <OP>OR</OP>   <OP>GROUP</OP>   <OP>AND</OP>   <OP>GROUP</OP>  </TranslationStack><QueryTranslation>("biodiversity"[MeSH Terms] OR "biodiversity"[All Fields]) AND ("informatics"[MeSH Terms] OR "informatics"[All Fields])</QueryTranslation></eSearchResult>