Bio/Search/Result/BlastResult.pm

filter: Statementstmt 53.5% 61 / 114 Branchbran 31.5% 12 / 38 Conditioncond 0.0% 0 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 47.6% 10 / 21 Podpod 100% 17 / 17 totaltotal 50.5% 100 / 198 CC 26 SCAR 21.4
CC
26
Cov
46%
no_hits_found
30.0
iteration
20.0
num_hits
12.0
CRAP 8.5
« Bio/LocatableSeq.pm ↑ Summary Bio/Tools/FootPrinter.pm »
1 #
2 # BioPerl module for Bio::Search::Result::BlastResult
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Steve Chervitz <sac@bioperl.org>
7 #
8 # Copyright Steve Chervitz
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::Search::Result::BlastResult - Blast-specific subclass of Bio::Search::Result::GenericResult
17  
18 =head1 SYNOPSIS
19  
20 # Working with iterations (PSI-BLAST results)
21  
22 $result->next_iteration();
23 $result->num_iterations();
24 $result->iteration();
25 $result->iterations();
26  
27 # See Bio::Search::Result::GenericResult for information about working with Results.
28  
29 # See L<Bio::Search::Iteration::IterationI|Bio::Search::Iteration::IterationI>
30 # for details about working with iterations.
31  
32 # TODO:
33 # * Show how to configure a SearchIO stream so that it generates
34 # BlastResult objects.
35  
36  
37 =head1 DESCRIPTION
38  
39 This object is a subclass of Bio::Search::Result::GenericResult
40 and provides some operations that facilitate working with BLAST
41 and PSI-BLAST results.
42  
43 For general information about working with Results, see
44 Bio::Search::Result::GenericResult.
45  
46 =head1 FEEDBACK
47  
48 =head2 Mailing Lists
49  
50 User feedback is an integral part of the evolution of this and other
51 Bioperl modules. Send your comments and suggestions preferably to
52 the Bioperl mailing list. Your participation is much appreciated.
53  
54 bioperl-l@bioperl.org - General discussion
55 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
56  
57 =head2 Support
58  
59 Please direct usage questions or support issues to the mailing list:
60  
61 I<bioperl-l@bioperl.org>
62  
63 rather than to the module maintainer directly. Many experienced and
64 reponsive experts will be able look at the problem and quickly
65 address it. Please include a thorough description of the problem
66 with code and data examples if at all possible.
67  
68 =head2 Reporting Bugs
69  
70 Report bugs to the Bioperl bug tracking system to help us keep track
71 of the bugs and their resolution. Bug reports can be submitted via the
72 web:
73  
74 https://github.com/bioperl/bioperl-live/issues
75  
76 =head1 AUTHOR - Steve Chervitz
77  
78 Email sac@bioperl.org
79  
80 =head1 APPENDIX
81  
82 The rest of the documentation details each of the object methods.
83 Internal methods are usually preceded with a _
84  
85 =cut
86  
87  
88 # Let the code begin...
89  
90  
91 package Bio::Search::Result::BlastResult;
92 12 $Bio::Search::Result::BlastResult::VERSION = '1.7.8';
93 12 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
94  
95 12 ▶use Bio::Search::BlastStatistics;
Subroutine BEGIN: called CC=1 SCAR=0.0
96  
97 12 ▶use base qw(Bio::Search::Result::GenericResult);
Subroutine BEGIN: called CC=1 SCAR=0.0
98  
99 =head2 new
100  
101 Title : new
102 Usage : my $obj = Bio::Search::Result::BlastResult->new();
103 Function: Builds a new Bio::Search::Result::BlastResult object
104 Returns : Bio::Search::Result::BlastResult
105 Args : See Bio::Search::Result::GenericResult();
106 The following parameters are specific to BlastResult:
107 -iterations => array ref of Bio::Search::Iteration::IterationI objects
108 -inclusion_threshold => e-value threshold for inclusion in the
109 PSI-BLAST score matrix model (blastpgp)
110  
111 =cut
112  
113 40 ▶sub new {
Subroutine new: called CC=4 SCAR=14.2
Pod documented
114 40 my($class,@args) = @_;
115  
116 40 my $self = $class->SUPER::new(@args);
117  
118 40 $self->{'_iterations'} = [];
119 40 $self->{'_iteration_index'} = 0;
120 40 $self->{'_iteration_count'} = 0;
121  
122 40 my( $iters, $ithresh ) = $self->_rearrange([qw(ITERATIONS
123 INCLUSION_THRESHOLD)],@args);
124  
125 40 $self->{'_inclusion_threshold'} = $ithresh; # This is a read-only variable
126  
127 40 ▶ if( defined $iters ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $iters) { } 40 0 40
128 40 ▶ $self->throw("Must define arrayref of Iterations when initializing a $class\n") unless ref($iters) =~ /array/i;
Branch: 1 branch
BranchTrueFalseTotal
unless ref($iters) =~ /array/i 0 40 40
129  
130 40 foreach my $i ( @{$iters} ) {
131 40 $self->add_iteration($i);
132 }
133 }
134 else {
135 # This shouldn't get called with the new SearchIO::blast.
136 0 print STDERR "BlastResult::new(): Not adding iterations.\n";
137 0 $self->{'_no_iterations'} = 1;
138 }
139  
140 40 return $self;
141 }
142  
143  
144 =head2 hits
145  
146 Title : hits
147 Usage : my @hits = $result->hits
148 Function: Returns the available hits for this Result
149 Returns : Array of L<Bio::Search::Hit::HitI> objects
150 Args : none
151 Note : This method overrides L<Bio::Search::Result::GenericResult::hits> to
152 take into account the possibility of multiple iterations, as occurs
153 in PSI-BLAST reports.
154 If there are multiple iterations, all 'new' hits for all iterations
155 are returned. These are the hits that did not occur in a previous
156 iteration.
157  
158 See Also: L<Bio::Search::Result::GenericResult::hits>
159  
160 =cut
161  
162 3 ▶sub hits {
Subroutine hits: called CC=3 SCAR=11.3
Pod documented
163 3 my ($self) = shift;
164 3 ▶ if ($self->{'_no_iterations'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_no_iterations"}) 0 3 3
165 0 return $self->SUPER::hits;
166 }
167 3 my @hits = ();
168 3 foreach my $it ($self->iterations) {
169 3 push @hits, $it->hits;
170 }
171 3 return @hits;
172 }
173  
174 =head2 next_hit
175  
176 Title : next_hit
177 Usage : while( $hit = $result->next_hit()) { ... }
178 Function: Returns the next available Hit object, representing potential
179 matches between the query and various entities from the database.
180 Returns : a Bio::Search::Hit::HitI object or undef if there are no more.
181 Args : none
182 Note : This method overrides L<Bio::Search::Result::GenericResult::next_hit>
183 to take into account the possibility of multiple iterations, as
184 occurs in PSI-BLAST reports.
185  
186 If there are multiple iterations, calling next_hit() traverses the
187 all of the hits, old and new, for each iteration, calling next_hit()
188 on each iteration.
189  
190 See Also: L<Bio::Search::Iteration::GenericIteration::next_hit>
191  
192 =cut
193  
194 749 ▶sub next_hit {
Subroutine next_hit: called CC=5 SCAR=16.1
Pod documented
195 749 my ($self,@args) = @_;
196 749 ▶ if ($self->{'_no_iterations'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_no_iterations"}) 0 749 749
197 0 return $self->SUPER::next_hit(@args);
198 }
199  
200 749 my $iter_index;
201 749 ▶ if (not defined $self->{'_last_hit'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $self->{'_last_hit'}) { } 56 693 749
202 56 $iter_index = $self->{'_iter_index'} = $self->_next_iteration_index;
203 } else {
204 693 $iter_index = $self->{'_iter_index'};
205 }
206  
207 749 ▶ return if $iter_index >= scalar @{$self->{'_iterations'}};
Branch: 1 branch
BranchTrueFalseTotal
if $iter_index >= scalar @{$self->{"_iterations"};} 19 730 749
208  
209 730 my $it = $self->{'_iterations'}->[$iter_index];
210 730 my $hit = $self->{'_last_hit'} = $it->next_hit;
211  
212 730 ▶ return defined($hit) ? $hit : $self->next_hit;
Branch: 1 branch
BranchTrueFalseTotal
defined $hit ? : 708 22 730
213 }
214  
215  
216 =head2 num_hits
217  
218 Title : num_hits
219 Usage : my $hitcount= $result->num_hits
220 Function: returns the number of hits for this query result
221 Returns : integer
222 Args : none
223 Note : This method overrides L<Bio::Search::Result::GenericResult::num_hits>
224 to take into account the possibility of multiple iterations, as
225 occurs in PSI-BLAST reports.
226  
227 If there are multiple iterations, calling num_hits() returns the
228 number of 'new' hits for each iteration. These are the hits that did
229 not occur in a previous iteration.
230  
231 See Also: L<Bio::Search::Result::GenericResult::num_hits>
232  
233 =cut
234  
235 0 ▶sub num_hits{
Subroutine num_hits: not called CC=3 SCAR=24.8
Pod documented
236 0 my ($self) = shift;
237 0 ▶ if ($self->{'_no_iterations'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_no_iterations"}) 0 0 0
238 0 return $self->SUPER::num_hits;
239 }
240 0 ▶ if (not defined $self->{'_iterations'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_iterations"}) 0 0 0
241 0 $self->throw("Can't get Hits: data not collected.");
242 }
243 0 return scalar( $self->hits );
244 }
245  
246 =head2 add_hit
247  
248 Title : add_hit
249 Usage : $report->add_hit($hit)
250 Function: Adds a HitI to the stored list of hits
251 Returns : Number of HitI currently stored
252 Args : Bio::Search::Hit::HitI
253  
254 =cut
255  
256 0 ▶sub add_hit {
Subroutine add_hit: not called CC=2 SCAR=17.9
Pod documented
257 0 my ($self,$hit) = @_;
258 0 my $iter = $self->iteration;
259 0 ▶ if( $hit->isa('Bio::Search::Hit::HitI') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hit->isa('Bio::Search::Hit::HitI')) { } 0 0 0
260 0 return $iter->add_hit(-hit => $hit);
261 } else {
262 0 $self->throw("Passed in a " .ref($hit).
263 " as a Iteration which is not a Bio::Search::Hit::HitI.");
264 }
265 0 return $iter->num_hits;
266 }
267  
268 =head2 add_iteration
269  
270 Title : add_iteration
271 Usage : $report->add_iteration($iteration)
272 Function: Adds a IterationI to the stored list of iterations
273 Returns : Number of IterationI currently stored
274 Args : Bio::Search::Iteration::IterationI
275  
276 =cut
277  
278 40 ▶sub add_iteration {
Subroutine add_iteration: called CC=2 SCAR=7.1
Pod documented
279 40 my ($self,$i) = @_;
280 40 ▶ if( $i->isa('Bio::Search::Iteration::IterationI') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i->isa('Bio::Search::Iteration::IterationI')) { } 40 0 40
281 40 push @{$self->{'_iterations'}}, $i;
282 40 $self->{'_iteration_count'}++;
283 } else {
284 0 $self->throw("Passed in a " .ref($i).
285 " as a Iteration which is not a Bio::Search::Iteration::IterationI.");
286 }
287 40 return scalar @{$self->{'_iterations'}};
288 }
289  
290  
291 =head2 next_iteration
292  
293 Title : next_iteration
294 Usage : while( $it = $result->next_iteration()) { ... }
295 Function: Returns the next Iteration object, representing all hits
296 found within a given PSI-Blast iteration.
297 Returns : a Bio::Search::Iteration::IterationI object or undef if there are no more.
298 Args : none
299  
300 =cut
301  
302 0 ▶sub next_iteration {
Subroutine next_iteration: not called CC=2 SCAR=17.9
Pod documented
303 0 my ($self) = @_;
304  
305 0 ▶ unless($self->{'_iter_queue_started'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_iter_queue_started"}) 0 0 0
306 0 $self->{'_iter_queue'} = [$self->iterations()];
307 0 $self->{'_iter_queue_started'} = 1;
308 }
309 0 return shift @{$self->{'_iter_queue'}};
310 }
311  
312 =head2 iteration
313  
314 Usage : $iteration = $blast->iteration( $number );
315 Purpose : Get an IterationI object for the specified iteration
316 in the search result (PSI-BLAST).
317 Returns : Bio::Search::Iteration::IterationI object
318 Throws : Bio::Root::NoSuchThing exception if $number is not within
319 range of the number of iterations in this report.
320 Argument : integer (optional, if not specified get the last iteration)
321 First iteration = 1
322  
323 =cut
324  
325 0 ▶sub iteration {
Subroutine iteration: not called CC=4 SCAR=30.0
Pod documented
326 0 my ($self,$num) = @_;
327 0 ▶ $num = scalar @{$self->{'_iterations'}} unless defined $num;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $num 0 0 0
328 0 ▶ unless ($num >= 1 and $num <= scalar $self->{'_iteration_count'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($num >= 1 and $num <= scalar $self->{"_iteration_count"}) 0 0 0
Condition0%0/3
$num >= 1 and $num <= scalar $self->{"_iteration_count"}
!ll&&!rl&&r
000
MC/DC0%0/2
$num >= 1 and $num <= scalar $self->{"_iteration_count"}
$num >= 1 $num <= scalar $self->{"_iteration_count"}
Truth table0%0/3
A and B
A= $num >= 1B= $num <= scalar $self->{"_iteration_count"}
ABresult
0X0
100
111
329 0 $self->throw(-class=>'Bio::Root::NoSuchThing',
330 -text=>"No such iteration number: $num. Valid range=1-$self->{'_iteration_count'}",
331 -value=>$num);
332 }
333 0 return $self->{'_iterations'}->[$num-1];
334 }
335  
336 =head2 num_iterations
337  
338 Usage : $num_iterations = $blast->num_iterations;
339 Purpose : Get the number of iterations in the search result (PSI-BLAST).
340 Returns : Total number of iterations in the report
341 Argument : none (read-only)
342  
343 =cut
344  
345 0 ▶sub num_iterations { shift->{'_iteration_count'} }
Subroutine num_iterations: not called CC=1 SCAR=6.9
Pod documented
346  
347 # Methods provided for consistency with BPpsilite.pm (now deprecated);
348 # these are now merely synonyms
349  
350 =head2 number_of_iterations
351  
352 Usage : $num_iterations = $blast->number_of_iterations;
353 Purpose : Get the number of iterations in the search result (PSI-BLAST).
354 Returns : Total number of iterations in the report
355 Argument : none (read-only)
356 Note : Alias of L<num_iterations>.
357  
358 =cut
359  
360 0 ▶sub number_of_iterations { shift->num_iterations }
Subroutine number_of_iterations: not called CC=1 SCAR=6.9
Pod documented
361  
362 =head2 round
363  
364 Usage : $round = $blast->round( $number );
365 Purpose : Get an IterationI object for the specified iteration
366 in the search result (PSI-BLAST).
367 Returns : Bio::Search::Iteration::IterationI object
368 Throws : Bio::Root::NoSuchThing exception if $number is not within
369 range of the number of iterations in this report.
370 Argument : integer (optional, if not specified get the last iteration)
371 First iteration = 1
372 Note : Alias of L<iteration>.
373  
374 =cut
375  
376 0 ▶sub round { shift->iteration(@_) }
Subroutine round: not called CC=1 SCAR=6.9
Pod documented
377  
378  
379 =head2 iterations
380  
381 Title : iterations
382 Usage : my @iterations = $result->iterations
383 Function: Returns the IterationI objects contained within this Result
384 Returns : Array of L<Bio::Search::Iteration::IterationI> objects
385 Args : none
386  
387 =cut
388  
389 8 ▶sub iterations {
Subroutine iterations: called CC=2 SCAR=7.0
Pod documented
390 8 my $self = shift;
391 8 my @its = ();
392 8 ▶ if( ref($self->{'_iterations'}) =~ /ARRAY/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref($self->{"_iterations"}) =~ /ARRAY/i) 8 0 8
393 8 @its = @{$self->{'_iterations'}};
394 }
395 8 return @its;
396 }
397  
398 =head2 psiblast
399  
400 Usage : if( $blast->psiblast ) { ... }
401 Purpose : Set/get a boolean indicator whether or not the report
402 is a PSI-BLAST report.
403 Returns : 1 if PSI-BLAST, undef if not.
404 Argument : 1 (when setting)
405  
406 =cut
407  
408 #----------------
409 0 ▶sub psiblast {
Subroutine psiblast: not called CC=2 SCAR=17.9
Pod documented
410 #----------------
411 0 my ($self, $val ) = @_;
412 0 ▶ if( $val ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($val) 0 0 0
413 0 $self->{'_psiblast'} = 1;
414 }
415 0 return $self->{'_psiblast'};
416 }
417  
418  
419 =head2 no_hits_found
420  
421 Usage : $nohits = $blast->no_hits_found( $iteration_number );
422 Purpose : Get boolean indicator indicating whether or not any hits
423 were present in the report.
424  
425 This is NOT the same as determining the number of hits via
426 the hits() method, which will return zero hits if there were no
427 hits in the report or if all hits were filtered out during the parse.
428  
429 Thus, this method can be used to distinguish these possibilities
430 for hitless reports generated when filtering.
431  
432 Returns : Boolean
433 Argument : (optional) integer indicating the iteration number (PSI-BLAST)
434 If iteration number is not specified and this is a PSI-BLAST result,
435 then this method will return true only if all iterations had
436 no hits found.
437  
438 =cut
439  
440 0 ▶sub no_hits_found {
Subroutine no_hits_found: not called CC=5 SCAR=34.0
Pod documented
441 0 my ($self, $round) = @_;
442  
443 0 my $result = 0; # final return value of this method.
444 # Watch the double negative!
445 # result = 0 means "yes hits were found"
446 # result = 1 means "no hits were found" (for the indicated iteration or all iterations)
447  
448 # If a iteration was not specified and there were multiple iterations,
449 # this method should return true only if all iterations had no hits found.
450 0 ▶ if( not defined $round ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $round) { } 0 0 0
451 0 ▶ if( $self->{'_iterations'} > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'_iterations'} > 1) { } 0 0 0
452 0 $result = 1;
453 0 foreach my $i( 1..$self->{'_iterations'} ) {
454 0 ▶ if( not defined $self->{"_iteration_$i"}->{'_no_hits_found'} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $$self{"_iteration_$i"}{"_no_hits_found"}) 0 0 0
455 0 $result = 0;
456 0 last;
457 }
458 }
459 }
460 else {
461 0 $result = $self->{"_iteration_1"}->{'_no_hits_found'};
462 }
463 }
464 else {
465 0 $result = $self->{"_iteration_$round"}->{'_no_hits_found'};
466 }
467  
468 0 return $result;
469 }
470  
471  
472 =head2 set_no_hits_found
473  
474 Usage : $blast->set_no_hits_found( $iteration_number );
475 Purpose : Set boolean indicator indicating whether or not any hits
476 were present in the report.
477 Returns : n/a
478 Argument : (optional) integer indicating the iteration number (PSI-BLAST)
479  
480 =cut
481  
482 0 ▶sub set_no_hits_found {
Subroutine set_no_hits_found: not called CC=2 SCAR=17.9
Pod documented
483 0 my ($self, $round) = @_;
484 0 ▶ $round ||= 1;
Condition0%0/2
$round ||= 1
l!l
00
MC/DC0%0/1
$round ||= 1
$round
Truth table0%0/2
A
A= $round
Aresult
11
00
485 0 $self->{"_iteration_$round"}->{'_no_hits_found'} = 1;
486 }
487  
488 =head2 _next_iteration_index
489  
490 Title : _next_iteration_index
491 Usage : private
492  
493 =cut
494  
495 56 ▶sub _next_iteration_index{
Subroutine _next_iteration_index: called CC=1 SCAR=0.0
496 56 my ($self,@args) = @_;
497 56 return $self->{'_iteration_index'}++;
498 }
499  
500  
501 =head2 rewind
502  
503 Title : rewind
504 Usage : $result->rewind;
505 Function: Allow one to reset the Iteration iterator to the beginning
506 Since this is an in-memory implementation
507 Returns : none
508 Args : none
509  
510 =cut
511  
512 5 ▶sub rewind {
Subroutine rewind: called CC=2 SCAR=6.9
Pod documented
513 5 my $self = shift;
514 5 $self->SUPER::rewind(@_);
515 5 $self->{'_iteration_index'} = 0;
516 5 foreach ($self->iterations) {
517 5 $_->rewind;
518 }
519 }
520  
521  
522 =head2 inclusion_threshold
523  
524 Title : inclusion_threshold
525 Usage : my $incl_thresh = $result->inclusion_threshold; (read-only)
526 Function: Gets the e-value threshold for inclusion in the PSI-BLAST
527 score matrix model (blastpgp) that was used for generating the report
528 being parsed.
529 Returns : number (real) or undef if not a PSI-BLAST report.
530 Args : none
531  
532 =cut
533  
534 0 ▶sub inclusion_threshold {
Subroutine inclusion_threshold: not called CC=1 SCAR=6.9
Pod documented
535 0 my $self = shift;
536 0 return $self->{'_inclusion_threshold'};
537 }
538  
539 12 1;
« Bio/LocatableSeq.pm ↑ Summary Bio/Tools/FootPrinter.pm »