Bio/SeqFeature/Collection.pm

filter: Statementstmt 77.7% 7 / 9 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 83.3% 10 / 12 CC 1 SCAR 0.9
CC
1
Cov
78%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« Bio/DB/Taxonomy/flatfile.pm ↑ Summary Bio/SeqIO/bsml.pm »
1 #
2 # BioPerl module for Bio::SeqFeature::Collection
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Jason Stajich <jason@bioperl.org>
7 #
8 # Copyright Jason Stajich
9 #
10 # You may distribute this module under the same terms as perl itself
11  
12 # POD documentation - main docs before the code
13  
14 =head1 NAME
15  
16 Bio::SeqFeature::Collection - A container class for SeqFeatures
17 suitable for performing operations such as finding features within a
18 range, that match a certain feature type, etc.
19  
20 =head1 SYNOPSIS
21  
22 use Bio::SeqFeature::Collection;
23 use Bio::Location::Simple;
24 use Bio::Tools::GFF;
25 use Bio::Root::IO;
26 use File::Spec;
27 # let's first input some features
28 my $gffio = Bio::Tools::GFF->new(-file => File::Spec->catfile
29 ("t","data","myco_sites.gff"),
30 -gff_version => 2);
31 my @features = ();
32 # loop over the input stream
33 while(my $feature = $gffio->next_feature()) {
34 # do something with feature
35 push @features, $feature;
36 }
37 $gffio->close();
38 # build the Collection object
39 my $col = Bio::SeqFeature::Collection->new();
40 # add these features to the object
41 my $totaladded = $col->add_features(\@features);
42  
43 my @subset = $col->features_in_range(-start => 1,
44 -end => 25000,
45 -strand => 1,
46 -contain => 0);
47 # subset should have 18 entries for this dataset
48 print "size is ", scalar @subset, "\n";
49 @subset = $col->features_in_range(-range => Bio::Location::Simple->new
50 (-start => 70000,
51 -end => 150000,
52 -strand => -1),
53 -contain => 1,
54 -strandmatch => 'strong');
55  
56 # subset should have 22 entries for this dataset
57 print "size is ", scalar @subset, "\n";
58 print "total number of features in collection is ",
59 $col->feature_count(),"\n";
60  
61 =head1 DESCRIPTION
62  
63 This object will efficiently allow one for query subsets of ranges
64 within a large collection of sequence features (in fact the objects
65 just have to be Bio::RangeI compliant). This is done by the creation
66 of bins which are stored in order in a B-Tree data structure as
67 provided by the DB_File interface to the Berkeley DB.
68  
69 This is based on work done by Lincoln for storage in a mysql instance
70 - this is intended to be an embedded in-memory implementation for
71 easily querying for subsets of a large range set.
72  
73 Collections can be made persistent by keeping the indexfile and
74 passing in the -keep flag like this:
75  
76 my $collection = Bio::SeqFeature::Collection->new(-keep => 1,
77 -file => 'col.idx');
78 $collaction->add_features(\@features);
79 undef $collection;
80  
81 # To reuse this collection, next time you initialize a Collection object
82 # specify the filename and the index will be reused.
83 $collection = Bio::SeqFeature::Collection->new(-keep => 1,
84 -file => 'col.idx');
85  
86  
87  
88 =head1 FEEDBACK
89  
90 =head2 Mailing Lists
91  
92 User feedback is an integral part of the evolution of this and other
93 Bioperl modules. Send your comments and suggestions preferably to
94 the Bioperl mailing list. Your participation is much appreciated.
95  
96 bioperl-l@bioperl.org - General discussion
97 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
98  
99 =head2 Support
100  
101 Please direct usage questions or support issues to the mailing list:
102  
103 I<bioperl-l@bioperl.org>
104  
105 rather than to the module maintainer directly. Many experienced and
106 reponsive experts will be able look at the problem and quickly
107 address it. Please include a thorough description of the problem
108 with code and data examples if at all possible.
109  
110 =head2 Reporting Bugs
111  
112 Report bugs to the Bioperl bug tracking system to help us keep track
113 of the bugs and their resolution. Bug reports can be submitted via
114 the web:
115  
116 https://github.com/bioperl/bioperl-live/issues
117  
118 =head1 AUTHOR - Jason Stajich
119  
120 Email jason@bioperl.org
121  
122 =head1 CONTRIBUTORS
123  
124 Using code and strategy developed by Lincoln Stein (lstein@cshl.org)
125 in Bio::DB::GFF implementation. Credit also to Lincoln for suggesting
126 using Storable to serialize features rather than my previous implementation
127 which kept the features in memory.
128  
129 =head1 APPENDIX
130  
131 The rest of the documentation details each of the object methods.
132 Internal methods are usually preceded with a _
133  
134 =cut
135  
136  
137 # Let the code begin...
138  
139  
140 package Bio::SeqFeature::Collection;
141 $Bio::SeqFeature::Collection::VERSION = '1.7.8';
142 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
143  
144 # Object preamble - inherits from Bio::Root::Root
145  
146 1 ▶use Bio::DB::GFF::Util::Binning;
Subroutine BEGIN: called CC=1 SCAR=0.0
147 0 ▶use DB_File;
Subroutine BEGIN: called CC=1 SCAR=2.6
148 use Bio::Location::Simple;
149 use Bio::SeqFeature::Generic;
150 use Storable qw(freeze thaw);
151  
152 use base qw(Bio::Root::Root Bio::SeqFeature::CollectionI);
153  
154  
155 # This may need to get re-optimized for BDB usage as these
156 # numbers were derived empirically by Lincoln on a mysql srv
157 # running on his laptop
158  
159 # this is the largest that any reference sequence can be (100 megabases)
160 use constant MAX_BIN => 100_000_000;
161  
162 # this is the smallest bin (1 K)
163 use constant MIN_BIN => 1_000;
164  
165 =head2 new
166  
167 Title : new
168 Usage : my $obj = Bio::SeqFeature::Collection->new();
169 Function: Builds a new Bio::SeqFeature::Collection object
170 Returns : Bio::SeqFeature::Collection
171 Args :
172  
173 -minbin minimum value to use for binning
174 (default is 100,000,000)
175 -maxbin maximum value to use for binning
176 (default is 1,000)
177 -file filename to store/read the
178 BTREE from rather than an in-memory structure
179 (default is false and in-memory).
180 -keep boolean, will not remove index file on
181 object destruction.
182 -features Array ref of features to add initially
183  
184 =cut
185  
186 sub new {
187 my($class,@args) = @_;
188  
189 my $self = $class->SUPER::new(@args);
190 my ($maxbin,$minbin, $file, $keep,
191 $features) = $self->_rearrange([qw(MAXBIN MINBIN FILE KEEP
192 FEATURES)],@args);
193  
194 defined $maxbin && $self->max_bin($maxbin);
195 defined $minbin && $self->min_bin($minbin);
196  
197 defined $features && $self->add_features($features);
198 $DB_BTREE->{'flags'} = R_DUP ;
199 $DB_BTREE->{'compare'} = \&_compare;
200 $self->{'_btreehash'} = {};
201 if( $file ) {
202 $self->debug("using file $file");
203 $self->indexfile($file);
204 }
205 $self->keep($keep);
206 $self->{'_btree'} = tie %{$self->{'_btreehash'}},
207 'DB_File', $self->indexfile, O_RDWR|O_CREAT, 0640, $DB_BTREE;
208 $self->{'_btree'} || $self->throw("Unable to tie DB_File handle");
209 return $self;
210 }
211  
212  
213 =head2 add_features
214  
215 Title : add_features
216 Usage : $collection->add_features(\@features);
217 Function:
218 Returns : number of features added
219 Args : arrayref of Bio::SeqFeatureI objects to index
220  
221  
222 =cut
223  
224 sub add_features{
225 my ($self,$feats) = @_;
226 if( ref($feats) !~ /ARRAY/i ) {
227 $self->warn("Must provide a valid Array reference to add_features");
228 return 0;
229 }
230 my $count = 0;
231 foreach my $f ( @$feats ) {
232 if( ! $f || ! ref($f) || ! $f->isa('Bio::RangeI') ) {
233 $self->warn("Must provide valid Bio::RangeI objects to add_features, skipping object '$f'\n");
234 next;
235 }
236 my $bin = bin($f->start,$f->end,$self->min_bin);
237 my $serialized = &feature_freeze($f);
238 $self->{'_btree'}->put($bin,$serialized);
239 if( $f->isa('Bio::SeqFeature::Generic') ) {
240 $self->debug( "$bin for ". $f->location->to_FTstring(). " matches ".$#{$self->{'_features'}}. "\n");
241 }
242 $count++;
243 }
244 return $count;
245 }
246  
247  
248 =head2 features_in_range
249  
250 Title : features_in_range
251 Usage : my @features = $collection->features_in_range($range)
252 Function: Retrieves a list of features which were contained or overlap the
253 the requested range (see Args for way to specify overlap or
254 only those containe)d
255 Returns : List of Bio::SeqFeatureI objects
256 Args : -range => Bio::RangeI object defining range to search,
257 OR
258 -start => start,
259 -end => end,
260 -strand => strand
261  
262 -contain => boolean - true if feature must be completely
263 contained with range
264 OR false if should include features that simply overlap
265 the range. Default: true.
266 -strandmatch => 'strong', ranges must have the same strand
267 'weak', ranges must have the same
268 strand or no strand
269 'ignore', ignore strand information
270 Default. 'ignore'.
271  
272 =cut
273  
274 sub features_in_range{
275 my $self = shift;
276 my (@args) = @_;
277 my ($range, $contain, $strandmatch,$start,$end,$strand);
278 if( @args == 1 ) {
279 $range = shift @args;
280 } else {
281 ($start,$end,$strand,$range,
282 $contain,$strandmatch) = $self->_rearrange([qw(START END
283 STRAND
284 RANGE CONTAIN
285 STRANDMATCH)],
286 @args);
287 $contain = 1 unless defined $contain;
288 }
289 $strand = 1 unless defined $strand;
290 if( $strand !~ /^([\-\+])$/ &&
291 $strand !~ /^[\-\+]?1$/ ) {
292 $self->warn("must provide a valid numeric or +/- for strand");
293 return ();
294 }
295 if( defined $1 ) { $strand .= 1; }
296  
297 if( !defined $start && !defined $end ) {
298 if( ! defined $range || !ref($range) || ! $range->isa("Bio::RangeI") )
299 {
300 $self->warn("Must defined a valid Range for the method feature_in_range");
301 return ();
302 }
303 ($start,$end,$strand) = ($range->start,$range->end,$range->strand);
304 }
305 my $r = Bio::Location::Simple->new(-start => $start,
306 -end => $end,
307 -strand => $strand);
308  
309 my @features;
310 my $maxbin = $self->max_bin;
311 my $minbin = $self->min_bin;
312 my $tier = $maxbin;
313 my ($k,$v,@bins) = ("",undef);
314 while ($tier >= $minbin) {
315 my ($tier_start,$tier_stop) = (bin_bot($tier,$start),
316 bin_top($tier,$end));
317 if( $tier_start == $tier_stop ) {
318 my @vals = $self->{'_btree'}->get_dup($tier_start);
319 if( scalar @vals > 0 ) {
320 push @bins, map { thaw($_) } @vals;
321 }
322 } else {
323 $k = $tier_start;
324 my @vals;
325 for( my $rc = $self->{'_btree'}->seq($k,$v,R_CURSOR);
326 $rc == 0;
327 $rc = $self->{'_btree'}->seq($k,$v, R_NEXT) ) {
328 last if( $k > $tier_stop || $k < $tier_start);
329 push @bins, thaw($v);
330 }
331 }
332 $tier /= 10;
333 }
334 my %seen = ();
335 foreach my $t ( map { ref($_) } @bins) {
336 next if $seen{$t}++;
337 eval "require $t";
338  
339 if( $@ ) {
340 $self->warn("Trying to thaw a stored feature $t which does not appear in your Perl library. $@");
341 next;
342 }
343 }
344 $strandmatch = 'ignore' unless defined $strandmatch;
345 return ( $contain ) ? grep { $r->contains($_,$strandmatch) } @bins :
346 grep { $r->overlaps($_,$strandmatch)} @bins;
347 }
348  
349 =head2 remove_features
350  
351 Title : remove_features
352 Usage : $collection->remove_features(\@array)
353 Function: Removes the requested sequence features (based on features
354 which have the same location)
355 Returns : Number of features removed
356 Args : Arrayref of Bio::RangeI objects
357  
358  
359 =cut
360  
361 sub remove_features{
362 my ($self,$feats) = @_;
363 if( ref($feats) !~ /ARRAY/i ) {
364 $self->warn("Must provide a valid Array reference to remove_features");
365 return 0;
366 }
367 my $countprocessed = 0;
368  
369 foreach my $f ( @$feats ) {
370 next if ! ref($f) || ! $f->isa('Bio::RangeI');
371 my $bin = bin($f->start,$f->end,$self->min_bin);
372 my @vals = $self->{'_btree'}->get_dup($bin);
373 my $vcount = scalar @vals;
374  
375 foreach my $v ( @vals ) {
376 # Once we have uniquely identifiable field
377 # I think it will work better.
378 if( $v eq &feature_freeze($f) ) {
379 $self->{'_btree'}->del_dup($bin,$v);
380 $vcount--;
381 $countprocessed++;
382 }
383 }
384 if( $vcount == 0 ) {
385 $self->{'_btree'}->del($bin);
386 }
387 }
388 $countprocessed;
389  
390 }
391  
392 =head2 get_all_features
393  
394 Title : get_all_features
395 Usage : my @f = $col->get_all_features()
396 Function: Return all the features stored in this collection (Could be large)
397 Returns : Array of Bio::RangeI objects
398 Args : None
399  
400  
401 =cut
402  
403 sub get_all_features{
404 my ($self) = @_;
405 my @features;
406 my ($key,$value);
407 for (my $status = $self->{'_btree'}->seq($key, $value, R_FIRST) ;
408 $status == 0 ;
409 $status = $self->{'_btree'}->seq($key, $value, R_NEXT) )
410 { next unless defined $value;
411 push @features, &thaw($value);
412 }
413 if( scalar @features != $self->feature_count() ) {
414 $self->warn("feature count does not match actual count\n");
415 }
416 return @features;
417 }
418  
419  
420 =head2 min_bin
421  
422 Title : min_bin
423 Usage : my $minbin= $self->min_bin;
424 Function: Get/Set the minimum value to use for binning
425 Returns : integer
426 Args : [optional] minimum bin value
427  
428  
429 =cut
430  
431 sub min_bin {
432 my ($self,$min) = @_;
433 if( defined $min ) {
434 $self->{'_min_bin'} = $min;
435 }
436 return $self->{'_min_bin'} || MIN_BIN;
437 }
438  
439 =head2 max_bin
440  
441 Title : max_bin
442 Usage : my $maxbin= $self->max_bin;
443 Function: Get/Set the maximum value to use for binning
444 Returns : integer
445 Args : [optional] maximum bin value
446  
447  
448 =cut
449  
450 sub max_bin {
451 my ($self,$max) = @_;
452 if( defined $max ) {
453 $self->{'_max_bin'} = $max;
454 }
455 return $self->{'max_bin'} || MAX_BIN;
456 }
457  
458 =head2 feature_count
459  
460 Title : feature_count
461 Usage : my $c = $col->feature_count()
462 Function: Retrieve the total number of features in the collection
463 Returns : integer
464 Args : none
465  
466  
467 =cut
468  
469 sub feature_count {
470 my $self = shift;
471 my $count = 0;
472 for ( keys %{$self->{'_btreehash'}} ) {
473 my $v = $self->{'_btreehash'}->{$_};
474 next unless defined $v;
475 $count++;
476 }
477 $count;
478 }
479  
480 =head2 indexfile
481  
482 Title : indexfile
483 Usage : $obj->indexfile($newval)
484 Function: Get/set the filename where index is kept
485 Returns : value of indexfile (a filename string)
486 Args : on set, new value (a filename string )
487  
488  
489 =cut
490  
491 sub indexfile{
492 my $self = shift;
493  
494 return $self->{'indexfile'} = shift if @_;
495 return $self->{'indexfile'};
496 }
497  
498 =head2 keep
499  
500 Title : keep
501 Usage : $obj->keep($newval)
502 Function: Get/set boolean flag to keep the indexfile after
503 exiting program
504 Example :
505 Returns : value of keep (boolean)
506 Args : on set, new value (boolean)
507  
508  
509 =cut
510  
511 sub keep{
512 my $self = shift;
513  
514 return $self->{'keep'} = shift if @_;
515 return $self->{'keep'};
516 }
517  
518 sub _compare{
519 if( defined $_[0] && ! defined $_[1]) {
520 return -1;
521 } elsif ( defined $_[1] && ! defined $_[0]) {
522 return 1;
523 }
524 $_[0] <=> $_[1];
525 }
526  
527 sub feature_freeze {
528 my $obj = shift;
529 _remove_cleanup_methods($obj);
530 return freeze($obj);
531 }
532  
533 sub _remove_cleanup_methods {
534 my $obj = shift;
535
536 # we have to remove any cleanup methods here for Storable
537 for my $funcref ( $obj->_cleanup_methods ) {
538 $obj->_unregister_for_cleanup($funcref);
539 }
540
541 # ... and the same for any contained features; hopefully any implementations
542 # adhere to implementing Bio::SeqFeatureI::sub_SeqFeature
543
544 for my $contained ($obj->sub_SeqFeature) {
545 _remove_cleanup_methods($contained);
546 }
547
548 1;
549 }
550  
551 sub feature_thaw {
552 return thaw(shift);
553 }
554  
555 sub DESTROY {
556 my $self = shift;
557 $self->{'_btree'} = undef;
558 untie(%{$self->{'_btreehash'}});
559 if( ! $self->keep && $self->indexfile ) {
560 my $f = $self->indexfile;
561 $self->debug( "unlinking ".$f. "\n");
562 close($f);
563 unlink($f);
564 }
565 $self->SUPER::DESTROY();
566 }
567  
568 1;
« Bio/DB/Taxonomy/flatfile.pm ↑ Summary Bio/SeqIO/bsml.pm »