bioroebe 0.10.80

data/lib/bioroebe/pdb/parse_pdb_file.rb

@@ -0,0 +1,1086 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Bioroebe::ParsePdbFile
+#
+# This class will parse a .pdb file.
+#
+# The format for a .pdb file is described here:
+#
+#   https://www.wwpdb.org/documentation/file-format
+#   https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/tutorials/pdbintro.html
+#
+# The following short reference table can be used to get an overview of
+# the main attributes of this format:
+#
+#    Record Type	Data Provided by Record
+#
+#----------------|-------------------------------------------------------------|
+#    ATOM        | atomic coordinate record containing the X,Y,Z orthogonal Å  |
+#                | coordinates for atoms in standard residues (amino acids and |
+#                | nucleic acids). Each atom in the coordinate section is      |
+#                | identified by a sequential number in the entry file.        |
+#                | ATOM records for proteins are listed from amino to          |
+#                | carboxyl terminus.                                          |
+#----------------|-------------------------------------------------------------|
+#    HETATM      | atomic coordinate record containing the X,Y,Z orthogonal Å  |
+#                | coordinates for atoms in nonstandard residues. Nonstandard  |
+#                | residues include inhibitors, cofactors, ions, and solvent.  |
+#                | The only functional difference from ATOM records is that    |
+#                | HETATM residues are by default not connected to other       |
+#                | residues. Note that water residues should be in HETATM      |
+#                | records.                                                    |
+#----------------|-------------------------------------------------------------|
+#    TER         | indicates the end of a chain of residues. For example, a    |
+#                | hemoglobin molecule consists of four subunit chains that    |
+#                | are not connected. TER indicates the end of a chain and     |
+#                | prevents the display of a connection to the next chain.     |
+#----------------|-------------------------------------------------------------|
+#    HELIX       | indicates the location and type (right-handed alpha, etc.)  |
+#                | of helices. One record per helix.                           |
+#----------------|-------------------------------------------------------------|
+#    SHEET       | indicates the location, sense (anti-parallel, etc.) and     |
+#                | registration with respect to the previous strand in the     |
+#                | sheet (if any) of each strand in the model. One record      |
+#                | per strand.                                                 |
+#                |                                                             |
+#                | See also:                                                   |
+#                |                                                             |
+#                |    https://www.wwpdb.org/documentation/file-format-content/format23/sect5.html#SHEET
+#                |                                                             |
+#----------------|-------------------------------------------------------------|
+#    SSBOND      | defines disulfide bond linkages between cysteine residues.  |
+#----------------|-------------------------------------------------------------|
+#    KEYWDS      | contains some extra information about the given structure   |
+#----------------|-------------------------------------------------------------|
+#
+# Format explained in more detail:
+#
+#   COLUMNS      DATA TYPE       CONTENTS                            
+# ------------------------------------------------------------------------------
+#    1 -  6      Record name     "ATOM  "                                            
+#    7 - 11      Integer         Atom serial number.                   
+#   13 - 16      Atom            Atom name.                            
+#   17           Character       Alternate location indicator.         
+#   18 - 20      Residue name    Residue name.                         
+#   22           Character       Chain identifier.                     
+#   23 - 26      Integer         Residue sequence number.              
+#   27           AChar           Code for insertion of residues.       
+#   31 - 38      Real(8.3)       Orthogonal coordinates for X in Angstroms.                       
+#   39 - 46      Real(8.3)       Orthogonal coordinates for Y in Angstroms.                            
+#   47 - 54      Real(8.3)       Orthogonal coordinates for Z in Angstroms.                            
+#   55 - 60      Real(6.2)       Occupancy.                            
+#   61 - 66      Real(6.2)       Temperature factor (Default = 0.0).                   
+#   73 - 76      LString(4)      Segment identifier, left-justified.   
+#   77 - 78      LString(2)      Element symbol, right-justified.      
+#   79 - 80      LString(2)      Charge on the atom.
+#        
+# Example: 
+# 
+#          1         2         3         4         5         6         7         8
+# 12345678901234567890123456789012345678901234567890123456789012345678901234567890
+# ATOM    145  N   VAL A  25      32.433  16.336  57.540  1.00 11.92      A1   N
+# ATOM    146  CA  VAL A  25      31.132  16.439  58.160  1.00 11.85      A1   C
+# ATOM    147  C   VAL A  25      30.447  15.105  58.363  1.00 12.34      A1   C
+# ATOM    148  O   VAL A  25      29.520  15.059  59.174  1.00 15.65      A1   O
+# ATOM    149  CB AVAL A  25      30.385  17.437  57.230  0.28 13.88      A1   C
+# ATOM    150  CB BVAL A  25      30.166  17.399  57.373  0.72 15.41      A1   C
+# ATOM    151  CG1AVAL A  25      28.870  17.401  57.336  0.28 12.64      A1   C
+# ATOM    152  CG1BVAL A  25      30.805  18.788  57.449  0.72 15.11      A1   C
+# ATOM    153  CG2AVAL A  25      30.835  18.826  57.661  0.28 13.58      A1   C
+# ATOM    154  CG2BVAL A  25      29.909  16.996  55.922  0.72 13.25      A1   C
+#
+# Usage example:
+#
+#   Bioroebe::ParsePdbFile.new(ARGV)
+#
+# =========================================================================== #
+# If you need a sample .pdb file, have a look here:
+#
+#   https://gist.github.com/cstein/6699200
+#
+# For more information about the ATOM entry, have a look here:
+#
+#   https://zhanglab.ccmb.med.umich.edu/SSIPe/pdb_atom_format.html#ATOM
+#
+# =========================================================================== #
+# require 'bioroebe/pdb/parse_pdb_file.rb'
+# Bioroebe.return_aminoacid_sequence_from_this_pdb_file
+# =========================================================================== #
+require 'bioroebe/base/commandline_application/commandline_application.rb'
+
+module Bioroebe
+
+class ParsePdbFile < ::Bioroebe::CommandlineApplication # === Bioroebe::ParsePdbFile
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === DEFAULT_PDB_FILE
+  # ========================================================================= #
+  DEFAULT_PDB_FILE = "#{::Bioroebe.log_directory?}test.pdb"
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = DEFAULT_PDB_FILE,
+      run_already = true
+    )
+    reset
+    unless i.is_a? Array
+      i = [i].flatten.compact
+    end
+    set_commandline_arguments(
+      return_entries_with_two_leading_hyphens_from(i)
+    )
+    set_pdb_files(
+      return_entries_without_two_leading_hyphens(i)
+    )
+    # ======================================================================= #
+    # === Handle blocks
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_silent
+      #
+      # Invocation example for this entry point:
+      #
+      #   Bioroebe::ParsePdbFile.new(ARGV) { :be_silent }
+      #
+      # ===================================================================== #
+      when :be_silent
+        set_be_silent
+      end
+    end
+    case run_already
+    when :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+    # ======================================================================= #
+    # === @do_create_a_fasta_file
+    #
+    # This variable has to exist outside of the method call
+    # reset_internal_variables() as it would otherwise
+    # ignore every commandline argument passed in by the
+    # user.
+    # ======================================================================= #
+    @do_create_a_fasta_file = false
+    # ======================================================================= #
+    # === @x_coordinates
+    # ======================================================================= #
+    @x_coordinates = []
+    # ======================================================================= #
+    # === @y_coordinates
+    # ======================================================================= #
+    @y_coordinates = []
+    # ======================================================================= #
+    # === @z_coordinates
+    # ======================================================================= #
+    @z_coordinates = []
+    # ======================================================================= #
+    # All internal variables can be reset through this method.    
+    # ======================================================================= #
+    reset_internal_variables
+  end
+
+  # ========================================================================= #
+  # === reset_internal_variables
+  # ========================================================================= #
+  def reset_internal_variables
+    self.header = ''
+    self.title  = ''
+    # ======================================================================= #
+    # === @body
+    # ======================================================================= #
+    @body  = nil
+    # ======================================================================= #
+    # === @taxid
+    # ======================================================================= #
+    @taxid = nil
+    # ======================================================================= #
+    # === @n_chains_are_in_this_atom
+    # ======================================================================= #
+    @n_chains_are_in_this_atom = 0
+    # ======================================================================= #
+    # === @alpha_helices
+    # ======================================================================= #
+    @alpha_helices = []
+    # ======================================================================= #
+    # === @beta_sheets
+    # ======================================================================= #
+    @beta_sheets   = []
+    # ======================================================================= #
+    # === @does_the_file_exist
+    # ======================================================================= #
+    @does_the_file_exist = false
+    # ======================================================================= #
+    # === @name_of_the_species
+    # ======================================================================= #
+    @name_of_the_species = nil
+    # ======================================================================= #
+    # === @taxid_of_the_species
+    # ======================================================================= #
+    @taxid_of_the_species = nil
+    # ======================================================================= #
+    # === @report_the_aminoacid_sequence
+    # ======================================================================= #
+    @report_the_aminoacid_sequence = true
+    # ======================================================================= #
+    # === @keywords
+    # ======================================================================= #
+    @keywords = nil
+  end
+
+  # ========================================================================= #
+  # === keywords?
+  # ========================================================================= #
+  def keywords?
+    @keywords
+  end; alias keywords keywords? # === keywords
+
+  # ========================================================================= #
+  # === set_pdb_files
+  #
+  # We will keep this as an Array.
+  # ========================================================================= #
+  def set_pdb_files(
+      i = DEFAULT_PDB_FILE
+    )
+    i = [i] unless i.is_a? Array
+    i.map! {|entry|
+      entry = entry.to_s.dup # To avoid frozen-Strings.
+      case entry
+      # ===================================================================== #
+      # === :1fat
+      # ===================================================================== #
+      when ':1fat'
+        entry = "#{::Bioroebe.project_base_directory?}data/1fat.pdb"
+      end
+      # ===================================================================== #
+      # The user may input a String such as "1NR6", but may not want to
+      # input the longer "1NR6.pdb". In that case, if such a .pdb file
+      # exists, we will use that as path instead.
+      # ===================================================================== #
+      if File.exist?("#{entry}.pdb") and !File.exist?(entry)
+        entry << '.pdb'
+      end
+      File.absolute_path(entry) # We require the full local path to the file at hand.
+    }
+    @pdb_files = i
+  end
+
+  # ========================================================================= #
+  # === try_to_determine_the_taxid_from_this_input
+  #
+  # This method will attempt to determine the taxid entry.
+  # ========================================================================= #
+  def try_to_determine_the_taxid_from_this_input(i)
+    if i.is_a? Array
+      # ===================================================================== #
+      # We will try to find entries like this:
+      #
+      #   SOURCE   3 ORGANISM_TAXID: 300852;
+      #
+      # ===================================================================== #
+      _ = i.select {|line| line.include? 'ORGANISM_TAXID:' }
+      unless _.empty?
+        @taxid = _.first.strip.delete(';').split(' ').last
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === taxid?
+  # ========================================================================= #
+  def taxid?
+    @taxid
+  end
+
+  # ========================================================================= #
+  # === body?
+  # ========================================================================= #
+  def body?
+    @body
+  end
+
+  # ========================================================================= #
+  # === input_sequence?
+  #
+  # This will return a String.
+  # ========================================================================= #
+  def input_sequence?
+    _ = @body
+    if _.is_a? Array
+      _ = _.join(N)
+    end
+    _
+  end
+
+  # ========================================================================= #
+  # === set_body
+  #
+  # This method keeps track of the main "body" of the .pdb file at hand.
+  # ========================================================================= #
+  def set_body(i)
+    @body = i
+  end; alias body= set_body # === body?
+
+  # ========================================================================= #
+  # === set_header
+  #
+  # The header may have an entry such as:
+  #
+  #   HEADER    RIBOSOMAL PROTEIN/RNA                   16-APR-10   3IYQ
+  #
+  # ========================================================================= #
+  def set_header(i)
+    if i
+      if i.is_a? Array
+        i = i.first
+        return if i.nil? # Can't work with nil-entries.
+      end
+      i = i.dup if i.frozen?
+      # ===================================================================== #
+      # We do a bit sanitizing here.
+      # ===================================================================== #
+      if i.include?('HEADER')
+        i.sub!(/HEADER/,'')
+      end
+      i.strip!
+      if i.include? '   '
+        i = i.split('  ').map(&:strip).first
+      end
+    end
+    @header = i
+  end; alias header= set_header # === header?
+
+  # ========================================================================= #
+  # === string?
+  # ========================================================================= #
+  def string?
+    @body
+  end; alias data? string? # === data?
+
+  # ========================================================================= #
+  # === n_atoms?
+  #
+  # Returns how many ATOM entries we have in this .pdb file.
+  # ========================================================================= #
+  def n_atoms?(i = data?)
+    i.select {|entry| entry.start_with? 'ATOM' }.size if i
+  end; alias n_atom_entries? n_atoms? # === n_atom_entries?
+
+  # ========================================================================= #
+  # === title?
+  # ========================================================================= #
+  def title?
+    @title
+  end; alias title title? # === title
+
+  # ========================================================================= #
+  # === header?
+  # ========================================================================= #
+  def header?
+    @header
+  end; alias header header? # === header
+
+  # ========================================================================= #
+  # === report_n_atoms
+  # ========================================================================= #
+  def report_n_atoms
+    if be_verbose?
+      e "#{sfancy(n_atoms?.to_s)}#{rev} ATOM entries were found "\
+        "being part of the file at"
+      e "`#{sfile(main_file?)}#{rev}`."
+    end
+  end
+
+  # ========================================================================= #
+  # === readlines_from_this_file
+  # ========================================================================= #
+  def readlines_from_this_file(file)
+    File.readlines(file)
+  end
+
+  # ========================================================================= #
+  # === set_header_title_and_body
+  #
+  # The input to this method should be an Array.
+  # ========================================================================= #
+  def set_header_title_and_body(dataset)
+    set_header(
+      dataset.select {|entry| entry.include? 'HEADER' }
+    )
+    self.title = dataset.select {|entry| entry.include? 'TITLE'  }
+    set_body(dataset)
+  end
+
+  # ========================================================================= #
+  # === try_to_determine_the_alpha_helices_in_this_protein
+  # ========================================================================= #
+  def try_to_determine_the_alpha_helices_in_this_protein(i)
+    if i.is_a? Array
+      selection = i.select {|line| line.start_with? 'HELIX  ' }
+      @alpha_helices = selection
+    end
+  end
+
+  # ========================================================================= #
+  # === n_alpha_helices?
+  # ========================================================================= #
+  def n_alpha_helices?
+    @alpha_helices.size
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_alpha_helices_that_were_found
+  # ========================================================================= #
+  def consider_reporting_alpha_helices_that_were_found(
+      i = @alpha_helices
+    )
+    unless i.empty?
+      if be_verbose?
+        erev "This protein contains "\
+             "#{slateblue(i.size.to_s)}#{rev} alpha-helices."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_beta_sheet_that_were_found
+  # ========================================================================= #
+  def consider_reporting_beta_sheet_that_were_found(i = @beta_sheets)
+    unless i.empty?
+      e "This protein contains #{slateblue(i.size.to_s)}#{rev} beta-sheets."
+    end
+  end
+
+  # ========================================================================= #
+  # === n_aminoacids?
+  # ========================================================================= #
+  def n_aminoacids?
+    @aminoacid_sequence.size if @aminoacid_sequence
+  end
+
+  # ========================================================================= #
+  # === silently_determine_the_aminoacid_sequence
+  #
+  # This method is probably not quite correct, as it does not take into
+  # consideration that there may be a succession of aminoacids.
+  # ========================================================================= #
+  def silently_determine_the_aminoacid_sequence(i)
+    this_aminoacid_sequence = ''.dup
+    selection = i.select {|line| line.start_with?('ATOM   ') }
+    last_number_of_aminoacid = 0
+    selection.each {|line, index|
+      line.strip!
+      # ===================================================================== #
+      # The line may look like this:
+      #
+      #   ATOM   69  CG2 THR A   8    23.165  11.137  48.942  1.00 30.40  C
+      #
+      # Each atom in the coordinate section is identified by a sequential
+      # number in the entry file. The entry at position 5, seen below,
+      # identifies the aminoacid there.
+      # ===================================================================== #
+      #     0    1   2    3  4   5     6       7        8     9     10    11
+      # ===================================================================== #
+      splitted = line.split(' ').map(&:strip).map {|entry| entry.squeeze(' ') }
+      @x_coordinates << splitted[6].to_f
+      @y_coordinates << splitted[7].to_f
+      @z_coordinates << splitted[8].to_f
+      this_aminoacid = three_to_one(splitted[3])
+      number_of_this_aminoacid = splitted[5].to_i
+      # ===================================================================== #
+      # Entries may look like this:
+      #
+      #   ATOM    490  HZ3 LYS A  70     4.674  -0.770  -3.751  1.00  2.07   H
+      #   ATOM    491  N   LYS A  71     8.012   0.034   2.745  1.00  0.74   N
+      #
+      # ===================================================================== #
+      if number_of_this_aminoacid > last_number_of_aminoacid
+        this_aminoacid_sequence << this_aminoacid
+        last_number_of_aminoacid = number_of_this_aminoacid
+      end
+    }
+    @aminoacid_sequence = this_aminoacid_sequence
+  end
+
+  # ========================================================================= #
+  # === aminoacid_sequence?
+  # ========================================================================= #
+  def aminoacid_sequence?
+    @aminoacid_sequence
+  end
+
+  # ========================================================================= #
+  # === calculate_the_distance_between_two_points
+  #
+  # Pass in two arrays to this method.
+  # ========================================================================= #
+  def calculate_the_distance_between_two_points(p1, p2)
+    a = (p2[0] - p1[0]) ** 2
+    b = (p2[1] - p1[1]) ** 2
+    c = (p2[2] - p1[2]) ** 2
+    return Math.sqrt(a+b+c)
+  end
+
+  # ========================================================================= #
+  # === check_whether_this_pdb_sequence_contains_dna
+  # ========================================================================= #
+  def check_whether_this_pdb_sequence_contains_dna
+    _ = input_sequence?
+    if _.include? 'MOLECULE: DNA'
+      erev 'This protein sequence contains at the least one DNA strand.'
+      sequence = _.scan(/ MOLECULE: DNA(.+)$/).flatten
+      if sequence
+        sequence = sequence.first.to_s.strip if sequence.respond_to? :first
+        # =================================================================== #
+        # This may look like this:
+        #
+        #   "(5'-D(*CP*GP*CP*GP*AP*AP*TP*TP*CP*GP*CP*G)-3');"
+        #
+        # =================================================================== #
+        sequence = sequence.tr('-','').delete("'D(P*);53")
+        result = ('This DNA sequence is '+colourize_dna(sequence)+rev+'.').dup
+        # =================================================================== #
+        # Check whether it is a palindrome.
+        # =================================================================== #
+        if is_this_sequence_a_palindrome? sequence
+          result << rev+' It is a palindrome.'
+        else
+          result << rev+' It is NOT a palindrome.'
+        end
+        erev result
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === try_to_determine_the_beta_sheets_in_this_protein
+  #
+  # Beta-sheets begin with the word 'SHEET  '.
+  # ========================================================================= #
+  def try_to_determine_the_beta_sheets_in_this_protein(i)
+    if i.is_a? Array
+      selection = i.select {|line| line.start_with? 'SHEET  ' }
+      @beta_sheets = selection
+    end
+  end
+
+  # ========================================================================= #
+  # === return_all_ATOM_entries
+  # ========================================================================= #
+  def return_all_ATOM_entries
+    @body.select {|entry| entry.start_with? 'ATOM  ' }
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_how_many_chains_are_in_this_structure
+  #
+  # A better way to report how many chains are in a structure
+  # is via:
+  #
+  #   COMPND   3 CHAIN: A, B;
+  #
+  # ========================================================================= #
+  def consider_reporting_how_many_chains_are_in_this_structure
+    # _ = return_all_ATOM_entries.max {|line|
+    #   line.split(' ')[1].to_i
+    # }
+    # # ===================================================================== #
+    # # The entry may look like this:
+    # #
+    # #   "ATOM  52643  N   LYS N 393      27.402 -53.192  44.13"
+    # #
+    # # ===================================================================== #
+    # _ = convert_this_alphabet_character_to_number(
+    #   _.split(' ')[2]
+    # )
+    selection = @body.select {|entry|
+      entry.include? 'COMPND  ' and entry.include? 'CHAIN: '
+    }
+    # ======================================================================= #
+    # Examples:
+    #
+    #   ["COMPND   3 CHAIN: A, B, C, D, E, F, G, H, I, J, K, L, M, N;                     \n",
+    #    "COMPND   8 CHAIN: O, P, Q, R, S, T, U;                                          \n"]
+    #
+    # ======================================================================= #
+    _ = selection.join(' ')
+    use_this_regex = /([A-Z])(,|;)/
+    scanned = _.scan(use_this_regex).map {|inner_array| inner_array[0].ord }
+    unless scanned.empty?
+      max = scanned.max - 64 # -64 because A is 65 and it is the start.
+      if be_verbose?
+        erev "There are #{steelblue(max)}#{rev} chains in this molecule."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === convert_this_alphabet_character_to_number
+  #
+  # The input of "A" would mean "1".
+  # ========================================================================= #
+  def convert_this_alphabet_character_to_number(i)
+    (i.ord - 64)
+  end
+
+  # ========================================================================= #
+  # === try_to_report_the_organism_at_hand
+  #
+  # This method will try to extract the organism's name.
+  #
+  # This entry may look like this:
+  #
+  #   SOURCE   2 ORGANISM_SCIENTIFIC: SQUALUS ACANTHIAS;
+  #   
+  # ========================================================================= #
+  def try_to_report_the_organism_at_hand(i = @body)
+    if i.is_a?(Array) and !i.empty?
+      # ===================================================================== #
+      # === ORGANISM_SCIENTIFIC
+      # ===================================================================== #
+      _ = i.select {|line| line.include? 'ORGANISM_SCIENTIFIC:' }
+      if _
+        first_element = _.first
+        if first_element
+          first_element.strip!
+          @name_of_the_species = first_element.split(':').last.delete(';').strip
+        end
+      end
+      # ===================================================================== #
+      # === ORGANISM_TAXID
+      #
+      # Next try to find out the taxid number of the organism at hand.
+      # ===================================================================== #
+      _ = i.select {|line| line.include? ' ORGANISM_TAXID: ' }
+      if _
+        first_element = _.first
+        if first_element
+          first_element.strip!
+          @taxid_of_the_species = first_element.split(':').last.delete(';').strip
+        end
+      end
+      if be_verbose? and @name_of_the_species
+        report_extra_information_about_the_species_at_hand
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === name_of_the_species?
+  # ========================================================================= #
+  def name_of_the_species?
+    @name_of_the_species
+  end
+
+  # ========================================================================= #
+  # === report_extra_information_about_the_species_at_hand
+  # ========================================================================= #
+  def report_extra_information_about_the_species_at_hand
+    result = ''.dup
+    result << 'The name of the organism (Entry: '+
+               steelblue('ORGANISM_SCIENTIFIC')+
+               rev+
+               ') is'+N
+    result << '`'+orange(name_of_the_species?)+rev+'`.'
+    if @taxid_of_the_species
+      organism_common = organism_common?.to_s
+      if organism_common and !organism_common.empty?
+        result << rev+' (Taxid: '+
+                  steelblue(@taxid_of_the_species.to_s)+
+                  rev+'; '+
+                  seagreen(
+                    organism_common
+                  )+rev+')'
+      end
+    end
+    erev result
+  end
+
+  # ========================================================================= #
+  # === organism_common?
+  # ========================================================================= #
+  def organism_common?
+    if @body
+      _ = @body.join(N).scan(/ORGANISM_COMMON: (.+);/).flatten.uniq
+      if _ and _.is_a?(Array)
+        _ = _.first.to_s
+      end
+      return _
+    end
+  end
+
+  # ========================================================================= #
+  # === process_each_pdb_file
+  #
+  # This method is the main powerhorse method of this class.
+  # ========================================================================= #
+  def process_each_pdb_file
+    @pdb_files.each {|file|
+      if File.exist?(file) and File.file?(file)
+        reset_internal_variables # Reset the internal variables here.
+        @does_the_file_exist = true
+        set_this_file(file)
+        dataset = readlines_from_this_file(file)
+        if dataset.any? {|line| line.include? 'KEYWDS' }
+          set_keywords(dataset)
+        end
+        set_header_title_and_body(dataset)
+        analyze_the_dataset
+        consider_creating_a_fasta_file
+      else
+        opnn; erev "No file at `#{sfile(file)}#{rev}` could be found."
+        @does_the_file_exist = false
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === taxid_of_the_species?
+  # ========================================================================= #
+  def taxid_of_the_species?
+    @taxid_of_the_species
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = @commandline_arguments
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i
+      # ===================================================================== #
+      # === parsedb 2HI4.pdb --no-colours
+      # ===================================================================== #
+      when /^-?-?no(-|_)?colou?rs$/i
+        disable_colours
+      # ===================================================================== #
+      # === parsedb 2HI4.pdb --create-fasta-file
+      # ===================================================================== #
+      when /^-?-?create(-|_)?fasta(-|_)?file$/i
+        @do_create_a_fasta_file = true
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === return_short_filename
+  # ========================================================================= #
+  def return_short_filename
+    File.basename(@this_file)
+  end
+
+  # ========================================================================= #
+  # === consider_creating_a_fasta_file
+  # ========================================================================= #
+  def consider_creating_a_fasta_file
+    if @do_create_a_fasta_file
+      what = aminoacid_sequence?
+      into = return_short_filename.sub(/\.pdb$/,'')+'.fasta'
+      into = File.absolute_path(into)
+      erev 'Storing into the file `'+sfile(into)+rev+'`.'
+      write_what_into(what, into)
+    end
+  end
+
+  # ========================================================================= #
+  # === set_this_file
+  # ========================================================================= #
+  def set_this_file(i)
+    @this_file = i
+  end
+
+  # ========================================================================= #
+  # === main_file?
+  # ========================================================================= #
+  def main_file?
+    @this_file
+  end; alias return_filename main_file? # === return_filename
+
+  # ========================================================================= #
+  # === try_to_determine_the_max_distance_between_the_atoms_in_this_protein?
+  # ========================================================================= #
+  def try_to_determine_the_max_distance_between_the_atoms_in_this_protein?(
+      array = @body
+    )
+    max_value = max_distance?(array)
+    if be_verbose?
+      erev 'The maximum difference between the atoms is '+
+           sfancy(max_value.to_s)+rev
+    end
+  end; alias try_to_determine_the_max_distance_between_the_atoms_in_this_protein try_to_determine_the_max_distance_between_the_atoms_in_this_protein? # === try_to_determine_the_max_distance_between_the_atoms_in_this_protein
+
+  # ========================================================================= #
+  # === max_distance?
+  # ========================================================================= #
+  def max_distance?(
+      array = @body
+    )
+    return if array.nil? or array.empty?
+    # ======================================================================= #
+    # ["ATOM    1  N   MET A  41       1.177 -10.035  -3.493  1.00  2.04   N",
+    #  "ATOM    2  CA  MET A  41       0.292  -8.839  -3.377  1.00  1.55   C"]
+    # ======================================================================= #
+    max_value = 0
+    modified_array = array.map {|line|
+      splitted = line.split(' ')
+      x = splitted[6].to_f
+      y = splitted[7].to_f
+      z = splitted[8].to_f
+      [x,y,z]
+    }
+    # ======================================================================= #
+    # [1.177, -10.035, -3.493]
+    # [0.292, -8.839, -3.377]
+    # ======================================================================= #
+    modified_array.each_with_index {|entry, index| index += 1
+      if index == modified_array.size
+        index = 0
+      end
+      array1 = entry
+      array2 = modified_array[index]
+      result = calculate_the_distance_between_two_points(array1, array2)
+      if result > max_value
+        max_value = result
+      end
+    }
+    return max_value
+  end
+
+  # ========================================================================= #
+  # === title?
+  # ========================================================================= #
+  def title=(i)
+    if i.is_a? Array
+      i.map!(&:chomp)
+      i.map!(&:strip)
+    end
+    @title = i
+  end; alias set_title title= # === set_title
+
+  # ========================================================================= #
+  # === calculate_the_centroid_position
+  #
+  # This method will calculate the centroid aka the "average position
+  # of the atoms" in that .pdb file. Currently this will only 
+  # assume that each atom is the same, but in reality we should also
+  # include the weight of the atom at hand - this is currently not
+  # implemented via this method, though.
+  #
+  # If this is ever improved, we need to include the weight of the
+  # corresponding atom as well.
+  # ========================================================================= #
+  def calculate_the_centroid_position
+    n_atoms = n_atoms?.to_i
+    if n_atoms > 0
+      x_average = @x_coordinates.sum / n_atoms.to_f
+      y_average = @y_coordinates.sum / n_atoms.to_f
+      z_average = @z_coordinates.sum / n_atoms.to_f
+    else
+      x_average = y_average = z_average = 0
+    end
+    array = [x_average, y_average, z_average]
+    return array
+  end; alias calculate_centroid calculate_the_centroid_position # === calculate_centroid
+
+  # ========================================================================= #
+  # === report_header
+  #
+  # This will also report the filename.
+  # ========================================================================= #
+  def report_header(
+      of_this_file = @this_file
+    )
+    if be_verbose?
+      _ = return_short_filename
+      e orange(header?)+rev+
+        ' (File: '+
+        steelblue(_)+
+        rev+'; Filesize: '+
+        (File.size(of_this_file) / 1024).to_s+
+        'kb'+')'+rev
+    end
+  end
+
+  # ========================================================================= #
+  # === analyze_the_dataset
+  #
+  # This method is the "powerhorse" of this class.
+  # ========================================================================= #
+  def analyze_the_dataset(
+      body = @body
+    )
+    if @does_the_file_exist
+      report_header
+      try_to_report_the_organism_at_hand(body)
+      report_n_atoms
+      check_whether_this_pdb_sequence_contains_dna
+      silently_determine_the_aminoacid_sequence(body)
+      consider_reporting_the_aminoacid_sequence
+      consider_reporting_the_number_of_individual_aminoacids
+      consider_reporting_the_number_of_residues
+      # ===================================================================== #
+      # Try to obtain the taxid.
+      # ===================================================================== #
+      try_to_determine_the_taxid_from_this_input(body)
+      try_to_determine_the_alpha_helices_in_this_protein(body)
+      consider_reporting_alpha_helices_that_were_found
+      try_to_determine_the_beta_sheets_in_this_protein(body)
+      try_to_determine_the_max_distance_between_the_atoms_in_this_protein(body)
+      consider_reporting_beta_sheet_that_were_found
+      consider_reporting_how_many_chains_are_in_this_structure
+      consider_reporting_the_keywords
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_the_keywords
+  #
+  # This method will report the discovered keyword entries in the given
+  # .pdb file at hand (if this .pdb file contains these keywords entries
+  # that is).
+  # ========================================================================= #
+  def consider_reporting_the_keywords(
+      keywords = keywords?
+    )
+    if keywords
+      erev "The keywords are: #{steelblue(keywords)}"
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_the_number_of_residues
+  # ========================================================================= #
+  def consider_reporting_the_number_of_residues
+    if @report_the_aminoacid_sequence and be_verbose?
+      erev 'Total no:of residues - '+steelblue(@aminoacid_sequence.size.to_s)
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_the_number_of_individual_aminoacids
+  # ========================================================================= #
+  def consider_reporting_the_number_of_individual_aminoacids
+    if @report_the_aminoacid_sequence and be_verbose?
+      hash = @aminoacid_sequence.each_char.tally
+      hash.each_pair {|aminoacid_one_letter, n_occurrences|
+        erev 'Total no:of '+
+              rev+
+              lightgreen(::Bioroebe.one_to_three(aminoacid_one_letter).upcase)+
+              rev+
+              ' - '+
+              steelblue(n_occurrences.to_s)
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === set_keywords
+  # ========================================================================= #
+  def set_keywords(i)
+    if i.is_a? Array
+      i.flatten!
+      selection = i.select {|entry| entry.include? 'KEYWDS' }
+      i = selection.first
+    end
+    @keywords = i.to_s.strip
+  end; alias keywords= set_keywords # === keywords=
+
+  # ========================================================================= #
+  # === consider_reporting_the_aminoacid_sequence
+  #
+  # This method will typically display the aminoacid sequence at hand.
+  # ========================================================================= #
+  def consider_reporting_the_aminoacid_sequence
+    if @report_the_aminoacid_sequence and be_verbose?
+      _ = @aminoacid_sequence
+      erev 'The aminoacid sequence ('+
+        steelblue(_.size.to_s)+rev+
+        ' aminoacids) is:'
+      # erev '  '+colourize_this_aminoacid_sequence(_) # <- We could colourize it.
+      erev "  #{steelblue(_)}"
+    end
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu
+    process_each_pdb_file
+    if be_verbose?
+      erev 'The centered position is at: '+
+           steelblue(
+             calculate_the_centroid_position.join(', ')
+           )
+    end
+  end
+
+end
+
+# =========================================================================== #
+# === Bioroebe.parse_pdb_file
+# =========================================================================== #
+def self.parse_pdb_file(i = ARGV)
+  Bioroebe::ParsePdbFile.new(i)
+end
+
+# =========================================================================== #
+# === Bioroebe.return_aminoacid_sequence_from_this_pdb_file
+#
+# This variant will (silently) return the aminoacid sequence. The
+# input must be a file that exists locally; if you already have
+# a String that you wish to just parse, use the method defined
+# below instead.
+#
+# Invocation example:
+#
+#   Bioroebe.return_aminoacid_sequence_from_this_pdb_file "1VII.pdb" # => "MLSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF"
+#
+# =========================================================================== #
+def self.return_aminoacid_sequence_from_this_pdb_file(i = ARGV)
+  Bioroebe::ParsePdbFile.new(i) { :be_silent }.aminoacid_sequence?
+end
+
+# =========================================================================== #
+# === Bioroebe.return_aminoacid_sequence_from_this_string
+# =========================================================================== #
+def self.return_aminoacid_sequence_from_this_string(i = ARGV)
+  _ = Bioroebe::ParsePdbFile.new(i, :do_not_run_yet) { :be_silent }
+  dataset = i.split("\n")
+  _.set_header_title_and_body(dataset)
+  _.aminoacid_sequence?
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  require 'colours/autoinclude'
+  _ = Bioroebe::ParsePdbFile.new(ARGV)
+end # pdbfile test.pdb
+    # pdbfile :1fat