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

💖 TFBS::Matrix::PWM 💖

okay bestie, welcome to the TFBS::...ix::PWM(3pm) page ✨ (yes the manual name is literally truncated like that, we don't make the rules 🫶) — it's part of the User Contributed Perl Documentation, and it's about to become your new personality.

---

✨ NAME ✨

TFBS::Matrix::PWM — the class for position weight matrices of nucleotide patterns 💅

---

🌸 SYNOPSIS 🌸

🎀 creating a TFBS::Matrix::PWM object manually

no cap, you got two ways to do this, and they're both cute:

my $matrixref = [ [ 0.61, -3.16,  1.83, -3.16,  1.21, -0.06],
                  [-0.15, -2.57, -3.16, -3.16, -2.57, -1.83],
                  [-1.57,  1.85, -2.57, -1.34, -1.57,  1.14],
                  [ 0.31, -3.16, -2.57,  1.76,  0.24, -0.83]
                ];
my $pwm = TFBS::Matrix::PWM->new(-matrix => $matrixref,
                                 -name   => "MyProfile",
                                 -ID     => "M0001"
                                );
# or

my $matrixstring = <<ENDMATRIX
 0.61 -3.16  1.83 -3.16  1.21 -0.06
-0.15 -2.57 -3.16 -3.16 -2.57 -1.83
-1.57  1.85 -2.57 -1.34 -1.57  1.14
 0.31 -3.16 -2.57  1.76  0.24 -0.83
ENDMATRIX
;
my $pwm = TFBS::Matrix::PWM->new(-matrixstring => $matrixstring,
                                 -name         => "MyProfile",
                                 -ID           => "M0001"
                                );

🦋 grabbing a TFBS::Matrix::PWM object from a database

lowkey you should go read the docs for the individual TFBS::DB::* modules if you wanna know how to connect to the different flavours of pattern database and pull TFBS::Matrix::* objects out of them:

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

💜 pulling a whole list of individual TFBS::Matrix::PWM objects out of a TFBS::MatrixSet object

(go read the TFBS::MatrixSet documentation if you wanna know how to make objects for storing and manipulating a bunch of matrices at once)

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

⭐ scanning a nucleotide sequence with a matrix

my $siteset = $pwm->search_seq(-file      =>"myseq.fa",
                               -threshold => "80%");

🔥 scanning a pairwise alignment with a matrix

my $site_pair_set = $pwm->search_aln(-file      =>"myalign.aln",
                                     -threshold => "80%",
                                     -cutoff    => "70%",
                                     -window    => 50);

---

🌈 DESCRIPTION 🌈

okay so. TFBS::Matrix::PWM is a class, and its instances are objects that represent position weight matrices, aka PWMs. A PWM is normally calculated from a raw position frequency matrix — go look at TFBS::Matrix::PFM if you want the whole explanation of what position frequency matrices are, it's giving prequel energy 📖.

For example, take this position frequency 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  ]

The standard computational procedure gets applied to it and it turns into this position weight matrix:

A:[ 0.61 -3.16  1.83 -3.16  1.21 -0.06]
C:[-0.15 -2.57 -3.16 -3.16 -2.57 -1.83]
G:[-1.57  1.85 -2.57 -1.34 -1.57  1.14]
T:[ 0.31 -3.16 -2.57  1.76  0.24 -0.83]

and that is what holds the "weights" associated with each nucleotide showing up at a given position in a pattern. iconic, honestly.

A TFBS::Matrix::PWM object comes fully equipped with methods to search nucleotide sequences — and pairwise alignments of nucleotide sequences — with the pattern it represents, and hand you back a set of sites: a TFBS::SiteSet object when it's a single sequence search, and a TFBS::SitePairSet for the alignment search 💫.

---

💬 FEEDBACK 💬

Please send bug reports and other comments to the author. fr fr, they wanna hear from you 🫶

---

👑 AUTHOR - Boris Lenhard 👑

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

---

🧚 APPENDIX 🧚

okay the rest of this doc goes deep on each of the object methods. Internal methods are preceded with an underscore, iykyk.

---

🌟 new

• Title — new
• Usage — my $pwm = TFBS::Matrix::PWM->new(%args)
• Function — constructor for the TFBS::Matrix::PWM object
• Returns — a new TFBS::Matrix::PWM object
• Args — you must specify exactly one of these 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

and then, optionally:

• -name — string, OPTIONAL
• -ID — string, OPTIONAL
• -class — string, OPTIONAL
• -tags — an array reference, OPTIONAL

---

🦄 search_seq

• Title — search_seq
• Usage — my $siteset = $pwm->search_seq(%args)
• Function — scans a nucleotide sequence with the pattern represented by the PWM
• Returns — a TFBS::SiteSet object
• Args — you must specify exactly one of these three:
  • -file — the name of a fasta file (single sequence)
  • or -seqobj — a Bio::Seq object (more accurately, a Bio::PrimarySeq object or a subclass thereof)
  • or -seqstring — a string containing the sequence

plus:

• -threshold — minimum score for the hit, either absolute (e.g. 11.2) or relative (e.g. "75%"). OPTIONAL: default "80%"
• -subpart — subpart of the sequence to search, given as

-subpart => { start => 140,
              end   => 180 }

where start and end are coordinates in the sequence; the coordinate range is interpreted in the BioPerl tradition (1-based, inclusive). OPTIONAL: by default searches entire alignment

---

💅 search_aln

• Title — search_aln
• Usage — my $site_pair_set = $pwm->search_aln(%args)
• Function — scans a pairwise alignment of nucleotide sequences with the pattern represented by the PWM: it reports only those hits that are present in equivalent positions of both sequences and that exceed a specified threshold score in both, AND are found in regions of the alignment above the specified conservation cutoff value.
• Returns — a TFBS::SitePairSet object
• Args — you must specify exactly one of these three:
  • -file — the name of the alignment file in Clustal format
  • or -alignobj — a Bio::SimpleAlign object (more accurately, a Bio::PrimarySeq object or a subclass thereof)
  • or -alignstring — a multi-line string containing the alignment in clustal format

plus:

• -threshold — minimum score for the hit, either absolute (e.g. 11.2) or relative (e.g. "75%"). OPTIONAL: default "80%"
• -window — size of the sliding window (in nucleotides) for calculating local conservation in the alignment. OPTIONAL: default 50
• -cutoff — conservation cutoff (%) for including the region in the results of the pattern search. OPTIONAL: default "70%"
• -subpart — subpart of the alignment to search, given as e.g.

-subpart => { relative_to => 1,
              start       => 140,
              end         => 180 }

where start and end are coordinates in the sequence indicated by relative_to (1 for the 1st sequence in the alignment, 2 for the 2nd). OPTIONAL: by default searches entire alignment

• -conservation — conservation profile, a TFBS::ConservationProfile. OPTIONAL: by default the conservation profile is computed internally on the fly (less efficient)

---

🎀 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 🫶

---

and that's the whole page bestie, you ate 💅 no cap, go forth and build PWMs. This gem of a manual was served up by perl v5.42.3 on 2026-08-21 — periodt. 🎀✨🦋