A test to ensure Bio::PrimarySeqI->trunc() doesn't use clone() for a Bio::Seq::RichSe...
[bioperl-live.git] / Bio / Search / Iteration / IterationI.pm
blobc6fe71b57a59368acd32736d6b00abc21dbcbc1c
1 #-----------------------------------------------------------------
3 # BioPerl module Bio::Search::Iteration::IterationI
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
7 # Cared for by Steve Chervitz <sac@bioperl.org>
9 # You may distribute this module under the same terms as perl itself
10 #-----------------------------------------------------------------
12 # POD documentation - main docs before the code
14 =head1 NAME
16 Bio::Search::Iteration::IterationI - Abstract interface to an
17 iteration from an iterated search result, such as PSI-BLAST.
19 =head1 SYNOPSIS
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:
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
33 # Iterate over all results in the input stream
34 while (my $result = $in->next_result) {
36 printf "Result #%d: %s\n", $in->result_count, $result->to_string;
37 printf "Total Iterations: %d\n", $result->num_iterations();
39 # Iterate over all iterations and process old and new hits
40 # separately.
42 while( my $it = $result->next_iteration) {
43 printf "\nIteration %d\n", $it->number;
44 printf "Converged: %d\n", $it->converged;
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;
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;
58 printf "%s\n\n", '-' x 50;
61 printf "Total Reports processed: %d: %s\n", $in->result_count;
63 __END__
65 # NOTE: The following functionality is just proposed
66 # (does not yet exist but might, given sufficient hew and cry):
68 # Zero-in on the new hits found in last iteration.
69 # By default, iteration() returns the last one.
71 my $last_iteration = $result->iteration();
72 while( my $hit = $last_iteration->next_hit) {
73 # Do something with new hit...
76 # Get the first iteration
78 my $first_iteration = $result->iteration(1);
81 =head1 DESCRIPTION
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.
89 =head2 Classification of Hits
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.
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 _________|___________
109 Occurred in a Occurred in a
110 previous iteration previous iteration
111 below threshold above threshold
112 (H) (I)
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>.
118 The IterationI interface defines a number of methods for extracting
119 these subsets of hits.
121 =over 4
123 =item * newhits_below_threshold() [subset D]
125 Hits that did not appear in a previous iteration and are below
126 threshold in the current iteration.
128 =item * newhits_not_below_threshold() [subset E]
130 Hits that did not appear in a previous iteration and are not below
131 threshold in the current iteration.
133 =item * newhits() [subset B]
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].
139 =item * oldhits_below_threshold() [subset H]
141 Hits that appeared in a previous iteration below threshold and are
142 still below threshold in the current iteration.
144 =item * oldhits_newly_below_threshold() [subset I]
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.)
150 =item * oldhits_not_below_threshold() [subset G]
152 Hits that appeared in a previous iteration not below threshold and
153 are still not below threshold in the current iteration.
155 =item * oldhits() [subset C]
157 All hits that occured 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.)
163 =item * hits_below_threshold() [subset D + subset F]
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].
170 =item * hits() [subset A]
172 The union of newhits() and oldhits() [subset B + subset C].
174 =back
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.
180 Iterator and numbers-of-hit methods are provided for subsets A, B, and C:
182 =over 4
184 =item * next_hit_new(), num_hits_new() [subset B]
186 =item * next_hit_old(), num_hits_old() [subset C]
188 =item * next_hit(), num_hits() [subset A]
190 =back
192 =head1 FEEDBACK
194 =head2 Mailing Lists
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.
200 bioperl-l@bioperl.org - General discussion
201 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
203 =head2 Support
205 Please direct usage questions or support issues to the mailing list:
207 I<bioperl-l@bioperl.org>
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.
214 =head2 Reporting Bugs
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:
220 https://github.com/bioperl/bioperl-live/issues
222 =head1 AUTHOR
224 Steve Chervitz E<lt>sac@bioperl.orgE<gt>
226 See L<the FEEDBACK section | FEEDBACK> for where to send bug reports and comments.
228 =head1 COPYRIGHT
230 Copyright (c) 2003 Steve Chervitz. All Rights Reserved.
232 =head1 DISCLAIMER
234 This software is provided "as is" without warranty of any kind.
236 =head1 APPENDIX
238 The rest of the documentation details each of the object
239 methods. Internal methods are usually preceded with a _
241 =cut
244 # Let the code begin...
247 package Bio::Search::Iteration::IterationI;
249 use strict;
252 use base qw(Bio::Root::RootI);
254 =head2 number
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
263 =cut
265 sub number {
266 my ($self,@args) = @_;
267 $self->throw_not_implemented;
270 =head2 converged
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
278 =cut
280 sub converged {
281 my ($self,@args) = @_;
282 $self->throw_not_implemented;
285 =head2 next_hit
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
299 See Also: L<hits>, L<Classification of Hits>
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.
306 To get just the new hits, use L<next_hit_new>.
307 To get just the old hits, use L<next_hit_old>.
309 =cut
311 sub next_hit {
312 my ($self,@args) = @_;
313 $self->throw_not_implemented;
316 =head2 next_hit_new
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
329 See Also: L<next_hit>, L<next_hit_old>, L<newhits>, L<Classification of Hits>
331 =cut
333 sub next_hit_new {
334 my ($self,@args) = @_;
335 $self->throw_not_implemented;
338 =head2 next_hit_old
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
352 See Also: L<next_hit>, L<next_hit_old>, L<oldhits>, L<Classification of Hits>
354 =cut
356 sub next_hit_old {
357 my ($self,@args) = @_;
358 $self->throw_not_implemented;
361 =head2 num_hits
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
370 See Also: L<num_hits_new>, L<num_hits_old>, L<Classification of Hits>
372 =cut
374 sub num_hits {
375 my ($self,@args) = @_;
376 $self->throw_not_implemented();
379 =head2 num_hits_new
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.
394 See Also: L<num_hits>, L<num_hits_old>, L<Classification of Hits>
396 =cut
398 sub num_hits_new {
399 my ($self,@args) = @_;
400 $self->throw_not_implemented();
403 =head2 num_hits_old
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.
417 See Also: L<num_hits>, L<num_hits_new>, L<Classification of Hits>
419 =cut
421 sub num_hits_old {
422 my ($self,@args) = @_;
423 $self->throw_not_implemented();
426 =head2 hits
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
439 See Also: L<newhits>, L<oldhits>, L<Classification of Hits>
441 =cut
443 sub hits { shift->throw_not_implemented(); }
445 =head2 newhits
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
458 See Also: L<hits>, L<oldhits>, L<newhits_below_threshold> + L<newhits_not_below_threshold>, L<Classification of Hits>
460 =cut
462 sub newhits { shift->throw_not_implemented(); }
464 =head2 oldhits
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
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>
479 =cut
481 sub oldhits { shift->throw_not_implemented(); }
483 =head2 newhits_below_threshold
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
496 See Also: L<newhits_not_below_threshold>, L<oldhits_newly_below_threshold>, L<newhits>, L<Classification of Hits>
498 =cut
500 sub newhits_below_threshold { shift->throw_not_implemented(); }
502 =head2 oldhits_below_threshold
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
515 See Also: L<oldhits_not_below_threshold>, L<oldhits_newly_below_threshold>, L<oldhits>, L<Classification of Hits>
517 =cut
519 sub oldhits_below_threshold { shift->throw_not_implemented(); }
521 =head2 oldhits_newly_below_threshold
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
535 See Also: L<newhits_below_threshold>, L<oldhits>, L<Classification of Hits>
537 =cut
539 sub oldhits_newly_below_threshold { shift->throw_not_implemented(); }
541 =head2 oldhits_not_below_threshold
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
554 See Also: L<oldhits_below_threshold>, L<oldhits>, L<Classification of Hits>
556 =cut
558 sub oldhits_not_below_threshold { shift->throw_not_implemented(); }
560 =head2 newhits_not_below_threshold
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
574 See Also: L<newhits_below_threshold>, L<newhits>, L<Classification of Hits>
576 =cut
578 sub newhits_not_below_threshold { shift->throw_not_implemented(); }
580 =head2 hits_below_threshold
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
592 See Also: L<newhits_below_threshold>, L<oldhits_newly_below_threshold>, L<oldhits_below_threshold>, L<Classification of Hits>
594 =cut
596 sub hits_below_threshold { shift->throw_not_implemented(); }
599 =head2 add_hit
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.
623 =cut
625 sub add_hit { shift->throw_not_implemented }
629 =head2 get_hit
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
639 The name string must be the same as that returned by
640 Bio::Search::Hit::HitI::name().
642 The lookup should be case-insensitive.
644 =cut
646 sub get_hit { shift->throw_not_implemented }