Debian Codegraph @

blib/lib/TFBS/DB/FlatFileDir.pm

raw
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;