SYNOPSIS
-
creating a database object by connecting to the existing directory
my $db = TFBS::DB::FlatFileDir->connect("/home/boris/MatrixDir");
-
retrieving a TFBS::Matrix::* object from 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');
-
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
my $matrixset = $db->get_MatrixSet(-matrixtype => "PFM");
-
creating a new FlatFileDir database in a 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 that
retrieves and stores TFBS::Matrix::* and TFBS::MatrixSet
objects in a set of flat files in a dedicated directory. It has a
very simple structure and can be easily set up manually if desired.
FEEDBACK
Please send bug reports and other comments to the author.
APPENDIX
The rest of the documentation details each of the object
methods. 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 use it - they will use specialized
I<connect> or I<create> constructors to create a
database object
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 an existing directory
Returns : a TFBS::DB::FlatFileDir object
Args : ($directory)
The name of the directory (possibly with 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 returns 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 fully qualified path).
get_Matrix_by_ID
Title : get_Matrix_by_ID
Usage : my $pfm = $db->get_Matrix_by_ID('M00034', 'PFM');
Function: fetches matrix data under the given ID from the
database and returns a TFBS::Matrix::* object
Returns : a TFBS::Matrix::* object; the exact type of the
object depending on the second argument (allowed
values are 'PFM', 'ICM', and 'PWM'); returns undef if
matrix with the given ID is not found
Args : (Matrix_ID, Matrix_type)
Matrix_ID is a string; Matrix_type is one of the
following: '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 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
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 the
following:
'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 : According to the current JASPAR2 data model, name is
not necessarily a unique identifier. 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 have been warned.
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)
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
(this is too C-like and may change in future versions)
Args : (ID)
A string
Comment : Yeah, yeah, 'delete_Matrix_having_ID' is a stupid name
for a method, but at least it should be obviuos what it does.
