bio 1.2.1 → 1.3.0

data/lib/bio/appl/blast/ncbioptions.rb

@@ -0,0 +1,220 @@
+#
+# = bio/appl/blast/ncbioptions.rb - NCBI Tools-style options parser
+#
+# Copyright::  Copyright (C) 2008 Naohisa Goto <ng@bioruby.org>
+# License::    The Ruby License
+#
+# $Id:$
+#
+# == Description
+#
+# Bio::Blast::NCBIOptions is a class to parse and store NCBI Tools-style
+# command-line options.
+# It is internally used in Bio::Blast and some other classes.
+#
+
+require 'bio/appl/blast'
+require 'shellwords'
+
+class Bio::Blast
+
+  # A class to parse and store NCBI-tools style command-line options.
+  # It is internally used in Bio::Blast and some other classes.
+  #
+  class NCBIOptions
+
+    # creates a new object from an array
+    def initialize(options = [])
+      #@option_pairs = []
+      @option_pairs = _parse_options(options)
+    end
+
+    # (protected) option pairs. internal use only.
+    attr_reader :option_pairs
+    protected :option_pairs
+
+    # (private) parse options from given array
+    def _parse_options(options)
+      i = 0
+      pairs = []
+      while i < options.size
+        opt = options[i].to_s
+        if m = /\A(\-.)/.match(opt) then
+          key = m[1]
+          if m.post_match.empty? then
+            i += 1
+            val = options.fetch(i) rescue ''
+          else
+            val = m.post_match
+          end
+          pairs.push([ key, val ])
+        elsif '-' == opt then
+          pairs.push [ opt ]
+        else
+          #warn "Arguments must start with \'-\'" if $VERBOSE
+          pairs.push [ opt ]
+        end
+        i += 1
+      end
+      pairs
+    end
+    private :_parse_options
+
+    # Normalize options.
+    # For two or more same options (e.g. '-p blastn -p blastp'),
+    # only the last option is used. (e.g. '-p blastp' for above example).
+    # 
+    # Note that completely illegal options are left untouched.
+    #
+    # ---
+    # *Returns*:: self
+    def normalize!
+      hash = {}
+      newpairs = []
+      @option_pairs.reverse_each do |pair|
+        if pair.size == 2 then
+          key = pair[0]
+          unless hash[key] then
+            newpairs.push pair
+            hash[key] = pair
+          end
+        else
+          newpairs.push pair
+        end
+      end
+      newpairs.reverse!
+      @option_pairs = newpairs
+      self
+    end
+
+    # current options as an array of strings
+    def options
+      @option_pairs.flatten
+    end
+
+    # parses a string and returns a new object
+    def self.parse(str)
+      options = Shellwords.shellwords(str)
+      self.new(options)
+    end
+
+    # (private) key string to regexp
+    def _key_to_regexp(key)
+      key = key.sub(/\A\-/, '')
+      Regexp.new('\A\-' + Regexp.escape(key) + '\z')
+    end
+    private :_key_to_regexp
+
+    # Return the option.
+    # ---
+    # *Arguments*:
+    # * _key_: option name as a string, e.g. 'm', 'p', or '-m', '-p'.
+    # *Returns*:: String or nil
+    def get(key)
+      re = _key_to_regexp(key)
+
+      # Note: the last option is used when two or more same option exist.
+      value = nil
+      @option_pairs.reverse_each do |pair|
+        if re =~ pair[0] then
+          value = pair[1]
+          break
+        end
+      end
+      return value
+    end
+
+    # Delete the given option.
+    # ---
+    # *Arguments*:
+    # * _key_: option name as a string, e.g. 'm', 'p', or '-m', '-p'.
+    # *Returns*:: String or nil
+    def delete(key)
+      re = _key_to_regexp(key)
+
+      # Note: the last option is used for return value
+      # when two or more same option exist.
+      oldvalue = nil
+      @option_pairs = @option_pairs.delete_if do |pair|
+        if re =~ pair[0] then
+          oldvalue = pair[1]
+          true
+        else
+          false
+        end
+      end
+      return oldvalue
+    end
+
+    # Sets the option to given value.
+    #
+    # For example, if you want to set '-p blastall' option,
+    #   obj.set('p', 'blastall')
+    # or
+    #   obj.set('-p', 'blastall')
+    # (above two are equivalent).
+    #
+    # ---
+    # *Arguments*:
+    # * _key_: option name as a string, e.g. 'm', 'p'.
+    # * _value_: value as a string, e.g. '7', 'blastp'.
+    # *Returns*:: previous value; String or nil
+    def set(key, value)
+      re = _key_to_regexp(key)
+      oldvalue = nil
+      flag = false
+      # Note: only the last options is modified for multiple same options.
+      @option_pairs.reverse_each do |pair|
+        if re =~ pair[0] then
+          oldvalue = pair[1]
+          pair[1] = value
+          flag = true
+          break
+        end
+      end
+      unless flag then
+        key = "-#{key}" unless key[0, 1] == '-'
+        @option_pairs.push([ key, value ])
+      end
+      oldvalue
+    end
+
+    # Adds options from given array.
+    # Note that existing options will also be normalized.
+    # ---
+    # *Arguments*:
+    # * _options_: options as an Array of String objects.
+    # *Returns*:: self
+    def add_options(options)
+      @option_pairs.concat _parse_options(options)
+      self.normalize!
+      self
+    end
+
+    # If self == other, returns true. Otherwise, returns false.
+    def ==(other)
+      return true if super(other)
+      begin
+        oopts = other.options
+      rescue
+        return false
+      end
+      return self.options == oopts 
+    end
+
+    # Returns an array for command-line options.
+    # prior_options are preferred to be used.
+    def make_command_line_options(prior_options = [])
+      newopts = self.class.new(self.options)
+      #newopts.normalize!
+      prior_pairs = _parse_options(prior_options)
+      prior_pairs.each do |pair|
+        newopts.delete(pair[0])
+      end
+      newopts.option_pairs[0, 0] = prior_pairs
+      newopts.options
+    end
+
+  end #class NCBIOptions
+
+end #class Bio::Blast

data/lib/bio/appl/blast/remote.rb

@@ -0,0 +1,106 @@
+#
+# = bio/appl/blast/remote.rb - remote BLAST wrapper basic module
+# 
+# Copyright::  Copyright (C) 2008  Naohisa Goto <ng@bioruby.org>
+# License::    The Ruby License
+#
+# $Id:$
+#
+
+require 'bio/appl/blast'
+
+class Bio::Blast
+
+  # Bio::Blast::Remote is a namespace for Remote Blast factory.
+  module Remote
+
+    autoload :GenomeNet, 'bio/appl/blast/genomenet'
+    autoload :Genomenet, 'bio/appl/blast/genomenet'
+
+    autoload :DDBJ, 'bio/appl/blast/ddbj'
+    autoload :Ddbj, 'bio/appl/blast/ddbj'
+
+    # creates a remote BLAST factory using GenomeNet
+    def self.genomenet(program, db, options = [])
+      GenomeNet.new(program, db, options)
+      #Bio::Blast.new(program, db, options, 'genomenet')
+    end
+
+    # creates a remote BLAST factory using DDBJ Web service
+    def self.ddbj(program, db, options = [])
+      DDBJ.new(program, db, options)
+      #Bio::Blast.new(program, db, options, 'ddbj')
+    end
+
+    # Common methods for meta-information processing
+    # (e.g. list of databases).
+    module Information
+
+      # (private) parses database information and stores data
+      def _parse_databases
+        raise NotImplementedError
+      end
+      private :_parse_databases
+
+      # Returns a list of available nucleotide databases.
+      #
+      # Note: see the note of databases method.
+      #
+      # ---
+      # *Returns*:: Array containing String objects
+      def nucleotide_databases
+        _parse_databases
+        @databases['blastn']
+      end
+
+      # Returns a list of available protein databases.
+      #
+      # Note: see the note of databases method.
+      # ---
+      # *Returns*:: Array containing String objects
+      def protein_databases
+        _parse_databases
+        @databases['blastp']
+      end
+
+      # Returns a list of available databases for given program.
+      #
+      # Note: It parses remote sites to obtain database information
+      # (e.g. http://blast.genome.jp/ for Bio::Blast::Remote::GenomeNet).
+      # Thus, if the site is changed, this method can not return correct data.
+      # Please tell BioRuby developers when the site is changed.
+      #
+      # ---
+      # *Arguments*:
+      # * _program_ (required): blast program('blastn', 'blastp', 'blastx', 'tblastn' or 'tblastx')
+      # *Returns*:: Array containing String objects
+      def databases(program)
+        _parse_databases
+        @databases[program] || []
+      end
+
+      # Returns a short description of given database.
+      #
+      # Note: see the note of databases method.
+      # ---
+      # *Arguments*:
+      # * _program_ (required): 'blastn', 'blastp', 'blastx', 'tblastn' or 'tblastx'
+      # * _db_ (required): database name
+      # *Returns*:: String
+      def database_description(program, db)
+        _parse_databases
+        h = @database_descriptions[program]
+        h ? (h[db] || '') : ''
+      end
+
+      # Resets data and clears cached data in this module.
+      def reset
+        @parse_databases = false
+        true
+      end
+    end #module Information
+
+  end #module Remote
+
+end #class Bio::Blast
+

data/lib/bio/appl/blast/report.rb

@@ -4,13 +4,14 @@
 # Copyright::  Copyright (C) 2003 Toshiaki Katayama <k@bioruby.org>
 # License::    The Ruby License
 #
-# $Id: report.rb,v 1.11 2007/04/05 23:35:39 trevor Exp $
+# $Id:$
 #
 
 require 'bio/appl/blast'
 require 'bio/appl/blast/xmlparser'
 require 'bio/appl/blast/rexml'
 require 'bio/appl/blast/format8'
+require 'bio/io/flatfile'
 
 module Bio
 class Blast
@@ -64,8 +65,10 @@ class Report
     if /<?xml/.match(data[/.*/])
       if defined?(XMLParser)
         xmlparser_parse(data)
+        @reports = blastxml_split_reports
       else
         rexml_parse(data)
+        @reports = blastxml_split_reports
       end
     else
       tab_parse(data)
@@ -81,10 +84,14 @@ class Report
     case parser
     when :xmlparser		# format 7
       xmlparser_parse(data)
+      @reports = blastxml_split_reports
     when :rexml		# format 7
       rexml_parse(data)
+      @reports = blastxml_split_reports
     when :tab		# format 8
       tab_parse(data)
+    when false
+      # do not parse, creates an empty object
     else
       auto_parse(data)
     end
@@ -98,23 +105,45 @@ class Report
   # 'gap-open', 'gap-extend', 'filter'
   attr_reader :parameters
 
+  #--
   # Shortcut for BlastOutput values.
-  attr_reader :program, :version, :reference, :db, :query_id, :query_def, :query_len
+  #++
+
+  # program name (e.g. "blastp") (String)
+  attr_reader :program
+
+  # BLAST version (e.g. "blastp 2.2.18 [Mar-02-2008]") (String)
+  attr_reader :version
+
+  # reference (String)
+  attr_reader :reference
+
+  # database name or title (String)
+  attr_reader :db
+
+  # query ID (String)
+  attr_reader :query_id
+
+  # query definition line (String)
+  attr_reader :query_def
+
+  # query length (Integer)
+  attr_reader :query_len
 
   # Matrix used (-M) : shortcuts for @parameters
   def matrix;       @parameters['matrix'];           end
   # Expectation threshold (-e) : shortcuts for @parameters
-  def expect;       @parameters['expect'].to_i;      end
+  def expect;       @parameters['expect'];           end
   # Inclusion threshold (-h) : shortcuts for @parameters
-  def inclusion;    @parameters['include'].to_i;     end
+  def inclusion;    @parameters['include'];          end
   # Match score for NT (-r) : shortcuts for @parameters
-  def sc_match;     @parameters['sc-match'].to_i;    end
+  def sc_match;     @parameters['sc-match'];         end
   # Mismatch score for NT (-q) : shortcuts for @parameters
-  def sc_mismatch;  @parameters['sc-mismatch'].to_i; end
+  def sc_mismatch;  @parameters['sc-mismatch'];      end
   # Gap opening cost (-G) : shortcuts for @parameters
-  def gap_open;     @parameters['gap-open'].to_i;    end
+  def gap_open;     @parameters['gap-open'];         end
   # Gap extension cost (-E) : shortcuts for @parameters
-  def gap_extend;   @parameters['gap-extend'].to_i;  end
+  def gap_extend;   @parameters['gap-extend'];       end
   # Filtering options (-F) : shortcuts for @parameters
   def filter;       @parameters['filter'];           end
   # PHI-BLAST pattern : shortcuts for @parameters
@@ -204,7 +233,17 @@ class Report
         yield x
       end
     end
-  end
+
+    # query ID, only available for new BLAST XML format
+    attr_accessor :query_id
+
+    # query definition, only available for new BLAST XML format
+    attr_accessor :query_def
+
+    # query length, only available for new BLAST XML format
+    attr_accessor :query_len
+
+  end #class Iteration
 
 
   # Bio::Blast::Report::Hit
@@ -323,8 +362,220 @@ class Report
     attr_accessor :mismatch_count
   end
 
+
+  # When the report contains results for multiple query sequences,
+  # returns an array of Bio::Blast::Report objects corresponding to
+  # the multiple queries.
+  # Otherwise, returns nil.
+  #
+  # Note for "No hits found":
+  # When no hits found for a query sequence, the result for the query
+  # is completely void and no information available in the result XML,
+  # including query ID and query definition.
+  # The only trace is that iteration number is skipped.
+  # This means that if the no-hit query is the last query,
+  # the query can not be detected, because the result XML is
+  # completely the same as the result XML without the query.
+  attr_reader :reports
+ 
+  private
+  # (private method)
+  # In new BLAST XML (blastall >= 2.2.14), results of multiple queries
+  # are stored in <Iteration>. This method splits iterations into
+  # multiple Bio::Blast objects and returns them as an array.
+  def blastxml_split_reports
+    unless self.iterations.find { |iter|
+        iter.query_id || iter.query_def || iter.query_len
+      } then
+      # traditional BLAST XML format, or blastpgp result.
+      return nil
+    end
+
+    # new BLAST XML format (blastall 2.2.14 or later)
+    origin = self
+    reports = []
+    prev_iternum = 0
+    firsttime = true
+
+    orig_iters = self.iterations
+    orig_iters.each do |iter|
+      blast = self.class.new(nil, false)
+      # When no hits found, the iteration is skipped in NCBI BLAST XML.
+      # So, filled with empty report object.
+      if prev_iternum + 1 < iter.num then
+        ((prev_iternum + 1)...(iter.num)).each do |num|
+          empty_i = Iteration.new
+          empty_i.num = num
+          empty_i.instance_eval {
+            if firsttime then
+              @query_id  = origin.query_id
+              @query_def = origin.query_def
+              @query_len = origin.query_len
+              firsttime = false
+            end
+          }
+          empty = self.class.new(nil, false)
+          empty.instance_eval {
+            # queriy_* are copied from the empty_i
+            @query_id  = empty_i.query_id
+            @query_def = empty_i.query_def
+            @query_len = empty_i.query_len
+            # others are copied from the origin
+            @program   = origin.program
+            @version   = origin.version
+            @reference = origin.reference
+            @db        = origin.db
+            @parameters.update(origin.parameters)
+            # the empty_i is added to the iterations
+            @iterations.push empty_i
+          }
+          reports.push empty
+        end
+      end
+
+      blast.instance_eval {
+        if firsttime then
+          @query_id  = origin.query_id
+          @query_def = origin.query_def
+          @query_len = origin.query_len
+          firsttime = false
+        end
+        # queriy_* are copied from the iter
+        @query_id  = iter.query_id if iter.query_id
+        @query_def = iter.query_def if iter.query_def
+        @query_len = iter.query_len if iter.query_len
+        # others are copied from the origin
+        @program   = origin.program
+        @version   = origin.version
+        @reference = origin.reference
+        @db        = origin.db
+        @parameters.update(origin.parameters)
+        # rewrites hit's query_id, query_def, query_len
+        iter.hits.each do |h|
+          h.query_id  = @query_id
+          h.query_def = @query_def
+          h.query_len = @query_len
+        end
+        # the iter is added to the iterations
+        @iterations.push iter
+      }
+
+      prev_iternum = iter.num
+      reports.push blast
+    end #orig_iters.each
+
+    # This object's iterations is set as first report's iterations
+    @iterations.clear
+    if rep = reports.first then
+      @iterations = rep.iterations
+    end
+
+    return reports
+  end
+
+  # Flatfile splitter for NCBI BLAST XML format.
+  # It is internally used when reading BLAST XML.
+  # Normally, users do not need to use it directly.
+  class BlastXmlSplitter < Bio::FlatFile::Splitter::Default
+
+    # creates a new splitter object
+    def initialize(klass, bstream)
+      super(klass, bstream)
+      @parsed_entries = []
+      @raw_unsupported = false
+    end
+
+    # rewinds
+    def rewind
+      ret = super
+      @parsed_entries.clear
+      @raw_unsupported = false
+      ret
+    end
+
+    # do nothing
+    def skip_leader
+      nil
+    end
+
+    # get an entry and return the entry as a string
+    def get_entry
+      if @parsed_entries.empty? then
+        @raw_unsupported = false
+        ent = super
+        prepare_parsed_entries(ent)
+        self.parsed_entry = @parsed_entries.shift
+      else
+        raise 'not supported for new BLAST XML format'
+      end
+      ent
+    end
+
+    # get an entry as a Bio::Blast::Report object
+    def get_parsed_entry
+      if @parsed_entries.empty? then
+        ent = get_entry
+      else
+        self.parsed_entry = @parsed_entries.shift
+        self.entry = nil
+        @raw_unsupported = true
+      end
+      self.parsed_entry
+    end
+
+    # current raw entry as a String
+    def entry
+      raise 'not supported for new BLAST XML format' if @raw_unsupported
+      super
+    end
+
+    # start position of the entry
+    def entry_start_pos
+      if entry_pos_flag then
+        raise 'not supported for new BLAST XML format' if @raw_unsupported
+      end
+      super
+    end
+
+    # (end position of the entry) + 1
+    def entry_ended_pos
+      if entry_pos_flag then
+        raise 'not supported for new BLAST XML format' if @raw_unsupported
+      end
+      super
+    end
+
+    private
+    # (private method) to prepare parsed entry
+    def prepare_parsed_entries(ent)
+      if ent then
+        blast = dbclass.new(ent)
+        if blast.reports and blast.reports.size >= 1 then
+          # new blast xml using <Iteration> for multiple queries
+          @parsed_entries.concat blast.reports
+        else
+          # traditional blast xml
+          @parsed_entries.push blast
+        end
+      end
+    end
+
+  end #class BlastXmlSplitter
+
+  # splitter for Bio::FlatFile support
+  FLATFILE_SPLITTER = BlastXmlSplitter
+
 end # Report
 
+# NCBI BLAST tabular (-m 8) output parser.
+# All methods are equal to Bio::Blast::Report.
+# Only DELIMITER (and RS) is different.
+# 
+class Report_tab < Report
+  # Delimter of each entry. Bio::FlatFile uses it. 
+  DELIMITER = RS = nil
+end #class Report_tabular
+
 end # Blast
 end # Bio