TFBS::...JASPAR2(3pm)

💖 TFBS::DB::JASPAR2(3pm) 💖

okay bestie, welcome to the User Contributed Perl Documentation for TFBS::DB::JASPAR2 — the header line calls it TFBS::...JASPAR2(3pm), and we are so ready. 🫶

✨ NAME ✨

TFBS::DB::JASPAR2 — interface to MySQL relational database of pattern matrices. It's giving database bestie energy, no cap. 💅

🌈 SYNOPSIS 🌈

Here's the vibe, bestie:

• creating a database object by connecting to the existing JASPAR2-type database

my $db = TFBS::DB::JASPAR2->connect("dbi:mysql:JASPAR2:myhost",
                                    "myusername",
                                    "mypassword");

• retrieving a TFBS::Matrix::* object from the database

# retrieving a PFM by ID
my $pfm = $db->get_Matrix_by_ID('M0079','PFM');

#retrieving a PWM by name
my $pwm = $db->get_Matrix_by_name('NF-kappaB', 'PWM');

• retrieving a set of matrices as a TFBS::MatrixSet object according to various criteria

# retrieving a set of PWMs from a list of IDs:
my @IDlist = ('M0019', 'M0045', 'M0073', 'M0101');
my $matrixset = $db->get_MatrixSet(-IDs => \@IDlist,
                                   -matrixtype => "PWM");

# retrieving a set of ICMs from a list of names:
my @namelist = ('p50', 'p53', 'HNF-1'. 'GATA-1', 'GATA-2', 'GATA-3');
my $matrixset = $db->get_MatrixSet(-names => \@namelist,
                                   -matrixtype => "ICM");

# retrieving a set of all PFMs in the database
# derived from human genes:
my $matrixset = $db->get_MatrixSet(-species => ['Homo sapiens'],
                                   -matrixtype => "PFM");

• creating a new JASPAR2-type database named MYJASPAR2:

my $db = TFBS::DB::JASPAR2->create("dbi:mysql:MYJASPAR2:myhost",
                                   "myusername",
                                   "mypassword");

• storing a matrix in the database (currently only PFMs):

#let $pfm is a TFBS::Matrix::PFM object
$db->store_Matrix($pfm);

💜 DESCRIPTION 💜

TFBS::DB::JASPAR2 is a read/write database interface module that retrieves and stores TFBS::Matrix::* and TFBS::MatrixSet objects in a relational database. That's the whole main character energy right there. 👑

🧬 JASPAR2 DATA MODEL 🧬

JASPAR2 is working name for a relational database model used for storing transcriptional factor pattern matrices in a MySQL database. It was initially designed to store matrices for the JASPAR database of high quality eukaryotic transcription factor specificity profiles by Albin Sandelin and Wyeth W. Wasserman. Besides the profile matrix itself, this data model stores profile ID (unique), name, structural class, basic taxonomic and bibliographic information as well as some additional optional tags. Iconic. ✨

Due to its data model, which precedeed the design of the module, TFBS::DB::JASPAR2 cannot store arbitrary tags for a matrix. The supported tags are:

'acc'      # (accession number;             # originally for
transcription factor protein seq)
'seqdb'    # sequence database where 'acc' comes from
'medline'  # PubMed ID
'species'  # Species name
'sysgroup'
'total_ic' # total information content - redundant, present
           # for historical "medline" => ($self->_get_medline($ID)
or  ""),                     "species" => ($self->_get_species($ID) or
""),                     "sysgroup"=> ($self->_get_sysgroup($ID) or ""),
                    "type"    => ($self->_get_type($ID) or ""),
                    "seqdb"   => ($self->_get_seqdb($ID) or ""),
                    "acc"     => ($self->_get_acc($ID) or ""),
                    "total_ic"=

🦋 ADVANCED 🦋

For the developers and the curious, here is the JASPAR2 data model:

CREATE TABLE matrix_data (
  ID varchar(16) DEFAULT '' NOT NULL,
  pos_ID varchar(24) DEFAULT '' NOT NULL,
  base enum('A','C','G','T'),
  position tinyint(3) unsigned,
  raw int(3) unsigned,
  info float(7,5) unsigned, -- calculated
  pwm float(7,5) unsigned,  -- calculated
  normalized float(7,5) unsigned,
  PRIMARY KEY (pos_ID),
  KEY id_index (ID)
);

CREATE TABLE matrix_info (
  ID varchar(16) DEFAULT '' NOT NULL,
  name varchar(15) DEFAULT '' NOT NULL,
  type varchar(8) DEFAULT '' NOT NULL,
  class varchar(20),
  phylum varchar (32),          -- maps to 'sysgroup' tag
  litt varchar(40),             -- not used by this module
  medline int(12),
  information varchar(20),      -- not used by this module
  iterations varchar(6),
  width int(2),                 -- calculated
  consensus varchar(25),        -- calculated
  IC float(6,4),                -- maps to 'total_ic' tag
  sites int(3) unsigned,        -- not used by this module
  PRIMARY KEY (ID)
)

CREATE TABLE matrix_seqs (
  ID varchar(16) DEFAULT '' NOT NULL,
  internal varchar(8) DEFAULT '' NOT NULL,
  seq_db varchar(15) NOT NULL,
  seq varchar(10) NOT NULL,
  PRIMARY KEY (ID, seq_db, seq)
)

CREATE TABLE matrix_species (
  ID varchar(16) DEFAULT '' NOT NULL,
  internal varchar(8) DEFAULT '' NOT NULL,
  species varchar(24) NOT NULL,
  PRIMARY KEY (ID, species)
)

It is our best intention to hide the details of this data model, which we are using on a daily basis in our work, from most TFBS users, simply because for historical reasons some table column names are confusing at best. Most users should only know the methods to store the data and which tags are supported. Periodt. 💅

---

💌 FEEDBACK 💌

Please send bug reports and other comments to the author. Bestie, they want your bug reports and comments, fr fr. 🫶

👑 AUTHOR - Boris Lenhard 👑

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

📎 APPENDIX 📎

okay bestie, welcome to the deep-lore part 💖 this is where every single object method gets its own lil spotlight. one thing before we dive in: any method whose name starts with an underscore is an internal method — not for you, hands off, no touching 🙅‍♀️

---

✨ new ✨

Title — new

Usage — 🚩 DEPRECATED, kept around for backward compatibility only:

DEPRECATED - for backward compatibility only
Use connect() or create() instead

so yeah, it's giving "existed once, still hangs around to not break your old code." do not start new stuff with it — go use connect() or create() instead, periodt 💅

---

🔌 connect 🔌

Title — connect

Usage —

my $db =
  TFBS::DB::JASPAR2->connect("dbi:mysql:DATABASENAME:HOSTNAME",
                              "USERNAME",
                              "PASSWORD");

Function — hooks you up to an already-existing JASPAR2-type database and hands you back a database object that interfaces it 🫶

Returns — a TFBS::DB::JASPAR2 object, slay

Args — your standard database connection triplet:

("dbi:mysql:DATABASENAME:HOSTNAME",  "USERNAME", "PASSWORD")

swap in the real values wherever you see DATABASENAME, HOSTNAME, USERNAME and PASSWORD. ngl, PASSWORD and USERNAME might be optional — it totally depends on what access permissions the database server is handing out 💀

---

🛠️ create 🛠️

Title — create

Usage —

my $newdb =
  TFBS::DB::JASPAR2->create("dbi:mysql:NEWDATABASENAME:HOSTNAME",
                            "USERNAME",
                            "PASSWORD");

Function — connects to the database server, makes a whole new JASPAR2-type database, and gives you back a database object that interfaces it ✨ (yes bestie, you're building it from scratch, main character energy)

Returns — a TFBS::DB::JASPAR2 object

Args — the standard database connection triplet:

("dbi:mysql:NEWDATABASENAME:HOSTNAME",  "USERNAME", "PASSWORD")

plug in the actual values for NEWDATABASENAME, HOSTNAME, USERNAME and PASSWORD. and again: PASSWORD and USERNAME might be optional depending on the user's access permissions for the database server 🌸

---

🗄️ dbh 🗄️

Title — dbh

Usage —

my $dbh = $db->dbh();
$dbh->do("UPDATE matrix_data SET name='ADD1' WHERE NAME='SREBP2'");

Function — returns the DBI database handle of the MySQL database that $db interfaces.

🚨 BESTIE. LISTEN. 🚨 This is for writing new methods for direct relational database manipulation. If you have write access AND you do not know what you are doing, you can severely corrupt the data. That's not a vibe, that's a catastrophe. For the docs on database handle methods, go read the DBI documentation.

Returns — the database (DBI) handle of the MySQL JASPAR2-type relational database that's associated with the TFBS::DB::JASPAR2 object

Args — none

---

🔍 get_Matrix_by_ID 🔍

Title — get_Matrix_by_ID

Usage —

my $pfm = $db->get_Matrix_by_ID('M00034', 'PFM');

Function — fetches the matrix data sitting under the given ID in the database and returns a TFBS::Matrix::* object

Returns — a TFBS::Matrix::* object, and the exact type depends on that second argument (allowed values are 'PFM', 'ICM', and 'PWM'). If there's no matrix with that ID? you get undef 😭

Args — (Matrix_ID, Matrix_type)

• Matrix_ID is a string
• Matrix_type is one of these cuties: 'PFM' (raw position frequency matrix), 'ICM' (information content matrix) or 'PWM' (position weight matrix)
• if you skip Matrix_type, a PWM is retrieved by default 💜

---

🔎 get_Matrix_by_name 🔎

Title — get_Matrix_by_name

Usage —

my $pfm = $db->get_Matrix_by_name('HNF-1', 'PWM');

Function — fetches the matrix data under the given name from the database and returns a TFBS::Matrix::* object

Returns — a TFBS::Matrix::* object, exact type depending on the second argument (allowed values are 'PFM', 'ICM', and 'PWM')

Args — (Matrix_name, Matrix_type)

• Matrix_name is a string
• Matrix_type is one of: 'PFM' (raw position frequency matrix), 'ICM' (information content matrix) or 'PWM' (position weight matrix)
• if Matrix_type is omitted, a PWM is pulled by default

⚠️ Warning: per the current JASPAR2 data model, name is not necessarily a unique identifier 😬 so if the database has several matrices rockin' the same name, this function fetches the first one and prints a warning on STDERR. You have been warned, bestie. Consider yourself warned. That's the warning. 🫠

---

🎀 get_MatrixSet 🎀

Title — get_MatrixSet

Usage —

my $matrixset = $db->get_MatrixSet(%args);

Function — fetches matrix data for all the matrices in the database that match the criteria you set with named arguments, and returns a TFBS::MatrixSet object

Returns — a TFBS::MatrixSet object 🌈

Args — this method takes named arguments:

• -IDs — a reference to an array of IDs (strings)
• -names — a reference to an array of transcription factor names (string)
• -classes — a reference to an array of structural class names (strings)
• -species — a reference to an array of Latin species names (strings)
• -sysgroups — a reference to an array of higher taxonomic categories (strings)
• -matrixtype — a string, 'PFM', 'ICM' or 'PWM'
• -min_ic — float, minimum total information content of the matrix

okay so the five arguments that expect list references are the ones doing the database query formulation: elements within a list get combined with 'OR' operators, and lists of different types get combined with 'AND'. like, for example:

my $matrixset = $db->(-classes => ['TRP_CLUSTER', 'FORKHEAD'],
                      -species => ['Homo sapiens', 'Mus musculus'],
                      -matrixtype => 'PWM');

that gives you a set of PWMs where (structural class is 'TRP_CLUSTER' OR 'FORKHEAD') AND (the species they're derived from is 'Homo sapiens' OR 'Mus musculus'). 🧚

and the -min_ic filter? that one's applied after the query — meaning matrix profiles with a total information content less than what you specified just don't make the set 💅

---

💾 store_Matrix 💾

Title — store_Matrix

Usage —

$db->store_Matrix($pfm);

Function — stores the contents of a TFBS::Matrix::DB object in the database

Returns — 0 on success; the contents of $@ on failure (yeah, this is too C-like and may change in future versions, we know 😭)

Args — (PFM_object) — a TFBS::Matrix::PFM object

Comment: this is an experimental method that is not 100% bulletproof. use at your own risk, bestie 🙈

---

📦 store_MatrixSet 📦

Title — store_MatrixSet

Usage —

$db->store_Matrix($matrixset);

Function — stores the TFBS::DB::PFM object(s) that are part of a TFBS::MatrixSet object into the database

Returns — 0 on success; the contents of $@ on failure (again: too C-like, may change in future versions)

Args — (MatrixSet_object) — a TFBS::MatrixSet object

Comment: 🚧 THIS METHOD IS NOT YET IMPLEMENTED 🚧

---

🗑️ delete_Matrix_having_ID 🗑️

Title — delete_Matrix_having_ID

Usage —

$db->delete_Matrix_with_ID('M00045');

Function — deletes the matrix with the given ID from the database. yeet 👋

Returns — 0 on success; the contents of $@ on failure (you guessed it — too C-like, may change in future versions)

Args — (ID) — a string

Comment: yeah, yeah, delete_Matrix_having_ID is a ridiculous name for a method, 100%. but at least it's obvious what it does, and honestly? iconic. 👑

---

and that's the whole thing, bestie 🫶 this page came from the perl v5.42.3 docs, dated 2026-08-21 — go forth, query responsibly, and please don't corrupt your database unless you truly know what you're doing 💖✨🌸