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

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ NAME ✨

Bio::Matrix::PSM::SiteMatrixI — bestie, this is the SiteMatrixI implementation, and it holds a position scoring matrix (aka a position weight matrix) plus log-odds. It lives in the User Contributed Perl Documentation, filed under the iconic name Bio::M...MatrixI(3pm) 💅

🎀 SYNOPSIS 🎀

  # You cannot use this module directly; see Bio::Matrix::PSM::SiteMatrix
  # for an example implementation
ok so lowkey the biggest thing here: you literally cannot use this module directly, no cap. Go look at Bio::Matrix::PSM::SiteMatrix for an example implementation instead 🫶

🦋 DESCRIPTION 🦋

SiteMatrix is designed to provide some basic methods when you're working with position scoring (weight) matrices — think transcription factor binding sites, that whole vibe. A DNA PSM consists of four vectors with frequencies {A,C,G,T}. That is the minimum information you should provide to construct a PSM object, periodt.

The vectors can be provided as strings with frequenciesx10 rounded to an int, going from {0..a} where 'a' represents the maximum (10). This is like MEME's compressed representation of a matrix, and honestly it's quite useful when working with a relational DB ✨

If arrays are provided as an input (references to arrays actually), they can be any number, real or integer — frequency or count, your call.

When creating the object you can ask the constructor to make a simple pseudo count correction by adding a number (typically 1) to all positions (with the -correction option). After adding the number the frequencies will be calculated. Only use correction when you supply counts, not frequencies — this is the rule, do not break it 🙈

It throws an exception if:

  • You mix as an input array and string (for example A matrix is given as array, C — as 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, keep scrolling)

  • 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 consensus 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 (for the relational DB girlies)

New methods, which might be of interest to anyone who wants to store PSM in a relational database without creating an entry for each position, is the ability to compress the PSM vector into a string, losing usually less than 1% of the data. 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 is not yest implemented. However you can still uncompress such 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 - Stefan Kirov 👑

Email skirov@utk.edu

ok bestie that's the lore so far — the actual method tea is still brewing, so don't go anywhere 🌸💅

✨ APPENDIX ✨

okay bestie, this is the bonus level: every method hanging out in Bio::M...MatrixI(3pm), same order, same facts, just with ✨sparkle✨. let's go.

calc_weight

  • Title: calc_weight
  • Usage: $self->calc_weight({A=>0.2562,C=>0.2438,G=>0.2432,T=>0.2568});
  • Function: Recalculates the PSM (or weights) based on the PFM (the frequency matrix) and a user supplied background model. slay
  • Throws: if no model is supplied
  • Example: (none listed)
  • Returns: (nothing listed)
  • Args: reference to a hash with background frequencies for A,C,G and T

next_pos

  • Title: next_pos
  • Usage: my %base=$site->next_pos;
  • Function: Retrieves the next position features: frequencies and weights for A,C,G,T, the main letter (as in consensus), and the probability for this letter to occur at this position, and the current position. 🦋
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: hash (pA,pC,pG,pT,lA,lC,lG,lT,base,prob,rel)
  • Args: none

curpos

  • Title: curpos
  • Usage: my $pos=$site->curpos;
  • Function: Gets/sets the current position. Converts to 0 if the argument is minus and to width if greater than width.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: integer
  • Args: integer

e_val

  • Title: e_val
  • Usage: my $score=$site->e_val;
  • Function: Gets/sets the e-value.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: real number
  • Args: real number

consensus

  • Title: consensus
  • Usage: (none listed)
  • Function: Returns the consensus.
  • Returns: string
  • Args: (optional) threshold value 1 to 10, default 5. '5' means the returned characters had a 50% or higher presence at their position.

accession_number

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

width

  • Title: width
  • Usage: my $width=$site->width;
  • Function: Returns the length of the site.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: number
  • Args: (none listed)

IUPAC

  • Title: IUPAC
  • Usage: my $iupac_consensus=$site->IUPAC;
  • Function: Returns IUPAC compliant consensus.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: string
  • Args: (none listed)

IC

  • Title: IC
  • Usage: my $ic=$site->IC;
  • Function: Information content.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: real number
  • Args: none

get_string

  • Title: get_string
  • Usage: my $freq_A=$site->get_string('A');
  • 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: (none listed)
  • Returns: string
  • Args: character {A,C,G,T}

id

  • Title: id
  • Usage: my $id=$site->id;
  • Function: Gets/sets the site id.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: string
  • Args: string

regexp

  • Title: regexp
  • Usage: my $regexp=$site->regexp;
  • Function: Returns a regular expression which matches the IUPAC convention. N will match X, N, - and .
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: string
  • Args: (none listed)

regexp_array

  • Title: regexp_array
  • Usage: my @regexp=$site->regexp;
  • Function: Returns a regular expression which matches the IUPAC convention. N will match X, N, - and .
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: array
  • Args: (none listed)
  • To do: I have separated regexp and regexp_array, but maybe they can be rewritten as one — just check what should be returned.

get_array

  • Title: get_array
  • Usage: my @freq_A=$site->get_array('A');
  • Function: Returns an array with frequencies for a specified base.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: array
  • Args: char

_to_IUPAC

  • Title: _to_IUPAC
  • Usage: (none listed)
  • Function: Converts a single position to IUPAC compliant symbol and returns its probability. For rules see the implementation.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: char, real number
  • Args: real numbers for A,C,G,T (positional)

_to_cons

  • Title: _to_cons
  • Usage: (none listed)
  • Function: Converts a single position to simple consensus character and returns its probability. For rules see the implementation,
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: char, real number
  • Args: real numbers for A,C,G,T (positional)

_calculate_consensus

  • Title: _calculate_consensus
  • Usage: (none listed)
  • Function: Internal stuff.
  • Throws: (none listed)
  • Example: (none listed)
  • Returns: (none listed)
  • Args: (none listed)

_compress_array

  • Title: _compress_array
  • Usage: (none listed)
  • 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: (none listed)
  • Example: Internal stuff
  • Returns: String
  • Args: array reference, followed by an max value and direction (optional, default 1-unsigned), 1 unsigned, any other is signed.

_uncompress_string

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

get_compressed_freq

  • Title: get_compressed_freq
  • Usage: (none listed)
  • 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: (none listed)
  • Example: my $strA=$self->get_compressed_freq('A');
  • Returns: String
  • Args: char

get_compressed_logs

  • Title: get_compressed_logs
  • Usage: (none listed)
  • Function: A method to provide a compressed log-odd vector. It uses one byte to code the log value for one of the log-odds vectors for one position.
  • Throws: (none listed)
  • Example: my $strA=$self->get_compressed_logs('A');
  • Returns: String
  • Args: char

sequence_match_weight

  • Title: sequence_match_weight
  • Usage: (none listed)
  • Function: This method will calculate the score of a match, based on the PWM if such is associated with the matrix object. Returns undef if no PWM 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

get_all_vectors

  • Title: get_all_vectors
  • Usage: (none listed)
  • 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! This page is from Bio::M...MatrixI(3pm), Perl v5.32.1, dated 2021-08-15. Go forth and slay your matrices 💅✨

📦 where this page comes from