bioroebe 0.10.80

data/lib/bioroebe/sequence/sequence.rb

@@ -0,0 +1,706 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Bioroebe::Sequence
+#
+# The code in this file will form a so-called sequence-object. It will keep
+# a nucleotide sequence or an aminoacid sequence (== protein).
+#
+# Additionally, it will carry information about the type of sequence
+# that is carried. This type can be queried via the .type? method.
+#
+# Several methods exist to return this nucleotide sequence when it
+# is necessary.
+#
+# To create a new Sequence object, try this:
+#
+#   seq = Bioroebe::Sequence.new('atgcatgcaaaa')
+#   seq.complement    # => "TACGTACGTTTT"
+#   seq.sequence?     # => "ATGCATGCAAAA"
+#   seq.composition?  # => {"A"=>6, "T"=>2, "G"=>2, "C"=>2}
+#   seq.gc_percentage # => 33.33
+#   seq.at_percentage # => 66.66666666666666
+#
+# =========================================================================== #
+# require 'bioroebe/sequence/sequence.rb'; < ::Bioroebe::Sequence
+# =========================================================================== #
+require 'bioroebe/raw_sequence/raw_sequence.rb'
+
+module Bioroebe
+
+class Sequence < ::Bioroebe::RawSequence
+
+  alias e puts
+
+  # ========================================================================= #
+  # === SHALL_WE_UPCASE
+  #
+  # This constant determines whether the given input at hand will be
+  # upcased or whether it will not.
+  #
+  # Note that the value :do_upcase implies true - so it is equivalent to
+  # setting it to true. In my opinion it reads nicer than true or false,
+  # so it will be retained as it is.
+  # ========================================================================= #
+  SHALL_WE_UPCASE = :do_upcase
+
+  # ========================================================================= #
+  # === REMOVE_INVALID_CHARACTERS
+  #
+  # If the following constant is set to true then invalid characters
+  # from the given input will be eliminated.
+  # ========================================================================= #
+  REMOVE_INVALID_CHARACTERS = true
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument given to the constructor (.new()) will become the
+  # sequence.
+  #
+  # Initialization example:
+  #
+  #   seq = Bioroebe::Sequence.new('ATTGCCG')
+  #
+  # ========================================================================= #
+  def initialize( # === Bioroebe::Sequence.new()
+      this_sequence = 'ATCG',
+      &block
+    )
+    reset
+    _ = this_sequence # Keep a copy - shorter to type.
+    # ===================================================================== #
+    # === Handle Hash as input next
+    # ===================================================================== #
+    if _.is_a? Hash
+      # ===================================================================== #
+      # === Handle :file
+      # ===================================================================== #
+      if _.has_key? :file
+        set_save_file(_.delete(:file))
+      end
+      # ===================================================================== #
+      # === Handle :desc
+      # ===================================================================== #
+      if _.has_key? :desc
+        set_description(_.delete(:desc))
+      end
+      # ===================================================================== #
+      # === Handle :alphabet
+      #
+      # Note that the "alphabet" is treated as synonymous to "type". Note
+      # that :type will also be checked.
+      # ===================================================================== #
+      if _.has_key? :alphabet
+        set_type(_.delete(:alphabet))
+      # ===================================================================== #
+      # === Handle :type
+      # ===================================================================== #
+      elsif _.has_key? :type
+        set_type(_.delete(:type))
+      # ===================================================================== #
+      # === Handle :aminoacid
+      # ===================================================================== #
+      elsif _.has_key? :aminoacid
+        set_type(_.delete(:aminoacid))
+      end
+      # ===================================================================== #
+      # === Handle :seq
+      # ===================================================================== #
+      if _.has_key? :seq
+        _ = _.delete :seq
+      # ===================================================================== #
+      # === Handle :sequence
+      # ===================================================================== #
+      elsif _.has_key? :sequence
+        _ = _.delete :sequence
+      end
+    end
+    # ======================================================================= #
+    # Next, set the main sequence that is to be used.
+    # ======================================================================= #
+    set_sequence(_)
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :is_DNA
+      # ===================================================================== #
+      when :is_DNA,
+           :is_dna
+        set_DNA_type
+      # ===================================================================== #
+      # === :aminoacid
+      # ===================================================================== #
+      when :aminoacid
+        set_protein_type
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :type
+    #
+    # The type can be :dna, :rna or :protein - or nil, which is the default.
+    # ======================================================================= #
+    @internal_hash[:type] = nil
+    # ======================================================================= #
+    # === :shall_we_upcase
+    # ======================================================================= #
+    @internal_hash[:shall_we_upcase] = SHALL_WE_UPCASE
+    # ======================================================================= #
+    # === :save_file
+    # ======================================================================= #
+    @internal_hash[:save_file] = nil
+    # ======================================================================= #
+    # Designate where a FASTA file may be stored.
+    # ======================================================================= #
+    set_save_file
+    # ======================================================================= #
+    # Initialize a default description next (to nil).
+    # ======================================================================= #
+    set_description
+    # ======================================================================= #
+    # Note that in the past, reset() used a call set_dna(), but this is
+    # no longer enabled by default. We will simply treat such a case as
+    # default in situations where it matters.
+    # ======================================================================= #
+  end
+
+  # ========================================================================= #
+  # === type?
+  #
+  # The type can be :dna, :rna or :protein. The default will be :dna.
+  # ========================================================================= #
+  def type?
+    @internal_hash[:type]
+  end; alias type type? # === type
+
+  # ========================================================================= #
+  # === to_regexp
+  #
+  # This method can be used to return a matching regexp-object.
+  # ========================================================================= #
+  def to_regexp
+    regex = ''.dup
+    _ = @sequence.chars
+    _.each {|this_nucleotide|
+      this_nucleotide.upcase!
+      case this_nucleotide
+      when 'A','T','C','G'
+        regex << this_nucleotide
+      when 'B'
+        regex << '[TGC]'
+      when 'D'
+        regex << '[ATG]'
+      when 'H'
+        regex << '[ATC]'
+      when 'K'
+        regex << '[TG]'
+      when 'M'
+        regex << '[AC]'
+      when 'N'
+        regex << '[ATGC]'
+      when 'R'
+        regex << '[AG]'
+      when 'S'
+        regex << '[GC]'
+      when 'V'
+        regex << '[AGC]'
+      when 'W'
+        regex << '[AT]'
+      when 'Y'
+        regex << '[TC]'
+      end
+    }
+    return Regexp.new(regex, Regexp::IGNORECASE)
+  end; alias to_regex to_regexp # === to_regex
+       alias to_re    to_regexp # === to_re
+
+  # ========================================================================= #
+  # === shall_we_upcase?
+  # ========================================================================= #
+  def shall_we_upcase?
+    @internal_hash[:shall_we_upcase]
+  end
+
+  # ========================================================================= #
+  # === description?
+  #
+  # Give us back the description of the sequence object at hand.
+  # ========================================================================= #
+  def description?
+    @internal_hash[:description]
+  end; alias desc? description? # === desc?
+
+  # ========================================================================= #
+  # === return_string_nucleotides_or_aminoacids
+  #
+  # This will either return the String "nucleotides" or "aminoacids".
+  #
+  # This functionality may be useful in downstream applications that
+  # try to display the correct terminology/word.
+  # ========================================================================= #
+  def return_string_nucleotides_or_aminoacids(
+      type = type?
+    )
+    case type
+    when :rna, :dna
+      'nucleotides'
+    when :protein
+      'aminoacids'
+    end
+  end; alias nucleotides_or_aminoacids? return_string_nucleotides_or_aminoacids # === nucleotides_or_aminoacids
+
+  # ========================================================================= #
+  # === n_uracil?
+  #
+  # Report how many Uracil can be found in the given String. This is more
+  # of an ad-hoc method, though.
+  # ========================================================================= #
+  def n_uracil?
+    @sequence.to_s.upcase.tr('T','U').count('U')
+  end
+
+  require 'bioroebe/toplevel_methods/file_and_directory_related_actions.rb'
+  # ========================================================================= #
+  # === save_sequence_to_this_file
+  #
+  # We save to a file but we are silent about this action, unless the
+  # directory does not exist.
+  # ========================================================================= #
+  def save_sequence_to_this_file(into)
+    what = sequence?
+    # ======================================================================= #
+    # === Must check whether the base directory exists
+    # ======================================================================= #
+    base_dir = File.dirname(into)
+    if File.exist? base_dir
+      ::Bioroebe.write_what_into(what, into)
+    else
+      e "No directory at #{base_dir} exists, thus we can not save "\
+        "the DNA sequence into a file."
+    end
+  end
+
+  # ========================================================================= #
+  # === sanitize_dataset
+  #
+  # This will sanitize the dataset, in particular for RNA and DNA.
+  # ========================================================================= #
+  def sanitize_dataset(
+      i = type?
+    )
+    case i
+    # ======================================================================= #
+    # === :protein
+    # ======================================================================= #
+    when :protein
+      # Do nothing in this case.
+    # ======================================================================= #
+    # === :dna
+    # ======================================================================= #
+    when :dna
+      # ===================================================================== #
+      # If we have DNA, all U must become T.
+      # ===================================================================== #
+      sequence?.tr!('U','T') if sequence?
+      # ===================================================================== #
+      # We also need to check for a constant.
+      # ===================================================================== #
+      if REMOVE_INVALID_CHARACTERS
+        @sequence = remove_invalid_entries_from_the_dna_sequence
+      end
+    # ======================================================================= #
+    # === :rna
+    #
+    # This entry point will replace all 'T' with a 'U'.
+    # ======================================================================= #
+    when :rna
+      # ===================================================================== #
+      # If we have RNA, all T must become U.
+      # ===================================================================== #
+      sequence?.tr!('T','U') if sequence?
+    end
+  end
+
+  # ========================================================================= #
+  # === set_type
+  #
+  # The type to use. By default, DNA.
+  # ========================================================================= #
+  def set_type(i = :dna)
+    i.downcase! if i.is_a? String
+    i = i.to_sym unless i.is_a? Symbol
+    @internal_hash[:type] = i # Can be :dna, :rna or :protein (or nil).
+    sanitize_rna if i == :rna
+  end; alias set_alphabet set_type # === set_alphabet
+       alias set_mode     set_type # === set_mode
+
+  # ========================================================================= #
+  # === sanitize_rna
+  #
+  # This method will convert all T into U.
+  # ========================================================================= #
+  def sanitize_rna
+    sanitize_dataset :rna
+  end
+
+  require 'bioroebe/toplevel_methods/log_directory.rb'
+  # ========================================================================= #
+  # === set_save_file
+  #
+  # Where to save any fasta file to etc..
+  #
+  # The default will be into a file called "default_sequence.fasta".
+  # ========================================================================= #
+  def set_save_file(
+      i = "#{Bioroebe.log_dir?}default_sequence.fasta"
+    )
+    @internal_hash[:save_file] = i
+  end
+
+  # ========================================================================= #
+  # === is_a_protein?
+  # ========================================================================= #
+  def is_a_protein?
+    @internal_hash[:type] == :protein
+  end; alias is_protein? is_a_protein? # === is_protein?
+
+  # ========================================================================= #
+  # === is_a_protein_now
+  #
+  # This will force the given sequence to "become" a protein - or be
+  # assumed to be a protein past this point.
+  # ========================================================================= #
+  def is_a_protein_now
+    @internal_hash[:type] = :protein
+  end
+
+  # ========================================================================= #
+  # === is_DNA?
+  # ========================================================================= #
+  def is_DNA?
+    @internal_hash[:type] == :dna
+  end; alias is_dna? is_DNA? # === is_dna?
+
+  # ========================================================================= #
+  # === is_RNA?
+  # ========================================================================= #
+  def is_RNA?
+    @internal_hash[:type] == :rna
+  end; alias is_rna? is_RNA? # === is_rna?
+
+  require 'bioroebe/toplevel_methods/infer.rb'
+  # ========================================================================= #
+  # === infer_type
+  # ========================================================================= #
+  def infer_type
+    set_type(
+      Bioroebe.infer_type_from_this_sequence(
+        sequence?
+      )
+    )
+  end
+
+  # ========================================================================= #
+  # === set_description
+  #
+  # Set a specific description for the given sequence object at hand.
+  #
+  # If it is a DNA sequence then we can "tag" it via a specific
+  # name. This may not be hugely necessary, but nonetheless the
+  # option is there. Proteins can be named as well, of course.
+  # ========================================================================= #
+  def set_description(i = nil)
+    @description = i
+  end; alias set_desc set_description # === set_desc
+       alias desc=    set_description # === desc=
+
+  # ========================================================================= #
+  # === to_genbank
+  #
+  # Convert into the genbank format.
+  #
+  # Usage example:
+  #
+  #   x = Bioroebe::Sequence.new('aaaatgggggggggggccccgtt'); y = x.to_genbank
+  #
+  # ========================================================================= #
+  def to_genbank
+    unless ::Bioroebe.const_defined?(:GenbankFlatFileFormatGenerator)
+      require 'bioroebe/genbank/genbank_flat_file_format_generator.rb'
+    end
+    _ = string?
+    result = Bioroebe::GenbankFlatFileFormatGenerator.new(_) { :be_quiet }.string?
+    return result
+  end
+
+  # ========================================================================= #
+  # === set_sequence
+  #
+  # This method sets the main sequence, aka DNA string or RNA string
+  # or protein string (aminoacids).
+  # ========================================================================= #
+  def set_sequence(
+      i,
+      upcase_downcase_or_make_no_modification = shall_we_upcase?
+    )
+    if i
+      # ===================================================================== #
+      # === Handle Arrays next:
+      # ===================================================================== #
+      if i.is_a? Array
+        i = i.join(' ').strip
+      end
+      # ===================================================================== #
+      # We need a String past this point.
+      # ===================================================================== #
+      i = i.to_s unless i.is_a? String
+      if i and !i.empty? and File.exist?(i)
+        i = File.read(i)
+      end
+      i = i.dup if i.frozen?
+      # ===================================================================== #
+      # Handle only numbers given to this method next. This will default
+      # to DNA-nucleotides though.
+      # ===================================================================== #
+      if i =~ /^\d+$/ and is_DNA?
+        i = n_random_dna(i)
+      end
+      case upcase_downcase_or_make_no_modification
+      # ===================================================================== #
+      # === :do_not_downcase
+      # ===================================================================== #
+      when :do_not_downcase
+        # Make no modification in this case.
+      # ===================================================================== #
+      # === :do_upcase
+      #
+      # This is also presently the default.
+      # ===================================================================== #
+      when :do_upcase,
+           :default
+        i.upcase!
+      # ===================================================================== #
+      # === :do_downcase
+      # ===================================================================== #
+      when :do_downcase
+        i.downcase!
+      end
+    end
+    @sequence = i.to_s.dup # .dup it to avoid having a frozen String.
+    sanitize_dataset
+  end; alias set_string        set_sequence # === set_string
+       alias set_input         set_sequence # === set_input
+       alias set_this_sequence set_sequence # === set_this_sequence
+
+  # ========================================================================= #
+  # === set_protein
+  # ========================================================================= #
+  def set_protein
+    set_type(:protein)
+  end; alias set_protein_type set_protein # === set_protein_type
+
+  # ========================================================================= #
+  # === set_rna
+  #
+  # Note that one alias name, the one called .convert_to_rna(), is a
+  # more explicit variant for "conversion" into RNA. It just changes
+  # one variable, though.
+  # ========================================================================= #
+  def set_rna
+    set_type(:rna)
+  end; alias set_rna_type   set_rna # === set_rna_type
+       alias convert_to_rna set_rna # === convert_to_rna
+
+  # ========================================================================= #
+  # === set_dna
+  # ========================================================================= #
+  def set_dna
+    set_type(:dna)
+  end; alias set_dna_type set_dna # === set_dna_type
+       alias set_DNA_type set_dna # === set_DNA_type
+       alias is_DNA_now   set_dna # === is_DNA_now
+
+  # ========================================================================= #
+  # === remove_invalid_entries_from_the_dna_sequence
+  # ========================================================================= #
+  def remove_invalid_entries_from_the_dna_sequence(i = sequence?)
+    return i.chars.select {|character|
+      DNA_NUCLEOTIDES.include? character.upcase
+    }.join
+  end
+
+  # ========================================================================= #
+  # === Bioroebe::Sequence.sequence_from_file
+  #
+  # This method can be used to read in a dataset from a file. The first
+  # argument to this method denotes that.
+  #
+  # Invocation examples:
+  #
+  #   x = Bioroebe::Sequence.sequence_from_file('/Depot/Temp/Bioroebe/vector_pBR322.fasta')
+  #   x = Bioroebe::Sequence.sequence_from_file('/home/x/DATA/PROGRAMMING_LANGUAGES/ruby/src/bioroebe/lib/bioroebe/data/alu_elements.fasta')
+  #
+  # ========================================================================= #
+  def self.sequence_from_file(this_file)
+    if File.exist? this_file
+      _ = ::Bioroebe::Sequence.new
+      dataset = File.readlines(this_file).map(&:chomp).reject {|line|
+        line.start_with? '#' # Remove ad-hoc comments from such files.
+      }
+      if dataset.first.start_with? '>' # Chop it off in this case.
+        dataset.shift # The first line will be removed, in this case.
+      end
+      sequence = dataset.join
+      _.set_sequence(sequence, :do_not_downcase)
+      return _
+    else
+      e "No file called `#{this_file}` exists."
+    end
+  end; self.instance_eval { alias from_this_file sequence_from_file } # === Bioroebe::Sequence.from_this_file
+
+  # ========================================================================= #
+  # === Bioroebe::Sequence[]
+  #
+  # Invocation example:
+  #
+  #   sequence = Bioroebe::Sequence['atgggtgggcccc']
+  #
+  # ========================================================================= #
+  def self.[](i)
+    new(i)
+  end
+
+end
+
+# =========================================================================== #
+# === Usage example
+#
+# x = Bioroebe::Seq.new('AGTACACTGGT')
+# =========================================================================== #
+Seq = Sequence # Add an "alias".
+
+# =========================================================================== #
+# === Bioroebe[]
+#
+# Assign a sequence through the [] method.
+#
+# Note that some aliases are allowed to this way; see the variants that
+# use self.instance_eval below this method definition.
+#
+# This method here could be compared to methods such as Integer(). Biopython
+# uses something similar, by the way. 
+#
+# For instance, you can do this too:
+#
+#   Bioroebe << 'ATT'
+#   x = Bioroebe['ATT']
+#   x = Bioroebe << 'ATT'
+#
+# =========================================================================== #
+def self.[](i = nil)
+  Bioroebe::Sequence.new(i)
+end; self.instance_eval { alias new      [] } # === Bioroebe.new
+     self.instance_eval { alias <<       [] } # === Bioroebe.<<
+     self.instance_eval { alias Sequence [] } # === Bioroebe.Sequence
+
+# =========================================================================== #
+# === Sequence()
+#
+# Note that Seq() also works, as an alias to this method.
+#
+# Invocation example:
+#
+#   require 'bioroebe'; include Bioroebe; x = Seq('ATCGTCGGAATAG')
+#
+# =========================================================================== #
+def Sequence(i)
+  Bioroebe::Sequence.new(i)
+end; alias Seq Sequence # === Bioroebe::Seq
+
+# =========================================================================== #
+# === @sequence
+#
+# Keep track of the main sequence in @sequence.
+# =========================================================================== #
+@sequence = ::Bioroebe::Sequence.new # Just a starter.
+
+# =========================================================================== #
+# === Bioroebe.sequence?
+#
+# Will return the sequence.
+# =========================================================================== #
+def self.sequence?
+  @sequence.sequence
+end
+
+# =========================================================================== #
+# === Bioroebe.create_new_sequence
+#
+# Create a new Bioroebe::Sequence object. It will also assign to
+# the @sequence module-level instance variable. 
+# =========================================================================== #
+def self.create_new_sequence(i = ARGV, &block)
+  @sequence = ::Bioroebe::Sequence.new(i, &block)
+end; self.instance_eval { alias sequence create_new_sequence } # === Bioroebe.sequence
+
+end
+
+# =========================================================================== #
+# === Bioroebe()
+#
+# Usage example for this:
+#
+#   require 'bioroebe'    
+#   seq = Bioroebe('AAAACCCGGT')
+#
+# =========================================================================== #
+def Bioroebe(i, &block)
+  ::Bioroebe.create_new_sequence(i, &block)
+end
+
+# =========================================================================== #
+# Next, we add some testing code:
+# =========================================================================== #
+if __FILE__ == $PROGRAM_NAME
+  require 'colours/autoinclude'
+  e; e orange('We will next test class Bioroebe::Sequence:'); e
+  seq = Bioroebe::Sequence.new('ATTGCGGCGTTAATTGCACACATT')
+  e 'The sequence of this object is: '+sfancy(seq.to_str)
+  e; e 'Next, showing some internal pp data:'; e
+  pp seq
+  e
+  e 'set_input next'
+  seq.set_input 'ATGCCCCAGATCCCCC'
+  e
+  e 'Does this sequence include another sequence such as "'+
+    Colours.steelblue('ATC')+'"? '+seq.include?('ATC').to_s
+  e
+  pp seq
+  e 'Changing the first position to "T" next.'
+  seq.first_position = 'T'
+  pp seq
+  e
+  seq.convert_to_rna
+  e
+  seq.desc = 'This is now RNA.'
+  pp seq
+  e
+  _ = Bioroebe('ATGC')
+  e _.to_s+' (Object type: '+
+    _.class.to_s+')'
+end # bioroebesequence