ngoto-bio 1.2.9.9501 → 1.3.0

data/lib/bio/io/togows.rb

@@ -0,0 +1,458 @@
+#
+# = bio/io/togows.rb - REST interface for TogoWS
+#
+# 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/).
+#
+# * Bio::TogoWS::REST is a REST client for the TogoWS.
+# * Bio::TogoWS::SOAP will be implemented in the future.
+#
+
+require 'uri'
+require 'cgi'
+require 'bio/version'
+require 'bio/command'
+
+module Bio
+
+  # Bio::TogoWS is a namespace for the TogoWS web services.
+  module TogoWS
+
+    # Internal Use Only.
+    #
+    # Bio::TogoWS::AccessWait is a module to implement a
+    # private method for access.
+    module AccessWait
+
+      # common default access wait for TogoWS services
+      TOGOWS_ACCESS_WAIT = 1
+
+      # Maximum waiting time to avoid dead lock.
+      # When exceeding this value, (max/2) + rand(max) is used,
+      # to randomize access.
+      # This means real maximum waiting time is (max * 1.5).
+      TOGOWS_ACCESS_WAIT_MAX = 60
+
+      # Sleeping if needed. 
+      # It sleeps about TOGOWS_ACCESS_WAIT * (number of waiting processes).
+      #
+      # ---
+      # *Returns*:: (Numeric) sleeped time
+      def togows_access_wait
+        w_min = TOGOWS_ACCESS_WAIT
+        debug = defined?(@debug) && @debug
+
+        # initializing class variable
+        @@togows_last_access ||= nil
+
+        # determines waiting time
+        wait = 0
+        if last = @@togows_last_access then
+          elapsed = Time.now - last
+          if elapsed < w_min then
+            wait = w_min - elapsed
+          end
+        end
+
+        # If wait is too long, truncated to TOGOWS_ACCESS_WAIT_MAX.
+        if wait > TOGOWS_ACCESS_WAIT_MAX then
+          orig_wait = wait
+          wait = TOGOWS_ACCESS_WAIT_MAX
+          wait = wait / 2 + rand(wait)
+          if debug then
+            $stderr.puts "TogoWS: sleeping time #{orig_wait} is too long and set to #{wait} to avoid dead lock."
+          end
+          newlast = Time.now + TOGOWS_ACCESS_WAIT_MAX
+        else
+          newlast = Time.now + wait
+        end
+
+        # put expected end time of sleeping
+        if !@@togows_last_access or @@togows_last_access < newlast then
+          @@togows_last_access = newlast
+        end
+
+        # sleeping if needed
+        if wait > 0 then
+          $stderr.puts "TogoWS: sleeping #{wait} second" if debug
+          sleep(wait)
+        end
+        # returns waited time
+        wait
+      end
+      private :togows_access_wait
+
+      # (private) resets last access.
+      # Should be used only for debug purpose.
+      def reset_togows_access_wait
+        @@togows_last_access = nil
+      end
+      private :reset_togows_access_wait
+
+    end #module AccessWait
+
+    # == Description
+    #
+    # Bio::TogoWS::REST is a REST client for the TogoWS web service.
+    #
+    # Details of the service are desribed in the following URI.
+    #
+    # * http://togows.dbcls.jp/site/en/rest.html
+    #
+    # == Examples
+    # 
+    # For light users, class methods can be used.
+    #
+    #   print Bio::TogoWS::REST.entry('genbank', 'AF237819')
+    #   print Bio::TogoWS::REST.search('uniprot', 'lung cancer')
+    #
+    # For heavy users, an instance of the REST class can be created, and
+    # using the instance is more efficient than using class methods.
+    #
+    #   t = Bio::TogoWS::REST.new
+    #   print t.entry('genbank', 'AF237819')
+    #   print t.search('uniprot', 'lung cancer')
+    #
+    # == References
+    #
+    # * http://togows.dbcls.jp/site/en/rest.html
+    #
+    class REST
+
+      include AccessWait
+
+      # URI of the TogoWS REST service
+      BASE_URI = 'http://togows.dbcls.jp/'.freeze
+
+      # preset default databases used by the retrieve method.
+      #
+      DEFAULT_RETRIEVAL_DATABASES =
+        %w( genbank uniprot embl ddbj dad )
+
+      # Creates a new object.
+      # ---
+      # *Arguments*:
+      # * (optional) _uri_: String or URI object
+      # *Returns*:: new object
+      def initialize(uri = BASE_URI)
+        uri = URI.parse(uri) unless uri.kind_of?(URI)
+        @pathbase = uri.path
+        @pathbase = '/' + @pathbase unless /\A\// =~ @pathbase
+        @pathbase = @pathbase + '/' unless /\/\z/ =~ @pathbase
+        @http = Bio::Command.new_http(uri.host, uri.port)
+        @header = {
+          'User-Agent' => "BioRuby/#{Bio::BIORUBY_VERSION_ID}"
+        }
+        @debug = false
+      end
+
+      # If true, shows debug information to $stderr.
+      attr_accessor :debug
+
+      # Debug purpose only.
+      # Returns Net::HTTP object used inside the object.
+      # The method will be changed in the future if the implementation
+      # of this class is changed.
+      def internal_http
+        @http
+      end
+
+      # Intelligent version of the entry method.
+      # If two or more databases are specified, sequentially tries
+      # them until valid entry is obtained.
+      #
+      # If database is not specified, preset default databases are used. 
+      # See DEFAULT_RETRIEVAL_DATABASES for details.
+      #
+      # When multiple IDs and multiple databases are specified, sequentially
+      # tries each IDs. Note that results with no hits found or with server
+      # errors are regarded as void strings. Also note that data format of
+      # the result entries can be different from entries to entries.
+      # 
+      # ---
+      # *Arguments*:
+      # * (required) _ids_: (String) an entry ID, or
+      #   (Array containing String) IDs. Note that strings containing ","
+      # * (optional) _hash_: (Hash) options below can be passed as a hash.
+      #   * (optional) <I>:database</I>: (String) database name, or
+      #     (Array containing String) database names.
+      #   * (optional) <I>:format</I>: (String) format
+      #   * (optional) <I>:field</I>: (String) gets only the specified field
+      # *Returns*:: String or nil
+      def retrieve(ids, hash = {})
+        begin
+          a = ids.to_ary
+        rescue NoMethodError
+          ids = ids.to_s
+        end
+        ids = a.join(',') if a
+        ids = ids.split(',')
+
+        dbs = hash[:database] || DEFAULT_RETRIEVAL_DATABASES
+        begin
+          dbs.to_ary
+        rescue NoMethodError
+          dbs = dbs.to_s.empty? ? [] : [ dbs.to_s ]
+        end
+        return nil if dbs.empty? or ids.empty?
+
+        if dbs.size == 1 then
+          return entry(dbs[0], ids, hash[:format], hash[:field])
+        end
+
+        results = []
+        ids.each do |idstr|
+          dbs.each do |dbstr|
+            r = entry(dbstr, idstr, hash[:format], hash[:field])
+            if r and !r.strip.empty? then
+              results.push r
+              break
+            end
+          end #dbs.each
+        end #ids.each
+        
+        results.join('')
+      end #def retrieve
+
+      # Retrieves entries corresponding to the specified IDs.
+      #
+      # Example:
+      #   t = Bio::TogoWS::REST.new
+      #   kuma = t.entry('genbank', 'AF237819')
+      #   # multiple IDs at a time
+      #   misc = t.entry('genbank', [ 'AF237819', 'AF237820' ])
+      #   # with format change
+      #   p53 = t.entry('uniprot', 'P53_HUMAN', 'fasta')
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _database_: (String) database name
+      # * (required) _ids_: (String) an entry ID, or
+      #   (Array containing String) IDs. Note that strings containing ","
+      #   are regarded as multiple IDs.
+      # * (optional) _format_: (String) format. nil means the default format
+      #   (differs depending on the database).
+      # * (optional) _field_: (String) gets only the specified field if not nil
+      # *Returns*:: String or nil
+      def entry(database, ids, format = nil, field = nil)
+        begin
+          a = ids.to_ary
+        rescue NoMethodError
+          ids = ids.to_s
+        end
+        ids = a.join(',') if a
+
+        arg = [ 'entry', database, ids ]
+        arg.push field if field
+        arg[-1] = "#{arg[-1]}.#{format}" if format
+        response = get(*arg)
+
+        prepare_return_value(response)
+      end
+
+      # Database search.
+      # Format of the search term string follows the Common Query Language.
+      # * http://en.wikipedia.org/wiki/Common_Query_Language
+      #
+      # Example:
+      #   t = Bio::TogoWS::REST.new
+      #   print t.search('uniprot', 'lung cancer')
+      #   # only get the 10th and 11th hit ID
+      #   print t.search('uniprot', 'lung cancer', 10, 2)
+      #   # with json format
+      #   print t.search('uniprot', 'lung cancer', 10, 2, 'json')
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _database_: (String) database name
+      # * (required) _query_: (String) query string
+      # * (optional) _offset_: (Integer) offset in search results.
+      # * (optional) _limit_: (Integer) max. number of returned results.
+      #   If offset is not nil and the limit is nil, it is set to 1.
+      # * (optional) _format_: (String) format. nil means the default format.
+      # *Returns*:: String or nil
+      def search(database, query, offset = nil, limit = nil, format = nil)
+        arg = [ 'search', database, query ]
+        if offset then
+          limit ||= 1
+          arg.push "#{offset},#{limit}"
+        end
+        arg[-1] = "#{arg[-1]}.#{format}" if format
+        response = get(*arg)
+
+        prepare_return_value(response)
+      end
+
+      # Data format conversion.
+      #
+      # Example:
+      #   t = Bio::TogoWS::REST.new
+      #   blast_string = File.read('test.blastn')
+      #   t.convert(blast_string, 'blast', 'gff')
+      #
+      # ---
+      # *Arguments*:
+      # * (required) _text_: (String) input data
+      # * (required) _inputformat_: (String) data source format
+      # * (required) _format_: (String) output format
+      # *Returns*:: String or nil
+      def convert(data, inputformat, format)
+        response = post_data(data, 'convert', "#{inputformat}.#{format}")
+
+        prepare_return_value(response)
+      end
+
+      # Returns list of available databases in the entry service.
+      # ---
+      # *Returns*:: Array containing String
+      def entry_database_list
+        database_list('entry')
+      end
+
+      # Returns list of available databases in the search service.
+      # ---
+      # *Returns*:: Array containing String
+      def search_database_list
+        database_list('search')
+      end
+
+      #--
+      # class methods
+      #++
+
+      # The same as Bio::TogoWS::REST#entry.
+      def self.entry(*arg)
+        self.new.entry(*arg)
+      end
+
+      # The same as Bio::TogoWS::REST#search.
+      def self.search(*arg)
+        self.new.search(*arg)
+      end
+
+      # The same as Bio::TogoWS::REST#convert.
+      def self.convert(*arg)
+        self.new.convert(*arg)
+      end
+
+      # The same as Bio::TogoWS::REST#retrieve.
+      def self.retrieve(*arg)
+        self.new.retrieve(*arg)
+      end
+
+      # The same as Bio::TogoWS::REST#entry_database_list
+      def self.entry_database_list(*arg)
+        self.new.entry_database_list(*arg)
+      end
+
+      # The same as Bio::TogoWS::REST#search_database_list
+      def self.search_database_list(*arg)
+        self.new.search_database_list(*arg)
+      end
+
+      private
+
+      # Access to the TogoWS by using GET method.
+      #
+      # Example 1:
+      #   get('entry', 'genbank', AF209156')
+      # Example 2:
+      #   get('search', 'uniprot', 'lung cancer')
+      #
+      # ---
+      # *Arguments*:
+      # * (optional) _path_: String
+      # *Returns*:: Net::HTTPResponse object
+      def get(*paths)
+        path = make_path(paths)
+        if @debug then
+          $stderr.puts "TogoWS: HTTP#get(#{path.inspect}, #{@header.inspect})"
+        end
+        togows_access_wait
+        @http.get(path, @header)
+      end
+
+      # Access to the TogoWS by using GET method. 
+      # Always adds '/' at the end of the path.
+      #
+      # Example 1:
+      #   get_dir('entry')
+      #
+      # ---
+      # *Arguments*:
+      # * (optional) _path_: String
+      # *Returns*:: Net::HTTPResponse object
+      def get_dir(*paths)
+        path = make_path(paths)
+        path += '/' unless /\/\z/ =~ path
+        if @debug then
+          $stderr.puts "TogoWS: HTTP#get(#{path.inspect}, #{@header.inspect})"
+        end
+        togows_access_wait
+        @http.get(path, @header)
+      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'.
+      # ---
+      # *Arguments*:
+      # * (required) _data_: String
+      # * (optional) _path_: String
+      # *Returns*:: Net::HTTPResponse object
+      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})"
+        end
+        togows_access_wait
+        Bio::Command.http_post_form(@http, path, { 'data' => data }, @header)
+      end
+
+      # Generates path string from the given paths.
+      # ---
+      # *Arguments*:
+      # * (required) _paths_: Array containing String objects
+      # *Returns*:: String
+      def make_path(paths)
+        @pathbase + paths.collect { |x| CGI.escape(x.to_s) }.join('/')
+      end
+
+      # If response.code == "200", returns body as a String.
+      # Otherwise, returns nil.
+      def prepare_return_value(response)
+        if @debug then
+          $stderr.puts "TogoWS: #{response.inspect}"
+        end
+        if response.code == "200" then
+          response.body
+        else
+          nil
+        end
+      end
+
+      # Returns list of available databases
+      # ---
+      # *Arguments*:
+      # * (required) _service_: String
+      # *Returns*:: Array containing String
+      def database_list(service)
+        response = get_dir(service)
+        str = prepare_return_value(response)
+        if str then
+          str.chomp.split(/\r?\n/)
+        else
+          raise 'Unexpected server response'
+        end
+      end
+
+    end #class REST
+
+  end #module TogoWS
+
+end #module Bio

data/lib/bio/shell/core.rb

@@ -5,7 +5,7 @@
 #               Toshiaki Katayama <k@bioruby.org>
 # License::     The Ruby License
 #
-# $Id: core.rb,v 1.27 2007/06/28 11:21:40 k Exp $
+# $Id:$
 #
 
 module Bio::Shell::Core
@@ -556,7 +556,7 @@ module Bio::Shell::Ghost
     end
     STDERR.puts
     STDERR.puts
-    STDERR.print "  Version : BioRuby #{Bio::BIORUBY_VERSION.join(".")}"
+    STDERR.print "  Version : BioRuby #{Bio::BIORUBY_VERSION_ID}"
     STDERR.print " / Ruby #{RUBY_VERSION}"
     STDERR.puts
     STDERR.puts

data/lib/bio/shell/plugin/entry.rb

@@ -86,15 +86,38 @@ module Bio::Shell
         puts "Retrieving entry from EMBOSS (#{arg})"
         entry = str
 
-      # KEGG API at http://www.genome.jp/kegg/soap/
+      # via Internet
       else
         case db.to_s.downcase
-        when 'genbank', 'gb', 'embl', 'emb', 'ddbj', 'dbj'
+        when 'genbank', 'gb', 'nuccore', 'indsc'
+          # NCBI
           puts "Retrieving entry from NCBI eUtils"
           entry = efetch(entry_id)
+
+        when 'embl', 'emb', /\Aembl/, /\Auni/, 'sp', /\Aensembl/
+          # EBI
+          puts "Retrieving entry from EBI Dbfetch"
+          db = 'embl' if db == 'emb'
+          db = 'uniprotkb' if db == 'uniprot' or db == 'sp'
+          entry = biofetch(db, entry_id)
+
+        when 'ddbj', 'dbj', 'dad'
+          # TogoWS REST
+          puts "Retrieving entry from TogoWS"
+          db = 'ddbj' if db == 'dbj'
+          entry = togowsentry(db, entry_id)
+
         else
-          puts "Retrieving entry from KEGG API (#{arg})"
-          entry = bget(arg)
+          togodblist = Bio::TogoWS::REST.entry_database_list rescue []
+          if togodblist.include?(db) then
+            # TogoWS REST
+            puts "Retrieving entry from TogoWS"
+            entry = togowsentry(db, entry_id)
+          else
+            # KEGG API at http://www.genome.jp/kegg/soap/
+            puts "Retrieving entry from KEGG API (#{arg})"
+            entry = bget(arg)
+          end
         end
       end
     end

data/lib/bio/shell/plugin/ncbirest.rb

@@ -13,38 +13,36 @@ module Bio::Shell
   private
 
   # NCBI eUtils EFetch service.
-  # When two or more arguments are given, or multiple accession numbers
-  # are given it acts the same as Bio::NCBI::REST.efetch.
-  # Otherwise, assumes nucleotide or protein accessin is given, and
-  # automatically tries several databases.
+  #
+  # With 1 argument, it gets sequence(s) by using
+  # Bio::NCBI::REST::EFetch.sequence.
+  # Nucleotide or protein database is automatically selected for each id.
+  #
+  # Example:
+  #   efetch('AF237819')
+  # 
+  # With two or more arguments, and when the 2nd argument is Symbol,
+  # it calls the corresponding Bio::NCBI::REST::EFetch class method.
+  #
+  # Example:
+  #   efetch('13054692', :pubmed)
+  #   # the same as Bio::NCBI::REST::EFetch.pubmed('13054692')
+  #
+  # Otherwise, it acts the same as Bio::NCBI::REST.efetch.
   def efetch(ids, *arg)
-    if !arg.empty? or ids.kind_of?(Array) or /\,/ =~ ids then
-      return Bio::NCBI::REST.efetch(ids, *arg)
-    end
-
-    rettype = 'gb'
-    prot_dbs = [ 'protein' ]
-    nucl_dbs = [ 'nuccore', 'nucleotide', 'nucgss', 'nucest' ]
-
-    case ids
-    when /\A[A-Z][A-Z][A-Z][0-9]+(\.[0-9]+)?\z/i,
-      /\A[OPQ][A-Z0-9]+(\.[0-9]+)?\z/i
-      # protein accession
-      dbs = prot_dbs
-    when /\A[0-9]+\z/, /\A[A-Z0-9]+\_[A-Z0-9]+\z/i
-      # NCBI GI or UniProt accession (with fail-safe)
-      dbs = prot_dbs + nucl_dbs
+    if arg.empty? then
+      Bio::NCBI::REST::EFetch.sequence(ids)
+    elsif arg[0].kind_of?(Symbol)
+      meth = arg[0]
+      case meth.to_s
+      when /\A(journal|omim|pmc|pubmed|sequence|taxonomy)\z/
+        Bio::NCBI::REST::EFetch.__send__(meth, ids, *(arg[1..-1]))
+      else
+        nil
+      end
     else
-      # nucleotide accession
-      dbs = nucl_dbs
-    end
-    result = nil
-    dbs.each do |db|
-      hash = { 'db' => db, 'rettype' => 'gb' }
-      result = Bio::NCBI::REST.efetch(ids, hash)
-      break if result and !result.empty?
+      Bio::NCBI::REST.efetch(ids, *arg)
     end
-    result
   end
 
   # NCBI eUtils EInfo

data/lib/bio/shell/plugin/togows.rb

@@ -0,0 +1,40 @@
+#
+# = bio/shell/plugin/togows.rb - plugin for TogoWS REST service
+#
+# Copyright::   Copyright (C) 2009
+#               Naohisa Goto <ng@bioruby.org>
+# License::     The Ruby License
+#
+# $Id:$
+#
+
+module Bio::Shell
+
+  private
+
+  # Shortcut method to fetch entry(entries) by using TogoWS REST "entry"
+  # service. Multiple databases may be used.
+  #
+  def togows(ids, *arg)
+    Bio::TogoWS::REST.retrieve(ids, *arg)
+  end
+
+  # Fetches entry(entries) by using TogoWS REST "entry" service.
+  # Same as Bio::TogoWS::REST.entry(database, ids, *arg).
+  def togowsentry(database, ids, *arg)
+    Bio::TogoWS::REST.entry(database, ids, *arg)
+  end
+
+  # Database search by using TogoWS REST "search" service.
+  # Same as Bio::TogoWS::REST.search(database, term, *arg).
+  def togowssearch(database, term, *arg)
+    Bio::TogoWS::REST.search(database, term, *arg)
+  end
+
+  # Data format conversion by using TogoWS REST "convert" service.
+  # Same as Bio::TogoWS::REST.convert(data, format_from, format_to).
+  def togowsconvert(data, format_from, format_to)
+    Bio::TogoWS::REST.convert(data, format_from, format_to)
+  end
+
+end

data/lib/bio/shell.rb

@@ -37,6 +37,7 @@ module Bio::Shell
   require 'bio/shell/plugin/blast'
   require 'bio/shell/plugin/psort'
   require 'bio/shell/plugin/ncbirest'
+  require 'bio/shell/plugin/togows'
 
   extend Ghost
 

data/lib/bio/util/color_scheme.rb

@@ -5,10 +5,10 @@
 # Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
 # License::   The Ruby License
 #
-#  $Id: color_scheme.rb,v 1.4 2007/04/05 23:35:41 trevor Exp $
+#  $Id:$
 #
 
-module Bio #:nodoc:
+module Bio
 
 #
 # bio/util/color_scheme.rb - Popular color codings for nucleic and amino acids

data/lib/bio/util/contingency_table.rb

@@ -5,10 +5,10 @@
 # Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
 # License::   The Ruby License
 #
-#  $Id: contingency_table.rb,v 1.7 2007/04/05 23:35:41 trevor Exp $
+#  $Id:$
 #
 
-module Bio #:nodoc:
+module Bio
 
 #
 # bio/util/contingency_table.rb - Statistical contingency table analysis for aligned sequences

data/lib/bio/util/restriction_enzyme.rb

@@ -5,10 +5,10 @@
 # Copyright:: Copyright (c) 2005-2007 Midwinter Laboratories, LLC (http://midwinterlabs.com)
 # License::   The Ruby License
 #
-#  $Id: restriction_enzyme.rb,v 1.16 2007/07/16 19:28:48 k Exp $
+#  $Id:$
 #
 
-module Bio #:nodoc:
+module Bio
 
   autoload :REBASE, 'bio/db/rebase'