bio 1.0.0 → 1.1.0

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

@@ -1,110 +1,195 @@
 #
-# bio/io/pubmed.rb - NCBI Entrez/PubMed client module
+# = bio/io/pubmed.rb - NCBI Entrez/PubMed client module
 #
-#   Copyright (C) 2001 KATAYAMA Toshiaki <k@bioruby.org>
+# Copyright::  Copyright (C) 2001 Toshiaki Katayama <k@bioruby.org>
+# Copyright::  Copyright (C) 2006 Jan Aerts <jan.aerts@bbsrc.ac.uk>
+# License::    The Ruby License
 #
-#  This library is free software; you can redistribute it and/or
-#  modify it under the terms of the GNU Lesser General Public
-#  License as published by the Free Software Foundation; either
-#  version 2 of the License, or (at your option) any later version.
-#
-#  This library is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-#  Lesser General Public License for more details.
-#
-#  You should have received a copy of the GNU Lesser General Public
-#  License along with this library; if not, write to the Free Software
-#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
-#
-#  $Id: pubmed.rb,v 1.12 2005/09/08 01:22:12 k Exp $
+# $Id: pubmed.rb,v 1.16 2007/04/05 23:35:41 trevor Exp $
 #
 
 require 'net/http'
 require 'cgi' unless defined?(CGI)
+require 'bio/command'
 
 module Bio
 
-  class PubMed
-
-    def self.query(id)
-      host = "www.ncbi.nlm.nih.gov"
-      path = "/entrez/query.fcgi?tool=bioruby&cmd=Text&dopt=MEDLINE&db=PubMed&uid="
-
-      http = Net::HTTP.new(host)
-      response, = http.get(path + 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.pmfetch(id)
-      host = "www.ncbi.nlm.nih.gov"
-      path = "/entrez/utils/pmfetch.fcgi?tool=bioruby&mode=text&report=medline&db=PubMed&id="
-
-      http = Net::HTTP.new(host)
-      response, = http.get(path + 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.search(str)
-      host = "www.ncbi.nlm.nih.gov"
-      path = "/entrez/query.fcgi?tool=bioruby&cmd=Search&doptcmdl=MEDLINE&db=PubMed&term="
+# == Description
+#
+# The Bio::PubMed class provides several ways to retrieve bibliographic
+# information from the PubMed database at
+# http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=PubMed. Basically, two
+# types of queries are possible:
+#
+# * searching for PubMed IDs given a query string:
+#   * Bio::PubMed#search
+#   * Bio::PubMed#esearch
+#
+# * retrieving the MEDLINE text (i.e. authors, journal, abstract, ...)
+#   given a PubMed ID
+#   * Bio::PubMed#query
+#   * Bio::PubMed#pmfetch
+#   * Bio::PubMed#efetch
+#
+# 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:
+#
+# * Overview: http://www.ncbi.nlm.nih.gov/entrez/query/static/overview.html
+# * How to link: http://www.ncbi.nlm.nih.gov/entrez/query/static/linking.html
+# * MEDLINE format: http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html#MEDLINEDisplayFormat
+# * Search field descriptions and tags: http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html#SearchFieldDescriptionsandTags
+# * Entrez utilities index: http://www.ncbi.nlm.nih.gov/entrez/utils/utils_index.html
+# * PmFetch CGI help: http://www.ncbi.nlm.nih.gov/entrez/utils/pmfetch_help.html
+# * E-Utilities CGI help: http://eutils.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html
+#
+# == Usage
+#
+#   require 'bio'
+#
+#   # If you don't know the pubmed ID:
+#   Bio::PubMed.search("(genome AND analysis) OR bioinformatics)").each do |x|
+#     p x
+#   end
+#   Bio::PubMed.esearch("(genome AND analysis) OR bioinformatics)").each do |x|
+#     p x
+#   end
+#   
+#   # To retrieve the MEDLINE entry for a given PubMed ID:
+#   puts Bio::PubMed.query("10592173")
+#   puts Bio::PubMed.pmfetch("10592173")
+#   puts Bio::PubMed.efetch("10592173", "14693808")
+#   # This can be converted into a Bio::MEDLINE object:
+#   manuscript = Bio::PubMed.query("10592173")
+#   medline = Bio::MEDLINE(manuscript)
+#  
+class PubMed
+
+  # Search the PubMed database by given keywords using entrez query and returns
+  # an array of PubMed IDs.
+  # ---
+  # *Arguments*:
+  # * _id_: query string (required)
+  # *Returns*:: array of PubMed IDs
+  def self.search(str)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/entrez/query.fcgi?tool=bioruby&cmd=Search&doptcmdl=MEDLINE&db=PubMed&term="
+
+    http = Bio::Command.new_http(host)
+    response, = http.get(path + CGI.escape(str))
+    result = response.body
+    result = result.gsub("\r", "\n").squeeze("\n")
+    result = result.scan(/<pre>(.*?)<\/pre>/m).flatten
+    return result
+  end
 
-      http = Net::HTTP.new(host)
-      response, = http.get(path + CGI.escape(str))
-      result = response.body
-      result = result.gsub("\r", "\n").squeeze("\n")
-      result = result.scan(/<pre>(.*?)<\/pre>/m).flatten
-      return result
+  # 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*:
+  # * _id_: query string (required)
+  # * _field_
+  # * _reldate_
+  # * _mindate_
+  # * _maxdate_
+  # * _datetype_
+  # * _retstart_
+  # * _retmax_ (default 100)
+  # * _retmode_
+  # * _rettype_
+  # *Returns*:: array of PubMed IDs
+  def self.esearch(str, hash = {})
+    hash['retmax'] = 100 unless hash['retmax']
+
+    opts = []
+    hash.each do |k, v|
+      opts << "#{k}=#{v}"
     end
 
-    def self.esearch(str, hash = {})
-      hash['retmax'] = 100 unless hash['retmax']
-
-      opts = []
-      hash.each do |k, v|
-        opts << "#{k}=#{v}"
-      end
+    host = "eutils.ncbi.nlm.nih.gov"
+    path = "/entrez/eutils/esearch.fcgi?tool=bioruby&db=pubmed&#{opts.join('&')}&term="
 
-      host = "eutils.ncbi.nlm.nih.gov"
-      path = "/entrez/eutils/esearch.fcgi?tool=bioruby&db=pubmed&#{opts.join('&')}&term="
+    http = Bio::Command.new_http(host)
+    response, = http.get(path + CGI.escape(str))
+    result = response.body
+    result = result.scan(/<Id>(.*?)<\/Id>/m).flatten
+    return result
+  end
 
-      http = Net::HTTP.new(host)
-      response, = http.get(path + CGI.escape(str))
-      result = response.body
-      result = result.scan(/<Id>(.*?)<\/Id>/m).flatten
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
+  # entrez query.
+  # ---
+  # *Arguments*:
+  # * _id_: PubMed ID (required)
+  # *Returns*:: MEDLINE formatted String
+  def self.query(id)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/entrez/query.fcgi?tool=bioruby&cmd=Text&dopt=MEDLINE&db=PubMed&uid="
+
+    http = Bio::Command.new_http(host)
+    response, = http.get(path + 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.efetch(*ids)
-      return [] if ids.empty?
-
-      host = "eutils.ncbi.nlm.nih.gov"
-      path = "/entrez/eutils/efetch.fcgi?tool=bioruby&db=pubmed&retmode=text&rettype=medline&id="
-
-      ids = ids.join(",")
-
-      http = Net::HTTP.new(host)
-      response, = http.get(path + ids)
-      result = response.body
-      result = result.split(/\n\n+/)
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
+  # entrez pmfetch.
+  # ---
+  # *Arguments*:
+  # * _id_: PubMed ID (required)
+  # *Returns*:: MEDLINE formatted String
+  def self.pmfetch(id)
+    host = "www.ncbi.nlm.nih.gov"
+    path = "/entrez/utils/pmfetch.fcgi?tool=bioruby&mode=text&report=medline&db=PubMed&id="
+
+    http = Bio::Command.new_http(host)
+    response, = http.get(path + 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
 
+  # 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)
+  #   Bio::PubMed.efetch([123,456,789])
+  # ---
+  # *Arguments*:
+  # * _ids_: list of PubMed IDs (required)
+  # *Returns*:: MEDLINE formatted String
+  def self.efetch(*ids)
+    return [] if ids.empty?
+
+    host = "eutils.ncbi.nlm.nih.gov"
+    path = "/entrez/eutils/efetch.fcgi?tool=bioruby&db=pubmed&retmode=text&rettype=medline&id="
+
+    ids = ids.join(",")
+
+    http = Bio::Command.new_http(host)
+    response, = http.get(path + ids)
+    result = response.body
+    result = result.split(/\n\n+/)
+    return result
   end
 
-end
+end # PubMed
+
+end # Bio
 
 
 if __FILE__ == $0
@@ -124,66 +209,3 @@ if __FILE__ == $0
   puts Bio::PubMed.efetch("10592173", "14693808")
 
 end
-
-=begin
-
-= Bio::PubMed
-
-These class methods access NCBI/PubMed database via HTTP.
-
---- Bio::PubMed.esearch(str, options)
-
-      Search keywords in PubMed by E-Utils and returns an array of PubMed IDs.
-      Options can be a hash containing keys include 'field', 'reldate',
-      'mindate', 'maxdate', 'datetype', 'retstart', 'retmax', 'retmode',
-      and 'rettype' as specified in the following URL:
-
-        ((<URL:http://eutils.ncbi.nlm.nih.gov/entrez/query/static/esearch_help.html#PubMed>))
-
-     Default 'retmax' is 100.
-
---- Bio::PubMed.efetch(pmids)
-
-      Returns an array of MEDLINE records.  A list of PubMed IDs can be
-      supplied as following:
-
-        Bio::PubMed.efetch(123)
-        Bio::PubMed.efetch(123,456,789)
-        Bio::PubMed.efetch([123,456,789])
-
---- Bio::PubMed.query(pmid)
-
-      Retrieve PubMed entry by PMID and returns MEDLINE format string (can
-      be parsed by the Bio::MEDLINE and can be converted into Bio::Reference
-      object).
-
---- Bio::PubMed.pmfetch(pmid)
-
-      Just another query method (by pmfetch).
-
---- Bio::PubMed.search(str)
-
-      Search the PubMed database by given keywords and returns the list of
-      matched records in MEDLINE format.
-
-
-= For more informations
-
-* Overview
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/query/static/overview.html>))
-* How to link
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/query/static/linking.html>))
-* MEDLINE format
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html#MEDLINEDisplayFormat>))
-* Search field descriptions and tags
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html#SearchFieldDescriptionsandTags>))
-* Entrez utilities index
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/utils/utils_index.html>))
-* PmFetch CGI help
-  * ((<URL:http://www.ncbi.nlm.nih.gov/entrez/utils/pmfetch_help.html>))
-* E-Utilities CGI help
-  * ((<URL:http://eutils.ncbi.nlm.nih.gov/entrez/query/static/eutils_help.html>))
-
-=end
-
-