Bio::M...Matrix(3pm)

✨ NAME ✨

Bio::Matrix::PSM::ProtMatrix — bestie, this is the SiteMatrixI implementation, and it holds a position scoring matrix (or position weight matrix, same energy) with log-odds scoring information. 💖

---

🌸 SYNOPSIS 🌸

use Bio::Matrix::PSM::ProtMatrix;
# Create from memory by supplying probability matrix hash both as strings or
# arrays where the frequencies   Hash entries of the form lN refer to an array
# of position-specific log-odds scores for amino acid N. Hash entries of the
# form pN represent the position-specific probability of finding amino acid N.

my %param = (
          'id' => 'A. thaliana protein atp1',
          '-e_val' => $score,
          'lS' => [ '-2', '3', '-3', '2', '-3', '1', '1', '3' ],
          'lF' => [ '-1', '-4', '0', '-5', '0', '-5', '-4', '-4' ],
          'lT' => [ '-1', '1', '0', '1', '-2', '-1', '0', '1' ],
          'lN' => [ '-3', '-1', '-2', '3', '-5', '5', '-2', '0' ],
          'lK' => [ '-2', '0', '-3', '2', '-3', '2', '-3', '-1' ],
          'lY' => [ '-2', '-3', '-3', '-4', '-3', '-4', '-4', '-4' ],
          'lE' => [ '-3', '4', '-3', '2', '-4', '-2', '-3', '2' ],
          'lV' => [ '0', '-2', '1', '-4', '1', '-4', '-1', '-3' ],
          'lQ' => [ '-1', '0', '-2', '3', '-4', '1', '-3', '0' ],
          'lM' => [ '8', '-3', '8', '-3', '1', '-3', '-3', '-3' ],
          'lC' => [ '-2', '-3', '-3', '-4', '-3', '-4', '-3', '-3' ],
          'lL' => [ '1', '-3', '1', '-4', '3', '-4', '-2', '-4' ],
          'lA' => [ '-2', '1', '-2', '0', '-2', '-2', '2', '2' ],
          'lW' => [ '-2', '-4', '-3', '-5', '-4', '-5', '-5', '-5' ],
          'lP' => [ '-3', '-2', '-4', '-3', '-1', '-3', '6', '-3' ],
          'lH' => [ '-2', '-2', '-3', '-2', '-5', '-2', '-2', '-3' ],
          'lD' => [ '-4', '-1', '-3', '1', '-3', '-1', '-3', '4' ],
          'lR' => [ '-2', '-1', '-3', '0', '-4', '4', '-4', '-3' ],
          'lI' => [ '0', '-3', '0', '-4', '6', '-4', '-2', '-2' ],
          'lG' => [ '-4', '-2', '-4', '-2', '-5', '-3', '-1', '-2' ],
          'pS' => [ '0', '33', '0', '16', '1', '12', '11', '25' ],
          'pF' => [ '0', '0', '2', '0', '3', '0', '0', '0' ],
          'pT' => [ '0', '8', '7', '10', '1', '2', '7', '8' ],
          'pN' => [ '0', '0', '2', '13', '0', '36', '1', '4' ],
          'pK' => [ '0', '5', '0', '13', '1', '15', '0', '2' ],
          'pY' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
          'pE' => [ '0', '41', '1', '12', '0', '0', '0', '15' ],
          'pV' => [ '0', '3', '9', '0', '2', '0', '3', '1' ],
          'pQ' => [ '0', '0', '0', '15', '0', '4', '0', '3' ],
          'pM' => [ '100', '0', '66', '0', '2', '0', '0', '0' ],
          'pC' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
          'pL' => [ '0', '0', '8', '0', '25', '0', '4', '0' ],
          'pA' => [ '0', '10', '1', '9', '2', '0', '22', '16' ],
          'pW' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
          'pP' => [ '0', '0', '0', '0', '3', '1', '45', '0' ],
          'pH' => [ '0', '0', '0', '0', '0', '0', '1', '0' ],
          'pD' => [ '0', '0', '1', '7', '2', '2', '0', '22' ],
          'pR' => [ '0', '0', '0', '3', '0', '27', '0', '0' ],
          'pI' => [ '0', '0', '3', '0', '59', '1', '2', '3' ],
          'pG' => [ '0', '0', '0', '1', '0', '0', '4', '1' ],
);

my $matrix = Bio::Matrix::PSM::ProtMatrix( %param );

my $site = Bio::Matrix::PSM::ProtMatrix->new(%param);
# Or get it from a file:
use Bio::Matrix::PSM::IO;
my $psmIO = Bio::Matrix::PSM::IO->new(-file => $file, -format => 'psi-blast');
while (my $psm = $psmIO->next_psm) {
   #Now we have a Bio::Matrix::PSM::Psm object,
   # see Bio::Matrix::PSM::PsmI for details
   #This is a Bio::Matrix::PSM::ProtMatrix object now
   my $matrix = $psm->matrix;
}

# Get a simple consensus, where alphabet is:
# {A, R, N, D, C, Q, E, G, H, I, L, K, M, F, P, S, T, W, Y, V,}
# choosing the highest probability or N if prob is too low
my $consensus = $site->consensus;

# Retrieving and using regular expressions:
my $regexp = $site->regexp;
my $count = grep($regexp,$seq);
my $count = ($seq=~ s/$regexp/$1/eg);
print "Motif $mid is present $count times in this sequence\n";

---

💅 DESCRIPTION 💅

ProtMatrix is here to hand you some basic methods when you're working with position scoring (weight) matrices related to protein sequences. Iconic behavior. ✨

So a protein PSM is literally 20 vectors with 20 frequencies (one per amino acid per position), and that's the minimum information you should give it to build a PSM object, no cap. 🧬

Those vectors can come in as strings with frequencies, where the frequency is {0..a} and a=1. That's the way MEME does its compressed representation of a matrix, and it's genuinely so useful when you're messing with a relational DB. 🫶

If you hand it arrays instead (references to arrays, actually, bestie, don't forget the \), they can be any number — real or integer, frequency or count. Whatever.

When the object gets created, the constructor is gonna check for positions that equal 0. If it finds one, it bumps the count for all positions by one and recalculates the frequency. 🚨

Potential bug — if you're using frequencies and one of the positions is 0, it will change significantly. But fr, you should never have a frequency that equals 0 anyway. 💀

It throws an exception if:

• You mix an array and a string as input (like, A matrix given as an array, C as a string) 🙈
• The position vector is (0,0,0,0) 😭
• One of the probability vectors is shorter than the rest 💔

---

🌟 Summary of the methods I use most frequently 🌟

(details below, bestie, we're getting there)

• iupac — return IUPAC compliant consensus as a string
• score — Returns the score as a real number
• IC — information content. Returns a real number
• id — identifier. Returns a string
• accession — accession number. Returns a string
• next_pos — return the sequence probably for each letter, IUPAC symbol, IUPAC probability and simple sequence consenus letter for this position. Rewind at the end. Returns a hash.
• pos — current position get/set. Returns an integer.
• regexp — construct a regular expression based on IUPAC consensus. For example AGWV will be [Aa][Gg][AaTt][AaCcGg]
• width — site width
• get_string — gets the probability vector for a single base as a string.
• get_array — gets the probability vector for a single base as an array.
• get_logs_array — gets the log-odds vector for a single base as an array.

---

New methods, which might be of interest to literally anyone who wants to store a PSM in a relational database without creating an entry for each position, is the ability to compress the PSM vector into a string while losing usually less than 1% of the data. 💖 So slay. This can be done with:

my $str=$matrix->get_compressed_freq('A');

or

my $str=$matrix->get_compressed_logs('A');

Loading from a database should be done with new, but it is not yet implemented. 😭 That's the tea. However you can still uncompress such a string with:

my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1,1); for PSM

or

my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1000,2); for log odds

---

🫶 FEEDBACK 🫶

💌 Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated. 🎀

bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🩹 Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. 🙏

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

---

👑 AUTHOR - James Thompson 👑

Email tex@biosysadmin.com 💌

---

✨ APPENDIX ✨

---

🌸 new

• Title: new
• Usage:

my $site = Bio::Matrix::PSM::ProtMatrix->new(
  %probs,
  %logs,
  -IC    => $ic,
  -e_val => $score,
  -id    => $mid
  -model => \%model
);

• Function: Creates a new Bio::Matrix::PSM::ProtMatrix object from memory
• Throws: If inconsistent data for all vectors (all 20 amino acids) is provided, if you mix input types (string vs array) or if a position freq is 0.
• Example:
• Returns: Bio::Matrix::PSM::ProtMatrix object
• Args: Hash references to log-odds scores and probabilities for position-specific scoring info, e-value (optional), information content (optional), id (optional), model for background distribution of proteins (optional).

---

🦋 alphabet

• Title: Returns an array (or array reference if desired) to the alphabet
• Usage:
• Function: Returns an array (or array reference) containing all of the allowable characters for this matrix.
• Throws:
• Example:
• Returns: Array or arrary reference.
• Args:

---

🎀 _calculate_consensus

• Title: _calculate_consensus
• Usage:
• Function: Calculates the consensus sequence for this matrix.
• Throws:
• Example:
• Returns:
• Args:

---

💖 next_pos

• Title: next_pos
• Usage:
• Function: Retrieves the next position features: frequencies for all 20 amino acids, log-odds scores for all 20 amino acids at this position, the main (consensus) letter at this position, the probability for the consensus letter to occur at this position and the relative current position as an integer.
• Throws:
• Example:
• Returns: hash (or hash reference) (pA,pR,pN,pD,...,logA,logR,logN,logD,aa,prob,rel)
  • pN entries represent the probability for amino acid N to be at this position
  • logN entries represent the log-odds score for having amino acid N at this position
  • aa is the consensus amino acid
  • prob is the probability for the consensus amino acid to be at this position
  • rel is the relative index of the current position (integer)
• Args: none

---

🧚 curpos

• Title: curpos
• Usage:
• Function: Gets/sets the current position.
• Throws:
• Example:
• Returns: Current position (integer).
• Args: New position (integer).

---

⭐ e_val

• Title: e_val
• Usage:
• Function: Gets/sets the e-value
• Throws:
• Example:
• Returns:
• Args: real number

---

🔥 IC

• Title: IC
• Usage:
• Function: Position-specific information content.
• Throws:
• Example:
• Returns: Information content for current position.
• Args: Information content for current position.

---

👑 accession_number

• Title: accession_number
• Usage:
• Function: accession number, this will be unique id for the ProtMatrix object as well for any other object, inheriting from ProtMatrix.
• Throws:
• Example:
• Returns: New accession number (string)
• Args: Accession number (string)

---

💜 consensus

• Title: consensus
• Usage:
• Function: Returns the consensus sequence for this PSM.
• Throws: if supplied with thresold outisde 5..10 range
• Example:
• Returns: string
• Args: (optional) threshold value 5 to 10 (corresponds to 50-100% at each position

---

🍓 get_string

• Title: get_string
• Usage:
• Function: Returns given probability vector as a string. Useful if you want to store things in a rel database, where arrays are not first choice
• Throws: If the argument is outside {A,C,G,T}
• Example:
• Returns: string
• Args: character {A,C,G,T}

---

🌈 width

• Title: width
• Usage:
• Function: Returns the length of the site
• Throws:
• Example:
• Returns: number
• Args:

---

🌸 get_array

• Title: get_array
• Usage:
• Function: Returns an array with frequencies for a specified amino acid.
• Throws:
• Example:
• Returns: Array representing frequencies for specified amino acid.
• Args: Single amino acid (character).

---

✨ get_logs_array

• Title: get_logs_array
• Usage:
• Function: Returns an array with log_odds for a specified base
• Throws:
• Example:
• Returns: Array representing log-odds scores for specified amino acid.
• Args: Single amino acid (character).

---

🎀 id

• Title: id
• Usage:
• Function: Gets/sets the site id
• Throws:
• Example:
• Returns: string
• Args: string

---

🦋 regexp

• Title: regexp
• Usage:
• Function: Returns a case-insensitive regular expression which matches the IUPAC convention. X's in consensus sequence will match anything.
• Throws:
• Example:
• Returns: string
• Args: Threshold for calculating consensus sequence (number in range 0-100 representing a percentage). Threshold defaults to 20.

---

💅 regexp_array

• Title: regexp_array
• Usage:
• Function: Returns an array of position-specific regular expressions. X's in consensus sequence will match anything.
• Throws:
• Example:
• Returns: Array of position-specific regular expressions.
• Args: Threshold for calculating consensus sequence (number in range 0-100 representing a percentage). Threshold defaults to 20.
• Notes: Simply calls regexp method in list context.

---

💖 _compress_array

• Title: _compress_array
• Usage:
• Function: Will compress an array of real signed numbers to a string (ie vector of bytes) -127 to +127 for bi-directional(signed) and 0..255 for unsigned ;
• Throws:
• Example: Internal stuff
• Returns: String
• Args: array reference, followed by max value and direction (optional, defaults to 1), direction of 1 is unsigned, anything else is signed.

---

🧚 _uncompress_string

• Title: _uncompress_string
• Usage:
• Function: Will uncompress a string (vector of bytes) to create an array of real signed numbers (opposite to_compress_array)
• Throws:
• Example: Internal stuff
• Returns: string, followed by max value and direction (optional, defaults to 1), direction of 1 is unsigned, anything else is signed.
• Args: array

---

⭐ get_compressed_freq

• Title: get_compressed_freq
• Usage:
• Function: A method to provide a compressed frequency vector. It uses one byte to code the frequence for one of the probability vectors for one position. Useful for relational database. Improvement of the previous 0..a coding.
• Throws:
• Example: my $strA=$self->get_compressed_freq('A');
• Returns: String
• Args: char

---

🔥 sequence_match_weight

• Title: sequence_match_weight
• Usage:
• Function: This method will calculate the score of a match, based on the PSM if such is associated with the matrix object. Returns undef if no PSM data is available.
• Throws: if the length of the sequence is different from the matrix width
• Example: my $score=$matrix->sequence_match_weight('ACGGATAG');
• Returns: Floating point
• Args: string

---

👑 _to_IUPAC

• Title: _to_IUPAC
• Usage:
• Function: Converts a single position to IUPAC compliant symbol and returns its probability. Currently returns the most likely amino acid/probability combination.
• Throws:
• Example:
• Returns: char, real number representing an amino acid and a probability.
• Args: real numbers for all 20 amino acids (ordered by alphabet contained in $self->{_alphabet}, minimum probability threshold.

---

💜 _to_cons

• Title: _to_cons
• Usage:
• Function: Converts a single position to simple consensus character and returns its probability. Currently just calls the _to_IUPAC subroutine.
• Throws:
• Example:
• Returns: char, real number
• Args: real numbers for A,C,G,T (positional)

---

🍓 get_all_vectors

• Title: get_all_vectors
• Usage:
• Function: returns all possible sequence vectors to satisfy the PFM under a given threshold
• Throws: If threshold outside of 0..1 (no sense to do that)
• Example: my @vectors = $self->get_all_vectors(4);
• Returns: Array of strings
• Args: (optional) floating

---

and that's the whole appendix, bestie 💖 every last method, every last field, no crumbs left behind. this one shipped as part of perl v5.32.1 back on 2021-08-15, so go forth and matrix responsibly 🫶✨