cheripic 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ace583d5063ea92f69faa4430b71f0bb0f654528
-  data.tar.gz: 00ae530b7c5c162aa0e699cae2c5dcaa9d159673
+  metadata.gz: 458f681424a73ea58acb8aefa73d68019ad0854d
+  data.tar.gz: 23547939b1fead465d06d2f6d8e45ce4172b1cb1
 SHA512:
-  metadata.gz: c179df9e44bdff364c8c9c7dd2a779609b05ed3d2f0ef5385c5c5ebb4910a98c35a05d861851dea3f34b14ab8d188994e6b7f254dde2b9356e73dbff08386cf0
-  data.tar.gz: f21ee021e4594bacaf319170746ad7655b0c579cb0c49495bf33dbef9dabd059f8d2e81edf44d64d24cea1f86a3e6315782d87fd8e475cf5698d35dce1bd3079
+  metadata.gz: 2e3af0df95197769c542b4aab76444a6b14842890b46a97d6be10101f267db5f5df7d1ed8d67083ac8890a866e1cab678a9b23c5dc03b1edb7b8fc2150b35097
+  data.tar.gz: 9aa159df9086102679bd6359d4a5bf94dfe72f52d9c11e66259ffd40754f767001bb2a67e996b958018a009db0a6aa558c7ebe4001c2f6bce9b8993bdfd66091

data/.gitignore

@@ -8,4 +8,5 @@
 /spec/reports/
 /tmp/
 .idea
+/packaging/
 

data/Gemfile

@@ -1,5 +1,4 @@
 source 'https://rubygems.org'
 
-gem 'bio-samtools', :git => 'git://github.com/helios/bioruby-samtools.git', :tag => 'v2.3.5'
 # Specify your gem's dependencies in cheripic.gemspec
 gemspec

data/bin/cheripic

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'cheripic'
+
+# rescue errors to get clean error messages through the logger
+# backtrace can be accessed by setting --loglevel to 'debug' option
+begin
+  submission = Cheripic::Cmd.new ARGV
+  submission.run
+rescue Cheripic::CheripicError => e
+  logger.error e.message
+  logger.debug e.backtrace unless e.backtrace.nil?
+  exit 1
+end

data/cheripic.gemspec

@@ -22,12 +22,12 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'yell', '~> 2.0', '>= 2.0.5'
   spec.add_runtime_dependency 'trollop', '~> 2.1', '>= 2.1.2'
   spec.add_runtime_dependency 'bio', '~> 1.5', '>= 1.5.0'
-  # spec.add_dependency 'bio-samtools', '~> 2.3.3'
+  spec.add_dependency 'bio-samtools', '~> 2.4.0'
   spec.add_dependency 'bio-gngm', '~> 0.2.1'
   spec.add_runtime_dependency 'rinruby', '~> 2.0', '>= 2.0.3'
 
   spec.add_development_dependency 'activesupport', '~> 4.2.6'
-  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'bundler', '~> 1.7.6'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'minitest'
   spec.add_development_dependency 'minitest-reporters', '>= 1.0.17'

data/lib/cheripic.rb

@@ -1,11 +1,17 @@
 
-# set up a golbal logger object to access across module
+# sets up a global logger object to access across module
 require 'yell'
+
+# Computing Homozygosity Enriched Regions In genomes to Prioritize Identification of Candidate variants (CHERIPIC)
+# Cheripic module provides tools and pipeline to extract potential candidate mutations
+# in around the region of the genome hosting the causative mutation behind the phenotype of interest.
 module Cheripic
 
   # custom error handling
   class CheripicError < StandardError; end
+  # custom error handling for IO
   class CheripicIOError < CheripicError; end
+  # custom error handling for Arg
   class CheripicArgError < CheripicError; end
 
   # Define a logger and pass `Object` as name.

data/lib/cheripic/bfr.rb

@@ -2,16 +2,26 @@
 
 module Cheripic
 
+  # Custom error handling for Bfr class
   class BfrError < CheripicError; end
 
+  # A class to calculate bulk frequency ratio (bfr) using one or two hashes of base fractions resulted from pileup
+  #
+  # @!attribute [rw] bfr_adj
+  #   @return [Float] a float value to adjust the bfr calculation
   class Bfr
 
     attr_accessor :bfr_adj
 
-    # get bulk frequency ratio (bfr) for marked hemi snps only
-    # ignore positions with complex variants
+    # A method to get bulk frequency ratio (bfr) for selected hemi snps.
+    #   This is done by selecting which hash (mutant or background) to use for bfr calculation
+    #   either calculates fraction or bfr
+    #   and ignores positions with complex variants.
+    # @param mut_hash [Hash] a hash of base fractions from pileup of mutant bulk
+    # @param bg_hash [Hash] a hash of base fractions from pileup of background bulk
+    # @return [Float] a ratio calculated
     def self.get_bfr(mut_hash, bg_hash='')
-      @bfr_adj = Options.params.bfr_adjust
+      @bfr_adj = Options.bfr_adjust
       if bg_hash != ''
         # checking if only two vars in base hash and that includes ref
         # checking if only one var in hemi snp
@@ -37,9 +47,12 @@ module Cheripic
       bfr
     end
 
-    # calculate bfr using both mutant and background bulk information
+    # A method to calculate bfr using a base fraction hash with hemi-snp
+    # @param two_key_hash [Hash] a hash of base fractions from pileup with 2 keys (a ref and variant base)
+    # @param other_hash [Hash] a hash of base fractions from pileup
+    # @return [Float] a ratio calculated
     def self.calculate_bfr(two_key_hash, other_hash)
-      # fix :ref value if absent due to below noise depth
+      # if :ref is absent such as below noise depth, then set to zero
       unless two_key_hash.key?(:ref)
         two_key_hash[:ref] = 0
       end
@@ -63,6 +76,9 @@ module Cheripic
       bfr
     end
 
+    # A method to calculate ratio using a base fraction hash
+    # @param hash [Hash] a hash of base fractions from pileup with 2 or 1 keys
+    # @return [Array<Float><String>] an array of ratio calculated and base character
     def self.calc_fraction(hash)
       unless hash.key?(:ref)
         hash[:ref] = 0

data/lib/cheripic/cmd.rb

@@ -2,6 +2,10 @@
 
 module Cheripic
 
+  # A command line option and processing object to handle input options
+  #
+  # @!attribute [rw] options
+  #   @return [Hash] a hash of trollop option names as keys and user or default setting as values
   class Cmd
 
     require 'trollop'
@@ -10,11 +14,16 @@ module Cheripic
 
     attr_accessor :options
 
+    # creates a Cmd object using input string entry
+    # @param args [String]
     def initialize(args)
       @options = parse_arguments(args)
       check_arguments
     end
 
+    # method to check input command string and run appropriate
+    # method of the object (help or examples or parsing arguments)
+    # @param args [String]
     def parse_arguments(args)
       Trollop::with_standard_exception_handling argument_parser do
         if args.empty? || args.include?('-h') || args.include?('--help')
@@ -26,6 +35,8 @@ module Cheripic
       end
     end
 
+    # trollop argument_parser for input args string and
+    # @return [Hash] a hash of trollop option names as keys and user or default setting as values
     def argument_parser
       cmds = self
       Trollop::Parser.new do
@@ -106,40 +117,44 @@ module Cheripic
       end
     end
 
+    # help message to display from command line
     def help_message
-      <<-EOS
+      msg = <<-EOS
 
-Cheripic v#{Cheripic::VERSION.dup}
-Authors: Shyam Rallapalli and Dan MacLean
+      Cheripic v#{Cheripic::VERSION.dup}
+      Authors: Shyam Rallapalli and Dan MacLean
 
-Description: Candidate mutation and closely linked marker selection for non reference genomes
-Uses bulk segregant data from non-reference sequence genomes
+      Description: Candidate mutation and closely linked marker selection for non reference genomes
+      Uses bulk segregant data from non-reference sequence genomes
 
-Inputs:
-1. Needs a reference fasta file of asssembly use for variant analysis
-2. Pileup files for mutant (phenotype of interest) bulks and background (wildtype phenotype) bulks
-3. If polyploid species, include of pileup from one or both parents
+      Inputs:
+      1. Needs a reference fasta file of asssembly use for variant analysis
+      2. Pileup files for mutant (phenotype of interest) bulks and background (wildtype phenotype) bulks
+      3. If polyploid species, include of pileup from one or both parents
 
-USAGE:
-cheripic <options>
+      USAGE:
+      cheripic <options>
 
-OPTIONS:
+      OPTIONS:
 
       EOS
+      msg.split("\n").map{ |line| line.lstrip }.join("\n")
     end
 
+    # examples to display from command line
     def print_examples
       msg = <<-EOS
 
-    Cheripic v#{Cheripic::VERSION.dup}
+        Cheripic v#{Cheripic::VERSION.dup}
 
-    EXAMPLE COMMANDS:
+        EXAMPLE COMMANDS:
 
       EOS
       puts msg.split("\n").map{ |line| line.lstrip }.join("\n")
       exit(0)
     end
 
+    # calls other methods to check if command line inputs are valid
     def check_arguments
       check_output_dir
       check_log_level
@@ -153,6 +168,7 @@ OPTIONS:
     #   end
     # end
 
+    # checks if input files are valid
     def check_input_files
       if @options[:polyploidy]
         inputfiles = %i{assembly mut_bulk bg_bulk mut_parent bg_parent}
@@ -173,6 +189,7 @@ OPTIONS:
       end
     end
 
+    # checks if output directory already exists
     def check_output_dir
       if Dir.exist?(@options[:output])
         raise CheripicArgError.new "#{@options[:output]} directory exists" +
@@ -180,6 +197,7 @@ OPTIONS:
       end
     end
 
+    # checks and sets logger level
     def check_log_level
       unless %w(error info warn debug).include?(@options[:loglevel])
         raise CheripicArgError.new "Loglevel #{@options[:loglevel]} is not valid. " +
@@ -188,6 +206,10 @@ OPTIONS:
       logger.level = Yell::Level.new @options[:loglevel].to_sym
     end
 
+    # Initializes an Implementer object using input options
+    # and calls run method of the Implementer to start the pipeline
+    # A hash of trollop option names as keys and user or default
+    # setting as values is passed to Implementer object
     def run
       @options[:output] = File.expand_path @options[:output]
       analysis = Implementer.new(@options)

data/lib/cheripic/contig.rb

@@ -4,16 +4,29 @@ require 'forwardable'
 
 module Cheripic
 
+# Custom error handling for Contig class
   class ContigError < CheripicError; end
 
+  # A contig object from assembly that stores positions of
+  # homozygous, heterozygous and hemi-variants
+  #
+  # @!attribute [rw] hm_pos
+  #   @return [Hash] a hash of homozygous variant positions as keys and allele frequency as values
+  # @!attribute [rw] ht_pos
+  #   @return [Hash] a hash of heterozygous variant positions as keys and allele frequency as values
+  # @!attribute [rw] hemi_pos
+  #   @return [Hash] a hash of hemi-variant positions as keys and allele frequency as values
+  # @!attribute [r] id
+  #   @return [String] id of the contig in assembly taken from fasta file
+  # @!attribute [r] length
+  #   @return [Integer] length of contig in bases
   class Contig
 
-    include Enumerable
-    extend Forwardable
-    # delegate [:size, :length] => :@contig
-    # def_delegator :@contig, :entry_id, :id
-    attr_accessor :hm_pos, :ht_pos, :hemi_pos, :id, :length
+    attr_accessor :hm_pos, :ht_pos, :hemi_pos
+    attr_reader :id, :length
 
+    # creates a Contig object using fasta entry
+    # @param fasta [Bio::FastaFormat] an individual fasta entry from input assembly file
     def initialize (fasta)
       @id = fasta.entry_id
       @length = fasta.length
@@ -22,16 +35,23 @@ module Cheripic
       @hemi_pos = {}
     end
 
+    # Number of homozygous variants identified in the contig
+    # @return [Integer]
     def hm_num
       self.hm_pos.length
     end
 
+    # Number of heterozygous variants identified in the contig
+    # @return [Integer]
     def ht_num
       self.ht_pos.length
     end
 
+    # Homozygosity enrichment score calculated using
+    # hm_num and ht_num of the contig object
+    # @return [Float]
     def hme_score
-      hmes_adjust = Options.params.hmes_adjust
+      hmes_adjust = Options.hmes_adjust
       if self.hm_num == 0 and self.ht_num == 0
         0.0
       else
@@ -39,10 +59,15 @@ module Cheripic
       end
     end
 
+    # Number of hemi-variants identified in the contig
+    # @return [Integer]
     def hemi_num
       self.hemi_pos.length
     end
 
+    # Mean of bulk frequency ratios (bfr) calculated using
+    # bfr values all hemi_pos of the contig
+    # @return [Float]
     def bfr_score
       if self.hemi_pos.values.empty?
         0.0
@@ -51,7 +76,9 @@ module Cheripic
       end
     end
 
-    # geometric mean of an array of numbers
+    # Calculates mean of an array of numbers
+    # @param array [Array] an array of bfr values from hemi_snp
+    # @return [Float] mean value as float
     def geom_mean(array)
       return array[0].to_f if array.length == 1
       array.reduce(:+) / array.size.to_f

data/lib/cheripic/contig_pileups.rb

@@ -4,8 +4,25 @@ require 'forwardable'
 
 module Cheripic
 
+  # Custom error handling for ContigPileup class
   class ContigPileupsError < CheripicError; end
 
+  # A ContigPileup object for each contig from assembly that stores
+  # pileup file information and variants are selected from analysis of pileup files
+  # selected variants from pileup files is stored as hashes
+  #
+  # @!attribute [rw] id
+  #   @return [String] id of the contig in assembly taken from fasta file
+  # @!attribute [rw] mut_bulk
+  #   @return [Hash] a hash of variant positions from mut_bulk as keys and pileup info as values
+  # @!attribute [rw] bg_bulk
+  #   @return [Hash] a hash of variant positions from bg_bulk as keys and pileup info as values
+  # @!attribute [rw] mut_parent
+  #   @return [Hash] a hash of variant positions from mut_parent as keys and pileup info as values
+  # @!attribute [rw] bg_parent
+  #   @return [Hash] a hash of variant positions from bg_parent as keys and pileup info as values
+  # @!attribute [rw] parent_hemi
+  #   @return [Hash] a hash of hemi-variant positions as keys and bfr calculated from parent bulks as values
   class ContigPileups
 
     include Enumerable
@@ -17,6 +34,8 @@ module Cheripic
     attr_accessor :id, :parent_hemi
     attr_accessor :mut_bulk, :bg_bulk, :mut_parent, :bg_parent
 
+    # creates a ContigPileup object using fasta entry id
+    # @param fasta [String] a contig id from fasta entry
     def initialize (fasta)
       @id = fasta
       @mut_bulk = {}
@@ -26,12 +45,15 @@ module Cheripic
       @parent_hemi = {}
     end
 
+    # bulk pileups are compared and variant positions are selected
+    # @return [Array<Hash>] variant positions are stored in hashes
+    # for homozygous, heterozygous and hemi-variant positions
     def bulks_compared
       @hm_pos = {}
       @ht_pos = {}
       @hemi_pos = {}
       @mut_bulk.each_key do | pos |
-        if Options.params.polyploidy and @parent_hemi.key?(pos)
+        if Options.polyploidy and @parent_hemi.key?(pos)
           bg_bases = ''
           if @bg_bulk.key?(pos)
             bg_bases = @bg_bulk[pos].var_base_frac
@@ -46,9 +68,11 @@ module Cheripic
       [@hm_pos, @ht_pos, @hemi_pos]
     end
 
-    # we are only dealing with single element hashes
-    # so discard hashes with more than one element and empty hashes
-    # empty hash results from position below selected coverage or bases freq below noise
+    # mut_bulk and bg_bulk pileups are compared at selected position of the contig.
+    # Empty hash results from position below selected coverage
+    # or bases freq below noise and such positions are deleted.
+    # @param pos [Integer] position in the contig
+    # stores variant type, position and allele fraction to either @hm_pos or @ht_pos hashes
     def compare_pileup(pos)
       base_hash = @mut_bulk[pos].var_base_frac
       base_hash.delete(:ref)
@@ -56,22 +80,43 @@ module Cheripic
       # we could ignore complex loci or
       # take the variant type based on predominant base
       if base_hash.length > 1
-        mut_type, ratio = var_mode(base_hash.values.max)
+        fraction = base_hash.values.max
+        mut_type = var_mode(fraction)
       else
-        base = base_hash.keys[0]
-        mut_type, ratio = var_mode(base_hash[base])
+        fraction = base_hash[base_hash.keys[0]]
+        mut_type = var_mode(fraction)
       end
       if @bg_bulk.key?(pos)
         bg_type = bg_bulk_var(pos)
         mut_type = compare_var_type(mut_type, bg_type)
       end
       unless mut_type == nil
-        categorise_pos(mut_type, pos, ratio)
+        categorise_pos(mut_type, pos, fraction)
       end
     end
 
-    # if both bulks have homozygous var at this position
-    # then ignore the position
+    # Categorizes variant zygosity based on the allele fraction provided.
+    # Uses lower and upper limit set for heterozygosity in the options.
+    # @note consider increasing the range of heterozygosity limits for RNA-seq data
+    # @param fraction [Float] allele fraction
+    # @return [Symbol] of either :het or :hom to represent heterozygous or homozygous respectively
+    def var_mode(fraction)
+      ht_low = Options.htlow
+      ht_high = Options.hthigh
+      mode = ''
+      if fraction.between?(ht_low, ht_high)
+        mode = :het
+      elsif fraction > ht_high
+        mode = :hom
+      end
+      mode
+    end
+
+    # Simple comparison of variant type of mut and bg bulks at a position
+    # If both bulks have homozygous variant at selected position then it is ignored
+    # @param muttype [Symbol] values are either :hom or :het
+    # @param bgtype [Symbol] values are either :hom or :het
+    # @return [Symbol] variant mode of the mut bulk (:hom or :het) at the position or nil
     def compare_var_type(muttype, bgtype)
       if muttype == :hom and bgtype == :hom
         nil
@@ -80,17 +125,26 @@ module Cheripic
       end
     end
 
+    # Method to extract var_mode from pileup information at a position in contig
+    #
+    # @param pos [Integer] position in the contig
+    # @return [Symbol] variant mode of the background bulk (:hom or :het) at the position
     def bg_bulk_var(pos)
       bg_base_hash = @bg_bulk[pos].var_base_frac
       if bg_base_hash.length > 1
         # taking only var mode
-        var_mode(bg_base_hash.values.max)[0]
+        var_mode(bg_base_hash.values.max)
       else
         # taking only var mode
-        var_mode(bg_base_hash[0])[0]
+        var_mode(bg_base_hash[0])
       end
     end
 
+    # method stores pos as key and allele fraction as value
+    # to @hm_pos or @ht_pos hash based on variant type
+    # @param var_type [Symbol]  values are either :hom or :het
+    # @param pos [Integer] position in the contig
+    # @param ratio [Float] allele fraction
     def categorise_pos(var_type, pos, ratio)
       if var_type == :hom
         @hm_pos[pos] = ratio
@@ -99,20 +153,10 @@ module Cheripic
       end
     end
 
-    # calculate var zygosity for non-polyploid variants
-    # increased range is used for heterozygosity for RNA-seq data
-    def var_mode(ratio)
-      ht_low = Options.params.htlow
-      ht_high = Options.params.hthigh
-      mode = ''
-      if ratio.between?(ht_low, ht_high)
-        mode = :het
-      elsif ratio > ht_high
-        mode = :hom
-      end
-      [mode, ratio]
-    end
-
+    # Compares parental pileups for the contig and identify position
+    # that indicate variants from homelogues called hemi-snps
+    # and calculates bulk frequency ratio (bfr)
+    # @return [Hash] parent_hemi hash with position as key and bfr as value
     def hemisnps_in_parent
       # mark all the hemi snp based on both parents
       self.mut_parent.each_key do |pos|