| 1 |
# TFBS module for TFBS::DB::FlatFileDir |
| 2 |
# |
| 3 |
# Copyright Boris Lenhard |
| 4 |
# |
| 5 |
# You may distribute this module under the same terms as perl itself |
| 6 |
# |
| 7 |
|
| 8 |
# POD |
| 9 |
|
| 10 |
=head1 NAME |
| 11 |
|
| 12 |
TFBS::DB::FlatFileDir - interface to a database of pattern matrices |
| 13 |
stored as a collection of flat files in a dedicated directory |
| 14 |
|
| 15 |
|
| 16 |
=head1 SYNOPSIS |
| 17 |
|
| 18 |
=over 4 |
| 19 |
|
| 20 |
=item * creating a database object by connecting to the existing directory |
| 21 |
|
| 22 |
my $db = TFBS::DB::FlatFileDir->connect("/home/boris/MatrixDir"); |
| 23 |
|
| 24 |
=item * retrieving a TFBS::Matrix::* object from the database |
| 25 |
|
| 26 |
# retrieving a PFM by ID |
| 27 |
my $pfm = $db->get_Matrix_by_ID('M00079','PFM'); |
| 28 |
|
| 29 |
#retrieving a PWM by name |
| 30 |
my $pwm = $db->get_Matrix_by_name('NF-kappaB', 'PWM'); |
| 31 |
|
| 32 |
=item * retrieving a set of matrices as a TFBS::MatrixSet object according to various criteria |
| 33 |
|
| 34 |
# retrieving a set of PWMs from a list of IDs: |
| 35 |
my @IDlist = ('M0019', 'M0045', 'M0073', 'M0101'); |
| 36 |
my $matrixset = $db->get_MatrixSet(-IDs => \@IDlist, |
| 37 |
-matrixtype => "PWM"); |
| 38 |
|
| 39 |
# retrieving a set of ICMs from a list of names: |
| 40 |
my @namelist = ('p50', 'p53', 'HNF-1'. 'GATA-1', 'GATA-2', 'GATA-3'); |
| 41 |
my $matrixset = $db->get_MatrixSet(-names => \@namelist, |
| 42 |
-matrixtype => "ICM"); |
| 43 |
|
| 44 |
# retrieving a set of all PFMs in the database |
| 45 |
my $matrixset = $db->get_MatrixSet(-matrixtype => "PFM"); |
| 46 |
|
| 47 |
=item * creating a new FlatFileDir database in a new directory: |
| 48 |
|
| 49 |
my $db = TFBS::DB::JASPAR2->create("/home/boris/NewMatrixDir"); |
| 50 |
|
| 51 |
=item * storing a matrix in the database: |
| 52 |
|
| 53 |
#let $pfm is a TFBS::Matrix::PFM object |
| 54 |
$db->store_Matrix($pfm); |
| 55 |
|
| 56 |
|
| 57 |
|
| 58 |
=back |
| 59 |
|
| 60 |
=head1 DESCRIPTION |
| 61 |
|
| 62 |
TFBS::DB::FlatFileDir is a read/write database interface module that |
| 63 |
retrieves and stores TFBS::Matrix::* and TFBS::MatrixSet |
| 64 |
objects in a set of flat files in a dedicated directory. It has a |
| 65 |
very simple structure and can be easily set up manually if desired. |
| 66 |
|
| 67 |
|
| 68 |
=head1 FEEDBACK |
| 69 |
|
| 70 |
Please send bug reports and other comments to the author. |
| 71 |
|
| 72 |
=head1 AUTHOR - Boris Lenhard |
| 73 |
|
| 74 |
Boris Lenhard E<lt>[email protected]<gt> |
| 75 |
|
| 76 |
=head1 APPENDIX |
| 77 |
|
| 78 |
The rest of the documentation details each of the object |
| 79 |
methods. Internal methods are preceded with an underscore. |
| 80 |
|
| 81 |
=cut |
| 82 |
|
| 83 |
|
| 84 |
# The code begins HERE: |
| 85 |
|
| 86 |
|
| 87 |
|
| 88 |
package TFBS::DB::FlatFileDir; |
| 89 |
|
| 90 |
use vars qw(@ISA); |
| 91 |
use strict; |
| 92 |
use Bio::Root::Root; |
| 93 |
use TFBS::Matrix::PFM; |
| 94 |
use TFBS::Matrix::ICM; |
| 95 |
use TFBS::Matrix::PWM; |
| 96 |
use TFBS::MatrixSet; |
| 97 |
|
| 98 |
@ISA = qw(TFBS::DB Bio::Root::Root); |
| 99 |
|
| 100 |
=head2 new |
| 101 |
|
| 102 |
Title : new |
| 103 |
Usage : my $db = TFBS::DB::FlatFileDir->new(%args); |
| 104 |
Function: the formal constructor for the TFBS::DB::FlatFileDir object; |
| 105 |
most users will not use it - they will use specialized |
| 106 |
I<connect> or I<create> constructors to create a |
| 107 |
database object |
| 108 |
Returns : a TFBS::DB::FlatFileDir object |
| 109 |
Args : -dir # the directory containing flat files |
| 110 |
|
| 111 |
=cut |
| 112 |
|
| 113 |
|
| 114 |
sub new { |
| 115 |
my $caller = shift; |
| 116 |
my $self = bless {_item => {}, |
| 117 |
_idlist_of_name=>{} , |
| 118 |
_idlist_of_class=>{} |
| 119 |
}, |
| 120 |
ref ($caller) || $caller; |
| 121 |
if (-d $_[0]) { |
| 122 |
$self->{dir} = $_[0]; |
| 123 |
} |
| 124 |
elsif ($_[0] eq '-dir' and -d $_[1]) { |
| 125 |
$self->{dir} = $_[1]; |
| 126 |
} |
| 127 |
else { |
| 128 |
$self->throw("Error initializing FlatFileDir database dir: ", |
| 129 |
($_[1] or $_[0] or "No directory parameter passed.")); |
| 130 |
} |
| 131 |
$self->_load_db_index(); |
| 132 |
return $self; |
| 133 |
} |
| 134 |
|
| 135 |
|
| 136 |
=head2 connect |
| 137 |
|
| 138 |
Title : connect |
| 139 |
Usage : my $db = TFBS::DB::FlatFileDir->connect($directory); |
| 140 |
Function: Creates a database object that retrieves TFBS::Matrix::* |
| 141 |
object data from or stores it in an existing directory |
| 142 |
Returns : a TFBS::DB::FlatFileDir object |
| 143 |
Args : ($directory) |
| 144 |
The name of the directory (possibly with fully qualified |
| 145 |
path). |
| 146 |
|
| 147 |
=cut |
| 148 |
|
| 149 |
sub connect { |
| 150 |
my ($caller, $dir) = @_; |
| 151 |
$caller->new(-dir=>$dir); |
| 152 |
} |
| 153 |
|
| 154 |
|
| 155 |
=head2 create |
| 156 |
|
| 157 |
Title : create |
| 158 |
Usage : my $newdb = TFBS::DB::FlatFileDir->create($new_directory); |
| 159 |
Function: connects to the database server, creates a new directory, |
| 160 |
sets up a FlatFileDir database and returns a database |
| 161 |
object that interfaces the database |
| 162 |
Returns : a TFBS::DB::FlatFileDir object |
| 163 |
Args : ($new_directory) |
| 164 |
The name of the directory to create |
| 165 |
(possibly with fully qualified path). |
| 166 |
|
| 167 |
=cut |
| 168 |
|
| 169 |
sub create { |
| 170 |
my ($caller, $dir) = @_; |
| 171 |
if (-d $dir) { die ("Directory $dir exists") ; } |
| 172 |
mkdir ($dir) or die("Error creating directory $dir, stopped"); |
| 173 |
open FILE, ">$dir/matrix_list.txt" |
| 174 |
or die ("Error creating matrix_list.txt"); |
| 175 |
close FILE; |
| 176 |
$caller->new(-dir=>$dir); |
| 177 |
} |
| 178 |
|
| 179 |
=head2 get_Matrix_by_ID |
| 180 |
|
| 181 |
Title : get_Matrix_by_ID |
| 182 |
Usage : my $pfm = $db->get_Matrix_by_ID('M00034', 'PFM'); |
| 183 |
Function: fetches matrix data under the given ID from the |
| 184 |
database and returns a TFBS::Matrix::* object |
| 185 |
Returns : a TFBS::Matrix::* object; the exact type of the |
| 186 |
object depending on the second argument (allowed |
| 187 |
values are 'PFM', 'ICM', and 'PWM'); returns undef if |
| 188 |
matrix with the given ID is not found |
| 189 |
Args : (Matrix_ID, Matrix_type) |
| 190 |
Matrix_ID is a string; Matrix_type is one of the |
| 191 |
following: 'PFM' (raw position frequency matrix), |
| 192 |
'ICM' (information content matrix) or 'PWM' (position |
| 193 |
weight matrix) |
| 194 |
If Matrix_type is omitted, a PWM is retrieved by default. |
| 195 |
|
| 196 |
=cut |
| 197 |
|
| 198 |
sub get_Matrix_by_ID { |
| 199 |
my ($self, $ID, $mt) = @_; |
| 200 |
$self->throw("No ID passed to get_Matrix_by_ID.") unless defined $ID; |
| 201 |
$mt = defined $mt ? $self->_check_matrixtype($mt) : "PWM"; |
| 202 |
my $matrixobj; |
| 203 |
{ |
| 204 |
no strict 'refs'; |
| 205 |
my $working_mt = $mt = uc $mt; |
| 206 |
my $matrixstring = $self->_read_file($ID,$mt) |
| 207 |
# if no desired $mt, is there a PFM? |
| 208 |
|| $self->_read_file($ID,$working_mt="PFM") |
| 209 |
|| return undef; |
| 210 |
|
| 211 |
eval("\$matrixobj= TFBS::Matrix::$working_mt->new".' |
| 212 |
( -ID => $ID, |
| 213 |
-name => $self->{_item}->{$ID}->{name} || "", |
| 214 |
-class => $self->{_item}->{$ID}->{class}|| "", |
| 215 |
-matrix=> $matrixstring, |
| 216 |
-tags=> $self->{_item}->{$ID}->{tags} |
| 217 |
|
| 218 |
);'. |
| 219 |
"if (\$working_mt ne \$mt) {\$matrixobj = \$matrixobj->to_$mt;}"); |
| 220 |
if ($@) {$self->throw($@); } |
| 221 |
} |
| 222 |
# print "MATRIXOBJ: $matrixobj\n"; |
| 223 |
return $matrixobj; |
| 224 |
|
| 225 |
} |
| 226 |
|
| 227 |
=head2 get_Matrix_by_name |
| 228 |
|
| 229 |
Title : get_Matrix_by_name |
| 230 |
Usage : my $pfm = $db->get_Matrix_by_name('HNF-1', 'PWM'); |
| 231 |
Function: fetches matrix data under the given name from the |
| 232 |
database and returns a TFBS::Matrix::* object |
| 233 |
Returns : a TFBS::Matrix::* object; the exact type of the object |
| 234 |
depending on the second argument (allowed values are |
| 235 |
'PFM', 'ICM', and 'PWM') |
| 236 |
Args : (Matrix_name, Matrix_type) |
| 237 |
Matrix_name is a string; Matrix_type is one of the |
| 238 |
following: |
| 239 |
'PFM' (raw position frequency matrix), |
| 240 |
'ICM' (information content matrix) or |
| 241 |
'PWM' (position weight matrix) |
| 242 |
If Matrix_type is omitted, a PWM is retrieved by default. |
| 243 |
Warning : According to the current JASPAR2 data model, name is |
| 244 |
not necessarily a unique identifier. In the case where |
| 245 |
there are several matrices with the same name in the |
| 246 |
database, the function fetches the first one and prints |
| 247 |
a warning on STDERR. You have been warned. |
| 248 |
|
| 249 |
=cut |
| 250 |
|
| 251 |
sub get_Matrix_by_name { |
| 252 |
my ($self, $name, $mt) = @_; |
| 253 |
my $ID=$self->{_idlist_of_name}->{$name}->[0] |
| 254 |
or return undef; |
| 255 |
if ((my $L= scalar @{ $self->{_idlist_of_name}->{$name} }) > 1) { |
| 256 |
$self->warn("There are $L matrices with name '$name'"); |
| 257 |
} |
| 258 |
return $self->get_Matrix_by_ID($ID, $mt); |
| 259 |
} |
| 260 |
|
| 261 |
sub get_matrix { |
| 262 |
# an obsolete method - kept for the time being for backward compatibility |
| 263 |
|
| 264 |
my ($self, %args) = @_; |
| 265 |
my $DIR = $self->{dir}; |
| 266 |
my $ID; |
| 267 |
# retrieval from .pwm files in a directory |
| 268 |
my $mt = ($self->_get_matrixtype_from_args(%args) |
| 269 |
or $self->throw("No -matrixtype provided.")); |
| 270 |
|
| 271 |
if ($args{-ID}) { |
| 272 |
$ID = $args{-ID}; |
| 273 |
} |
| 274 |
elsif (my $name = $args{-name}) { |
| 275 |
$ID=$self->{_idlist_of_name}->{$name}->[0] |
| 276 |
or $self->warn("No matrix with name $name found."); |
| 277 |
if ((my $L= scalar @{ $self->{_idlist_of_name}->{$name} }) > 1) { |
| 278 |
$self->warn("There are $L matrices with name '$name'"); |
| 279 |
} |
| 280 |
} |
| 281 |
else { |
| 282 |
$self->throw("No -ID or -name passed to ".ref($self)); |
| 283 |
} |
| 284 |
|
| 285 |
my $matrixobj; |
| 286 |
{ |
| 287 |
no strict 'refs'; |
| 288 |
my $ucmt = uc $mt; |
| 289 |
my $matrixstring =`cat $DIR/$ID.$mt`; |
| 290 |
|
| 291 |
eval("\$matrixobj= TFBS::Matrix::$ucmt->new".' |
| 292 |
( -ID => $ID, |
| 293 |
-name => $self->{_item}->{$ID}->{name}, |
| 294 |
-class => $self->{_item}->{$ID}->{class}, |
| 295 |
-matrix=> $matrixstring # FIXME - temporary |
| 296 |
);'); |
| 297 |
if ($@) {$self->throw($@); } |
| 298 |
} |
| 299 |
# print "MATRIXOBJ: $matrixobj\n"; |
| 300 |
return $matrixobj; |
| 301 |
} |
| 302 |
|
| 303 |
=head2 store_Matrix |
| 304 |
|
| 305 |
Title : store_Matrix |
| 306 |
Usage : $db->store_Matrix($matrixobj); |
| 307 |
Function: Stores the contents of a TFBS::Matrix::DB object in the database |
| 308 |
Returns : 0 on success; $@ contents on failure |
| 309 |
(this is too C-like and may change in future versions) |
| 310 |
Args : ($matrixobj) # a TFBS::Matrix::* object |
| 311 |
|
| 312 |
=cut |
| 313 |
|
| 314 |
|
| 315 |
sub store_Matrix { |
| 316 |
my ($self, $matrixobj) = @_; |
| 317 |
my ($mt) = ($matrixobj =~ /TFBS::Matrix::(\w+)/) |
| 318 |
or $self->throw("Wrong type of object passed to store_Matrix."); |
| 319 |
if (defined $self->{_item}->{$matrixobj->ID()}) { |
| 320 |
$self->throw("ID ".$matrixobj->ID()." exists in the database."); |
| 321 |
} |
| 322 |
else { |
| 323 |
my $matrixfile = $self->{dir}."/".$matrixobj->ID().".".lc($mt); |
| 324 |
open FILE, ">$matrixfile" |
| 325 |
or $self->throw("Could not write file $matrixfile."); |
| 326 |
print FILE $matrixobj->rawprint; |
| 327 |
close FILE; |
| 328 |
my $ic = ($mt eq "ICM") ? $matrixobj->total_ic : |
| 329 |
($mt eq "PFM") ? $matrixobj->to_ICM->total_ic : ""; |
| 330 |
$self->{_item}->{$matrixobj->ID()} = { 'name' => $matrixobj->name || "", |
| 331 |
'ic' => $ic, |
| 332 |
'class'=> $matrixobj->class || "" }; |
| 333 |
|
| 334 |
my %tags= $matrixobj->all_tags(); |
| 335 |
foreach my $named_tag (keys %tags){ |
| 336 |
$self->{_item}->{$matrixobj->ID()}{'tag'}{$named_tag}=$tags{$named_tag}; |
| 337 |
# print $named_tag , " ", $self->{_item}->{$matrixobj->ID()}{'tag'}{$named_tag}, "\n"; |
| 338 |
|
| 339 |
} |
| 340 |
|
| 341 |
$self->_update_db_index(); |
| 342 |
} |
| 343 |
return 0; |
| 344 |
|
| 345 |
} |
| 346 |
|
| 347 |
=head2 delete_Matrix_having_ID |
| 348 |
|
| 349 |
Title : delete_Matrix_having_ID |
| 350 |
Usage : $db->delete_Matrix_with_ID('M00045'); |
| 351 |
Function: Deletes the matrix having the given ID from the database |
| 352 |
Returns : 0 on success; $@ contents on failure |
| 353 |
(this is too C-like and may change in future versions) |
| 354 |
Args : (ID) |
| 355 |
A string |
| 356 |
Comment : Yeah, yeah, 'delete_Matrix_having_ID' is a stupid name |
| 357 |
for a method, but at least it should be obviuos what it does. |
| 358 |
|
| 359 |
=cut |
| 360 |
|
| 361 |
|
| 362 |
sub delete_Matrix_having_ID { |
| 363 |
my ($self, $ID) = @_; |
| 364 |
my $DIR = $self->{dir}; |
| 365 |
unlink <$DIR/$ID.*>; |
| 366 |
delete $self->{_item}->{$ID}; |
| 367 |
$self->_update_db_index(); |
| 368 |
} |
| 369 |
|
| 370 |
|
| 371 |
sub _update_db_index { |
| 372 |
my $self = shift; |
| 373 |
rename $self->{dir}."/matrix_list.txt", $self->{dir}."/~matrix_list.txt"; |
| 374 |
open FILE, ">".$self->{dir}."/matrix_list.txt"; |
| 375 |
foreach my $ID ( keys %{$self->{_item}} ) { |
| 376 |
print FILE join("\t", $ID, |
| 377 |
$self->{_item}->{$ID}->{ic}, |
| 378 |
$self->{_item}->{$ID}->{name}, |
| 379 |
$self->{_item}->{$ID}->{class} |
| 380 |
)."\t"; |
| 381 |
# add tagged annotation |
| 382 |
# my %tag = $self->{_item}->{$ID}->{'all_tags'}; |
| 383 |
foreach my $name(sort keys %{$self->{'_item'}->{$ID}{'tag'}}){ |
| 384 |
|
| 385 |
print FILE "; ", $name, " \"", $self->{'_item'}->{$ID}{'tag'}{$name}, "\"\ "; |
| 386 |
|
| 387 |
} |
| 388 |
|
| 389 |
|
| 390 |
|
| 391 |
|
| 392 |
|
| 393 |
print FILE "\n"; |
| 394 |
|
| 395 |
|
| 396 |
|
| 397 |
} |
| 398 |
close FILE; |
| 399 |
} |
| 400 |
|
| 401 |
sub _load_db_index { |
| 402 |
my ($self, $field, $value) = @_; |
| 403 |
my $DIR = $self->{dir}; |
| 404 |
open (MATRIXLIST, "$DIR/matrix_list.txt") |
| 405 |
or $self->throw("Could not read matrix list $DIR/matrix_list.txt"); |
| 406 |
while (my $line = <MATRIXLIST>) { |
| 407 |
chomp $line; |
| 408 |
my ($ID, $ic, $name, $class) = split /\s+/, $line ; |
| 409 |
if ($ID =~ /(\w+)\.(\w+)$/) { |
| 410 |
$ID = $1; |
| 411 |
} |
| 412 |
|
| 413 |
defined($self->{_item}->{$ID}) |
| 414 |
and $self->warn("Duplicate entries for ID $ID"); |
| 415 |
$self->{_item}->{$ID} = {name=>$name, ic=>$ic, class=>$class}; |
| 416 |
push @{ $self->{_idlist_of_name}->{$name} }, $ID; |
| 417 |
push @{ $self->{_idlist_of_class}->{$class} }, $ID; |
| 418 |
# annoatation |
| 419 |
|
| 420 |
my @anno= split(/\s?;\s?/, $line); |
| 421 |
my %tags; |
| 422 |
shift @anno; |
| 423 |
foreach (@anno){ |
| 424 |
my ($name, $val)=split(/\s?\"/, $_); |
| 425 |
# print "$name $val\n"; |
| 426 |
$self->{_item}->{$ID}->{'tags'}->{$name}=$val; |
| 427 |
|
| 428 |
} |
| 429 |
|
| 430 |
|
| 431 |
|
| 432 |
} |
| 433 |
close MATRIXLIST; |
| 434 |
return scalar keys %{ $self->{_item} }; # false if list empty |
| 435 |
} |
| 436 |
|
| 437 |
|
| 438 |
sub get_MatrixSet { |
| 439 |
my ($self, %args) = @_; |
| 440 |
my $DIR = $self->{db}; |
| 441 |
my $arrayref; |
| 442 |
my $mt = $self->_check_matrixtype($args{-matrixtype}) |
| 443 |
|| $self->throw("No matrix type provided."); |
| 444 |
delete $args{'-matrixtype'}; |
| 445 |
my ($field, $value) = %args; |
| 446 |
unless (defined $field) { |
| 447 |
$field="-IDs"; |
| 448 |
$arrayref = [ keys %{ $self->{_item}} ]; |
| 449 |
} |
| 450 |
my @IDlist; |
| 451 |
if ($field eq "-IDs") { |
| 452 |
@IDlist = @$arrayref; |
| 453 |
} |
| 454 |
elsif ($field eq "-names") { |
| 455 |
foreach (@$arrayref) { |
| 456 |
push @IDlist, @{ $self->{_idlist_of_name}->{$_} }; |
| 457 |
} |
| 458 |
} |
| 459 |
elsif ($field eq "-classes") { |
| 460 |
foreach (@$arrayref) { |
| 461 |
push @IDlist, @{ $self->{_idlist_of_class}->{$_} }; |
| 462 |
} |
| 463 |
} |
| 464 |
else { |
| 465 |
$self->throw("Unknown matrixset selector: $field."); |
| 466 |
} |
| 467 |
my $matrixset = TFBS::MatrixSet->new(); |
| 468 |
foreach my $ID(@IDlist) { |
| 469 |
$matrixset->add_matrix($self->get_Matrix_by_ID($ID, $mt)); |
| 470 |
} |
| 471 |
close MATRIXLIST; |
| 472 |
return $matrixset; |
| 473 |
} |
| 474 |
|
| 475 |
|
| 476 |
sub _check_matrixtype { |
| 477 |
my ($self, $mt) = @_; |
| 478 |
$mt = uc $mt; |
| 479 |
return undef unless $mt; |
| 480 |
unless ( $mt eq "PFM" |
| 481 |
or $mt eq "ICM" |
| 482 |
or $mt eq "PWM") { |
| 483 |
$self->throw("Unsupported matrix type: ".$mt); |
| 484 |
} |
| 485 |
|
| 486 |
return $mt; |
| 487 |
} |
| 488 |
|
| 489 |
sub _read_file { |
| 490 |
my ($self, $id, $mt) = @_; |
| 491 |
local $/ = undef; |
| 492 |
open FILE, $self->{dir}."/$id.".lc($mt) or return undef; |
| 493 |
my $matrixstring = <FILE>; #slurp; |
| 494 |
close FILE; |
| 495 |
return $matrixstring; |
| 496 |
} |
| 497 |
|
| 498 |
1; |