TFBS::...FileDir(3pm)

📦
version 0.7.1 · 6 versions
, in ubuntu stonking

okay so bestie, before we even get into it: this is the manual page for TFBS::...FileDir(3pm) from the User Contributed Perl Documentation, and it's literally just the read/write directory-of-flat-files database interface. It's giving "Boris made a folder and said 'this is a database now'" and honestly? iconic. Let's go. 💅

✨ NAME ✨

TFBS::DB::FlatFileDir — the interface to a database of pattern matrices that live as a whole lil collection of flat files in one dedicated directory. That's the whole vibe. 🌸

🎀 SYNOPSIS 🎀

  • making a database object by connecting to a directory that already exists
my $db = TFBS::DB::FlatFileDir->connect("/home/boris/MatrixDir");
  • pulling a TFBS::Matrix::* object out of the database
# retrieving a PFM by ID
my $pfm = $db->get_Matrix_by_ID('M00079','PFM');

#retrieving a PWM by name
my $pwm = $db->get_Matrix_by_name('NF-kappaB', 'PWM');
  • pulling 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:
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
my $matrixset = $db->get_MatrixSet(-matrixtype => "PFM");
  • making a brand new FlatFileDir database in a brand new directory
my $db = TFBS::DB::JASPAR2->create("/home/boris/NewMatrixDir");
  • storing a matrix in the database
#let $pfm is a TFBS::Matrix::PFM object
$db->store_Matrix($pfm);

💖 DESCRIPTION 💖

TFBS::DB::FlatFileDir is a read/write database interface module, and what it does is retrieve and store TFBS::Matrix::* and TFBS::MatrixSet objects across a set of flat files sitting in a dedicated directory. Its structure is very simple — like, shockingly simple — and you can totally just set it up by hand if that's what your heart wants. No cap. 🦋

🌈 FEEDBACK 🌈

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

👑 AUTHOR — Boris Lenhard 👑

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

📚 APPENDIX 📚

Everything below details each of the object methods, one by one. Just so you know the lore: internal methods are preceded with an underscore.

new

  • Title: new
  • Usage: my $db = TFBS::DB::FlatFileDir->new(%args);
  • Function: the formal constructor for the TFBS::DB::FlatFileDir object. Most users will not be using this — they'll use the specialized connect or create constructors to get their database object instead.
  • Returns: a TFBS::DB::FlatFileDir object
  • Args: -dir — the directory containing flat files

connect

  • Title: connect
  • Usage: my $db = TFBS::DB::FlatFileDir->connect($directory);
  • Function: creates a database object that retrieves TFBS::Matrix::* object data from, or stores it in, a directory that already exists
  • Returns: a TFBS::DB::FlatFileDir object
  • Args: ($directory) — the name of the directory, and yes it can come with a fully qualified path

create

  • Title: create
  • Usage: my $newdb = TFBS::DB::FlatFileDir->create($new_directory);
  • Function: connects to the database server, creates a new directory, sets up a FlatFileDir database, and hands you back a database object that interfaces the database
  • Returns: a TFBS::DB::FlatFileDir object
  • Args: ($new_directory) — the name of the directory to create, possibly with a fully qualified path

get_Matrix_by_ID

  • Title: get_Matrix_by_ID
  • Usage: my $pfm = $db->get_Matrix_by_ID('M00034', 'PFM');
  • Function: fetches the matrix data under the given ID from the database and returns a TFBS::Matrix::* object
  • Returns: a TFBS::Matrix::* object — the exact type depends on that second argument (allowed values are 'PFM', 'ICM', and 'PWM'). Returns undef if there's no matrix with that ID. Sad but true. 😭
  • Args: (Matrix_ID, Matrix_type)
    • Matrix_ID 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 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 — the exact type of the object depends 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 retrieved by default.
  • Warning: per the current JASPAR2 data model, a name is not necessarily a unique identifier. If several matrices in the database share the same name, this function fetches the first one and prints a warning on STDERR. You have been warned. 💀
not me reading "you have been warned" in a manual in the year of our lord. anyway. it's real.

store_Matrix

  • Title: store_Matrix
  • Usage: $db->store_Matrix($matrixobj);
  • 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 — their words, not mine 🙈)
  • Args: ($matrixobj) — a TFBS::Matrix::* object

delete_Matrix_having_ID

  • Title: delete_Matrix_having_ID
  • Usage: $db->delete_Matrix_with_ID('M00045');
  • Function: deletes the matrix having the given ID from the database
  • Returns: 0 on success; $@ contents on failure (again: this is too C-like and may change in future versions)
  • Args: (ID) — a string
  • Comment: yeah yeah, 'delete_Matrix_having_ID' is a silly name for a method, but at least it should be obvious what it does. 😌

and that's the whole page, bestie — perl v5.42.3, dated 2026-08-21, from the User Contributed Perl Documentation, TFBS::...FileDir(3pm). go forth and put some flat files in a folder. slay. 💜✨

📦 where this page comes from