TFBS::...JASPAR7(3pm)

✨ TFBS::DB::JASPAR ✨ — the manual page for TFBS::...JASPAR7(3pm) 💅

okay bestie, buckle up 🎀 this is the Perl module doc for TFBS::DB::JASPAR, and yes it is in the 3pm section, and yes we are gonna read the WHOLE thing together, no skimming, no cap.

---

💖 NAME 💖

TFBS::DB::JASPAR — it's the interface to a MySQL relational database full of pattern matrices. Current status: experimental. 🙈 (not me trusting experimental software with my whole pipeline... anyway.)

---

🌸 SYNOPSIS 🌸

Here's the vibe, bestie — five little situations, each with its own snack-sized code block:

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

my $db = TFBS::DB::JASPAR6->connect("dbi:mysql:JASPAR6: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:
 @namelist = ('p50', 'p53', 'HNF-1'. 'GATA-1', 'GATA-2', 'GATA-3');
my $matrixset = $db->get_MatrixSet(-names => \@namelist,
                   -matrixtype => "ICM");

⚠️ bestie, notice how those command names are written — -IDs and -names and -matrixtype — copy them exactly as-is, don't go freestyling your own spelling, okay? 🫶

• creating a new JASPAR6-type database named MYJASPAR6:

my $db = TFBS::DB::JASPAR4->create("dbi:mysql:MYJASPAR6: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 🦋

So TFBS::DB::JASPAR is a read/write database interface module — meaning it goes both ways, it retrieves and it stores TFBS::Matrix::* and TFBS::MatrixSet objects inside a relational database. 💾✨

The interface is nearly identical to the JASPAR2 and JASPAR4 interface — like, same energy, same handshake — but the underlying data model is different. So your muscle memory still works; the plumbing underneath does not. 🧚

---

👑 JASPAR6 DATA MODEL 👑

JASPAR6 is a working name for a relational database model used for storing transcriptional factor pattern matrices in a MySQL database. 🗄️

It was initially designed (JASPAR2) 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, and custom, tags 🏷️

Here goes a moore thorough description on tables and IDs 📝 (yes, "moore", that's literally what the docs say, I'm not fixing it, iykyk 😭)

---

🧪 ADVANCED 🧪

----------------------- ADVANCED ---------------------------------

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

MISSING TEXT HEER ON HOW IT WORKS

😭😭 not the docs just... not having the text. it's giving "I'll finish my essay later". We love her anyway. 💀

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. Most users should only know the methods to store the data and which tags are supported. 🙈✨

-------------------------------------------------------------------------

---

💌 FEEDBACK 💌

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

---

🌈 AUTHOR - Boris Lenhard 🌈

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

---

🦋 APPENDIX 🦋

okay bestie, this is the deep-dive part — every single object method gets its lil moment here. ✨ And real talk: if a method name starts with an underscore, that's an internal method, like backstage at the concert, not for you to touch. 🙈

---

new 💤

• Title: new
• Usage: DEPRECATED — it's hanging around for backward compatibility only. Use connect() or create() instead, no cap.

connect 🔌

• Title: connect
• Usage:

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

• Function: it connects to an already-existing JASPAR6-type database and hands you back a database object that interfaces that database, like a little translator between you and the tables. 🫶
• Returns: a TFBS::DB::JASPAR6 object, periodt.
• Args: a standard database connection triplet — ("dbi:mysql:DATABASENAME:HOSTNAME", "USERNAME", "PASSWORD"). Swap DATABASENAME, HOSTNAME, USERNAME and PASSWORD for your actual real-life values, obviously. And heads up 👀: PASSWORD and USERNAME might be optional, it all depends on what access permissions you've got on that database server.

dbh 🔧

• Title: dbh
• Usage:

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

• Function: hands you the DBI database handle of the MySQL database that $db is interfacing. And listen — this is for WRITING NEW METHODS FOR DIRECT RELATIONAL DATABASE MANIPULATION. So basically: if you have write access AND you have no idea what you're doing, you can severely corrupt the data. 💀 Not a drill. If you want the tea on database handle methods, go read DBI.
• Returns: the database (DBI) handle of the MySQL JASPAR2-type relational database associated with the TFBS::DB::JASPAR2 object. (Yes, this literally says JASPAR2 in there — the docs said what they said, I'm just the messenger. 🍓)
• Args: none, not a single one.

store_Matrix 📥

• Title: store_Matrix
• Usage: $db->store_Matrix($matrixobject);
• Function: stores everything inside a TFBS::Matrix::DB object into the database. Slay.
• Returns: 0 on success; the contents of $@ on failure. The docs themselves say this is "too C-like and may change in future versions" — so like, it's giving retro, embrace it. 😭
• Args: (PFM_object) — a TFBS::Matrix::PFM, FBS::Matrix::PWM or FBS::Matrix::ICM object. PFM objects are the recommendation here, because they convert to the other formats nice and easy.
• Also sitting in there, verbatim:

# might have to give version and collection here

• Comment: this is an experimental method that is not 100% bulletproof. Use at your own risk, bestie. 🎀

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 hands back a TFBS::Matrix::* object. 🎁
• Returns: a TFBS::Matrix::* object — the exact type depends on what form the matrix is stored in inside the database, and PFM is the default.
• Args: (Matrix_ID) — Matrix_ID id is a string referring to the stable JASPAR ID, usually something like "MA0001", with or without version numbers. "MA0001" gives you the latest version of MA0001, while "MA0001.2" gives you the second version, if it exists. Non-existing matrices get you warnings. ⚠️

get_Matrix_by_name 📛

• Title: get_Matrix_by_name
• Usage: my $pfm = $db->get_Matrix_by_name('HNF-1');
• Function: fetches matrix data under the given name from the database and returns a TFBS::Matrix::* object.
• Returns: a TFBS::Matrix::* object — again, exact type depends on what form the matrix object was stored in (default is PFM).
• Args: (Matrix_name)

Warning 🚨: according to the current JASPAR6 data model, name is not necessarily a unique identifier. Also, names change over time, because of course they do. 😭 In the case where there are several matrices with the same name in the database, the function fetches the first one and prints a warning on STDERR. You've been warned. Some matrices have multiple versions — the function will return the latest version. For a specific version, use get_Matrix_by_ID($ID.$version).

get_MatrixSet 🎯

• Title: get_MatrixSet
• Usage: my $matrixset = $db->get_MatrixSet(%args);
• Function: fetches matrix data for all matrices in the database that match the criteria defined by the named arguments, and returns a TFBS::MatrixSet object.
• Returns: a TFBS::MatrixSet object, obviously. 💅
• Args: this method takes named arguments that correspond to arbitrary tags, plus some utility functions. Note this is different from JASPAR2 and, to some extent, JASPAR4. Since any tag is supported for database storage, any tag can be used for information retrieval — iconic behaviour, honestly. ✨ On top of that, arguments like name, class, and collection can be used (even though they are not tags).

By default you only get the last version of each matrix. The only two ways to get older matrices out of this are: use an array of IDs with actual versions like MA0001.1, or set the argument -all_versions=>1, in which case you get all versions for each stable ID. 👑

Examples include:

Fundamental matrix features 🧬

• -all — gives absolutely all matrix entries, regardless of version and collection. Only useful for backup situations and sanity checks. Takes precedence over everything else. 🌈
• -ID — a reference to an array of stable IDs (strings), with or without version, as above. Typically something like "MA0001.2". Takes precedence over everything except -all.
• -name — a reference to an array of transcription factor names (string). Will only take the latest version. NOT a preferred way to access since names change over time. 🙈
• -collection — a string corresponding to a JASPAR collection. Per default CORE.
• -all_versions — gives all matrix versions that fit with the rest of the criteria, including obsolete ones. Is off per default. Typical usage is in combination with stable IDs without versions, to get all versions of a particular matrix.

Typical tag queries 🏷️

These can be either a string or a reference to an array of strings. If it's an array, it will be interpreted as an "or" statement. 💫

• -class — a reference to an array of structural class names (strings)
• -species — a reference to an array of NCBI Taxonomy IDs (integers)
• -taxgroup — a reference to an array of higher taxonomic categories (string)

Computed features of the matrices 🧮

• -min_ic — float, minimum total information content of the matrix.
• -matrixtype — string describing the type of matrix to retrieve. If left out, the format will revert to the database format, which is PFM.

The arguments that expect list references are used in database query formulation: elements within lists are combined with 'OR' operators, and the lists of different types with 'AND'. For example,

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

gives a set of TFBS::Matrix::PFM objects (given that the matrix models are stored as such) whose (structural class is 'TRP_CLUSTER' OR 'FORKHEAD') AND (the species they are derived from is 'Homo sapiens' OR 'Mus musculus').

As above, unless IDs with version numbers are used, only one matrix per stable ID will be returned: the matrix with the highest version number. 🔝

The -min_ic filter is applied after the query, in the sense that matrix profiles with total information content less than specified are not included in the set. ✂️

delete_Matrix_having_ID 🗑️

• Title: delete_Matrix_having_ID
• Usage: $db->delete_Matrix_with_ID('M00045.1');
• Function: deletes the matrix having the given ID from the database. Bye bestie. 👋
• Returns: 0 on success; the contents of $@ on failure. (Again: "this is too C-like and may change in future versions". The C-energy is immovable. 💀)
• Args: (ID) — a string. It has to be a matrix ID with a version suffix in JASPAR6.
• Comment: yeah, yeah, delete_Matrix_having_ID is a stupid name for a method, but at least it should be obvious what it does. 😭

get_TFFM_by_ID 🆔

• Title: get_TFFM_by_ID
• Usage: my $tffm = $db->get_TFFM_by_ID('TFFM0001');
• Function: fetches TFFM data under the given ID from the database and returns a TFBS::TFFM object.
• Returns: a TFBS::TFFM object. 🫶
• Args: TFFM ID. TFFM_ID id is a string which refers to the stable JASPAR TFFM ID (usually something like "TFFM0001"), with or without version numbers. "TFFM0001" will give the latest version of TFFM0001, while "TFFM0001.2" will give the second version, if existing. Warnings will be given for non-existing TFFMs. ⚠️

get_TFFM_by_matrix_ID 🔗

• Title: get_TFFM_by_matrix_ID
• Usage: my $tffm = $db->get_TFFM_by_matrix_ID('MA0001.1');
• Function: fetches TFFM data related to the given matrix ID from the database and returns a TFBS::TFFM object.
• Returns: a TFBS::TFFM object.
• Args: Matrix ID. Matrix ID id is a string which refers to the stable JASPAR matrix ID (usually something like "MA0148.3"). Note that this should be a fully qualified matrix ID (with version), because the TFFM is related to a specific version of a matrix. If no matrix version is given, the latest version of the matrix is retrieved and the corresponding TFFM for that matrix version is retrieved — there could be no TFFM. In general only a few matrices have associated TFFMs, so in many cases no TFFM will be retrieved. In these cases we return undef. 🫥

get_TFFM_by_name 📛

• Title: get_TFFM_by_name
• Usage: my $tffm = $db->get_TFFM_by_name('HNF-1');
• Function: fetches TFFM data under the given name from the database and returns a TFBS::TFFM object.
• Returns: a TFBS::TFFM object.
• Args: a TFFM name — the name of the transcription factor for which this TFFM was modelled. This is the same as the name of the matrix used to train the TFFM. 🧠

Warning 🚨: according to the current JASPAR data model, name is not necessarily a unique identifier. Also, names change over time. In the case where there are several TFFMs with the same name in the database, the function fetches the first one and prints a warning on STDERR. You've been warned. Some matrices have multiple versions — the function will return the latest version. For specific versions, use get_TFFM_by_ID($ID.$version).

---

and that's a wrap on the whole page, bestie!! 🎀 you made it to the very end and honestly? ate. 💅

this beauty is perl v5.42.3, dated 2026-08-21, and it lives under TFBS::...JASPAR7(3pm) in the User Contributed Perl Documentation. go forth and query responsibly, mwah. 💖✨🦋