bioroebe 0.10.80

data/lib/bioroebe/sequence/dna.rb

@@ -0,0 +1,211 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Bioroebe::DNA
+#
+# This is a typical "segment of" DNA, a sequence object.
+#
+# In theory you would not need to use this, since you can just use
+# Bioroebe::Sequence anyway - but perhaps some people prefer the
+# more explicit name DNA, so this is one reason why this class
+# exists.
+#
+# A sequence of DNA can be associated with a "gene", as an optional
+# identifier. It could also be associated with more than one gene,
+# but right now that is not supported - it will depend on future
+# use cases whether this will be enabled or not. 
+# =========================================================================== #
+# require 'bioroebe/sequence/dna.rb'
+# =========================================================================== #
+require 'bioroebe/requires/require_sequence.rb'
+
+module Bioroebe
+
+class DNA < ::Bioroebe::Sequence # === Bioroebe::DNA
+
+  require 'bioroebe/sequence/nucleotide_module/nucleotide_module.rb'
+  include Bioroebe::NucleotideModule
+
+  require 'bioroebe/codons/codons.rb'
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      this_sequence  = 'ATCG'
+    )
+    reset
+    super(
+      this_sequence
+    )
+    set_dna_type # Make sure we have a DNA only.
+  end
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @name_of_the_gene
+    # ======================================================================= #
+    @name_of_the_gene = nil # No name is assigned by default.
+  end
+
+  # ========================================================================= #
+  # === set_name_of_the_gene
+  #
+  # Use this method if you want to give the gene a specific name.
+  # ========================================================================= #
+  def set_name_of_the_gene(i)
+    @name_of_the_gene = i
+  end; alias name=         set_name_of_the_gene # === name=
+       alias set_name      set_name_of_the_gene # === set_name
+       alias name_of_gene= set_name_of_the_gene # === name_of_gene=
+       alias set_gene_name set_name_of_the_gene # === set_gene_name
+
+  # ========================================================================= #
+  # === name_of_gene?
+  # ========================================================================= #
+  def name_of_gene?
+    @name_of_the_gene
+  end; alias name_of_gene name_of_gene? # === name_of_gene
+       alias name?        name_of_gene? # === name?
+
+  # ========================================================================= #
+  # === to_rna
+  #
+  # Convert the main sequence to RNA and return that result.
+  # ========================================================================= #
+  def to_rna
+    string?.tr('T','U')
+  end; alias to_RNA to_rna # === to_RNA
+       alias to_T   to_rna # === to_T
+
+  # ========================================================================= #
+  # === to_aminoacids
+  #
+  # This will convert the given DNA input into the corresponding
+  # aminoacid "output" - aka a translational output, following
+  # the regular conversion of DNA→mRNA→protein.
+  #
+  # If the second argument to this method is true, then we will filter
+  # away all "STOP" elements.
+  # ========================================================================= #
+  def to_aminoacids(
+      i                  = string?,
+      ignore_stop_codons = true
+    )
+    i = [i].flatten
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      # ===================================================================== #
+      # We don't have to handle :frame1 since this is the default anyway.
+      # ===================================================================== #
+      case yielded
+      when :frame2
+        i.map! {|entry| entry[1..-1] }
+      when :frame3
+        i.map! {|entry| entry[2..-1] }
+      end
+    end
+    i.map {|entry|
+      if entry and (entry.size > 2) # Must check for at the least 3 nucleotides there.
+        # =================================================================== #
+        # Get a chunk of 3 nucleotides next. This will yield an array of
+        # codons such as this one here:
+        #
+        #   ["GCC", "CAC", "AGG", "CAC", "AAC"]
+        #
+        # =================================================================== #
+        codons = entry.scan(/.../)
+        # =================================================================== #
+        # Next, find the corresponding aminoacid for this codon.
+        # =================================================================== #
+        aminoacids = codons.map {|codon|
+          result = ::Bioroebe.codon_to_aminoacid(codon)
+          result
+        }
+        if ignore_stop_codons
+          aminoacids.reject! {|inner_entry|
+            inner_entry == 'STOP'
+          }
+        end
+        result = aminoacids.join
+        result # Return the result here.
+      else
+        entry
+      end
+    }
+  end; alias to_aa      to_aminoacids # === to_aa
+       alias to_protein to_aminoacids # === to_protein
+
+  # ========================================================================= #
+  # === gc_percentage?
+  #
+  # Usage example:
+  #
+  #   x = Bioroebe::DNA.new('TTATTAAGTATTACG'); x.gc_percentage? # => "20.000"
+  #
+  # ========================================================================= #
+  def gc_percentage?
+    require 'bioroebe/calculate/calculate_gc_content.rb'
+    Bioroebe.gc_content(string?)
+  end
+
+end
+
+# =========================================================================== #
+# === Bioroebe.to_aminoacids
+#
+# This method can be used to convert a String such as 'ATG' into the
+# corresponding aminoacid sequence - in this example, the String 'M'.
+#
+# Invocation examples:
+#
+#   Bioroebe.to_aminoacids 'AUGGCCAUGGCGCCCAGAACUGAGAUCAAUAGUACCCGUAUUAACGGGUGA' # => "MAMAPRTEINSTRING"
+#   Bioroebe.to_aminoacids '/rosalind_prot.txt' # => "MAMAPRTEINSTRING"
+#
+# =========================================================================== #
+def self.to_aminoacids(i, &block)
+  if i and File.file?(i)
+    i = File.read(i).strip
+  end
+  result = ::Bioroebe::DNA.new.to_aminoacids(i, &block)
+  if i.is_a?(String) and !result.is_a?(String)
+    # ======================================================================= #
+    # If the user did input a String, then we must make sure that the
+    # returned value will also be a String.
+    # ======================================================================= #
+    result = result.join(' ').strip
+  end
+  result
+end; self.instance_eval { alias to_aa          to_aminoacids } # === Bioroebe.to_aa
+     self.instance_eval { alias to_protein     to_aminoacids } # === Bioroebe.to_protein
+     self.instance_eval { alias rna_to_protein to_aminoacids } # === Bioroebe.rna_to_protein 
+
+# =========================================================================== #
+# === Bioroebe.dna_sequence
+#
+# Usage example:
+#
+#   dna = Bioroebe.dna_sequence('ATTCGGU')
+#
+# =========================================================================== #
+def self.dna_sequence(i)
+  i = i.first if i.is_a? Array
+  i.delete!('U') # Reject Uracil there.
+  ::Bioroebe::DNA.new(i)
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  dna = Bioroebe::DNA.new(ARGV)
+  puts 'The DNA sequence is: '+dna.sequence?
+  puts 'The RNA sequence is: '+dna.to_rna
+end # dna ATCGATCGAAATTACCCCCCCC

data/lib/bioroebe/sequence/nucleotide_module/nucleotide_module.rb

@@ -0,0 +1,404 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Bioroebe::NucleotideModule
+# =========================================================================== #
+# require 'bioroebe/sequence/nucleotide_module/nucleotide_module.rb'
+# include Bioroebe::NucleotideModule
+# =========================================================================== #
+module Bioroebe
+
+module NucleotideModule # === Bioroebe::NucleotideModule
+
+  require 'bioroebe/toplevel_methods/nucleotides.rb'
+  # ========================================================================= #
+  # === Bioroebe::NucleotideModule.complementary_strand
+  #
+  # This method will return the complementary strand. So, the complementary
+  # strand to "A" will be "T"; and from "T" it will be "A"; from "G" it
+  # will be "C" and from "C" it will be "G".
+  #
+  # Note that special "nucleotides" such as R or Y, may be used as well - R
+  # refers to a Purine, and Y refers to a Pyrimidine.
+  #
+  # Usage example:
+  #
+  #   x = Bioroebe::Sequence.new('ATGCAA'); x.complementary # => "TACGTT"
+  #
+  # ========================================================================= #
+  def self.complementary_strand(
+      i = @sequence.chars
+    )
+    if i and i.is_a?(String)
+      i = i.chars
+    end
+    return i.map {|line|
+      ::Bioroebe.complementary_nucleotide(line)
+    }.join
+  end; self.instance_eval { alias complementary                  complementary_strand } # === complementary
+       self.instance_eval { alias build_complementary_dna_strand complementary_strand } # === build_complementary_dna_strand
+       self.instance_eval { alias build_second_strand            complementary_strand } # === build_second_strand
+       self.instance_eval { alias build_complementary_strand     complementary_strand } # === build_complementary_strand
+
+  require 'bioroebe/toplevel_methods/nucleotides.rb'
+  # ========================================================================= #
+  # === complementary_strand
+  # ========================================================================= #
+  def complementary_strand(i = '')
+    return ::Bioroebe.complementary_strand(i)
+  end; alias complementary                  complementary_strand # === complementary
+       alias build_complementary_dna_strand complementary_strand # === build_complementary_dna_strand
+       alias build_second_strand            complementary_strand # === build_second_strand
+       alias build_complementary_strand     complementary_strand # === build_complementary_strand
+
+  # ========================================================================= #
+  # === to_rna
+  #
+  # This method will simply return the RNA sequence corresponding to
+  # the DNA sequence.
+  # ========================================================================= #
+  def to_rna(i = seq?)
+    i.tr('T','U')
+  end; alias rna        to_rna # === rna
+       alias rna?       to_rna # === rna?
+       alias transcribe to_rna # === transcribe
+       alias to_RNA     to_rna # === to_RNA
+
+  # ========================================================================= #
+  # === to_T
+  # ========================================================================= #
+  def to_T(i = seq?)
+    i.tr('U','T')
+  end
+
+  # ========================================================================= #
+  # === to_dna
+  # ========================================================================= #
+  def to_dna
+    seq?.tr('U','T')
+  end; alias dna to_dna # === dna
+
+  # ========================================================================= #
+  # === n_random_dna
+  #
+  # This method will assign a random DNA sequence.
+  #
+  # The first argument tells us how long that sequence should be,
+  # defaulting to 100.
+  #
+  # The second argument means that we will also invoke set_string(), which
+  # may lead to an infinite loop if you are not careful, so be mindful
+  # of that.
+  # ========================================================================= #
+  def n_random_dna(
+      n_elements     = :default,
+      do_also_assign = false
+    )
+    case n_elements
+    when :default
+      n_elements = 100
+    end
+    _ = n_elements.to_i.times.map { DNA_NUCLEOTIDES.sample }.join.strip
+    set_string(_) if do_also_assign
+    return _
+  end
+
+  # ========================================================================= #
+  # === gc_percentage
+  #
+  # This method will return a number, in percent, how many of the nucleotides
+  # are either G or C.
+  #
+  # Invocation example:
+  #
+  #   seq = Bioroebe::Sequence.new("ATGC"); seq.gc_percentage # => 50.0
+  #
+  # ========================================================================= #
+  def gc_percentage(
+      round_to_n_positions = 2
+    )
+    sum = @sequence.count('G') + @sequence.count('C')
+    result = (sum * 100.0 / @sequence.size)
+    if round_to_n_positions
+      result = result.round(round_to_n_positions)
+    end
+    return result
+  end; alias gc_percent gc_percentage # === gc_percent
+
+  # ========================================================================= #
+  # === back_from_rna
+  # ========================================================================= #
+  def back_from_rna(i = seq?)
+    i.tr('U','T')
+  end; alias back_transcribe back_from_rna # === back_transcribe
+
+  # ========================================================================= #
+  # === cut_with_enzyme
+  #
+  # Use this method to cut the given sequence via a restriction enzyme.
+  # This is only relevant for DNA or RNA, not proteins - at the least
+  # in regards to restriction enzymes. Obviously proteins may be
+  # cleavable via proteolytic enzymes.
+  #
+  # Usage example:
+  #
+  #   sequence = Bioroebe::Sequence.new(::Bioroebe.return_random_aminoacid(50)); result = sequence.cut_with_enzyme 'EcoRI'
+  #   sequence = Bioroebe::Sequence.new(150); result = sequence.cut_with_enzyme 'EcoRI'
+  #
+  # ========================================================================= #
+  def cut_with_enzyme(this_enzyme)
+    require 'bioroebe/enzymes/restriction_enzyme.rb'
+    target_sequence = ::Bioroebe.restriction_enzyme("#{this_enzyme}.site")
+    main_string?.split(/#{target_sequence}/)
+  end
+
+  # ========================================================================= #
+  # === remove_invalid_entries_from_the_dna_sequence
+  #
+  # Get rid of all entries except for A, T, G and C.
+  # ========================================================================= #
+  def remove_invalid_entries_from_the_dna_sequence
+    @sequence.tr!('B,D-F,H-S,U-Z','') if @sequence
+  end
+
+  # ========================================================================= #
+  # === at_percentage
+  #
+  # This is the complement of GC percentage, thus why we deduct from 100.
+  # ========================================================================= #
+  def at_percentage
+    (100 - gc_percentage)
+  end; alias at_percent    at_percentage # === at_percent
+       alias AT_percentage at_percentage # === AT_percentage
+
+  # ========================================================================= #
+  # === has_stop_codon?
+  #
+  # This method will return true if the sequence includes at the least one
+  # stop codon; otherwise this method will return false.
+  #
+  # Usage examples:
+  #
+  #   require 'bioroebe'; include Bioroebe; x = Seq('ATC GTC GGA ATAG'); puts x.has_stop_codon?         # false
+  #   require 'bioroebe'; include Bioroebe; x = Seq('ATG GTC GGA ATAG'); puts x.has_stop_codon? :frame1 # true
+  #   require 'bioroebe'; include Bioroebe; x = Seq('ATG GTC GGA ATAG'); puts x.has_stop_codon? :frame2
+  #   require 'bioroebe'; include Bioroebe; x = Seq('ATG GTC GGA ATAG'); puts x.has_stop_codon? :frame3
+  #
+  # ========================================================================= #
+  def has_stop_codon?(
+      optional_use_this_frame = nil
+    )
+    _ = @sequence
+    stop_codons = ::Bioroebe.stop_codons?
+    # ======================================================================= #
+    # We must ensure that the stop-codons are actually initialized. If not
+    # then we will do so here quickly, then re-assign.
+    # ======================================================================= #
+    if stop_codons.empty?
+      ::Bioroebe.initialize_stop_codons
+      stop_codons = ::Bioroebe.stop_codons?
+    end
+    if optional_use_this_frame
+      case optional_use_this_frame
+      when :frame1, :in_frame1
+        _ = _.scan(/.../)
+      when :frame2, :in_frame2
+        _ = _[1..-1].scan(/.../)
+      when :frame3, :in_frame3
+        _ = _[2..-1].scan(/.../)
+      else
+        e 'Unknown input: '+orange(optional_use_this_frame.to_s)+
+          ' (class '+optional_use_this_frame.class.to_s+')'
+        return false
+      end
+      stop_codons.any? {|this_stop_codon_triplett|
+        _.include? this_stop_codon_triplett
+      }
+    else
+      stop_codons.any? {|this_stop_codon_triplett|
+        _.include? this_stop_codon_triplett
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === allow_only_valid_dna
+  #
+  # Allow only valid DNA. It will discard anything that is not A, T, C or G.
+  #
+  # "ATCGIIII".allow_only_valid_dna
+  # ========================================================================= #
+  def allow_only_valid_dna(
+      i = @sequence.dup
+    )
+    return_string = ''.dup
+    i.each_char { |entry|
+      case entry.downcase
+      when 'a','t','c','g' # Uracil is only in RNA, not in DNA.
+        return_string << entry # But don't put the downcased string into that.
+      end
+    }
+    return return_string
+  end; alias only_valid_dna_nucleotides allow_only_valid_dna # === only_valid_dna_nucleotides
+
+  require 'bioroebe/codons/codons.rb'
+  # ========================================================================= #
+  # === codon_to_aminoacid
+  #
+  # This method will translate a DNA-codon (or RNA-codon) into the
+  # corresponding aminoacid.
+  # 
+  # Usage example:
+  #
+  #   codon_to_aminoacid TCC
+  #
+  # ========================================================================= #
+  def codon_to_aminoacid(codon = sequence?)
+    ::Bioroebe.codon_to_aminoacid(codon)
+  end; alias translate_aminoacid_into_dna codon_to_aminoacid # === translate_aminoacid_into_dna
+
+  # ========================================================================= #
+  # === to_dna
+  #
+  # This method will convert a RNA sequence into a DNA sequence.
+  #
+  # It will return the translation.
+  #
+  # bio; puts Bioroebe.new.to_dna('actgggcgagagklklklklk')
+  # ========================================================================= #
+  def to_dna(
+      i = sequence?, upcase_me = true
+    )
+    if is_RNA?
+      i = sequence? if i.nil?
+      ::Bioroebe.to_dna(i, upcase_me)
+    end
+  end; alias dna to_dna # === dna
+
+  # ========================================================================= #
+  # === random
+  #
+  # This method is only for DNA really.
+  # ========================================================================= #
+  def random(n_elements = :default)
+    n_random_dna(
+      n_elements, true
+    ) if is_dna?
+  end
+
+  # ========================================================================= #
+  # === to_aminoacid_sequence
+  #
+  # If you wish to convert the main sequence into the corresponding
+  # aminoacid sequence, use this method here.
+  #
+  # You can specify a different reading frame as well - see the usage
+  # example that follows.
+  #
+  # Usage example if you have a sequence object called seq:
+  #
+  #   seq = Bioroebe::Sequence.new(50); seq.translate(:frame_two)
+  #   seq = Bioroebe::Sequence.new(50); seq.translate(table: "Vertebrate Mitochondrial")
+  #   seq = Bioroebe::Sequence.new("ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGATAG"); seq.translate(table: "Vertebrate Mitochondrial")
+  # 
+  # ========================================================================= #
+  def to_aminoacid_sequence(
+      i                      = sequence?,
+      use_this_reading_frame = :default # This is :frame_one.
+    )
+    if i.is_a? Hash
+      if i.has_key? :table
+        Bioroebe.set_use_this_codon_table(i.delete(:table))
+        use_this_reading_frame = :default
+        i = sequence?
+      end
+    end
+    # ======================================================================= #
+    # We must sanitize the first argument if it is a Symbol, at the least
+    # for 3 specific symbols.
+    # ======================================================================= #
+    if i.is_a? Symbol
+      case i
+      when :frame_one,
+           :default
+        i = sequence?
+        use_this_reading_frame = :frame_one
+      when :frame_two
+        i = sequence?
+        use_this_reading_frame = :frame_two
+      when :frame_three
+        i = sequence?
+        use_this_reading_frame = :frame_three
+      end
+    end
+    unless Bioroebe.const_defined? :DnaToAminoacidSequence
+      require 'bioroebe/conversions/dna_to_aminoacid_sequence.rb'
+    end
+    _ = ::Bioroebe::DnaToAminoacidSequence.new(
+      i, :do_not_run_yet
+    ) # bl $BIOROEBE/conversions/dna_to_aminoacid_sequence.rb
+    _.be_quiet_and_no_colours
+    case i
+    # ======================================================================= #
+    # === :frame_one
+    # ======================================================================= #
+    when :frame_one,
+         :from_frame_one,
+         'one','1',1
+      use_this_reading_frame = :frame_one
+      i = sequence?
+      _.use_this_sequence = i
+    # ======================================================================= #
+    # === :frame_two
+    # ======================================================================= #
+    when :frame_two,
+         :from_frame_two,'two','2',2
+      use_this_reading_frame = :frame_two
+      i = sequence?
+      _.use_this_sequence = i
+    when :frame_three,
+         :from_frame_three,'three','3',3
+      use_this_reading_frame = :frame_three
+      i = sequence?
+      _.use_this_sequence = i
+    end
+    # ======================================================================= #
+    # We may also use another reading frame, which will be handled next.
+    # ======================================================================= #
+    _.use_this_reading_frame = use_this_reading_frame
+    _.run
+    return _.sequence?
+  end; alias translate to_aminoacid_sequence # === translate (translate tag)
+
+  # ========================================================================= #
+  # === gc_percentage
+  #
+  # This will return, as a float (aka number), the percentage of GC of
+  # a given RNA or DNA string. An example value may be 55.3, which stands
+  # for 55.3%.
+  #
+  # It will not work if .type? is a protein, though, which is why it is
+  # part of this module, so that we can avoid calling it on a protein.
+  #
+  # Usage example:
+  #
+  #   x = Bioroebe::Sequence.new('AGCT'); x.gc_percentage
+  #
+  # ========================================================================= #
+  def gc_percentage
+    if is_a_protein? # Old safeguard in place - not necessarily needed anymore, but still retained.
+      e 'This method only works for RNA or DNA, not for a protein sequence.'
+    else # else comes the default assumption.
+      _ = string?
+      the_size = _.size
+      x = _.count('G')+_.count('C')
+      return (x * 100.0 / the_size)
+    end
+  end; alias gc_percent gc_percentage # === gc_percent
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  NucleotideModule.new(ARGV)
+end # nucleotide_module