bio 1.4.3.0001 → 1.5.0

data/lib/bio/io/flatfile/buffer.rb

@@ -5,7 +5,6 @@
 #
 # License:: The Ruby License
 #
-#  $Id:$
 #
 #
 # See documents for Bio::FlatFile::BufferedInputStream and Bio::FlatFile.
@@ -151,8 +150,8 @@ module Bio
               yield self.new(fobj, uri.to_s)
             end
           else
-            fobj = uri.open(*arg)
-            self.new(fobj, uri.to_s)
+            fobj0 = uri.open(*arg)
+            self.new(fobj0, uri.to_s)
           end
         else
           if block_given?
@@ -160,8 +159,8 @@ module Bio
               yield self.new(fobj, uri)
             end
           else
-            fobj = OpenURI.open_uri(uri, *arg)
-            self.new(fobj, uri)
+            fobj0 = OpenURI.open_uri(uri, *arg)
+            self.new(fobj0, uri)
           end
         end
       end

data/lib/bio/io/hinv.rb

@@ -4,7 +4,6 @@
 # Copyright::  Copyright (C) 2008 Toshiaki Katayama <k@bioruby.org>
 # License::    The Ruby License
 #
-# $Id:$
 #
 
 require 'bio/command'
@@ -17,11 +16,11 @@ module Bio
   # Accessing the H-invDB web services.
   #
   # * http://www.h-invitational.jp/
-  # * http://www.jbirc.aist.go.jp/hinv/hws/doc/index.html
+  # * http://h-invitational.jp/hinv/hws/doc/index.html
   #
   class Hinv
 
-    BASE_URI = "http://www.jbirc.aist.go.jp/hinv/hws/"
+    BASE_URI = "http://h-invitational.jp/hinv/hws/"
 
     module Common
       def query(options = nil)

data/lib/bio/io/ncbirest.rb

@@ -15,13 +15,21 @@ module Bio
 
 class NCBI
 
-  autoload :SOAP,       'bio/io/ncbisoap'
 
   # (Hash) Default parameters for Entrez (eUtils).
   # They may also be used for other NCBI services.
   ENTREZ_DEFAULT_PARAMETERS = {
-    'tool' => "#{$0} (bioruby/#{Bio::BIORUBY_VERSION_ID})",
-    'email' => nil,
+    # Cited from
+    # http://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.Release_Notes
+    #  tool:
+    #  Name of application making the E-utility call.
+    #  Value must be a string with no internal spaces.
+    'tool' => "bioruby",
+    # Cited from
+    # http://www.ncbi.nlm.nih.gov/books/NBK25497/
+    # The value of email should be a complete and valid e-mail address
+    # of the software developer and not that of a third-party end user.
+    'email' => 'staff@bioruby.org',
   }
 
   # Resets Entrez (eUtils) default parameters.
@@ -29,8 +37,8 @@ class NCBI
   # *Returns*:: (Hash) default parameters
   def self.reset_entrez_default_parameters
     h = {
-      'tool' => "#{$0} (bioruby/#{Bio::BIORUBY_VERSION_ID})",
-      'email' => nil,
+      'tool'  => "bioruby",
+      'email' => 'staff@bioruby.org',
     }
     ENTREZ_DEFAULT_PARAMETERS.clear
     ENTREZ_DEFAULT_PARAMETERS.update(h)
@@ -45,6 +53,24 @@ class NCBI
 
   # Sets default email address used for Entrez (eUtils).
   # It may also be used for other NCBI services.
+  #
+  # In http://www.ncbi.nlm.nih.gov/books/NBK25497/ 
+  # NCBI says:
+  # "The value of email should be a complete and valid e-mail address of
+  # the software developer and not that of a third-party end user."
+  #
+  # By default, email address of BioRuby staffs is set.
+  #
+  # From the above NCBI documentation, the tool and email value is used
+  # only for unblocking IP addresses blocked by NCBI due to excess requests.
+  # For the purpose, NCBI says:
+  # "Please be aware that merely providing values for tool and email
+  # in requests is not sufficient to comply with this policy;
+  # these values must be registered with NCBI."
+  #
+  # Please use your own email address and tool name when registering
+  # tool and email values to NCBI.
+  #
   # ---
   # *Arguments*:
   # * (required) _str_: (String) email address
@@ -62,6 +88,17 @@ class NCBI
 
   # Sets default tool name for Entrez (eUtils).
   # It may also be used for other NCBI services.
+  #
+  # In http://www.ncbi.nlm.nih.gov/books/NBK25497/ 
+  # NCBI says:
+  # "The value of tool should be a string with no internal spaces that
+  # uniquely identifies the software producing the request."
+  #
+  # "bioruby" is set by default.
+  # Please use your own tool name when registering to NCBI.
+  #
+  # See the document of default_email= for more information.
+  #
   # ---
   # *Arguments*:
   # * (required) _str_: (String) tool name
@@ -148,7 +185,7 @@ class REST
   def ncbi_check_parameters(opts)
     #return if Time.now < Time.gm(2010,5,31)
     if opts['email'].to_s.empty? then
-      raise 'Set email parameter for the query, or set Bio::NCBI.default_email = "(your email address)"'
+      raise 'Set email parameter for the query, or set Bio::NCBI.default_email = "(email address of the author of this software)"'
     end
     if opts['tool'].to_s.empty? then
       raise 'Set tool parameter for the query, or set Bio::NCBI.default_tool = "(your tool name)"'

data/lib/bio/io/pubmed.rb

@@ -5,47 +5,42 @@
 # 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
+# information from the PubMed database at NCBI.
 #
 # 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)
+#   * Bio::PubMed#search   (only retrieves top 20 hits; will be deprecated)
 #
 # * 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)
+#   * Bio::PubMed#query    (will be deprecated)
+#   * Bio::PubMed#pmfetch  (will be deprecated)
 #
-# The different methods within the same group are interchangeable and should
-# return the same result.
+# Since BioRuby 1.5, all implementations uses NCBI E-Utilities services.
+# The different methods within the same group still remain because
+# specifications of arguments and/or return values are different.
+# The search, query, and pmfetch will be obsoleted in the future.
 # 
 # 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
+# * PubMed Tutorial:
+#   http://www.nlm.nih.gov/bsd/disted/pubmedtutorial/index.html
+# * E-utilities Quick Start:
+#   http://www.ncbi.nlm.nih.gov/books/NBK25500/
+# * Creating a Web Link to PubMed:
+#   http://www.ncbi.nlm.nih.gov/books/NBK3862/
 #
 # == Usage
 #
@@ -61,10 +56,14 @@ module Bio
 #   end
 #   
 #   # To retrieve the MEDLINE entry for a given PubMed ID:
-#   puts Bio::PubMed.efetch("10592173", "14693808")
+#   Bio::PubMed.efetch("10592173").each { |x| puts x }
 #   puts Bio::PubMed.query("10592173")
 #   puts Bio::PubMed.pmfetch("10592173")
 #
+#   # To retrieve MEDLINE entries for given PubMed IDs:
+#   Bio::PubMed.efetch([ "10592173", "14693808" ]).each { |x| puts x }
+#   puts Bio::PubMed.query("10592173", "14693808") # returns a String
+#
 #   # This can be converted into a Bio::MEDLINE object:
 #   manuscript = Bio::PubMed.query("10592173")
 #   medline = Bio::MEDLINE.new(manuscript)
@@ -80,15 +79,15 @@ class PubMed < Bio::NCBI::REST
   # *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_
+  #   * _"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" }
@@ -104,15 +103,15 @@ class PubMed < Bio::NCBI::REST
   # *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_
+  #   * _"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" }
@@ -124,26 +123,29 @@ class PubMed < Bio::NCBI::REST
     result
   end
 
+  # This method will be DEPRECATED in the future.
+  #
   # 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.
+  # an array of PubMed IDs.
+  #
+  # Caution: this method returns the first 20 hits only,
+  #
   # Instead, use of the 'esearch' method is strongly recomended.
+  #
+  # Implementation details: Since BioRuby 1.5, this method internally uses
+  # NCBI EUtils with retmax=20 by using Bio::PubMed#efetch method.
+  #
   # ---
   # *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
+    warn "Bio::PubMed#search is now a subset of Bio::PubMed#esearch. Using Bio::PubMed#esearch is recommended." if $VERBOSE
+    esearch(str, { "retmax" => 20 })
   end
 
+  # This method will be DEPRECATED in the future.
+  #
   # Retrieve PubMed entry by PMID and returns MEDLINE formatted string using
   # entrez query.
   # ---
@@ -151,68 +153,61 @@ class PubMed < Bio::NCBI::REST
   # * _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 )
+    warn "Bio::PubMed#query internally uses Bio::PubMed#efetch. Using Bio::PubMed#efetch is recommended." if $VERBOSE
+    ret = efetch(ids)
+    if ret && ret.size > 0 then
+      ret.join("\n\n") + "\n"
     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.
+  # This method will be DEPRECATED in the future.
+  #
+  # Retrieve PubMed entry by PMID and returns MEDLINE formatted string.
+  #
   # ---
   # *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
+    warn "Bio::PubMed#pmfetch internally use Bio::PubMed#efetch. Using Bio::PubMed#efetch is recommended." if $VERBOSE
 
-    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 )
+    ret = efetch(id)
+    if ret && ret.size > 0 then
+      ret.join("\n\n") + "\n"
     else
-      result = result.gsub("\r", "\n").squeeze("\n").gsub(/<\/?pre>/, '')
-      return result
+      ""
     end
   end
 
+  # The same as Bio::PubMed.new.esearch(*args).
   def self.esearch(*args)
     self.new.esearch(*args)
   end
 
+  # The same as Bio::PubMed.new.efetch(*args).
   def self.efetch(*args)
     self.new.efetch(*args)
   end
 
+  # This method will be DEPRECATED. Use esearch method.
+  #
+  # The same as Bio::PubMed.new.search(*args).
   def self.search(*args)
     self.new.search(*args)
   end
 
+  # This method will be DEPRECATED. Use efetch method.
+  #
+  # The same as Bio::PubMed.new.query(*args).
   def self.query(*args)
     self.new.query(*args)
   end
 
+  # This method will be DEPRECATED. Use efetch method.
+  #
+  # The same as Bio::PubMed.new.pmfetch(*args).
   def self.pmfetch(*args)
     self.new.pmfetch(*args)
   end

data/lib/bio/io/togows.rb

@@ -4,7 +4,6 @@
 # Copyright::  Copyright (C) 2009 Naohisa Goto <ng@bioruby.org>
 # License::    The Ruby License
 #
-# $Id:$
 #
 # Bio::TogoWS is a set of clients for the TogoWS web services
 # (http://togows.dbcls.jp/).
@@ -245,9 +244,16 @@ module Bio
         rescue NoMethodError
           ids = ids.to_s
         end
-        ids = a.join(',') if a
 
-        arg = [ 'entry', database, ids ]
+        arg = [ 'entry', database ]
+        if a then
+          b = a.dup
+          (a.size - 1).downto(1) { |i| b.insert(i, :",") }
+          arg.concat b
+        else
+          arg.push ids
+        end
+
         arg.push field if field
         arg[-1] = "#{arg[-1]}.#{format}" if format
         response = get(*arg)
@@ -280,7 +286,7 @@ module Bio
         arg = [ 'search', database, query ]
         if offset then
           limit ||= 1
-          arg.push "#{offset},#{limit}"
+          arg.concat [ "#{offset}", :",", "#{limit}" ]
         end
         arg[-1] = "#{arg[-1]}.#{format}" if format
         response = get(*arg)
@@ -398,8 +404,7 @@ module Bio
       end
 
       # Access to the TogoWS by using POST method.
-      # The data is stored to the form key 'data'.
-      # Mime type is 'application/x-www-form-urlencoded'.
+      # Mime type is 'application/octet-stream'.
       # ---
       # *Arguments*:
       # * (required) _data_: String
@@ -408,19 +413,37 @@ module Bio
       def post_data(data, *paths)
         path = make_path(paths)
         if @debug then
-          $stderr.puts "TogoWS: Bio::Command.http_post_form(#{path.inspect}, { \"data\" => (#{data.size} bytes) }, #{@header.inspect})"
+          $stderr.puts "TogoWS: Bio::Command.http_post(#{path.inspect}, data(#{data.size} bytes), #{@header.inspect})"
         end
         togows_access_wait
-        Bio::Command.http_post_form(@http, path, { 'data' => data }, @header)
+        Bio::Command.http_post(@http, path, data, @header)
       end
 
       # Generates path string from the given paths.
+      # Symbol objects are not URL-escaped.
+      # String objects are joined with '/'.
+      # Symbol objects are joined directly without '/'.
+      #
       # ---
       # *Arguments*:
-      # * (required) _paths_: Array containing String objects
+      # * (required) _paths_: Array containing String or Symbol objects
       # *Returns*:: String
       def make_path(paths)
-        @pathbase + paths.collect { |x| CGI.escape(x.to_s) }.join('/')
+        flag_sep = false
+        a = paths.collect do |x|
+          case x
+          when Symbol
+            # without URL escape
+            flag_sep = false
+            str = x.to_s
+          else
+            str = CGI.escape(x.to_s)
+            str = '/' + str if flag_sep
+            flag_sep = true
+          end
+          str
+        end
+        @pathbase + a.join('')
       end
 
       # If response.code == "200", returns body as a String.