TFBS::...ix::PFM(3pm)

✨ NAME ✨

TFBS::Matrix::PFM — the class for raw position frequency matrix patterns 💖 (yes that's Matrix, bestie, the header line up top says TFBS::...ix::PFM(3pm) because the terminal is dramatic and truncates things, but the real deal is right here)

---

🌸 SYNOPSIS 🌸

okay so there are like four whole ways to get your hands on one of these, let's go:

• making a TFBS::Matrix::PFM object by hand, like a true main character:

my $matrixref = [ [ 12,  3,  0,  0,  4,  0 ],
                  [  0,  0,  0, 11,  7,  0 ],
                  [  0,  9, 12,  0,  0,  0 ],
                  [  0,  0,  0,  1,  1, 12 ]
                ];
my $pfm = TFBS::Matrix::PFM->new(-matrix => $matrixref,
                                 -name   => "MyProfile",
                                 -ID     => "M0001"
                                );
# or

my $matrixstring =
    "12 3 0 0 4 0\n0 0 0 11 7 0\n0 9 12 0 0 0\n0 0 0 1 1 12";

my $pfm = TFBS::Matrix::PFM->new(-matrixstring => $matrixstring,
                                 -name         => "MyProfile",
                                 -ID           => "M0001"
                                );

• pulling a TFBS::Matix::PFM object out of a database 🗄️ (and yes, that spelling is on purpose, it's called Matix in the original, we don't fix it, we honor it):

(peep the docs for the individual TFBS::DB::* modules to learn how to connect to the different flavors of pattern database and yank TFBS::Matrix::* objects out of them)

my $db_obj = TFBS::DB::JASPAR2->new
                (-connect => ["dbi:mysql:JASPAR2:myhost",
                              "myusername", "mypassword"]);
my $pfm = $db_obj->get_Matrix_by_ID("M0001", "PFM");
# or
my $pfm = $db_obj->get_Matrix_by_name("MyProfile", "PFM");

• getting a whole list of individual TFBS::Matrix::PFM objects out of a TFBS::MatrixSet object 👑

(check out TFBS::MatrixSet to learn how to make objects for storing and manipulating multiple matrices)

my @pfm_list = $matrixset->all_patterns(-sort_by=>"name");

• glow-up time: converting a raw frequency matrix into other matrix types 🦋:

my $pwm = $pfm->to_PWM(); # convert to position weight matrix
my $icm = $icm->to_ICM(); # convert to information con

---

💜 DESCRIPTION 💜

TFBS::Matrix::PFM is a class whose instances are objects representing raw position frequency matrices (PFMs). A PFM is derived from N nucleotide patterns of a fixed size, bestie. Like, take this set of sequences:

AGGCCT
AAGCCT
AGGCAT
AAGCCT
AAGCCT
AGGCAT
AGGCCT
AGGCAT
AGGTTT
AGGCAT
AGGCCT
AGGCCT

and it will give you the matrix:

A:[ 12  3  0  0  4  0 ]
C:[  0  0  0 11  7  0 ]
G:[  0  9 12  0  0  0 ]
T:[  0  0  0  1  1 12 ]

which is literally just the count of each nucleotide at each position in the sequence ✨ (and if you've got a set of sequences like the ones above and you want to build a TFBS::Matrix::PFM object out of them, go peek at the TFBS::PatternGen::SimplePFM module, it's giving exactly that)

PFMs convert so easily into other matrix types, namely information content matrices and position weight matrices. A TFBS::Matrix::PFM object has the methods to_ICM and to_PWM which do exactly that, returning a TFBS::Matrix::ICM and TFBS::Matrix::PWM object respectively. slay 💅

---

🫶 FEEDBACK 🫶

Please send bug reports and other comments to the author. (they genuinely want them, no cap)

---

👑 AUTHOR - Boris Lenhard 👑

Boris Lenhard <Boris.Lenhard@cgb.ki.se>

---

📖 APPENDIX 📖

The rest of the documentation details each of the object methods. Internal methods are preceded with an underscore. (iykyk)

🧚 new

• Title : new
• Usage : my $pfm = TFBS::Matrix::PFM->new(%args)
• Function : constructor for the TFBS::Matrix::PFM object
• Returns : a new TFBS::Matrix::PFM object
• Args : # you must specify either one of the following three:

-matrix,      # reference to an array of arrays of integers
   #or
-matrixstring,# a string containing four lines
              # of tab- or space-delimited integers
   #or
-matrixfile,  # the name of a file containing four lines
              # of tab- or space-delimited integers
#######

-name,        # string, OPTIONAL
-ID,          # string, OPTIONAL
-class,       # string, OPTIONAL
-tags         # an array reference, OPTIONAL

• Warnings : Warns if the matrix provided has columns with different sums. Columns with different sums contradict the usual origin of matrix data and, unless you are absolutely sure that column sums should be different, it would be wise to check your matrices. like, please check them, bestie, future you will thank you 😭

🍓 column_sum

• Title : column_sum
• Usage : my $nr_sequences = $pfm->column_sum()
• Function : calculates the sum of elements of one column (the first one by default) which normally equals the number of sequences used to derive the PFM.
• Returns : the sum of elements of one column (an integer)
• Args : columnn number (starting from 1), OPTIONAL — you DO NOT need to specify it unless you are dealing with a matrix (yes, "columnn", the original said it with two n's, we're keeping the lore 🎀)

⭐ to_PWM

• Title : to_PWM
• Usage : my $pwm = $pfm->to_PWM()
• Function : converts a raw frequency matrix (a TFBS::Matrix::PFM object) to a position weight matrix. At present it assumes uniform background distribution of nucleotide frequencies.
• Returns : a new TFBS::Matrix::PWM object
• Args : none; in future releases, it should be able to accept a user defined background probability of the four nucleotides

🌈 to_ICM

• Title : to_ICM
• Usage : my $icm = $pfm->to_ICM()
• Function : converts a raw frequency matrix (a TFBS::Matrix::PFM object) to an information content matrix. At present it assumes uniform background distribution of nucleotide frequencies.
• Returns : a new TFBS::Matrix::ICM object
• Args : -small_sample_correction # undef (default), 'schneider' or 'pseudocounts'

🦋 How a PFM is converted to ICM

For a PFM element PFM[i,k], the probability without pseudocounts is estimated to be simply

p[i,k] = PFM[i,k] / Z

where:

• Z equals the column sum of the matrix i.e. the number of motifs used to construct the PFM.
• i is the column index (position in the motif)
• k is the row index (a letter in the alphacer, here k is one of (A,C,G,T)) — yes, "alphacer", that's the original spelling, we respect the ancestors 💀

Here is how one normally calculates the pseudocount-corrected positional probability p'[i,j]:

p'[i,k] = (PFM[i,k] + 0.25*sqrt(Z)) / (Z + sqrt(Z))

0.25 is for the flat distribution of nucleotides, and sqrt(Z) is the recommended pseudocount weight. In the general case,

p'[i,k] = (PFM[i,k] + q[k]*B) / (Z + B)

where q[k] is the background distribution of the letter (nucleotide) k, and B an arbitrary pseudocount value or expression (for no pseudocounts B=0).

For a given position i, the deviation from random distribution in bits is calculated as (Baldi and Brunak eq. 1.9 (2ed) or 1.8 (1ed)):

• for an arbitrary alphabet of A letters:

D[i] = log2(A) + sum_for_all_k(p[i,k]*log2(p[i,k]))

• special case for nucleotides (A=4)

D[i] = 2 + sum_for_all_k(p[i,k]*log2(p[i,k]))

D[i] equals the information content of the position i in the motif. To calculate the entire ICM, you have to calculate the contrubution of each nucleotide at a position i to D[i], i.e.

ICM[i,k] = p'[i,k] * D[i]

("contrubution" — again, original text, not me, but the math is the math 💖)

🎀 draw_logo

• Title : draw_logo
• Usage : my $gd_image = $pfm->draw_logo()
• Function : draws a sequence logo; similar to the method in TFBS::Matrix::ICM, but can automatically calculate error bars for drawing
• Returns : a GD image object (see documentation of the GD module)
• Args : many; PFM-specific options are:

-small_sample_correction # One of
                         # "Schneider" (uses correction
                         #   described by Schneider et al.
                         #   (Schneider t et al. (1986) J.Biol.Chem.
                         # "pseudocounts" - standard pseudocount
                         #   correction,  more suitable for
                         #   PFMs with large r column sums
                         # If the parameter is omitted, small
                         # sample correction is not applied

-draw_error_bars         # if true, adds error bars to each position
                         # in the logo. To calculate the error bars,
                         # it uses the -small_sample_connection
                         # argument if explicitly set,
                         # or "Schneider" by default

For other args, see the draw_logo entry in the TFBS::Matrix::ICM documentation 👑

💫 add_PFM

• Title : add_PFM
• Usage : $pfm->add_PFM($another_pfm)
• Function : adds the values of $pnother_pfm matrix to $pfm (yes, $pnother_pfm, the typo is canon 🫶)
• Returns : reference to the updated $pfm object
• Args : a TFBS::Matrix::PFM object

🌸 name / ID / class / matrix / length / revcom / rawprint / prettyprint

name ID class matrix length revcom rawprint prettyprint

The above methods are common to all matrix objects. Please consult TFBS::Matrix to find out how to use them. (they're the shared wardrobe, every matrix object wears them ✨)

---

heads up bestie: the synopsis calls it TFBS::Matix::PFM and the synopsis example does my $icm = $icm->to_ICM();, and both of those are exactly what the page says, so don't come for me, come for the original 💅

---

and that's the whole page, no notes 🙈 — this was perl v5.42.3, dated 2026-08-21, and it's User Contributed Perl Documentation for TFBS::...ix::PFM(3pm). go build yourself a matrix, you're doing amazing 💖🦋✨