Bio/Search/Iteration/IterationI.pm

filter: Statementstmt 22.8% 8 / 35 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 9.5% 2 / 21 Podpod 100% 19 / 19 totaltotal 38.6% 29 / 75 CC 1 SCAR 6.4
CC
1
Cov
23%
number
2.0
converged
2.0
next_hit
2.0
CRAP 1.9
« Bio/Align/AlignI.pm ↑ Summary Bio/Seq/MetaI.pm »
1 #-----------------------------------------------------------------
2 #
3 # BioPerl module Bio::Search::Iteration::IterationI
4 #
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 #
7 # Cared for by Steve Chervitz <sac@bioperl.org>
8 #
9 # You may distribute this module under the same terms as perl itself
10 #-----------------------------------------------------------------
11  
12 # POD documentation - main docs before the code
13  
14 =head1 NAME
15  
16 Bio::Search::Iteration::IterationI - Abstract interface to an
17 iteration from an iterated search result, such as PSI-BLAST.
18  
19 =head1 SYNOPSIS
20  
21 # Bio::Search::Iteration::IterationI objects cannot be
22 # instantiated since this module defines a pure interface.
23 # Given an object that implements the
24 # Bio::Search::Iteration::IterationI interface,
25 # you can do the following things with it:
26  
27 # First, open up a SearchIO stream
28 use Bio::SearchIO;
29 my $file = shift or die "Usage: $0 <BLAST-report-file>\n";
30 my $in = Bio::SearchIO->new(-format => 'blast',
31 -file => $file # comment out this line to read STDIN
32 );
33 # Iterate over all results in the input stream
34 while (my $result = $in->next_result) {
35  
36 printf "Result #%d: %s\n", $in->result_count, $result->to_string;
37 printf "Total Iterations: %d\n", $result->num_iterations();
38  
39 # Iterate over all iterations and process old and new hits
40 # separately.
41  
42 while( my $it = $result->next_iteration) {
43 printf "\nIteration %d\n", $it->number;
44 printf "Converged: %d\n", $it->converged;
45  
46 # Print out the hits not found in previous iteration
47 printf "New hits: %d\n", $it->num_hits_new;
48 while( my $hit = $it->next_hit_new ) {
49 printf " %s, Expect=%g\n", $hit->name, $hit->expect;
50 }
51  
52 # Print out the hits found in previous iteration
53 printf "Old hits: %d\n", $it->num_hits_old;
54 while( my $hit = $it->next_hit_old ) {
55 printf " %s, Expect=%g\n", $hit->name, $hit->expect;
56 }
57 }
58 printf "%s\n\n", '-' x 50;
59 }
60  
61 printf "Total Reports processed: %d: %s\n", $in->result_count;
62  
63 __END__
64  
65 # NOTE: The following functionality is just proposed
66 # (does not yet exist but might, given sufficient hew and cry):
67  
68 # Zero-in on the new hits found in last iteration.
69 # By default, iteration() returns the last one.
70  
71 my $last_iteration = $result->iteration();
72 while( my $hit = $last_iteration->next_hit) {
73 # Do something with new hit...
74 }
75  
76 # Get the first iteration
77  
78 my $first_iteration = $result->iteration(1);
79  
80  
81 =head1 DESCRIPTION
82  
83 Bio::Search::Result::ResultI objects are data structures containing
84 the results from the execution of a search algorithm. As such, it may
85 contain various algorithm specific information as well as details of
86 the execution, but will contain a few fundamental elements, including
87 the ability to return Bio::Search::Hit::HitI objects.
88  
89 =head2 Classification of Hits
90  
91 Within a given iteration, the hits can be classified into a number of
92 useful subsets based on whether or not the hit appeard in a previous
93 iteration and whether or not the hit is below the threshold E-value
94 for inclusion in the score matrix model.
95  
96 All hits
97 (A)
98 _______________|_________________
99 | |
100 New hits Old hits
101 (B) (C)
102 _________|________ _______|_________
103 | | | |
104 Below Above Below Above
105 threshold threshold threshold threshold
106 (D) (E) (F) (G)
107 _________|___________
108 | |
109 Occurred in a Occurred in a
110 previous iteration previous iteration
111 below threshold above threshold
112 (H) (I)
113  
114 Notes: The term I<threshold> in the diagram and descriptions below
115 refer to this inclusion threshold. I<Below threshold> actually means
116 I<at or below threshold>.
117  
118 The IterationI interface defines a number of methods for extracting
119 these subsets of hits.
120  
121 =over 4
122  
123 =item * newhits_below_threshold() [subset D]
124  
125 Hits that did not appear in a previous iteration and are below
126 threshold in the current iteration.
127  
128 =item * newhits_not_below_threshold() [subset E]
129  
130 Hits that did not appear in a previous iteration and are not below
131 threshold in the current iteration.
132  
133 =item * newhits() [subset B]
134  
135 All newly found hits, below and above the inclusion threshold. This
136 is the union of newhits_below_threshold() + newhits_not_below_threshold()
137 [subset D + subset E].
138  
139 =item * oldhits_below_threshold() [subset H]
140  
141 Hits that appeared in a previous iteration below threshold and are
142 still below threshold in the current iteration.
143  
144 =item * oldhits_newly_below_threshold() [subset I]
145  
146 Hits that appeared in a previous iteration above threshold but are
147 below threshold in the current iteration. (Not applicable to the first
148 iteration.)
149  
150 =item * oldhits_not_below_threshold() [subset G]
151  
152 Hits that appeared in a previous iteration not below threshold and
153 are still not below threshold in the current iteration.
154  
155 =item * oldhits() [subset C]
156  
157 All hits that occurred in a previous iteration, whether below or above
158 threshold in the current iteration. Union of oldhits_below_threshold()
159 + oldhits_newly_below_threshold() + oldhits_not_below_threshold()
160 [subset H + subset I + subset G]. (Not applicable to the first
161 iteration.)
162  
163 =item * hits_below_threshold() [subset D + subset F]
164  
165 All hits, old and new, that are below the inclusion threshold in this
166 iteration. This is the union of newhits_below_threshold() +
167 oldhits_below_threshold() + oldhits_newly_below_threshold()
168 [subset D + subset H + subset I].
169  
170 =item * hits() [subset A]
171  
172 The union of newhits() and oldhits() [subset B + subset C].
173  
174 =back
175  
176 For the first iteration, the methods L<oldhits>, L<oldhits_below_threshold>,
177 L<oldhits_newly_below_threshold>, and oldhits_not_below_threshold()
178 will return empty lists.
179  
180 Iterator and numbers-of-hit methods are provided for subsets A, B, and C:
181  
182 =over 4
183  
184 =item * next_hit_new(), num_hits_new() [subset B]
185  
186 =item * next_hit_old(), num_hits_old() [subset C]
187  
188 =item * next_hit(), num_hits() [subset A]
189  
190 =back
191  
192 =head1 FEEDBACK
193  
194 =head2 Mailing Lists
195  
196 User feedback is an integral part of the evolution of this and other
197 Bioperl modules. Send your comments and suggestions preferably to one
198 of the Bioperl mailing lists. Your participation is much appreciated.
199  
200 bioperl-l@bioperl.org - General discussion
201 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
202  
203 =head2 Support
204  
205 Please direct usage questions or support issues to the mailing list:
206  
207 I<bioperl-l@bioperl.org>
208  
209 rather than to the module maintainer directly. Many experienced and
210 reponsive experts will be able look at the problem and quickly
211 address it. Please include a thorough description of the problem
212 with code and data examples if at all possible.
213  
214 =head2 Reporting Bugs
215  
216 Report bugs to the Bioperl bug tracking system to help us keep track
217 the bugs and their resolution. Bug reports can be submitted via the
218 web:
219  
220 https://github.com/bioperl/bioperl-live/issues
221  
222 =head1 AUTHOR
223  
224 Steve Chervitz E<lt>sac@bioperl.orgE<gt>
225  
226 See L<the FEEDBACK section | FEEDBACK> for where to send bug reports and comments.
227  
228 =head1 COPYRIGHT
229  
230 Copyright (c) 2003 Steve Chervitz. All Rights Reserved.
231  
232 =head1 DISCLAIMER
233  
234 This software is provided "as is" without warranty of any kind.
235  
236 =head1 APPENDIX
237  
238 The rest of the documentation details each of the object
239 methods. Internal methods are usually preceded with a _
240  
241 =cut
242  
243 #'
244 # Let the code begin...
245  
246  
247 package Bio::Search::Iteration::IterationI;
248 13 $Bio::Search::Iteration::IterationI::VERSION = '1.7.8';
249 13 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
250  
251  
252 13 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
253  
254 =head2 number
255  
256 Title : number
257 Usage : $it_number = $iteration->number();
258 Purpose : returns the number of the iteration (a.k.a "round")
259 within the Result.
260 Returns : integer
261 Args : [optional] integer to set the number of the iteration
262  
263 =cut
264  
265 0 ▶sub number {
Subroutine number: not called CC=1 SCAR=6.9
Pod documented
266 0 my ($self,@args) = @_;
267 0 $self->throw_not_implemented;
268 }
269  
270 =head2 converged
271  
272 Title : converged
273 Usage : $it_converged = $iteration->converged();
274 Purpose : Indicates whether or not the iteration has converged
275 Returns : boolean
276 Args : [optional] boolean value to set the converged of the iteration
277  
278 =cut
279  
280 0 ▶sub converged {
Subroutine converged: not called CC=1 SCAR=6.9
Pod documented
281 0 my ($self,@args) = @_;
282 0 $self->throw_not_implemented;
283 }
284  
285 =head2 next_hit
286  
287 Title : next_hit
288 Usage : while( $hit = $iteration->next_hit( [$found_again]) ) { ... }
289 Purpose : Iterates through all of the HitI objects
290 including new hits and old hits found in a previous iteration
291 and both below and above the inclusion threshold.
292 Corresponds to subset A in the "Classification of Hits"
293 documentation section of this module.
294 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
295 Hits will be returned in the order in which they occur in the report
296 unless otherwise specified.
297 Args : none
298  
299 See Also: L<hits>, L<Classification of Hits>
300  
301 next_hit() iterates through all hits, including the new ones
302 for this iteration and those found in previous iterations.
303 You can interrogate each hit using L<Bio::Search::Hit::HitI::found_again>
304 to determine whether it is new or old.
305  
306 To get just the new hits, use L<next_hit_new>.
307 To get just the old hits, use L<next_hit_old>.
308  
309 =cut
310  
311 0 ▶sub next_hit {
Subroutine next_hit: not called CC=1 SCAR=6.9
Pod documented
312 0 my ($self,@args) = @_;
313 0 $self->throw_not_implemented;
314 }
315  
316 =head2 next_hit_new
317  
318 Title : next_hit_new
319 Usage : while( $hit = $iteration->next_hit_new() ) { ... }
320 Purpose : Iterates through all newly found hits (did not occur in a
321 previous iteration) and are either below or above the inclusion threshold.
322 Corresponds to subset B in the "Classification of Hits"
323 documentation section of this module.
324 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
325 Hits will be returned in the order in which they occur in the report
326 unless otherwise specified.
327 Args : none
328  
329 See Also: L<next_hit>, L<next_hit_old>, L<newhits>, L<Classification of Hits>
330  
331 =cut
332  
333 0 ▶sub next_hit_new {
Subroutine next_hit_new: not called CC=1 SCAR=6.9
Pod documented
334 0 my ($self,@args) = @_;
335 0 $self->throw_not_implemented;
336 }
337  
338 =head2 next_hit_old
339  
340 Title : next_hit_old
341 Usage : while( $hit = $iteration->next_hit_old() ) { ... }
342 Purpose : Iterates through the Hit objects representing just the
343 hits that have been found in a previous iteration, whether
344 below or above the inclusion threshold.
345 Corresponds to subset C in the "Classification of Hits"
346 documentation section of this module.
347 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
348 Hits will be returned in the order in which they occur in the report
349 unless otherwise specified.
350 Args : none
351  
352 See Also: L<next_hit>, L<next_hit_old>, L<oldhits>, L<Classification of Hits>
353  
354 =cut
355  
356 0 ▶sub next_hit_old {
Subroutine next_hit_old: not called CC=1 SCAR=6.9
Pod documented
357 0 my ($self,@args) = @_;
358 0 $self->throw_not_implemented;
359 }
360  
361 =head2 num_hits
362  
363 Title : num_hits
364 Usage : my $hitcount_total = $iteration->num_hits
365 Purpose : Returns the total number of hits for this query result, including new and old
366 below and above inclusion threshold.
367 Returns : integer
368 Args : none
369  
370 See Also: L<num_hits_new>, L<num_hits_old>, L<Classification of Hits>
371  
372 =cut
373  
374 0 ▶sub num_hits {
Subroutine num_hits: not called CC=1 SCAR=6.9
Pod documented
375 0 my ($self,@args) = @_;
376 0 $self->throw_not_implemented();
377 }
378  
379 =head2 num_hits_new
380  
381 Title : num_hits_new
382 Usage : my $hitcount_new = $result->num_hits_new;
383 : my $hitcount_new_below_thresh = $result->num_hits_new( 1 );
384 Purpose : Returns the number of new hits in this iteration that were not
385 found in a previous iteration and are either below or above the
386 the inclusion threshold.
387 Corresponds to subset B in the "Classification of Hits"
388 documentation section of this module.
389 Returns : integer
390 Args : (optional) boolean, true if you want to get a count of just the new hits
391 that are below the inclusion threshold.
392  
393  
394 See Also: L<num_hits>, L<num_hits_old>, L<Classification of Hits>
395  
396 =cut
397  
398 0 ▶sub num_hits_new {
Subroutine num_hits_new: not called CC=1 SCAR=6.9
Pod documented
399 0 my ($self,@args) = @_;
400 0 $self->throw_not_implemented();
401 }
402  
403 =head2 num_hits_old
404  
405 Title : num_hits_old
406 Usage : my $hitcount_old = $result->num_hits_old;
407 : my $hitcount_old_below_thresh = $result->num_hits_old( 1 );
408 Purpose : Returns the number of new hits in this iteration that were
409 found in a previous iteration and are either below or above the
410 the inclusion threshold.
411 Corresponds to subset C in the "Classification of Hits"
412 documentation section of this module.
413 Returns : integer
414 Args : (optional) boolean, true if you want to get a count of just the old hits
415 that are below the inclusion threshold.
416  
417 See Also: L<num_hits>, L<num_hits_new>, L<Classification of Hits>
418  
419 =cut
420  
421 0 ▶sub num_hits_old {
Subroutine num_hits_old: not called CC=1 SCAR=6.9
Pod documented
422 0 my ($self,@args) = @_;
423 0 $self->throw_not_implemented();
424 }
425  
426 =head2 hits
427  
428 Title : hits
429 Usage : foreach( $obj->hits() ) { ... };
430 Purpose : Provides access to all hits, both new and old, and either
431 below or above the inclusion threshold.
432 Corresponds to subset A in the "Classification of Hits"
433 documentation section of this module.
434 Returns : An array containing all HitI objects.
435 Hits will be ordered according to their occurrence in the report
436 unless otherwise specified.
437 Args : none
438  
439 See Also: L<newhits>, L<oldhits>, L<Classification of Hits>
440  
441 =cut
442  
443 0 ▶sub hits { shift->throw_not_implemented(); }
Subroutine hits: not called CC=1 SCAR=6.9
Pod documented
444  
445 =head2 newhits
446  
447 Title : newhits
448 Usage : foreach( $obj->newhits() ) { ... };
449 Purpose : Provides access to hits that were not found in a previous iteration
450 and may be either below or above the inclusion threshold.
451 Corresponds to subset B in the "Classification of Hits"
452 documentation section of this module.
453 Returns : An array containing Bio::Search::Hit::HitI objects.
454 Hits will be ordered according to their occurrence in the report
455 unless otherwise specified.
456 Args : none
457  
458 See Also: L<hits>, L<oldhits>, L<newhits_below_threshold> + L<newhits_not_below_threshold>, L<Classification of Hits>
459  
460 =cut
461  
462 0 ▶sub newhits { shift->throw_not_implemented(); }
Subroutine newhits: not called CC=1 SCAR=6.9
Pod documented
463  
464 =head2 oldhits
465  
466 Title : oldhits
467 Usage : foreach( $obj->oldhits() ) { ... };
468 Purpose : Provides access to hits that were found in a previous iteration
469 and are either below or above the inclusion threshold in the current iteration.
470 Corresponds to subset C in the "Classification of Hits"
471 documentation section of this module.
472 Returns : An array containing Bio::Search::Hit::HitI objects.
473 Hits will be ordered according to their occurrence in the report
474 unless otherwise specified.
475 Args : none
476  
477 See Also: L<hits>, L<newhits>, L<oldhits_below_threshold>, L<oldhits_newly_below_threshold>, L<oldhits_not_below_threshold>, L<Classification of Hits>
478  
479 =cut
480  
481 0 ▶sub oldhits { shift->throw_not_implemented(); }
Subroutine oldhits: not called CC=1 SCAR=6.9
Pod documented
482  
483 =head2 newhits_below_threshold
484  
485 Title : newhits_below_threshold
486 Usage : foreach( $obj->newhits_below_threshold() ) { ... };
487 Purpose : Provides access to hits that did not appear in a
488 previous iteration and are below threshold.
489 Corresponds to subset D in the "Classification of Hits"
490 documentation section of this module.
491 Returns : An array containing Bio::Search::Hit::HitI objects.
492 Hits will be returned in the order in which they occur in the report
493 unless otherwise specified.
494 Args : none
495  
496 See Also: L<newhits_not_below_threshold>, L<oldhits_newly_below_threshold>, L<newhits>, L<Classification of Hits>
497  
498 =cut
499  
500 0 ▶sub newhits_below_threshold { shift->throw_not_implemented(); }
Subroutine newhits_below_threshold: not called CC=1 SCAR=6.9
Pod documented
501  
502 =head2 oldhits_below_threshold
503  
504 Title : oldhits_below_threshold
505 Usage : foreach( $obj->oldhits_below_threshold() ) { ... };
506 Purpose : Provides access to hits that appeared in a
507 previous iteration below inclusion threshold and are still below threshold.
508 Corresponds to subset H in the "Classification of Hits"
509 documentation section of this module.
510 Returns : An array containing Bio::Search::Hit::HitI objects.
511 Hits will be returned in the order in which they occur in the report
512 unless otherwise specified.
513 Args : none
514  
515 See Also: L<oldhits_not_below_threshold>, L<oldhits_newly_below_threshold>, L<oldhits>, L<Classification of Hits>
516  
517 =cut
518  
519 0 ▶sub oldhits_below_threshold { shift->throw_not_implemented(); }
Subroutine oldhits_below_threshold: not called CC=1 SCAR=6.9
Pod documented
520  
521 =head2 oldhits_newly_below_threshold
522  
523 Title : oldhits_newly_below_threshold
524 Usage : foreach( $obj->oldhits_newly_below_threshold() ) { ... };
525 Purpose : Provides access to hits that appeared in a previous
526 iteration above threshold but are below threshold in the
527 current iteration. Not applicable to the first iteration.
528 Corresponds to subset I in the "Classification of Hits"
529 documentation section of this module.
530 Returns : An array containing Bio::Search::Hit::HitI objects.
531 Hits will be returned in the order in which they occur in the report
532 unless otherwise specified.
533 Args : none
534  
535 See Also: L<newhits_below_threshold>, L<oldhits>, L<Classification of Hits>
536  
537 =cut
538  
539 0 ▶sub oldhits_newly_below_threshold { shift->throw_not_implemented(); }
Subroutine oldhits_newly_below_threshold: not called CC=1 SCAR=6.9
Pod documented
540  
541 =head2 oldhits_not_below_threshold
542  
543 Title : oldhits_not_below_threshold
544 Usage : foreach( $obj->oldhits_not_below_threshold() ) { ... };
545 Purpose : Provides access to hits that appeared in a previous iteration
546 not below threshold and are still not below threshold.
547 Corresponds to subset G in the "Classification of Hits"
548 documentation section of this module.
549 Returns : An array containing Bio::Search::Hit::HitI objects.
550 Hits will be returned in the order in which they occur in the report
551 unless otherwise specified.
552 Args : none
553  
554 See Also: L<oldhits_below_threshold>, L<oldhits>, L<Classification of Hits>
555  
556 =cut
557  
558 0 ▶sub oldhits_not_below_threshold { shift->throw_not_implemented(); }
Subroutine oldhits_not_below_threshold: not called CC=1 SCAR=6.9
Pod documented
559  
560 =head2 newhits_not_below_threshold
561  
562 Title : newhits_not_below_threshold
563 Usage : foreach( $obj->newhits_not_below_threshold() ) { ... };
564 Purpose : Provides access to hits that did not appear in a
565 previous iteration and are not below threshold
566 in the current iteration.
567 Corresponds to subset E in the "Classification of Hits"
568 documentation section of this module.
569 Returns : An array containing Bio::Search::Hit::HitI objects.
570 Hits will be returned in the order in which they occur in the report
571 unless otherwise specified.
572 Args : none
573  
574 See Also: L<newhits_below_threshold>, L<newhits>, L<Classification of Hits>
575  
576 =cut
577  
578 0 ▶sub newhits_not_below_threshold { shift->throw_not_implemented(); }
Subroutine newhits_not_below_threshold: not called CC=1 SCAR=6.9
Pod documented
579  
580 =head2 hits_below_threshold
581  
582 Title : hits_below_threshold
583 Usage : foreach( $obj->hits_below_threshold() ) { ... };
584 Purpose : Provides access to all hits, old and new, that are below the inclusion threshold.
585 Corresponds to the union of subset D and subset F in the
586 "Classification of Hits" documentation section of this module.
587 Returns : An array containing Bio::Search::Hit::HitI objects.
588 Hits will be returned in the order in which they occur in the report
589 unless otherwise specified.
590 Args : none
591  
592 See Also: L<newhits_below_threshold>, L<oldhits_newly_below_threshold>, L<oldhits_below_threshold>, L<Classification of Hits>
593  
594 =cut
595  
596 0 ▶sub hits_below_threshold { shift->throw_not_implemented(); }
Subroutine hits_below_threshold: not called CC=1 SCAR=6.9
Pod documented
597  
598  
599 =head2 add_hit
600  
601 Title : add_hit
602 Usage : $report->add_hit(-hit =>$hit_obj,
603 -old =>$boolean,
604 -below_threshold =>$boolean,
605 -newly_below =>$boolean )
606 Purpose : Adds a HitI to the stored list of hits
607 Returns : Number of HitI currently stored for the class of the added hit.
608 Args : Tagged values, the only required one is -hit. All others are used
609 only for PSI-BLAST reports.
610 -hit => Bio::Search::Hit::HitI object
611 -old => boolean, true indicates that the hit was found
612 in a previous iteration. Default=false.
613 -below_threshold => boolean, true indicates that the hit is below
614 the inclusion threshold.
615 -newly_below => boolean, true indicates that the hit is below
616 the inclusion threshold in this iteration but was above
617 the inclusion threshold in a previous iteration.
618 Only appropriate for old hits. Default=false.
619 Throws : Bio::Root::BadParameter if the hit is not a
620 Bio::Search::Hit::HitI.
621 Bio::Root::BadParameter if -old=>false and -newly_below=>true.
622  
623 =cut
624  
625 0 ▶sub add_hit { shift->throw_not_implemented }
Subroutine add_hit: not called CC=1 SCAR=6.9
Pod documented
626  
627  
628  
629 =head2 get_hit
630  
631 Title : get_hit
632 Usage : $hit = $report->get_hit( $hit_name )
633 Purpose : Gets a HitI object given its name
634 if a hit with this name exists within this Iteration.
635 Returns : Bio::Search::Hit::HitI object or undef if there is no such hit.
636 Args : $hit_name = string containing name of the hit
637 Throws : n/a
638  
639 The name string must be the same as that returned by
640 Bio::Search::Hit::HitI::name().
641  
642 The lookup should be case-insensitive.
643  
644 =cut
645  
646 0 ▶sub get_hit { shift->throw_not_implemented }
Subroutine get_hit: not called CC=1 SCAR=6.9
Pod documented
647  
648  
649 13 1;
650  
651  
« Bio/Align/AlignI.pm ↑ Summary Bio/Seq/MetaI.pm »