cheripic 1.0.0 → 1.1.0

data/lib/cheripic/regions.rb

@@ -4,21 +4,34 @@ require 'forwardable'
 
 module Cheripic
 
+  # Custom error handling for Regions class
   class RegionsError < CheripicError; end
 
+  # An application of Bio::DB::Fasta object that lets to extract selected regions of the fasta entries
+  #
+  # @!attribute [r] reference_db
+  #   @return [Bio::DB::Fasta::FastaFile] indexed fasta object
+  # @!attribute [r] id_len
+  #   @return [Hash] a hash of fasta entry ids as keys and sequence length as values
   class Regions
 
     include Enumerable
     extend Forwardable
     def_delegators :@id_len, :each, :each_key, :each_value, :length, :[]
-    attr_accessor :reference_db, :id_len
+    attr_reader :reference_db, :id_len
 
+    # creates a Regions object using fasta
+    #
+    # @param assembly [String] path to a fasta file
     def initialize(assembly)
       @reference_db = Bio::DB::Fasta::FastaFile.new({:fasta=>assembly})
       @id_len = {}
       self.get_id_len
     end
 
+    # A method to extract fasta entry ids and length and make a hash
+    #
+    # @return [Hash] a hash of fasta entry ids as keys and sequence length as values
     def get_id_len
       @reference_db.load_fai_entries
       @reference_db.index.entries.each_entry do | entry |
@@ -26,10 +39,13 @@ module Cheripic
       end
     end
 
-    # for each id and position returns left and right sequence
-    # of pre-selected length
+    # A method to returns left and right sequence of specified length, for a provided id and position
+    # @note this method excludes the base at the position provided
+    # @param id [String]
+    # @param pos [Integer]
+    # @return [Array<String>]
     def fetch_seq(id, pos)
-      limit = Options.params.sel_seq_len + 1
+      limit = Options.sel_seq_len + 1
       len = @id_len[id]
       low = pos-limit <= 0 ? 0 : pos-limit
       high = pos+limit >= len ? len : pos+limit

data/lib/cheripic/variants.rb

@@ -4,15 +4,33 @@ require 'forwardable'
 
 module Cheripic
 
+  # Custom error handling for Variants class
   class VariantsError < CheripicError; end
 
+  # A Variants object for each analysis pipeline that stores
+  # assembly details and extracts pileups for each contig
+  # assembly and pileup details are stored as
+  # hashes of Contig and ContigPileups objects
+  #
+  # @!attribute [r] assembly
+  #   @return [Hash] a hash of contig ids from assembly as keys and respective Contig objects as values
+  # @!attribute [r] pileups
+  #   @return [Hash] a hash of contig ids from assembly as keys and respective ContigPileups objects as values
+  # @!attribute [r] hmes_frags
+  #   @return [Hash] a hash of contigs with selected hme score, a subset of assembly hash
+  # @!attribute [r] bfr_frags
+  #   @return [Hash] a hash of contigs with selected bfr score, a subset of assembly hash
+  # @!attribute [r] pileups_analyzed
+  #   @return [Boolean] a Boolean option to check if pileups for the assembly are analyzed or not
   class Variants
 
     include Enumerable
     extend Forwardable
     def_delegators :@assembly, :each, :each_key, :each_value, :size, :length, :[]
-    attr_accessor :assembly, :has_run, :pileups, :hmes_frags, :bfr_frags
+    attr_reader :assembly, :pileups, :hmes_frags, :bfr_frags, :pileups_analyzed
 
+    # creates a Variants object using user input files
+    # @param options [Hash] a hash of required input files as keys and file paths as values
     def initialize(options)
       @params = options
       @assembly = {}
@@ -31,10 +49,11 @@ module Cheripic
         @assembly[contig.id] = contig
         @pileups[contig.id] = ContigPileups.new(contig.id)
       end
+      @pileups_analyzed = false
     end
 
-    # Read and store pileup data for each bulk and parents
-    #
+    # Reads and store pileup data for each of input bulk and parents pileup files
+    # And sets pileups_analyzed to true that pileups files are processed
     def analyse_pileups
       @bg_bulk = @params.bg_bulk
       @mut_parent = @params.mut_parent
@@ -47,9 +66,13 @@ module Cheripic
         end
       end
 
-      @has_run = true
+      @pileups_analyzed = true
     end
 
+    # Input pileup file is read and positions are selected that pass the thresholds
+    # @param pileupfile [String] path to the pileup file to read
+    # @param sym [Symbol] Symbol of the pileup file used to write selected variants
+    # pileup information to respective ContigPileups object
     def extract_pileup(pileupfile, sym)
       # read mpileup file and process each variant
       File.foreach(pileupfile) do |line|
@@ -61,8 +84,12 @@ module Cheripic
       end
     end
 
+    # Once pileup files are analysed and variants are extracted from each bulk;
+    # bulks are compared to identify and isolate variants for downstream analysis.
+    # If polyploidy set to trye and mut_parent and bg_parent bulks are provided
+    # hemisnps in parents are extracted for bulk frequency ratio analysis
     def compare_pileups
-      unless defined?(@has_run)
+      unless @pileups_analyzed
         self.analyse_pileups
       end
       @assembly.each_key do | id |
@@ -75,11 +102,15 @@ module Cheripic
       end
     end
 
+    # From Assembly contig objects, contigs are selected based on user selected options
+    # for homozygosity enrichment score (hme_score)
     def hmes_frags
       # calculate every time method gets called
       @hmes_frags = select_contigs(:hme_score)
     end
 
+    # From Assembly contig objects, contigs are selected based on user selected options
+    # for bulk frequency ratio (bfr_score)
     def bfr_frags
       unless defined?(@bfr_frags)
         @bfr_frags = select_contigs(:bfr_score)
@@ -87,14 +118,19 @@ module Cheripic
       @bfr_frags
     end
 
+    # Applies selection procedure on assembly contigs based on the ratio_type provided.
+    # If only_frag_with_vars is set to true then contigs without any variant are discarded for :hme_score
+    # while contigs without any hemisnps are discarded for :bfr_score
+    # If filter_out_low_hmes is set to true then contigs are further filtered based on a cut off value of the score
+    # @param ratio_type [Symbol] ratio_type is either :hme_score or :bfr_score
     def select_contigs(ratio_type)
       selected_contigs ={}
-      only_frag_with_vars = Options.params.only_frag_with_vars
+      only_frag_with_vars = Options.only_frag_with_vars
       @assembly.each_key do | frag |
         if only_frag_with_vars
           if ratio_type == :hme_score
             # selecting fragments which have a variant
-            if @assembly[frag].hm_num + @assembly[frag].ht_num > 2 * Options.params.hmes_adjust
+            if @assembly[frag].hm_num + @assembly[frag].ht_num > 2 * Options.hmes_adjust
               selected_contigs[frag] = @assembly[frag]
             end
           else # ratio_type == :bfr_score
@@ -116,6 +152,10 @@ module Cheripic
       selected_contigs
     end
 
+    # Filters out contigs below a cutoff for selected ratio_type
+    # a cutoff value is calculated based on ratio_type provided
+    # @param ratio_type [Symbol] ratio_type is either :hme_score or :bfr_score
+    # @param selected_contigs [Hash] a hash of contigs with selected ratio_type, a subset of assembly hash
     def filter_contigs(selected_contigs, ratio_type)
       cutoff = get_cutoff(selected_contigs, ratio_type)
       selected_contigs.each_key do | frag |
@@ -126,15 +166,19 @@ module Cheripic
       selected_contigs
     end
 
+    # Cut off value calculation used to filter out low scored contigs.
+    #
+    # @param ratio_type [Symbol] ratio_type is either :hme_score or :bfr_score
+    # @param selected_contigs [Hash] a hash of contigs with selected ratio_type, a subset of assembly hash
     def get_cutoff(selected_contigs, ratio_type)
-      filter_out_low_hmes = Options.params.filter_out_low_hmes
+      filter_out_low_hmes = Options.filter_out_low_hmes
       # set minimum cut off hme_score or bfr_score to pick fragments with variants
       # calculate min hme score for back or out crossed data or bfr_score for polypoidy data
       # if no filtering applied set cutoff to 1.1
       if filter_out_low_hmes
         if ratio_type == :hme_score
-          adjust = Options.params.hmes_adjust
-          if Options.params.cross_type == 'back'
+          adjust = Options.hmes_adjust
+          if Options.cross_type == 'back'
             cutoff = (1.0/adjust) + 1.0
           else # outcross
             cutoff = (2.0/adjust) + 1.0
@@ -148,6 +192,9 @@ module Cheripic
       cutoff
     end
 
+    # Cut off value calculation for bfr contigs.
+    # ratio value at index 0.1% length of an array or at index zero of an array that contains decreasing order of bfr ratios
+    # @param selected_contigs [Hash] a hash of contigs with selected bfr score, a subset of assembly hash
     def bfr_cutoff(selected_contigs, prop=0.1)
       ratios = []
       selected_contigs.each_key do | frag |
@@ -162,8 +209,8 @@ module Cheripic
       ratios[index - 1]
     end
 
-    # method is to discard homozygous variant positions for which background bulk
-    # pileup shows proportion higher than 0.35 for variant allele/non-reference allele
+    # Method is to discard homozygous variant positions for which background bulk
+    # pileup shows a fraction value higher than 0.35 for variant allele/non-reference allele
     # a recessive variant is expected to have 1/3rd frequency in background bulk
     def verify_bg_bulk_pileup
       unless defined?(@hmes_frags)

data/lib/cheripic/version.rb

@@ -1,3 +1,7 @@
 module Cheripic
-  VERSION = '1.0.0'
+
+  # Sets the semantic version number for this module.
+  # Version number will be used in help messages and for generating gem.
+  VERSION = '1.1.0'
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cheripic
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Shyam Rallapalli
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-20 00:00:00.000000000 Z
+date: 2016-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yell
@@ -70,6 +70,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
+- !ruby/object:Gem::Dependency
+  name: bio-samtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
 - !ruby/object:Gem::Dependency
   name: bio-gngm
   requirement: !ruby/object:Gem::Requirement
@@ -124,14 +138,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 1.7.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 1.7.6
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -249,6 +263,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/cheripic
 - bin/console
 - bin/setup
 - cheripic.gemspec
@@ -283,7 +298,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
 summary: picks causative mutation from bulks segregant sequencing