BioDSL 1.0.0

data/lib/BioDSL/commands/align_seq_mothur.rb

@@ -0,0 +1,194 @@
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+#                                                                              #
+# Copyright (C) 2007-2015 Martin Asser Hansen (mail@maasha.dk).                #
+#                                                                              #
+# This program is free software; you can redistribute it and/or                #
+# modify it under the terms of the GNU General Public License                  #
+# as published by the Free Software Foundation; either version 2               #
+# of the License, or (at your option) any later version.                       #
+#                                                                              #
+# This program 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 General Public License for more details.                                 #
+#                                                                              #
+# You should have received a copy of the GNU General Public License            #
+# along with this program; if not, write to the Free Software                  #
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,    #
+# USA.                                                                         #
+#                                                                              #
+# http://www.gnu.org/copyleft/gpl.html                                         #
+#                                                                              #
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+#                                                                              #
+# This software is part of the BioDSL framework (www.BioDSL.org).        #
+#                                                                              #
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+
+module BioDSL
+  # == Align sequences in the stream using Mothur.
+  #
+  # This is a wrapper for the +mothur+ command +align.seqs()+. Basically,
+  # it aligns sequences to a reference alignment.
+  #
+  # Please refer to the manual:
+  #
+  # http://www.mothur.org/wiki/Align.seqs
+  #
+  # Mothur must be installed for +align_seq_mothurs+ to work. Read more here:
+  #
+  # http://www.mothur.org/
+  #
+  # == Usage
+  #
+  #    align_seq_mothur(<template_file: <file>>[, cpus: <uint>])
+  #
+  # === Options
+  #
+  # * template_file: <file>  - File with template alignment in FASTA format.
+  # * cpus: <uint>           - Number of CPU cores to use (default=1).
+  #
+  # == Examples
+  #
+  # To align the entries in the FASTA file `test.fna` to the template alignment
+  # in the file `template.fna` do:
+  #
+  #    BP.new.
+  #    read_fasta(input: "test.fna").
+  #    align_seq_mothur(template_file: "template.fna").
+  #    run
+  class AlignSeqMothur
+    require 'English'
+    require 'BioDSL/helpers/aux_helper'
+
+    include AuxHelper
+
+    STATS = %i(records_in records_out sequences_in sequences_out residues_in
+               residues_out)
+
+    # Constructor for the AlignSeqMothur class.
+    #
+    # @param [Hash] options Options hash.
+    # @option options [String] :template_file Path to template file.
+    # @option options [Integer] :cpus         Number of CPUs to use.
+    #
+    # @return [AlignSeqMothur] Returns an instance of the class.
+    def initialize(options)
+      @options = options
+
+      aux_exist('mothur')
+      check_options
+      defaults
+    end
+
+    # Return a lambda for the align_seq_mothur command.
+    #
+    # @return [Proc] Returns the align_seq_mothur command lambda.
+    def lmb
+      lambda do |input, output, status|
+        status_init(status, STATS)
+
+        TmpDir.create('input.fna', 'input.align') do |tmp_in, tmp_out, tmp_dir|
+          process_input(input, output, tmp_in)
+          run_mothur(@options[:template_file], @options[:cpus], tmp_dir, tmp_in)
+          process_output(output, tmp_out)
+        end
+      end
+    end
+
+    private
+
+    # Check the options.
+    def check_options
+      options_allowed(@options, :template_file, :cpus)
+      options_required(@options, :template_file)
+      options_files_exist(@options, :template_file)
+      options_assert(@options, ':cpus >= 1')
+      options_assert(@options, ":cpus <= #{BioDSL::Config::CORES_MAX}")
+    end
+
+    # Set default options.
+    def defaults
+      @options[:cpus] ||= 1
+    end
+
+    # Process all records in the input stream and write those with sequences to
+    # file and all other records to the output stream.
+    #
+    # @param input  [BioDSL::Stream] The input stream.
+    # @param output [BioDSL::Stream] The output stream.
+    # @param tmp_in [String]            Path to temporary file.
+    def process_input(input, output, tmp_in)
+      BioDSL::Fasta.open(tmp_in, 'w') do |ios|
+        input.each_with_index do |record, i|
+          @status[:records_in] += 1
+
+          if record[:SEQ]
+            write_entry(ios, record, i)
+          else
+            output << record
+            @status[:records_out] += 1
+          end
+        end
+      end
+    end
+
+    # Write a record containing sequence information to a FASTA file IO handle.
+    # If no sequence_name is found in the record use the sequence index
+    # instead.
+    #
+    # @param ios    [Fasta::IO] FASTA IO.
+    # @param record [Hash]      BioDSL record to create FASTA entry from.
+    # @param i      [Integer]   Sequence index.
+    def write_entry(ios, record, i)
+      seq_name = record[:SEQ_NAME] || i.to_s
+      entry    = BioDSL::Seq.new(seq_name: seq_name, seq: record[:SEQ])
+
+      @status[:sequences_in] += 1
+      @status[:residues_in]  += entry.length
+
+      ios.puts entry.to_fasta
+    end
+
+    # Read all FASTA entries from output file and emit to the output stream.
+    #
+    # @param output  [BioDSL::Stream] The output stream.
+    # @param tmp_out [String]            Path to temporary file.
+    def process_output(output, tmp_out)
+      BioDSL::Fasta.open(tmp_out) do |ios|
+        ios.each do |entry|
+          output << entry.to_bp
+          @status[:records_out]   += 1
+          @status[:sequences_out] += 1
+          @status[:residues_out]  += entry.length
+        end
+      end
+    end
+
+    # Run Mothur using a system call.
+    #
+    # @param template_file [String]  Path to template file.
+    # @param cpus          [Integer] Number of CPUs to use.
+    # @param tmp_dir       [String]  Path to temporary dir.
+    # @param tmp_in        [String]  Path to temporary file.
+    #
+    # @raise [RunTimeError] If system call fails.
+    def run_mothur(template_file, cpus, tmp_dir, tmp_in)
+      cmd = <<-CMD.gsub(/^\s+\|/, '').delete("\n")
+        |mothur "#set.dir(input=#{tmp_dir});
+        |set.dir(output=#{tmp_dir});
+        |align.seqs(candidate=#{tmp_in},
+        |template=#{template_file},
+        |processors=#{cpus})"
+      CMD
+
+      if BioDSL.verbose
+        system(cmd)
+      else
+        system("#{cmd} > /dev/null 2>&1")
+      end
+
+      fail 'Mothur failed' unless $CHILD_STATUS.success?
+    end
+  end
+end

data/lib/BioDSL/commands/analyze_residue_distribution.rb

@@ -0,0 +1,222 @@
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+#                                                                              #
+# Copyright (C) 2007-2015 Martin Asser Hansen (mail@maasha.dk).                #
+#                                                                              #
+# This program is free software; you can redistribute it and/or                #
+# modify it under the terms of the GNU General Public License                  #
+# as published by the Free Software Foundation; either version 2               #
+# of the License, or (at your option) any later version.                       #
+#                                                                              #
+# This program 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 General Public License for more details.                                 #
+#                                                                              #
+# You should have received a copy of the GNU General Public License            #
+# along with this program; if not, write to the Free Software                  #
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,    #
+# USA.                                                                         #
+#                                                                              #
+# http://www.gnu.org/copyleft/gpl.html                                         #
+#                                                                              #
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+#                                                                              #
+# This software is part of the BioDSL framework (www.BioDSL.org).        #
+#                                                                              #
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
+
+module BioDSL
+  # == Analyze the residue distribution from sequences in the stream.
+  #
+  # +analyze_residue_distribution+ determines the distribution per position
+  # of residues from sequences and output records per observed residue with
+  # counts at the different positions. Using the +percent+ option outputs the
+  # count as percentages of observed residues per position.
+  #
+  # The records output looks like this:
+  #
+  #     {:RECORD_TYPE=>"residue distribution",
+  #      :V0=>"A",
+  #      :V1=>5,
+  #      :V2=>0,
+  #      :V3=>0,
+  #      :V4=>0}
+  #
+  #  Which are ready for +write_table+. See examples.
+  #
+  # == Usage
+  #
+  #    analyze_residue_distribution([percent: <bool>])
+  #
+  # === Options
+  #
+  # * percent: <bool>  - Output distributions in percent (default=false).
+  #
+  # == Examples
+  #
+  # Consider the following entries in the file `test.fna`:
+  #
+  #    >DNA
+  #    AGCT
+  #    >RNA
+  #    AGCU
+  #    >Protein
+  #    FLS*
+  #    >Gaps
+  #    -.~
+  #
+  # Now we run the data through the following pipeline and get the resulting
+  # table:
+  #
+  #    BP.new.
+  #    read_fasta(input: "test.fna").
+  #    analyze_residue_distribution.
+  #    grab(select: "residue").
+  #    write_table(skip: [:RECORD_TYPE]).
+  #    run
+  #
+  #    A 2 0 0 0
+  #    G 0 2 0 0
+  #    C 0 0 2 0
+  #    T 0 0 0 1
+  #    U 0 0 0 1
+  #    F 1 0 0 0
+  #    L 0 1 0 0
+  #    S 0 0 1 0
+  #    * 0 0 0 1
+  #    - 1 0 0 0
+  #    . 0 1 0 0
+  #    ~ 0 0 1 0
+  #
+  # Here we do the same as above, but output percentages instead of absolute
+  # counts:
+  #
+  #    BP.new.
+  #    read_fasta(input: "test.fna").
+  #    analyze_residue_distribution(percent: true).
+  #    grab(select: "residue").
+  #    write_table(skip: [:RECORD_TYPE]).
+  #    run
+  #
+  #    A 50  0 0 0
+  #    G 0 50  0 0
+  #    C 0 0 50  0
+  #    T 0 0 0 33
+  #    U 0 0 0 33
+  #    F 25  0 0 0
+  #    L 0 25  0 0
+  #    S 0 0 25  0
+  #    * 0 0 0 33
+  #    - 25  0 0 0
+  #    . 0 25  0 0
+  #    ~ 0 0 25  0
+  class AnalyzeResidueDistribution
+    STATS = %i(records_in records_out sequences_in sequences_out residues_in
+               residues_out)
+
+    # Constructor for the AnalyzeResidueDistribution class.
+    #
+    # @param [Hash] options Options hash.
+    # @option options [Boolean] :percent Output distribution in percent.
+    #
+    # @return [AnalyzeResidueDistribution] Returns an instance of the class.
+    def initialize(options)
+      @options = options
+
+      check_options
+
+      @counts        = Hash.new { |h, k| h[k] = Hash.new(0) }
+      @total         = Hash.new(0)
+      @residues      = Set.new
+    end
+
+    # Return a lambda for the read_fasta command.
+    #
+    # @return [Proc] Returns the read_fasta command lambda.
+    def lmb
+      require 'set'
+
+      lambda do |input, output, status|
+        status_init(status, STATS)
+
+        input.each do |record|
+          @status[:records_in] += 1
+
+          analyze_residues(record[:SEQ]) if record[:SEQ]
+
+          if output
+            output << record
+            @status[:records_out] += 1
+          end
+        end
+
+        calc_dist(output)
+      end
+    end
+
+    private
+
+    # Check the options.
+    def check_options
+      options_allowed(@options, :percent)
+      options_allowed_values(@options, percent: [nil, true, false])
+    end
+
+    # Analyze the sequence distribution of a given sequence.
+    #
+    # @param seq [String] - Sequence to analyze.
+    def analyze_residues(seq)
+      @status[:sequences_in]  += 1
+      @status[:sequences_out] += 1
+      @status[:residues_in]   += seq.length
+      @status[:residues_out]  += seq.length
+
+      seq.upcase.chars.each_with_index do |char, i|
+        c = char.to_sym
+        @counts[i][c] += 1
+        @total[i]     += 1
+        @residues.add(c)
+      end
+    end
+
+    # Calculate the residue destribution.
+    #
+    # @param output [BioDSL::Stream] Output stream.
+    def calc_dist(output)
+      @residues.each do |res|
+        record               = {}
+        record[:RECORD_TYPE] = 'residue distribution'
+        record[:V0]          = res.to_s
+
+        if @options[:percent]
+          calc_dist_percent(record, res)
+        else
+          calc_dist_count(record, res)
+        end
+
+        output << record
+      end
+    end
+
+    # Calculate the residue distribution in percent for a given residue.
+    #
+    # @param record [Hash] BioDSL record.
+    # @param res [Symbol] Residue.
+    def calc_dist_percent(record, res)
+      @counts.each do |pos, dist|
+        value = (@total[pos] == 0) ? 0 : 100 * dist[res] / @total[pos]
+        record["V#{pos + 1}".to_sym] = value
+      end
+    end
+
+    # Calculate the residue distribution for a given residue.
+    #
+    # @param record [Hash] BioDSL record.
+    # @param res [Symbol] Residue.
+    def calc_dist_count(record, res)
+      @counts.each do |pos, dist|
+        record["V#{pos + 1}".to_sym] = dist[res]
+      end
+    end
+  end
+end