demultiplexer 0.0.1 → 0.1.0

data/lib/demultiplexer.rb

@@ -21,8 +21,22 @@
 #                                                                              #
 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
 
+require 'google_hash'
+require 'status'
+require 'sample_reader'
+require 'index_builder'
+require 'data_io'
+
 # Class containing methods for demultiplexing MiSeq sequences.
 class Demultiplexer
+  DEFAULT = { verbose:        false,
+              mismatches_max: 0,
+              revcomp_index1: false,
+              revcomp_index2: false,
+              scores_min:     16,
+              scores_mean:    16
+            }
+
   attr_reader :status
 
   # Public: Class method to run demultiplexing of MiSeq sequences.
@@ -55,6 +69,7 @@ class Demultiplexer
   #
   # Returns Demultiplexer object
   def self.run(fastq_files, options)
+    options       = DEFAULT.merge(options)
     log_file      = File.join(options[:output_dir], 'Demultiplex.log')
     demultiplexer = new(fastq_files, options)
     Screen.clear if options[:verbose]
@@ -63,7 +78,7 @@ class Demultiplexer
     demultiplexer.status.save(log_file)
   end
 
-  # Constructor method for Demultiplexer object.
+  # Internal: Constructor method for Demultiplexer object.
   #
   # fastq_files - Array with paths to FASTQ files.
   # options     - Options Hash.
@@ -91,14 +106,14 @@ class Demultiplexer
     @samples      = SampleReader.read(options[:samples_file],
                                       options[:revcomp_index1],
                                       options[:revcomp_index2])
-    @undetermined = @samples.size + 1
+    @undetermined = @samples.size
     @index_hash   = IndexBuilder.build(@samples, options[:mismatches_max])
     @data_io      = DataIO.new(@samples, fastq_files, options[:compress],
                                options[:output_dir])
-    @status       = Status.new
+    @status       = Status.new(@samples)
   end
 
-  # Method to demultiplex reads according the index. This is done by
+  # Internal: Method to demultiplex reads according the index. This is done by
   # simultaniously read-opening all input files (forward and reverse index
   # files and forward and reverse read files) and read one entry from each.
   # Such four entries we call a set of entries. If the quality scores from
@@ -130,11 +145,11 @@ class Demultiplexer
 
   private
 
-  # Method that matches the combined index1 and index2 sequences against the
-  # search index. In case of a match the reads are written to file according to
-  # the information in the search index, otherwise the reads will have thier
-  # names appended with the index sequences and they will be written to the
-  # Undetermined files.
+  # Internal: Method that matches the combined index1 and index2 sequences
+  # against the search index. In case of a match the reads are written to file
+  # according to the information in the search index, otherwise the reads will
+  # have thier names appended with the index sequences and they will be written
+  # to the Undetermined files.
   #
   # ios_out - DataIO object with an accessor method for file output handles.
   # index1  - Seq object with index1.
@@ -144,15 +159,17 @@ class Demultiplexer
   #
   # Returns nothing.
   def match_index(ios_out, index1, index2, read1, read2)
-    if (sample_id = @index_hash["#{index1.seq}#{index2.seq}".hash])
+    key = "#{index1.seq.upcase}#{index2.seq.upcase}".hash
+
+    if (sample_id = @index_hash[key])
       write_match(ios_out, sample_id, read1, read2)
     else
       write_undetermined(ios_out, index1, index2, read1, read2)
     end
   end
 
-  # Method that writes a index match to file according to the information in
-  # the search index.
+  # Internal: Method that writes a index match to file according to the
+  # information in the search index.
   #
   # ios_out - DataIO object with an accessor method for file output handles.
   # read1   - Seq object with read1.
@@ -167,8 +184,8 @@ class Demultiplexer
     io_reverse.puts read2.to_fastq
   end
 
-  # Method that appends the read names with the index sequences and writes
-  # the reads to the Undetermined files.
+  # Internal: Method that appends the read names with the index sequences and
+  # writes the reads to the Undetermined files.
   #
   # ios_out - DataIO object with an accessor method for file output handles.
   # index1  - Seq object with index1.
@@ -187,7 +204,7 @@ class Demultiplexer
     io_reverse.puts read2.to_fastq
   end
 
-  # Method to check the quality scores of the given indexes.
+  # Internal: Method to check the quality scores of the given indexes.
   # If the mean score is higher than @options[:scores_mean] or
   # if the min score is higher than @options[:scores_min] then
   # the indexes are OK.
@@ -201,7 +218,7 @@ class Demultiplexer
       index_qual_min_ok?(index1, index2)
   end
 
-  # Method to check the mean quality scores of the given indexes.
+  # Internal: Method to check the mean quality scores of the given indexes.
   # If the mean score is higher than @options[:scores_mean] the
   # indexes are OK.
   #
@@ -221,7 +238,7 @@ class Demultiplexer
     true
   end
 
-  # Method to check the min quality scores of the given indexes.
+  # Internal: Method to check the min quality scores of the given indexes.
   # If the min score is higher than @options[:scores_min] the
   # indexes are OK.
   #
@@ -240,24 +257,4 @@ class Demultiplexer
 
     true
   end
-
-  # Method that iterates over @samples and compiles a sorted Array with all
-  # unique index1 sequences.
-  #
-  # Returns Array with uniq index1 sequences.
-  def uniq_index1
-    @status.index1 = @samples.each_with_object(SortedSet.new) do |a, e|
-      a << e.index1
-    end.to_a
-  end
-
-  # Method that iterates over @samples and compiles a sorted Array with all
-  # unique index2 sequences.
-  #
-  # Returns Array with uniq index2 sequences.
-  def uniq_index2
-    @status.index2 = @samples.each_with_object(SortedSet.new) do |a, e|
-      a << e.index2
-    end.to_a
-  end
 end

data/lib/index_builder.rb

@@ -21,9 +21,17 @@
 #                                                                              #
 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
 
+# Class for IndexBuilder errors.
+IndexBuilderError = Class.new(StandardError)
+
 # Class containing methods for building an search index.
 class IndexBuilder
-  # Class method that build a search index from a given Array of samples.
+  # Internal: Class method that build a search index from a given Array of
+  # samples. The index consists of a Google Hash, which don't have Ruby's
+  # garbage collection and therefore is much more efficient. The Hash keys
+  # consists of index1 and index2 concatenated, and furthermore, if
+  # mismatches_max is given index1, and index2 are permutated accordingly.
+  # The Hash values are the sample number.
   #
   # samples - Array of samples (Sample objects with id, index1 and index2).
   #
@@ -32,15 +40,16 @@ class IndexBuilder
   #   IndexBuilder.build(samples)
   #     # => <Google Hash>
   #
-  # Returns a Google Hash where the key is the index and the value is the TODO
+  # Returns a Google Hash where the key is the index and the value is sample
+  # number.
   def self.build(samples, mismatches_max)
     index_builder = new(samples, mismatches_max)
     index_hash    = index_builder.index_init
     index_builder.index_populate(index_hash)
   end
 
-  # Constructor method for IndexBuilder object. The given Array of samples and
-  # mismatches_max are saved as an instance variable.
+  # Internal: Constructor method for IndexBuilder object. The given Array of
+  # samples and mismatches_max are saved as an instance variable.
   #
   # samples        - Array of Sample objects.
   # mismatches_max - Integer denoting the maximum number of misses allowed in
@@ -57,7 +66,7 @@ class IndexBuilder
     @mismatches_max = mismatches_max
   end
 
-  # Method to initialize the index. If @mismatches_max is <= then
+  # Internal: Method to initialize the index. If @mismatches_max is <= then
   # GoogleHashSparseLongToInt is used else GoogleHashDenseLongToInt due to
   # memory and performance.
   #
@@ -72,7 +81,7 @@ class IndexBuilder
     index_hash
   end
 
-  # Method to populate the index.
+  # Internal: Method to populate the index.
   #
   # index_hash - Google Hash with initialized index.
   #
@@ -82,12 +91,10 @@ class IndexBuilder
       index_list1 = permutate([sample.index1], @mismatches_max)
       index_list2 = permutate([sample.index2], @mismatches_max)
 
-      # index_check_list_sizes(index_list1, index_list2)
-
       index_list1.product(index_list2).each do |index1, index2|
         key = "#{index1}#{index2}".hash
 
-        index_check_existing(index_hash, key)
+        index_check_existing(index_hash, key, sample, index1, index2)
 
         index_hash[key] = i
       end
@@ -98,37 +105,26 @@ class IndexBuilder
 
   private
 
-  # Method to check if two index lists differ in size, if so an exception is
-  # raised.
-  #
-  # index_list1 - Array with index1
-  # index_list2 - Array with index2
-  #
-  # Returns nothing.
-  def index_check_list_sizes(index_list1, index_list2)
-    return if index_list1.size == index_list2.size
-
-    fail "Permutated list sizes differ: \
-    #{index_list1.size} != #{index_list2.size}"
-  end
-
-  # Method to check if a index key already exists in the index, and if so an
-  # exception is raised.
+  # Internal: Method to check if a index key already exists in the index, and
+  # if so an exception is raised.
   #
   # index_hash - Google Hash with index
   # key        - Integer from Google Hash's #hash method
+  # sample     - Sample object whos index to check.
+  # index1     - String with index1 sequence.
+  # index2     - String with index2 sequence.
   #
   # Returns nothing.
-  def index_check_existing(index_hash, key)
+  def index_check_existing(index_hash, key, sample, index1, index2)
     return unless index_hash[key]
 
-    fail "Index combo of #{index1} and #{index2} already exists for \
-         sample id: #{@samples[index_hash[key]].id} and #{sample.id}"
+    fail IndexBuilderError, "Index combo of #{index1} and #{index2} already \
+         exists for sample id: #{@samples[index_hash[key]].id} and #{sample.id}"
   end
 
-  # Method that for each word in a given Array of word permutates each word a
-  # given number (permuate) of times using a given alphabet, such that an Array
-  # of words with all possible combinations is returned.
+  # Internal: Method that for each word in a given Array of word permutates
+  # each word a given number (permuate) of times using a given alphabet, such
+  # that an Array of words with all possible combinations is returned.
   #
   # list     - Array of words (Strings) to permutate.
   # permuate - Number of permutations (Integer).
@@ -155,8 +151,8 @@ class IndexBuilder
     list
   end
 
-  # Method that permutates a given word using a given alphabet, such that an
-  # Array of words with all possible combinations is returned.
+  # Internal: Method that permutates a given word using a given alphabet, such
+  # that an Array of words with all possible combinations is returned.
   #
   # word     - String with word to permutate.
   # alphabet - String with alphabet used for permutation.

data/lib/sample_reader.rb

@@ -21,11 +21,19 @@
 #                                                                              #
 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
 
+require 'csv'
+require 'set'
+require 'biopieces'
+
+# Class for all SampleReader errors.
+SampleReaderError = Class.new(StandardError)
+
 # Class containing methods for reading and checking sample information.
 class SampleReader
-  # Class method that reads sample information from a samples file, which
-  # consists of ASCII text in three tab separated columns: The first column is
-  # the sample_id, the second column is index1 and the third column is index2.
+  # Internal: Class method that reads sample information from a samples file,
+  # which consists of ASCII text in three tab separated columns: The first
+  # column is the sample_id, the second column is index1 and the third column is
+  # index2.
   #
   # If revcomp1 or revcomp2 is set then index1 and index2 are
   # reverse-complemented accordingly.
@@ -45,8 +53,8 @@ class SampleReader
     sample_reader.samples_parse(file)
   end
 
-  # Constructor method for SampleReader object. The given revcomp1 and revcomp2
-  # flags are stored as instance variables.
+  # Internal: Constructor method for SampleReader object. The given revcomp1 and
+  # revcomp2 flags are stored as instance variables.
   #
   # revcomp1 - Flag indicating that index1 should be reverse-complemented.
   # revcomp2 - Flag indicating that index2 should be reverse-complemented.
@@ -62,9 +70,9 @@ class SampleReader
     @revcomp2 = revcomp2
   end
 
-  # Method that reads sample information from a samples file, which consists
-  # of ASCII text in three tab separated columns: The first column is the
-  # sample_id, the second column is index1 and the third column is index2.
+  # Internal: Method that reads sample information from a samples file, which
+  # consists of ASCII text in three tab separated columns: The first column is
+  # the sample_id, the second column is index1 and the third column is index2.
   #
   # file - String with path to sample file.
   #
@@ -82,8 +90,8 @@ class SampleReader
     errors.push(*samples_check_uniq_id(samples))
 
     unless errors.empty?
-      pp errors
-      fail 'errors found in sample file.'
+      warn errors
+      fail SampleReaderError, 'errors found in sample file.'
     end
 
     samples
@@ -91,9 +99,9 @@ class SampleReader
 
   private
 
-  # Method that reads sample information form a samples file, which consists
-  # of ASCII text in three tab separated columns: The first column is the
-  # sample_id, the second column is index1 and the third column is index2.
+  # Internal: Method that reads sample information form a samples file, which
+  # consists of ASCII text in three tab separated columns: The first column is
+  # the sample_id, the second column is index1 and the third column is index2.
   #
   # If @options[:revcomp_index1] or @options[:revcomp_index2] is set then
   # index1 and index2 are reverse-complemented accordingly.
@@ -110,14 +118,16 @@ class SampleReader
     samples = []
 
     CSV.read(file, col_sep: "\t").each do |id, index1, index2|
-      samples << Sample.new(id, index1, index2)
+      next if id[0] == '#'
+
+      samples << Sample.new(id, index1.upcase, index2.upcase)
     end
 
     samples
   end
 
-  # Method that iterates over the a given Array of sample Objects, and if
-  # @options[:revcomp_index1] or @options[:revcomp_index2] is set then
+  # Internal: Method that iterates over the a given Array of sample Objects,
+  # and if @options[:revcomp_index1] or @options[:revcomp_index2] is set then
   # index1 and index2 are reverse-complemented accordingly.
   #
   # samples - Array of Sample objects.
@@ -139,9 +149,9 @@ class SampleReader
     BioPieces::Seq.new(seq: index, type: :dna).reverse.complement.seq
   end
 
-  # Method that iterates over the a given Array of sample Objects, and if
-  # the combination of index1 and index2 is non-unique an error is pushed
-  # on an error Array.
+  # Internal: Method that iterates over the a given Array of sample Objects,
+  # and if the combination of index1 and index2 is non-unique an error is
+  # pushed on an error Array.
   #
   # samples - Array of Sample objects.
   #
@@ -161,8 +171,8 @@ class SampleReader
     errors
   end
 
-  # Method that iterates over the a given Array of sample Objects, and if
-  # a sample id is non-unique an error is pushed  on an error Array.
+  # Internal: Method that iterates over the a given Array of sample Objects,
+  # and if a sample id is non-unique an error is pushed on an error Array.
   #
   # samples - Array of Sample objects.
   #
@@ -182,7 +192,7 @@ class SampleReader
     errors
   end
 
-  # Struct for holding sample information.
+  # Internal: Struct for holding sample information.
   #
   # id     - Sample id.
   # index1 - Index1 sequence.
@@ -194,5 +204,17 @@ class SampleReader
   #     # => <Sample>
   #
   # Returns Sample object.
-  Sample = Struct.new(:id, :index1, :index2)
+  Sample = Struct.new(:id, :index1, :index2) do
+    # Internal: Method that returns a String representaion of a Sample object.
+    #
+    # Examples
+    #
+    #   Sample.to_s
+    #     # => "test\tATCG\tTCGA"
+    #
+    # Returns a String with the values joined by "\t".
+    def to_s
+      [id, index1, index2].join("\t")
+    end
+  end
 end

data/lib/status.rb

@@ -25,8 +25,8 @@
 class Status
   attr_accessor :count, :match, :undetermined, :index1_bad_mean,
                 :index2_bad_mean, :index1_bad_min, :index2_bad_min
-  # Method to initialize a Status object, which contains the following instance
-  # variables initialized to 0:
+  # Internal: Constructor method to initialize a Status object, which contains
+  # the following instance variables initialized to 0:
   #
   #   @count           - Number or reads.
   #   @match           - Number of reads found in index.
@@ -36,13 +36,16 @@ class Status
   #   @index1_bad_min  - Number of reads dropped due to bad min in index1.
   #   @index2_bad_min  - Number of reads dropped due to bad min in index2.
   #
+  # samples - Array of Sample objects.
+  #
   # Examples
   #
-  #   Status.new
+  #   Status.new(samples)
   #   # => <Status>
   #
   # Returns a Status object.
-  def initialize
+  def initialize(samples)
+    @samples         = samples
     @count           = 0
     @match           = 0
     @undetermined    = 0
@@ -53,8 +56,9 @@ class Status
     @time_start      = Time.now
   end
 
-  # Method to format a String from a Status object. This is done by adding the
-  # relevant instance variables to a Hash and return this as an YAML String.
+  # Internal: Method to format a String from a Status object. This is done by
+  # adding the relevant instance variables to a Hash and return this as an YAML
+  # String.
   #
   # Returns a YAML String.
   def to_s
@@ -66,36 +70,59 @@ class Status
       index2_bad_mean:      @index2_bad_mean,
       index1_bad_min:       @index1_bad_min,
       index2_bad_min:       @index2_bad_min,
-      time:                 time }.to_yaml
+      sample_ids:           @samples.map(&:id),
+      index1:               uniq_index1,
+      index2:               uniq_index2,
+      time_elapsed:         time_elapsed }.to_yaml
   end
 
-  # Method that calculate the percentage of undetermined reads.
+  # Internal: Method to save stats to the log file 'Demultiplex.log' in the
+  # output directory.
+  #
+  # Returns nothing.
+  def save(file)
+    File.open(file, 'w') do |ios|
+      ios.puts self
+    end
+  end
+
+  private
+
+  # Internal: Method that calculate the percentage of undetermined reads.
   #
   # Returns a Float with the percentage of undetermined reads.
   def undetermined_percent
+    return 0.0 if @count == 0
+
     (100 * @undetermined / @count.to_f).round(1)
   end
 
-  # Method that calculates the elapsed time and formats a nice Time String.
+  # Internal: Method that calculates the elapsed time and formats a nice Time
+  # String.
   #
   # Returns String with elapsed time.
-  def time
+  def time_elapsed
     time_elapsed = Time.now - @time_start
     (Time.mktime(0) + time_elapsed).strftime('%H:%M:%S')
   end
 
-  # Method to save stats to the log file 'Demultiplex.log' in the output
-  # directory.
+  # Internal: Method that iterates over @samples and compiles a sorted Array
+  # with all unique index1 sequences.
   #
-  # Returns nothing.
-  def save(file)
-    @stats[:sample_id] = @samples.map(&:id)
-
-    @stats[:index1] = uniq_index1
-    @stats[:index2] = uniq_index2
+  # Returns Array with uniq index1 sequences.
+  def uniq_index1
+    @samples.each_with_object(SortedSet.new) do |e, a|
+      a << e.index1
+    end.to_a
+  end
 
-    File.open(file, 'w') do |ios|
-      ios.puts @status
-    end
+  # Internal: Method that iterates over @samples and compiles a sorted Array
+  # with all unique index2 sequences.
+  #
+  # Returns Array with uniq index2 sequences.
+  def uniq_index2
+    @samples.each_with_object(SortedSet.new) do |e, a|
+      a << e.index2
+    end.to_a
   end
 end

data/test/helper.rb

@@ -21,9 +21,13 @@
 #                                                                              #
 # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< #
 
+require 'pp'
+require 'fileutils'
+require 'tempfile'
 require 'demultiplexer'
 require 'test/unit'
 
+# Adding stream capture methods.
 module Kernel
   def capture_stdout
     out = StringIO.new
@@ -44,6 +48,7 @@ module Kernel
   end
 end
 
+# Adding custom test class method to TestCase.
 class Test::Unit::TestCase
   def self.test(desc, &impl)
     define_method("test #{desc}", &impl)