TFBS::...JASPAR6(3pm)

🌸 NAME 🌸

okay so, bestie, meet TFBS::DB::JASPAR6 — she's the ✨interface✨ to a MySQL relational database stuffed full of pattern matrices. Current status: experimental 🧪 (yes she's still in her beta era, handle with care 💅).

---

💖 SYNOPSIS 💖

Here's the whole vibe, one move at a time 🫶

• making a database object by connecting to a JASPAR6-type database that already exists

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

• pulling a TFBS::Matrix::* object out of 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');

• grabbing a whole set of matrices as a TFBS::MatrixSet object, filtered however you want 🌈

# 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");

• spinning up a brand 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 get to move in 🏠)

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

---

🦋 DESCRIPTION 🦋

TFBS::DB::JASPAR6 is a read/write database interface module, periodt. She retrieves and stores TFBS::Matrix::* and TFBS::MatrixSet objects in a relational database. The interface is nearly identical to the JASPAR2 and JASPAR4 interface, but the underlying data model? Completely different, no cap. 💀

---

👑 JASPAR6 DATA MODEL 👑

JASPAR6 is the working name for a relational database model used to store transcriptional factor pattern matrices in a MySQL database. It was originally designed (back in her JASPAR2 days) 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 also stores:

• profile ID (unique 👑)
• name
• structural class
• basic taxonomic and bibliographic information
• plus some additional, and custom, tags 🏷️

Here goes a moore thorough description on tables and IDs.

🔥 ADVANCED 🔥

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

MISSING TEXT HEER ON HOW IT WORKS

(and yes bestie, the typo is canon, I don't make the rules 🙈)

It is our best intention to hide the details of this data model — the one we're using on a daily basis in our work — from most TFBS users. Most users should only need to know the methods for storing the data and which tags are supported, fr fr. 🫶

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

---

💌 FEEDBACK 💌

Please send bug reports and other comments to the author. She wants to hear from you 💖

---

🌟 AUTHOR - Boris Lenhard 🌟

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

---

💖 APPENDIX 💖

Okay bestie, here's the rest — every single method, explained like we're texting at 2am. Internal methods are the ones with an underscore up front, keep an eye out. 👀

---

🌸 new

• Title — new
• Usage — DEPRECATED — kept around for backward compatibility only. Use connect() or create() instead, fr fr.
• Args — none listed here, it's just legacy vibes.

It's deprecated, bestie. connect() or create() are the moment now. Do not build new things on new. 💅

🌸 connect

• Title — connect
• Usage —

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

• Function — hooks you up to an already-existing JASPAR6-type database and hands back a database object that interfaces it. It's giving "I already know a guy." 🫶
• Returns — a TFBS::DB::JASPAR6 object.
• Args — a standard database connection triplet, exactly like this: ("dbi:mysql:DATABASENAME:HOSTNAME", "USERNAME", "PASSWORD"). Swap in your actual values for DATABASENAME, HOSTNAME, USERNAME and PASSWORD. Heads up: PASSWORD and USERNAME might be optional depending on what access permissions your user has on that database server. iykyk 🙈

🌸 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 is interfacing. THIS IS USED FOR WRITING NEW METHODS FOR DIRECT RELATIONAL DATABASE MANIPULATION — so like, if you have write access AND you do not know what you are doing, you can severely corrupt the data. 😭 For documentation about database handle methods, see DBI.
• Returns — the database (DBI) handle of the MySQL JASPAR2-type relational database associated with the TFBS::DB::JASPAR2 object.
• Args — none.

Seriously tho. Raw handle, raw power, raw consequences. Know what you're doing before you do() anything. 💀

🌸 store_Matrix

• Title — store_Matrix
• Usage —

$db->store_Matrix($matrixobject);

• Function — stores the contents of a TFBS::Matrix::DB object in the database.
• Returns — 0 on success; $@ contents on failure (the docs literally say this is too C-like and may change in future versions — iconic honesty ngl).
• Args — (PFM_object): a TFBS::Matrix::PFM, FBS::Matrix::PWM or FBS::Matrix::ICM object. PFM objects are the recommended pick since they're easily converted to the other formats. 🎀

# might have to give version and collection here

• Comment — this is an experimental method that is not 100% bulletproof; use at your own risk. 🫣

🌸 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 and hands back a TFBS::Matrix::* object.
• Returns — a TFBS::Matrix::* object; the exact type depends on what form the matrix is stored in within the database (PFM is the default).
• Args — (Matrix_ID). The Matrix_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. You'll get warnings for matrices that don't exist. ⭐

🌸 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 and returns a TFBS::Matrix::* object.
• Returns — a TFBS::Matrix::* object; the exact type depends on what form the matrix object was stored in within the database (default PFM).
• Args — (Matrix_name).

Warning: according to the current JASPAR6 data model, name is not necessarily a unique identifier. Also, names change over time. 😩 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 returns the latest one. For specific versions, 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 matching the criteria defined by the named arguments, and returns a TFBS::MatrixSet object.
• Returns — a TFBS::MatrixSet object.
• Args — this method takes named arguments corresponding to arbitrary tags, plus some utility functions. ✨

Notably, 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. On top of that, arguments like 'name', 'class', 'collection' can be used — even though they aren't tags. 🦋

By default, only the last version of the matrix is given. The only ways to get older matrices out of this are to use an array of IDs with actual versions like MA0001.1, or to 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 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. Poof. 💀
• Returns — 0 on success; $@ contents on failure (yep, this is too C-like and may change in future versions).
• Args — (ID). A string. Has to be a matrix ID with 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. 💅

---

Bestie, that's the whole appendix — every arg, every warning, every "this might break" disclaimer, untouched and slaying. 🌈

Docs by Boris Lenhard, perl v5.42.3, dated 2026-08-21 — go forth and query responsibly. 🫶🎀