sequenceserver 1.0.0.pre.2 → 1.0.0.pre.3

data/lib/sequenceserver/blast/exceptions.rb

@@ -0,0 +1,27 @@
+module SequenceServer
+  module BLAST
+    # To signal error in query sequence or options.
+    #
+    # ArgumentError is raised when BLAST+'s exit status is 1; see [1].
+    class ArgumentError < ArgumentError
+    end
+
+    # To signal internal errors.
+    #
+    # RuntimeError is raised when BLAST+'s exits status is one of 2, 3, 4, or
+    # 255; see [1].  These are rare, infrastructure errors, used internally,
+    # and of concern only to the admins/developers.
+    class RuntimeError  < RuntimeError
+      def initialize(status, message)
+        @status  = status
+        @message = message
+      end
+
+      attr_reader :status, :message
+
+      def to_s
+        "#{status}, #{message}"
+      end
+    end
+  end
+end

data/lib/sequenceserver/blast/hit.rb

@@ -0,0 +1,32 @@
+module SequenceServer
+  # Define BLAST::Hit.
+  module BLAST
+    # Hit Object to store all the hits per Query.
+    # @member [Fixnum]     number
+    # @member [String]     id
+    # @member [String]     def
+    # @member [String]     accession
+    # @member [Fixnum]     len
+    # @member [HSP]        hsp
+    Hit = Struct.new(:number, :id, :title, :accession, :len, :hsps) do
+      def initialize(*args)
+        args[0] = args[0].to_i
+        args[2] = '' if args[2] == 'No definition line'
+        args[4] = args[4].to_i
+        super
+      end
+
+      alias_method :length, :len
+
+      # Hit evalue is the minimum evalue of all HSP(s).
+      def evalue
+        hsps.map(&:evalue).min
+      end
+
+      # Hit score is the sum of bit scores of all HSP(s).
+      def score
+        hsps.map(&:bit_score).reduce(:+)
+      end
+    end
+  end
+end

data/lib/sequenceserver/blast/hsp.rb

@@ -0,0 +1,260 @@
+module SequenceServer
+  # Define BLAST::HSP and BLAST::HSP::*.
+  module BLAST
+    # Structure to hold generic HSP data for each hit.
+    #
+    # HSP class is not used directly.  Relevant HSP stats and formatting the
+    # alignment changes with BLAST algorithm. We subclass HSP for each BLAST
+    # algorithm.
+    HSP = Struct.new(:number, :bit_score, :score, :evalue, :qstart, :qend,
+                     :sstart, :send, :qframe, :sframe, :identity, :positives,
+                     :gaps, :len, :qseq, :sseq, :midline) do
+      INTEGER_ARGS = [0, 2].concat((4..13).to_a)
+      FLOAT_ARGS   = [1, 3]
+
+      def initialize(*args)
+        INTEGER_ARGS.each do |i|
+          args[i] = args[i].to_i
+        end
+
+        FLOAT_ARGS.each do |i|
+          args[i] = args[i].to_f
+        end
+
+        super
+      end
+
+      alias_method :length, :len
+
+      # Returns a Hash of stats common to all BLAST algorithms. Subclasses must
+      # update the returned Hash to add relevant stats of their own.
+      #
+      def stats
+        {
+          'Score'      => [bit_score, score],
+          'E value'    => evalue,
+          'Identities' => [in_fraction(identity,   length),
+                           in_percentage(identity, length)],
+          'Gaps'       => [in_fraction(gaps,   length),
+                           in_percentage(gaps, length)]
+        }
+      end
+
+      # Returns pretty formatted alignment String.
+      #
+      # Calls out to `nqseq`, `nsseq`, `qframe_unit`, `sframe_unit`,
+      # `qframe_sign`, and `sframe_sign` attributes. The default value of
+      # these attributes suit BLASTP. Subclasses must override these
+      # attributes appropriately.
+      #
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength, Style/FormatString
+      def pp
+        chars = 60
+        lines = (length / chars.to_f).ceil
+        width = [qend, send, qstart, sstart].map(&:to_s).map(&:length).max
+
+        nqseq = self.nqseq
+        nsseq = self.nsseq
+
+        s = ''
+        (1..lines).each do |i|
+          lqstart = nqseq
+          lqseq = qseq[chars * (i - 1), chars]
+          nqseq += (lqseq.length - lqseq.count('-')) * qframe_unit * qframe_sign
+          lqend = nqseq - qframe_sign
+          s << "Query   %#{width}d  #{lqseq}  #{lqend}\n" % lqstart
+
+          lmseq = midline[chars * (i - 1), chars]
+          s << "#{' ' * (width + 8)}  #{lmseq}\n"
+
+          lsstart = nsseq
+          lsseq = sseq[chars * (i - 1), chars]
+          nsseq += (lsseq.length - lsseq.count('-')) * sframe_unit * sframe_sign
+          lsend = nsseq - sframe_sign
+          s << "Subject %#{width}d  #{lsseq}  #{lsend}\n" % lsstart
+
+          s << "\n" unless i == lines
+        end
+        s
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/MethodLength, Style/FormatString
+
+      ## We calculate start and end coordinate of each line of the alignment ##
+      ## based on the six attributes below. See `pp` method.                 ##
+
+      # Alignment start coordinate for query sequence.
+      #
+      # This will be qstart or qend depending on the direction in which the
+      # (translated) query sequence aligned.
+      def nqseq
+        qframe >= 0 ? qstart : qend
+      end
+
+      # Alignment start coordinate for subject sequence.
+      #
+      # This will be sstart or send depending on the direction in which the
+      # (translated) subject sequence aligned.
+      def nsseq
+        sframe >= 0 ? sstart : send
+      end
+
+      # Jump in query coordinate.
+      #
+      # Roughly,
+      #
+      #   qend = qstart + n * qframe_unit
+      #
+      # This will be 1 or 3 depending on whether the query sequence was
+      # translated or not.
+      def qframe_unit
+        1
+      end
+
+      # Jump in subject coordinate.
+      #
+      # Roughly,
+      #
+      #   send = sstart + n * sframe_unit
+      #
+      # This will be 1 or 3 depending on whether the subject sequence was
+      # translated or not.
+      def sframe_unit
+        1
+      end
+
+      # If we should add or subtract qframe_unit from qstart to arrive at qend.
+      #
+      # Roughly,
+      #
+      #   qend = qstart + (qframe_sign) * n * qframe_unit
+      #
+      # This will be +1 or -1, depending on the direction in which the
+      # (translated) query sequence aligned.
+      def qframe_sign
+        qframe >= 0 ? 1 : -1
+      end
+
+      # If we should add or subtract sframe_unit from sstart to arrive at send.
+      #
+      # Roughly,
+      #
+      #   send = sstart + (sframe_sign) * n * sframe_unit
+      #
+      # This will be +1 or -1, depending on the direction in which the
+      # (translated) subject sequence aligned.
+      def sframe_sign
+        sframe >= 0 ? 1 : -1
+      end
+
+      ## We define stats in terms of the following functions. ##
+
+      # Return fractional representation as String.
+      #
+      # NOTE:
+      #   Rational class reduces the fraction so we can't use that.
+      def in_fraction(num, den)
+        "#{num}/#{den}"
+      end
+
+      # Return percentage as Float.
+      def in_percentage(num, den)
+        format '%.2f', (num * 100.0 / den)
+      end
+    end
+
+    class HSP
+      # HSP subclass for BLASTX algorithm.
+      class BLASTX < self
+        def stats
+          super.update 'Query frame' => qframe
+        end
+
+        # Translated nucleotide query against protein database, hence 3.
+        def qframe_unit
+          3
+        end
+      end
+
+      # HSP subclass for BLASTP algorithm.
+      class BLASTP < self
+        def stats
+          super.update(
+            'Positives' =>
+            [
+              in_fraction(positives,   length),
+              in_percentage(positives, length)
+            ]
+          )
+        end
+      end
+
+      # HSP subclass for BLASTN algorithm.
+      class BLASTN < self
+        def stats
+          super.update('Strand' =>
+                       "#{qframe > 0 ? '+' : '-'}/#{sframe > 0 ? '+' : '-'}")
+        end
+
+        # BLASTN is a bit weird in that, no matter which direction the query
+        # sequence aligned in, qstart is taken as alignment start coordinate
+        # for query.
+        #
+        # NOTE:
+        #   Because BLAST reverses the qstart and qend for BLASTN?
+        def nqseq
+          qstart
+        end
+
+        # BLASTN is a bit weird in that, no matter which direction the subject
+        # sequence aligned in, sstart is taken as alignment start coordinate
+        # for subject.
+        #
+        # NOTE:
+        #   Because BLAST reverses the sstart and send for BLASTN?
+        def nsseq
+          sstart
+        end
+      end
+
+      # HSP subclass for TBLASTX algorithm.
+      class TBLASTX < self
+        def stats
+          super.update(
+            'Frame'     => in_fraction(qframe, sframe),
+            'Positives' =>
+            [
+              in_fraction(positives, length),
+              in_percentage(positives, length)
+            ]
+          )
+        end
+
+        # Translated nucleotide query against translated nucleotide database,
+        # hence 3.
+        def qframe_unit
+          3
+        end
+
+        # Translated nucleotide query against translated nucleotide database,
+        # hence 3.
+        def sframe_unit
+          3
+        end
+      end
+
+      # HSP subclass for TBLASTN algorithm.
+      class TBLASTN < self
+        def stats
+          super.update 'Hit frame' => sframe
+        end
+
+        # Protein query against translated nucleotide database, hence 3.
+        def sframe_unit
+          3
+        end
+      end
+    end
+  end
+end

data/lib/sequenceserver/blast/query.rb

@@ -0,0 +1,28 @@
+module SequenceServer
+  # Define BLAST::Query.
+  module BLAST
+    # Capture results per query of a BLAST search.
+    # @member [String]     number
+    # @member [String]     def
+    # @member [Fixnum]     len
+    # @member [Array(Hit)] hits
+    Query = Struct.new(:number, :def, :len, :hits) do
+      def initialize(*args)
+        args[0] = args[0].to_i
+        args[1] = "Query_#{args[0]}" if args[1] == 'No definition line'
+        args[2] = args[2].to_i
+        @id, *rest = args[1].split
+        @title = rest.join(' ')
+        super
+      end
+
+      def sort_hits_by_evalue!
+        @hits = hits.sort_by(&:evalue)
+      end
+
+      attr_reader :id, :title
+
+      alias_method :length, :len
+    end
+  end
+end

data/lib/sequenceserver/blast/report.rb

@@ -0,0 +1,123 @@
+module SequenceServer
+  module BLAST
+    # Captures BLAST results from BLAST+'s XML output.
+    class Report
+      include Links
+
+      # Expects a File object and Database objects used to BLAST against.
+      #
+      # Parses the XML file into an intermediate representation (ir) and
+      # constructs an object model from that.
+      #
+      # NOTE:
+      #   Databases param is optional for test suite.
+      #
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def initialize(rfile, databases = nil)
+        @archive_file = rfile
+
+        xml_file = BLAST.format('report' => @archive_file,
+                                'type'   => 'full',
+                                'format' => 'xml')
+
+        ir = File.open(xml_file[:filepath]) do |f|
+          node_to_array Ox.parse(f.read).root
+        end
+
+        @program = ir[0]
+        @program_version = ir[1]
+        @querydb = Array databases
+        @parameters = {
+          :matrix    => ir[7][0],
+          :evalue    => ir[7][1],
+          :gapopen   => ir[7][2],
+          :gapextend => ir[7][3],
+          :filters   => ir[7][4]
+        }
+
+        ir[8].each_with_index do |n, i|
+          @stats ||= n[5][0]
+          @queries ||= []
+          @queries.push(Query.new(n[0], n[2], n[3], []))
+
+          # Ensure a hit object is received. No hits, returns a newline. Note
+          # that checking to "\n" doesn't work since n[4] = ["\n"]
+          if n[4] == ["\n"]
+            @queries[i][:hits] = []
+          else
+            n[4].each_with_index do |hits, j|
+              @queries[i][:hits].push(Hit.new(hits[0], hits[1], hits[2],
+                                              hits[3], hits[4], []))
+              hits[5].each do |hsp|
+                hsp_klass = HSP.const_get program.upcase
+                @queries[i][:hits][j][:hsps].push(hsp_klass.new(*hsp))
+              end
+            end
+            @queries[i].sort_hits_by_evalue!
+          end
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      attr_reader :archive_file
+      attr_reader :program, :program_version
+
+      # :nodoc:
+      # params are defaults provided by BLAST or user input to tweak the
+      # result. stats are computed metrics provided by BLAST.
+      #
+      # BLAST+ doesn't list all input params (like word_size) in the XML
+      # output. Only matrix, evalue, gapopen, gapextend, and filters.
+      attr_reader :params, :stats
+
+      attr_reader :querydb
+
+      attr_reader :queries
+
+      # Helper methods for pretty printing results
+
+      def link_per_hit(sequence_id)
+        links = Links.instance_methods.map { |m| send(m, sequence_id) }
+
+        # Sort links based on :order key (ascending)
+        links.compact!.sort_by! { |link| link[:order] }
+      end
+
+      # Returns an array of database objects which contain the queried
+      # sequence id.
+      # NOTE: This function may return more than one database object for
+      # a single sequence id.
+      #
+      # e.g., which_blastdb('SI_2.2.23') => [<Database: ...>, ...]
+      def which_blastdb(sequence_id)
+        querydb.select { |db| db.include? sequence_id }
+      end
+
+      private
+
+      PARSEABLE_AS_ARRAY = %w(Parameters BlastOutput_param Iteration_stat
+                              Statistics Iteration_hits BlastOutput_iterations
+                              Iteration Hit Hit_hsps Hsp)
+
+      def node_to_array(element)
+        element.nodes.map { |n| node_to_value n }
+      end
+
+      def node_to_value(node)
+        # Ensure that the recursion doesn't fails when String value is received.
+        return node if node.is_a?(String)
+
+        if PARSEABLE_AS_ARRAY.include? node.name
+          value = node_to_array(node)
+        else
+          value = first_text(node)
+        end
+        value
+      end
+
+      def first_text(node)
+        node.nodes.find { |n| n.is_a? String }
+      end
+    end
+  end
+end