TFBS::...JASPAR5(3pm)

📦
version 0.7.1 · 6 versions
, in ubuntu stonking

💖 TFBS::DB::JASPAR5 💖 (that's TFBS::...JASPAR5(3pm) bestie, User Contributed Perl Documentation)

okay so grab a strawberry milk 🍓 because we're about to get cozy with a whole database interface module. it's giving "i contain pattern matrices and i have opinions about MySQL". let's go ✨

🌸 NAME 🌸

TFBS::DB::JASPAR5 — it's the interface to a MySQL relational database full of pattern matrices. current status: experimental. 🧪 (yes, we're in our experimental era, be gentle with it)

🎀 SYNOPSIS 🎀

creating a database object by connecting to the existing JASPAR5-type database

  • so you literally just call connect, like:
my $db = TFBS::DB::JASPAR5->connect("dbi:mysql:JASPAR5:myhost",
                                    "myusername",
                                    "mypassword");

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

  • pull a PFM out by its ID, or a PWM out by its name:
# 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

  • main character move: get a whole set at once, matching whatever criteria 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");
👀 ikykyk but yes, the @namelist line above really does say 'HNF-1'. 'GATA-1' and yes the leading space is real too. that's the page exactly as it is, no notes 💅

creating a new JASPAR5-type database named MYJASPAR5

  • and when you want to make a brand new one:
my $db = TFBS::DB::JASPAR4->create("dbi:mysql:MYJASPAR5:myhost",
                                   "myusername",
                                   "mypassword");
💀 and yes, the example really does say TFBS::DB::JASPAR4->create in there. we are simply reporting what the page says. periodt.

storing a matrix in the database (currently only PFMs)

  • drop a matrix in — currently the only kind it takes is a PFM:
#let $pfm is a TFBS::Matrix::PFM object
$db->store_Matrix($pfm);

🦋 DESCRIPTION 🦋

TFBS::DB::JASPAR5 is a read/write database interface module — like, both directions, we give and we receive 🫶 — and it retrieves and stores TFBS::Matrix::* and TFBS::MatrixSet objects in a relational database.

here's the juicy bit: the interface is nearly identical to the JASPAR2 and JASPAR4 interface. same energy, same vibe check, same calls. but the underlying data model is different. so your muscle memory transfers, your assumptions about what's under the hood do not. 🌈

👑 JASPAR5 DATA MODEL 👑

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

originally (back when it was JASPAR2) it was designed to store matrices for the JASPAR database of high quality eukaryotic transcription factor specificity profiles, by Albin Sandelin and Wyeth W. Wasserman. iconic founders, honestly.

besides the profile matrix itself, this data model stores:

  • profile ID (unique — one of a kind, main character only 💖)
  • 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 JASPAR5 data model:

MISSING TEXT HEER ON HOW IT WORKS

(that's not me being lazy bestie, that is genuinely what the page says 🙈)

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. so like, don't worry about the tables, just vibe with the methods. 💅

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

📬 FEEDBACK 📬

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

⭐ AUTHOR - Boris Lenhard ⭐

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

(still more to come, don't go anywhere 🧚)

💖 APPENDIX 💖

okay bestie, this is the part where we get into every single method — the whole menu, no skips. Also heads up: any method with a leading underscore (_) is an internal one, so like, not for you unless you're feeling feral.

✨ new ✨

  • Title: new
  • Usage:
DEPRECATED - for backward compatibility only
Use connect() or create() instead

that's it. that's the whole thing. it's giving legacy code energy, we don't use it, we use connect() or create(). periodt. 💅

✨ connect ✨

  • Title: connect
  • Usage:
my $db =
 TFBS::DB::JASPAR5->connect("dbi:mysql:DATABASENAME:HOSTNAME",
                             "USERNAME",
                             "PASSWORD");
  • Function: links up to the JASPAR5-type database that already exists and hands you back a database object that's basically the middleman interfacing that database 🫶
  • Returns: a TFBS::DB::JASPAR5 object
  • Args: a standard database connection triplet — ("dbi:mysql:DATABASENAME:HOSTNAME", "USERNAME", "PASSWORD")

where you literally swap in the real values for DATABASENAME, HOSTNAME, USERNAME and PASSWORD. ngl, PASSWORD and USERNAME might be optional — it totally depends on what access permissions you have 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: hands you the DBI database handle of the MySQL database that $db is interfacing. ⚠️ and bestie, listen: THIS IS USED FOR WRITING NEW METHODS FOR DIRECT RELATIONAL DATABASE MANIPULATION — so if you have write access AND you do not know what you're doing, you can severely corrupt the data. no cap. the data. corrupted. by you. 😭

for documentation about database handle methods, see L<DBI>

  • Returns: the database (DBI) handle of the MySQL JASPAR2-type relational database associated with the TFBS::DB::JASPAR2 object
  • Args: none

✨ 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 (this is too C-like and may change in future versions 🙈)
  • Args: (PFM_object) — a TFBS::Matrix::PFM, FBS::Matrix::PWM or FBS::Matrix::ICM object. PFM objects are the recommended ones to use, as they are easily converted to other formats ✨
  • Comment: this is an experimental method that is not 100% bulletproof — use at your own risk 🌸
# might have to give version and collection here

✨ get_Matrix_by_ID ✨

  • Title: get_Matrix_by_ID
  • Usage:
my $pfm = $db->get_Matrix_by_ID('M00034', 'PFM');
  • Function: fetches matrix data stored under the given ID from the database and returns a TFBS::Matrix::* object
  • Returns: a TFBS::Matrix::* object — the exact type depends on what form the matrix is stored in the database (PFM is default)
  • Args: (Matrix_ID)

Matrix_ID is a string that refers 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. Warnings will be given for non-existing matrices 👀

✨ get_Matrix_by_name ✨

  • Title: get_Matrix_by_name
  • Usage:
my $pfm = $db->get_Matrix_by_name('HNF-1');
  • Function: fetches matrix data stored under the given name from the database and returns a TFBS::Matrix::* object
  • Returns: a TFBS::Matrix::* object — the exact type depends on what form the matrix object was stored in the database (default PFM)
  • Args: (Matrix_name)
Warning: per the current JASPAR5 data model, name is not necessarily a unique identifier. also, names change over time. so if there are multiple 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, and this function will return the latest version. 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 accepts named arguments, corresponding to arbitrary tags, and also some utility functions.

note that this is different from JASPAR2 and to some extent JASPAR4. as any tag is supported for database storage, any tag can be used for information retrieval. 🌈 additionally, arguments like 'name', 'class', 'collection' can be used (even though they are not tags).

per 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 save -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 is 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 the 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 🗑️
  • Returns: 0 on success; $@ contents on failure (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 JASPAR5.
  • Comment: yeah, yeah, 'delete_Matrix_having_ID' is a stupid name for a method, but at least it should be obvious what it does. 💀

and that's a wrap on the whole page bestie, you ate that 🎀✨ this one's from perl v5.42.3, dated 2026-08-21 — go forth and query responsibly, ily 🫶💜

📦 where this page comes from