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

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

💖 Bio::Matrix::PSM::SiteMatrix — the manual page, bestie edition ✨

okay so this is the Bio::Matrix::PSM::SiteMatrix page from the Bioperl docs (it's a 3pm manpage, user-contributed perl documentation, iykyk). it holds a position scoring matrix (aka position weight matrix) AND the log-odds. let's get into it 💅

✨ NAME ✨

Bio::Matrix::PSM::SiteMatrix — it's the SiteMatrixI implementation, and it's literally holding a position scoring matrix (or position weight matrix, same vibe) plus the log-odds for you. no cap 🫶

🎀 SYNOPSIS 🎀

  use Bio::Matrix::PSM::SiteMatrix;
  # Create from memory by supplying probability matrix hash
  # both as strings or arrays
  # where the frequencies  $a,$c,$g and $t are supplied either as
  # arrayref or string. Accordingly, lA, lC, lG and lT are the log
  # odds (only as arrays, no checks done right now)
  my ($a,$c,$g,$t,$score,$ic, $mid)=@_;
  #or
  my ($a,$c,$g,$t,$score,$ic,$mid)=('05a011','110550','400001',
                                    '100104',0.001,19.2,'CRE1');
  #Where a stands for all (this frequency=1), see explanation below
  my %param=(-pA=>$a,-pC=>$c,-pG=>$g,-pT=>$t,
             -lA=>$la, -lC=>$lc,-lG=>$lg,-lT=>$l,
             -IC=>$ic,-e_val=>$score, -id=>$mid);
  my $site=Bio::Matrix::PSM::SiteMatrix->new(%param);
  #Or get it from a file:
  use Bio::Matrix::PSM::IO;
  my $psmIO= Bio::Matrix::PSM::IO->new(-file=>$file, -format=>'transfac');
  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::SiteMatrix object now
    my $matrix=$psm->matrix;
  }

  # Get a simple consensus, where alphabet is {A,C,G,T,N},
  # choosing the character that both satisfies a supplied or default threshold
  # frequency and is the most frequenct character at each position, or N.
  # So for the position with A, C, G, T frequencies of 0.5, 0.25, 0.10, 0.15,
  # the simple consensus character will be 'A', whilst for 0.5, 0.5, 0, 0 it
  # would be 'N'.
  my $consensus=$site->consensus;

  # Get the IUPAC ambiguity code representation of the data in the matrix.
  # Because the frequencies may have been pseudo-count corrected, insignificant
  # frequences (below 0.05 by default) are ignored. So a position with
  # A, C, G, T frequencies of 0.5, 0.5, 0.01, 0.01 will get the IUPAC code 'M',
  # while 0.97, 0.01, 0.01, 0.01 will get the code 'A' and
  # 0.25, 0.25, 0.25, 0.25 would get 'N'.
  my $iupac=$site->IUPAC;

  # Getting/using regular expression (a representation of the IUPAC string)
  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";

lowkey obsessed with how much that synopsis does 💜

🌸 DESCRIPTION 🌸

so SiteMatrix exists to give you some basic methods when you're working with position scoring (weight) matrices — think transcription factor binding sites, that kind of thing. a DNA PSM is made of four vectors with frequencies {A,C,G,T}. that's the minimum info you should hand over to build a PSM object, bestie. 🧬

the vectors can come in as strings, where the frequencies are multiplied by 10 and rounded to an int, going from {0..a} and 'a' means the maximum (10). this is basically MEME's compressed representation of a matrix, and it's genuinely so useful when you're working with a relational DB. iconic behaviour honestly. if you pass arrays instead (well, references to arrays actually), they can be any number — real or integer, frequency or count. no limits, we love that for you. ✨

when you're creating the object you can ask the constructor to do a simple pseudo count correction by adding a number (typically 1) to all positions — that's the -correction option. after adding the number, the frequencies get calculated.

⚠️ only use correction when you supply counts, not frequencies. for real. do not skip this one.

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 — chaotic, don't)
  • the position vector is (0,0,0,0)
  • one of the probability vectors is shorter than the rest

👑 the methods i use most frequently 👑

(details below, bestie)

  • 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.

🦋 the new methods (very main character energy) 🦋

ok so if you're the kind of person who wants to store a PSM in a relational database without creating an entry for each position, these are for you. you can compress the PSM vector into a string and you'll usually lose less than 1% of the data. slay. 💅

do it like this:

  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's not yet implemented (yes, the original says "not yest" — we keep the facts, we just ✨vibe✨ with them). but you can still uncompress a string like this:

  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 — genuinely, it's how things grow 🌱 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. there are so many experienced and responsive experts who will be able to look at the problem and quickly address it. if at all possible, please include a thorough description of the problem with code and data examples. 🙏

🐛 Reporting Bugs

report bugs to the Bioperl bug tracking system to help us keep track of 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

⭐ CONTRIBUTORS

Sendu Bala, bix@sendu.me.uk

💖 APPENDIX 💖

okay bestie this is the ✨rest✨ of the docs — every single method this object has, even the internal ones (you can spot those because they start with _, sneaky little things 🫶). Let's get into it.

🎀 new 🎀

  • Title — new
  • Usage —
my $site=Bio::Matrix::PSM::SiteMatrix->new(-pA=>$a,-pC=>$c,
                                            -pG=>$g,-pT=>$t,
                                            -IC=>$ic,
                                            -e_val=>$score,
                                            -id=>$mid);
  • Function — makes you a brand new Bio::Matrix::PSM::SiteMatrix object straight out of memory. no disk, no drama, just vibes ✨
  • Throws — it WILL throw if you hand it inconsistent data across all the vectors (A, C, G and T), if you mix your input types (string vs array, pick a lane bestie 😭), or if any position freq is 0.
  • Returns — a Bio::Matrix::PSM::SiteMatrix object 🎁
  • Args —
    • -pA => vector with the frequencies or counts of A
    • -pC => vector for C
    • -pG => vector for G
    • -pt => vector for T
    • -lA => vector for the log of A
    • -lC => vector for the log of C
    • -lG => vector for the log of G
    • -lT => vector for the log of T
    • -IC => real number, the information content of this matrix
    • -e_val => real number, the expect value
    • -id => string, an identifier
    • -width => int, width of the matrix in nucleotides
    • -sites => int, the number of sites that went into this matrix
    • -model => hash ref, background frequencies for A, C, G and T
    • -correction => number, the number to add to all positions to achieve pseudo count correction (default 0: no correction)
NB: do not use correction when your input is frequences! 🚨 like genuinely don't
  • -accession_number => string, an accession number

Vectors can be strings of the frequencies, where the frequencies are multiplied by 10 and rounded to the nearest whole number, and where 'a' is used to denote the maximal frequency 10. There should be no punctuation (spaces etc.) in the string. For example, 'a0501'. 💅

Alternatively, frequencies or counts can be represented by an array ref containing the counts, frequencies or logs as any kind of number. slay, options.

🧮 _calculate_consensus 🧮

  • Title — _calculate_consensus
  • Function — Internal stuff 🙈 (that's literally all it says, iykyk)

⚖️ calc_weight ⚖️

  • Title — calc_weight
  • Usage — $obj->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.
  • Throws — if no model is supplied 😤
  • Returns — n/a
  • Args — reference to a hash with background frequencies for A, C, G and T

➡️ next_pos ➡️

  • Title — next_pos
  • Usage — (none given)
  • Function — retrieves the next position's features: frequencies for A, C, G, T, the main letter (as in consensus) and the probability for this letter to occur at this position, plus the current position.
  • Returns — hash (pA,pC,pG,pT,logA,logC,logG,logT,base,prob,rel)
  • Args — none

📍 curpos 📍

  • Title — curpos
  • Usage — (none given)
  • Function — gets/sets the current position. Converts to 0 if the argument is minus and to width if it's greater than width.
  • Returns — integer
  • Args — integer

📊 e_val 📊

  • Title — e_val
  • Usage — (none given)
  • Function — gets/sets the e-value
  • Returns — real number
  • Args — none to get, real number to set

🌈 IC 🌈

  • Title — IC
  • Usage — (none given)
  • Function — get/set the Information Content
  • Returns — real number
  • Args — none to get, real number to set

🔖 accession_number 🔖

  • Title — accession_number
  • Function — get/set the accession number. this will be the unique id for the SiteMatrix object as well for any other object inheriting from SiteMatrix.
  • Returns — string
  • Args — none to get, string to set

👑 consensus 👑

  • Title — consensus
  • Usage — (none given)
  • 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.

📏 width 📏

  • Title — width
  • Usage — (none given)
  • Function — returns the length of the sites used to make this matrix
  • Returns — int
  • Args — none

🧁 sites 🧁

  • Title — sites
  • Usage — (none given)
  • Function — get/set the number of sites that were used to make this matrix
  • Returns — int
  • Args — none to get, int to set

🦋 IUPAC 🦋

  • Title — IUPAC
  • Usage — (none given)
  • Function — returns an IUPAC compliant consensus
  • Returns — string
  • Args — optionally, also supply a whole number (int) of 1 or higher to set the significance level when considering the frequencies. 1 (the default) means a 0.05 significance level: frequencies lower than 0.05 will be ignored. 2 means a 0.005 level, and so on. 💫

🔬 _to_IUPAC 🔬

  • Title — _to_IUPAC
  • Usage — (none given)
  • Function — converts a single position to an IUPAC compliant symbol. For rules, see the implementation 👀
  • Returns — char, real number
  • Args — real numbers for frequencies of A, C, G, T (positional)

optionally, also supply a whole number (int) of 1 or higher to set the significance level when considering the frequencies. 1 (the default) means a 0.05 significance level: frequencies lower than 0.05 will be ignored. 2 means a 0.005 level, and so on.

✂️ _to_cons ✂️

  • Title — _to_cons
  • Usage — (none given)
  • Function — converts a single position to a simple consensus character and returns its probability. For rules, see the implementation.
  • Returns — char, real number
  • Args — real numbers for A, C, G, T (positional), and an optional 5th argument of threshold (as a number between 1 and 10, where 5 is default and means the returned character had a 50% or higher presence at this position)

🧵 get_string 🧵

  • Title — get_string
  • Usage — (none given)
  • Function — returns a given probability vector as a string. super 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}
  • Returns — string
  • Args — character {A,C,G,T}

🗂️ get_array 🗂️

  • Title — get_array
  • Usage — (none given)
  • Function — returns an array with frequencies for a specified base
  • Returns — array
  • Args — char

📈 get_logs_array 📈

  • Title — get_logs_array
  • Usage — (none given)
  • Function — returns an array with log_odds for a specified base
  • Returns — array
  • Args — char

🪪 id 🪪

  • Title — id
  • Usage — (none given)
  • Function — gets/sets the site id
  • Returns — string
  • Args — string

🔍 regexp 🔍

  • Title — regexp
  • Usage — (none given)
  • Function — returns a regular expression which matches the IUPAC convention. N will match X, N, - and .
  • Returns — string
  • Args — none (works at the threshold last used for making the IUPAC string)

🧺 regexp_array 🧺

  • Title — regexp_array
  • Usage — (none given)
  • Function — returns a regular expression which matches the IUPAC convention. N will match X, N, - and .
  • Returns — array
  • Args — none (works at the threshold last used for making the IUPAC string)
  • To do — I have separated regexp and regexp_array, but maybe they can be rewritten as one — just check what should be returned 🤷

🗜️ _compress_array 🗜️

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

🎈 _uncompress_string 🎈

  • Title — _uncompress_string
  • Usage — (none given)
  • Function — will uncompress a string (vector of bytes) to create an array of real signed numbers (opposite to _compress_array)
  • Returns — string, followed by a 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 given)
  • 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 a relational database. An improvement of the previous 0..a coding. 🔥
  • Example — my $strA=$self->get_compressed_freq('A');
  • Returns — String
  • Args — char

🧳 get_compressed_logs 🧳

  • Title — get_compressed_logs
  • Usage — (none given)
  • 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.
  • Example — my $strA=$self->get_compressed_logs('A');
  • Returns — String
  • Args — char

🎯 sequence_match_weight 🎯

  • Title — sequence_match_weight
  • Usage — (none given)
  • 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 given)
  • Function — returns all possible sequence vectors to satisfy the PFM under a given threshold
  • Throws — if threshold is outside of 0..1 (no sense to do that, bestie)
  • Example — my @vectors=$self->get_all_vectors(4);
  • Returns — Array of strings
  • Args — (optional) floating

and that's the whole thing, no notes 💅 you made it to the end, so proud of you fr fr 🥹✨

this page is perl v5.32.1, dated 2021-08-15, and it's giving absolute legend behaviour. mwah, go write some matrices 💖🎀🦋

📦 where this page comes from