wwood-bioruby 1.2.11

data/lib/bio/io/ncbisoap.rb

@@ -0,0 +1,155 @@
+#
+# = bio/io/ncbisoap.rb - SOAP interface for NCBI Entrez Utilities
+#
+# Copyright::   Copyright (C) 2004, 2006
+#               Toshiaki Katayama <k@bioruby.org>
+# License::     The Ruby License
+#
+# $Id: ncbisoap.rb,v 1.3 2007/04/05 23:35:41 trevor Exp $
+#
+
+require 'bio/io/soapwsdl'
+
+module Bio
+class NCBI
+
+# == References
+#
+# * http://eutils.ncbi.nlm.nih.gov/entrez/query/static/esoap_help.html
+#
+# == Methods
+#
+# All methods accept a hash as its argument and most of the keys can be
+# ommited (values are string).
+#
+# Note: Methods which name ends with _MS are designed for use with
+# Microsoft Visual Studio and SOAP Toolkit 3.0
+#
+# * http://www.ncbi.nlm.nih.gov/entrez/query/static/esoap_ms_help.html
+#
+# * run_eFetch(_MS)
+#   * "db", "id", "WebEnv", "query_key", "tool", "email", "retstart",
+#     "retmax", "rettype", "strand", "seq_start", "seq_stop", "complexity",
+#     "report" 
+#
+# * run_eGquery(_MS)
+#   * "term", "tool", "email"
+#
+# * run_eInfo(_MS)
+#   * "db", "tool", "email"
+#
+# * run_eSpell(_MS)
+#   * "db", "term", "tool", "email"
+#
+# * run_eLink(_MS)
+#   * "db", "id", "reldate", "mindate", "maxdate", "datetype", "term"
+#     "dbfrom", "WebEnv", "query_key", "cmd", "tool", "email"
+#
+# * run_eSearch(_MS)
+#   * "db", "term", "WebEnv", "QueryKey", "usehistory", "tool", "email",
+#     "field", "reldate", "mindate", "maxdate", "datetype", "RetStart",
+#     "RetMax", "rettype", "sort"
+#
+# * run_eSummary(_MS)
+#   * "db", "id", "WebEnv", "query_key", "retstart", "retmax", "tool", "email"
+#
+# == Complex data types
+#
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/egquery.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/einfo.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/esearch.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/esummary.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/elink.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/efetch.xsd
+# * http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/espell.xsd
+#
+class SOAP < Bio::SOAPWSDL
+
+  BASE_URI = "http://www.ncbi.nlm.nih.gov/entrez/eutils/soap/"
+
+  # set default to EUtils
+  SERVER_URI = BASE_URI + "eutils.wsdl"
+
+  def initialize(wsdl = nil)
+    super(wsdl || self.class::SERVER_URI)
+  end
+
+  def method_missing(*arg)
+    sleep 3			# make sure to rest for 3 seconds per request
+    @driver.send(*arg)
+  end
+
+  class EUtils < Bio::NCBI::SOAP
+    SERVER_URI = BASE_URI + "eutils.wsdl"
+  end
+
+  class EUtilsLite < Bio::NCBI::SOAP
+    SERVER_URI = BASE_URI + "eutils_lite.wsdl"
+  end
+
+  class EFetch < Bio::NCBI::SOAP
+    SERVER_URI = BASE_URI + "efetch.wsdl"
+  end
+
+  class EFetchLite < Bio::NCBI::SOAP
+    SERVER_URI = BASE_URI + "efetch_lit.wsdl"
+  end
+
+end # SOAP
+end # NCBI
+end # Bio
+
+
+if __FILE__ == $0
+
+  puts ">>> Bio::NCBI::SOAP::EFetch"
+  efetch = Bio::NCBI::SOAP::EFetch.new
+
+  puts "### run_eFetch in EFetch"
+  hash = {"db" => "protein", "id" => "37776955"}
+  result = efetch.run_eFetch(hash)
+  p result
+
+  puts ">>> Bio::NCBI::SOAP::EUtils"
+  eutils = Bio::NCBI::SOAP::EUtils.new
+
+  puts "### run_eFetch in EUtils"
+  hash = {"db" => "pubmed", "id" => "12345"}
+  result = eutils.run_eFetch(hash)
+  p result
+
+  puts "### run_eGquery - Entrez meta search to count hits in each DB"
+  hash = {"term" => "kinase"}
+  result = eutils.run_eGquery(hash)      # working?
+  p result
+
+  puts "### run_eInfo - listing of the databases"
+  hash = {"db" => "protein"}
+  result = eutils.run_eInfo(hash)
+  p result
+
+  puts "### run_eSpell"
+  hash = {"db" => "pubmed", "term" => "kinas"}
+  result = eutils.run_eSpell(hash)
+  p result
+  p result["CorrectedQuery"]
+  
+  puts "### run_eLink"
+  hash = {"db" => "protein", "id" => "37776955"}
+  result = eutils.run_eLink(hash)        #  working?
+  p result
+
+  puts "### run_eSearch"
+  hash = {"db" => "pubmed", "term" => "kinase"}
+  result = eutils.run_eSearch(hash)
+  p result
+
+  puts "### run_eSummary"
+  hash = {"db" => "protein", "id" => "37776955"}
+  result = eutils.run_eSummary(hash)
+  p result
+
+end
+
+
+

data/lib/bio/io/pubmed.rb

@@ -0,0 +1,307 @@
+#
+# = bio/io/pubmed.rb - NCBI Entrez/PubMed client module
+#
+# Copyright::  Copyright (C) 2001, 2007, 2008 Toshiaki Katayama <k@bioruby.org>
+# Copyright::  Copyright (C) 2006 Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::    The Ruby License
+#
+# $Id:$
+#
+
+require 'bio/io/ncbirest'
+require 'bio/command'
+require 'cgi'
+
+module Bio
+
+# == Description
+#
+# The Bio::PubMed class provides several ways to retrieve bibliographic
+# information from the PubMed database at
+#   http://www.ncbi.nlm.nih.gov/sites/entrez?db=PubMed
+#
+# Basically, two types of queries are possible:
+#
+# * searching for PubMed IDs given a query string:
+#   * Bio::PubMed#esearch  (recommended)
+#   * Bio::PubMed#search   (only retrieves top 20 hits)
+#
+# * retrieving the MEDLINE text (i.e. authors, journal, abstract, ...)
+#   given a PubMed ID
+#   * Bio::PubMed#efetch   (recommended)
+#   * Bio::PubMed#query    (unstable for the change of the HTML design)
+#   * Bio::PubMed#pmfetch  (still working but could be obsoleted by NCBI)
+#
+# The different methods within the same group are interchangeable and should
+# return the same result.
+# 
+# Additional information about the MEDLINE format and PubMed programmable
+# APIs can be found on the following websites:
+#
+# * PubMed Overview:
+#     http://www.ncbi.nlm.nih.gov/entrez/query/static/overview.html
+# * PubMed help:
+#     http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html
+# * Entrez utilities index:
+#      http://www.ncbi.nlm.nih.gov/entrez/utils/utils_index.html
+# * How to link:
+#     http://www.ncbi.nlm.nih.gov/books/bv.fcgi?rid=helplinks.chapter.linkshelp
+#
+# == Usage
+#
+#   require 'bio'
+#
+#   # If you don't know the pubmed ID:
+#   Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics").each do |x|
+#     p x
+#   end
+#
+#   Bio::PubMed.search("(genome AND analysis) OR bioinformatics").each do |x|
+#     p x
+#   end
+#   
+#   # To retrieve the MEDLINE entry for a given PubMed ID:
+#   puts Bio::PubMed.efetch("10592173", "14693808")
+#   puts Bio::PubMed.query("10592173")
+#   puts Bio::PubMed.pmfetch("10592173")
+#
+#   # This can be converted into a Bio::MEDLINE object:
+#   manuscript = Bio::PubMed.query("10592173")
+#   medline = Bio::MEDLINE.new(manuscript)
+#  
+class PubMed < Bio::NCBI::REST
+
+  # Search the PubMed database by given keywords using E-Utils and returns 
+  # an array of PubMed IDs.
+  # 
+  # For information on the possible arguments, see
+  # http://eutils.ncbi.nlm.nih.gov/entrez/query/static/esearch_help.html#PubMed
+  # ---
+  # *Arguments*:
+  # * _str_: query string (required)
+  # * _hash_: hash of E-Utils options
+  #   * _retmode_: "xml", "html", ...
+  #   * _rettype_: "medline", ...
+  #   * _retmax_: integer (default 100)
+  #   * _retstart_: integer
+  #   * _field_
+  #   * _reldate_
+  #   * _mindate_
+  #   * _maxdate_
+  #   * _datetype_
+  # *Returns*:: array of PubMed IDs or a number of results
+  def esearch(str, hash = {})
+    opts = { "db" => "pubmed" }
+    opts.update(hash)
+    super(str, opts)
+  end
+
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
+  # entrez efetch. Multiple PubMed IDs can be provided:
+  #   Bio::PubMed.efetch(123)
+  #   Bio::PubMed.efetch([123,456,789])
+  # ---
+  # *Arguments*:
+  # * _ids_: list of PubMed IDs (required)
+  # * _hash_: hash of E-Utils options
+  #   * _retmode_: "xml", "html", ...
+  #   * _rettype_: "medline", ...
+  #   * _retmax_: integer (default 100)
+  #   * _retstart_: integer
+  #   * _field_
+  #   * _reldate_
+  #   * _mindate_
+  #   * _maxdate_
+  #   * _datetype_
+  # *Returns*:: Array of MEDLINE formatted String
+  def efetch(ids, hash = {})
+    opts = { "db" => "pubmed", "rettype"  => "medline" }
+    opts.update(hash)
+    super(ids, opts)
+  end
+
+  # Search the PubMed database by given keywords using entrez query and returns
+  # an array of PubMed IDs. Caution: this method returns the first 20 hits only.
+  # Instead, use of the 'esearch' method is strongly recomended.
+  # ---
+  # *Arguments*:
+  # * _id_: query string (required)
+  # *Returns*:: array of PubMed IDs
+  def search(str)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/sites/entrez?tool=bioruby&cmd=Search&doptcmdl=Brief&db=PubMed&term="
+
+    ncbi_access_wait
+
+    http = Bio::Command.new_http(host)
+    response = http.get(path + CGI.escape(str))
+    result = response.body
+    result = result.scan(/value="(\d+)" id="UidCheckBox"/m).flatten
+    return result
+  end
+
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
+  # entrez query.
+  # ---
+  # *Arguments*:
+  # * _id_: PubMed ID (required)
+  # *Returns*:: MEDLINE formatted String
+  def query(*ids)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/sites/entrez?tool=bioruby&cmd=Text&dopt=MEDLINE&db=PubMed&uid="
+    list = ids.collect { |x| CGI.escape(x.to_s) }.join(",")
+
+    ncbi_access_wait
+
+    http = Bio::Command.new_http(host)
+    response = http.get(path + list)
+    result = response.body
+    result = result.scan(/<pre>\s*(.*?)<\/pre>/m).flatten
+
+    if result =~ /id:.*Error occurred/
+      # id: xxxxx Error occurred: Article does not exist
+      raise( result )
+    else
+      if ids.size > 1
+        return result
+      else
+        return result.first
+      end
+    end
+  end
+
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
+  # entrez pmfetch.
+  # ---
+  # *Arguments*:
+  # * _id_: PubMed ID (required)
+  # *Returns*:: MEDLINE formatted String
+  def pmfetch(id)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/entrez/utils/pmfetch.fcgi?tool=bioruby&mode=text&report=medline&db=PubMed&id="
+
+    ncbi_access_wait
+
+    http = Bio::Command.new_http(host)
+    response = http.get(path + CGI.escape(id.to_s))
+    result = response.body
+    if result =~ /#{id}\s+Error/
+      raise( result )
+    else
+      result = result.gsub("\r", "\n").squeeze("\n").gsub(/<\/?pre>/, '')
+      return result
+    end
+  end
+
+  def self.esearch(*args)
+    self.new.esearch(*args)
+  end
+
+  def self.efetch(*args)
+    self.new.efetch(*args)
+  end
+
+  def self.search(*args)
+    self.new.search(*args)
+  end
+
+  def self.query(*args)
+    self.new.query(*args)
+  end
+
+  def self.pmfetch(*args)
+    self.new.pmfetch(*args)
+  end
+
+end # PubMed
+
+end # Bio
+
+
+if __FILE__ == $0
+
+  puts "=== instance methods ==="
+
+  pubmed = Bio::PubMed.new
+
+  puts "--- Search PubMed by E-Utils ---"
+  opts = {"rettype" => "count"}
+  puts Time.now
+  puts pubmed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  puts pubmed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  puts pubmed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  pubmed.esearch("(genome AND analysis) OR bioinformatics").each do |x|
+    puts x
+  end
+
+  puts "--- Retrieve PubMed entry by E-Utils ---"
+  puts Time.now
+  puts pubmed.efetch(16381885)
+  puts Time.now
+  puts pubmed.efetch("16381885")
+  puts Time.now
+  puts pubmed.efetch("16381885")
+  puts Time.now
+  opts = {"retmode" => "xml"}
+  puts pubmed.efetch([10592173, 14693808], opts)
+  puts Time.now
+  puts pubmed.efetch(["10592173", "14693808"], opts)
+
+  puts "--- Search PubMed by Entrez CGI ---"
+  pubmed.search("(genome AND analysis) OR bioinformatics").each do |x|
+    p x
+  end
+
+  puts "--- Retrieve PubMed entry by Entrez CGI ---"
+  puts pubmed.query("16381885")
+
+
+  puts "--- Retrieve PubMed entry by PMfetch ---"
+  puts pubmed.pmfetch("16381885")
+
+
+  puts "=== class methods ==="
+
+
+  puts "--- Search PubMed by E-Utils ---"
+  opts = {"rettype" => "count"}
+  puts Time.now
+  puts Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  puts Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  puts Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics", opts)
+  puts Time.now
+  Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics").each do |x|
+    puts x
+  end
+
+  puts "--- Retrieve PubMed entry by E-Utils ---"
+  puts Time.now
+  puts Bio::PubMed.efetch(16381885)
+  puts Time.now
+  puts Bio::PubMed.efetch("16381885")
+  puts Time.now
+  puts Bio::PubMed.efetch("16381885")
+  puts Time.now
+  opts = {"retmode" => "xml"}
+  puts Bio::PubMed.efetch([10592173, 14693808], opts)
+  puts Time.now
+  puts Bio::PubMed.efetch(["10592173", "14693808"], opts)
+
+  puts "--- Search PubMed by Entrez CGI ---"
+  Bio::PubMed.search("(genome AND analysis) OR bioinformatics").each do |x|
+    p x
+  end
+
+  puts "--- Retrieve PubMed entry by Entrez CGI ---"
+  puts Bio::PubMed.query("16381885")
+
+
+  puts "--- Retrieve PubMed entry by PMfetch ---"
+  puts Bio::PubMed.pmfetch("16381885")
+
+end