Bio::Search::Iteration IterationI
SummaryIncluded librariesPackage variablesSynopsisDescriptionGeneral documentationMethods
Summary
Bio::Search::Iteration::IterationI - Abstract interface to an
iteration from an iterated search result, such as PSI-BLAST.
Package variables
No package variables defined.
Included modules
Bio::Root::RootI
Inherit
Bio::Root::RootI
Synopsis
    # Bio::Search::Iteration::IterationI objects cannot be 
    # instantiated since this module defines a pure interface.
    # Given an object that implements the 
    # Bio::Search::Iteration::IterationI interface, 
    # you can do the following things with it:

    # First, open up a SearchIO stream
    use Bio::SearchIO;
    my $file = shift or die "Usage: $0 \n";
    my $in = new Bio::SearchIO(-format => 'blast',
                               -file => $file # comment out this line to read STDIN
                              );
    # Iterate over all results in the input stream
    while (my $result = $in->next_result) {

        printf "Result #%d: %s\n", $in->result_count, $result->to_string;
        printf "Total Iterations: %d\n", $result->num_iterations();

        # Iterate over all iterations and process old and new hits
        # separately.

        while( my $it = $result->next_iteration) { 
            printf "\nIteration %d\n", $it->number;
            printf "Converged: %d\n", $it->converged;

            # Print out the hits not found in previous iteration
            printf "New hits: %d\n", $it->num_hits_new;
            while( my $hit = $it->next_hit_new ) {
                printf "  %s, Expect=%g\n", $hit->name, $hit->expect; 
            }

            # Print out the hits found in previous iteration
            printf "Old hits: %d\n", $it->num_hits_old; 
            while( my $hit = $it->next_hit_old ) {
                printf "  %s, Expect=%g\n", $hit->name, $hit->expect; 
            }
        }
        printf "%s\n\n", '-' x 50;
    }

    printf "Total Reports processed: %d: %s\n", $in->result_count;

    __END__

    # NOTE: The following functionality is just proposed
    # (does not yet exist but might, given sufficient hew and cry):

    # Zero-in on the new hits found in last iteration.
    # By default, iteration() returns the last one.

    my $last_iteration = $result->iteration();
    while( my $hit = $last_iteration->next_hit) {
        # Do something with new hit...
    }

    # Get the first iteration

    my $first_iteration = $result->iteration(1);
Description
Bio::Search::Result::ResultI objects are data structures containing
the results from the execution of a search algorithm. As such, it may
contain various algorithm specific information as well as details of
the execution, but will contain a few fundamental elements, including
the ability to return Bio::Search::Hit::HitI objects. Within a given iteration, the hits can be classified into a number of
useful subsets based on whether or not the hit appeard in a previous
iteration and whether or not the hit is below the threshold E-value
for inclusion in the score matrix model.
                           All hits
                             (A)
               _______________|_________________
               |                               |
            New hits                        Old hits
              (B)                             (C)
      _________|________                _______|_________
      |                |                |               |
    Below            Above             Below          Above
  threshold        threshold         threshold      threshold
     (D)              (E)              (F)             (G)
                               _________|___________
                               |                   |
                         Occurred in a         Occurred in a
                         previous iteration    previous iteration
                         below threshold       above threshold
                              (H)                  (I)
Notes: The term threshold in the diagram and descriptions below
refer to this inclusion threshold. Below threshold actually means
at or below threshold.
The IterationI interface defines a number of methods for extracting
these subsets of hits.
    * newhits_below_threshold() [subset D]
    Hits that did not appear in a previous iteration and are below
threshold in the current iteration.
    * newhits_not_below_threshold() [subset E]
    Hits that did not appear in a previous iteration and are not below
threshold in the current iteration.
    * newhits() [subset B]
    All newly found hits, below and above the inclusion threshold. This
is the union of newhits_below_threshold() + newhits_not_below_threshold()
[subset D + subset E].
    * oldhits_below_threshold() [subset H]
    Hits that appeared in a previous iteration below threshold and are
still below threshold in the current iteration.
    * oldhits_newly_below_threshold() [subset I]
    Hits that appeared in a previous iteration above threshold but are
below threshold in the current iteration. (Not applicable to the first
iteration.)
    * oldhits_not_below_threshold() [subset G]
    Hits that appeared in a previous iteration not below threshold and
are still not below threshold in the current iteration.
    * oldhits() [subset C]
    All hits that occured in a previous iteration, whether below or above
threshold in the current iteration. Union of oldhits_below_threshold()
+ oldhits_newly_below_threshold() + oldhits_not_below_threshold()
[subset H + subset I + subset G]. (Not applicable to the first
iteration.)
    * hits_below_threshold() [subset D + subset F]
    All hits, old and new, that are below the inclusion threshold in this
iteration. This is the union of newhits_below_threshold() +
oldhits_below_threshold() + oldhits_newly_below_threshold()
[subset D + subset H + subset I].
    * hits() [subset A]
    The union of newhits() and oldhits() [subset B + subset C].
For the first iteration, the methods oldhits, oldhits_below_threshold,
oldhits_newly_below_threshold, and oldhits_not_below_threshold()
will return empty lists.
Iterator and numbers-of-hit methods are provided for subsets A, B, and C:
    * next_hit_new(), num_hits_new() [subset B]
    * next_hit_old(), num_hits_old() [subset C]
    * next_hit(), num_hits() [subset A]
Methods
numberDescriptionCode
convergedDescriptionCode
next_hitDescriptionCode
next_hit_newDescriptionCode
next_hit_oldDescriptionCode
num_hitsDescriptionCode
num_hits_newDescriptionCode
num_hits_oldDescriptionCode
hitsDescriptionCode
newhitsDescriptionCode
oldhitsDescriptionCode
newhits_below_thresholdDescriptionCode
oldhits_below_thresholdDescriptionCode
oldhits_newly_below_thresholdDescriptionCode
oldhits_not_below_thresholdDescriptionCode
newhits_not_below_thresholdDescriptionCode
hits_below_thresholdDescriptionCode
add_hitDescriptionCode
get_hitDescriptionCode
Methods description
numbercode    nextTop
 Title   : number
 Usage   : $it_number = $iteration->number();
 Purpose : returns the number of the iteration (a.k.a "round") 
           within the Result.
 Returns : integer
 Args    : [optional] integer to set the number of the iteration
convergedcodeprevnextTop
 Title   : converged
 Usage   : $it_converged = $iteration->converged();
 Purpose : Indicates whether or not the iteration has converged 
 Returns : boolean 
 Args    : [optional] boolean value to set the converged of the iteration
next_hitcodeprevnextTop
 Title   : next_hit
 Usage   : while( $hit = $iteration->next_hit( [$found_again]) ) { ... }
 Purpose : Iterates through all of the HitI objects
           including new hits and old hits found in a previous iteration
           and both below and above the inclusion threshold.
           Corresponds to subset A in the "Classification of Hits"
           documentation section of this module.
 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: hits, Classification of Hits
next_hit() iterates through all hits, including the new ones
for this iteration and those found in previous iterations.
You can interrogate each hit using Bio::Search::Hit::HitI::found_again
to determine whether it is new or old.
To get just the new hits, use next_hit_new.
To get just the old hits, use next_hit_old.
next_hit_newcodeprevnextTop
 Title   : next_hit_new
 Usage   : while( $hit = $iteration->next_hit_new() ) { ... }
 Purpose : Iterates through all newly found hits (did not occur in a
           previous iteration) and are either below or above the inclusion threshold.
           Corresponds to subset B in the "Classification of Hits"
           documentation section of this module.
 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: next_hit, next_hit_old, newhits, Classification of Hits
next_hit_oldcodeprevnextTop
 Title   : next_hit_old
 Usage   : while( $hit = $iteration->next_hit_old() ) { ... }
 Purpose : Iterates through the Hit objects representing just the
           hits that have been found in a previous iteration, whether
           below or above the inclusion threshold.
           Corresponds to subset C in the "Classification of Hits"
           documentation section of this module.
 Returns : A Bio::Search::Hit::HitI object or undef if there are no more.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: next_hit, next_hit_old, oldhits, Classification of Hits
num_hitscodeprevnextTop
 Title   : num_hits
 Usage   : my $hitcount_total = $iteration->num_hits
 Purpose : Returns the total number of hits for this query result, including new and old
           below and above inclusion threshold.
 Returns : integer
 Args    : none
See Also: num_hits_new, num_hits_old, Classification of Hits
num_hits_newcodeprevnextTop
 Title   : num_hits_new
 Usage   : my $hitcount_new = $result->num_hits_new;
         : my $hitcount_new_below_thresh = $result->num_hits_new( 1 );
 Purpose : Returns the number of new hits in this iteration that were not
           found in a previous iteration and are either below or above the
           the inclusion threshold.
           Corresponds to subset B in the "Classification of Hits"
           documentation section of this module.
 Returns : integer
 Args    : (optional) boolean, true if you want to get a count of just the new hits
           that are below the inclusion threshold.
See Also: num_hits, num_hits_old, Classification of Hits
num_hits_oldcodeprevnextTop
 Title   : num_hits_old
 Usage   : my $hitcount_old = $result->num_hits_old;
         : my $hitcount_old_below_thresh = $result->num_hits_old( 1 );
 Purpose : Returns the number of new hits in this iteration that were
           found in a previous iteration and are either below or above the
           the inclusion threshold.
           Corresponds to subset C in the "Classification of Hits"
           documentation section of this module.
 Returns : integer
 Args    : (optional) boolean, true if you want to get a count of just the old hits
           that are below the inclusion threshold.
See Also: num_hits, num_hits_new, Classification of Hits
hitscodeprevnextTop
 Title    : hits
 Usage    : foreach( $obj->hits() ) { ... };
 Purpose  : Provides access to all hits, both new and old, and either
            below or above the inclusion threshold.
            Corresponds to subset A in the "Classification of Hits"
            documentation section of this module.
 Returns  : An array containing all HitI objects.
            Hits will be ordered according to their occurrence in the report
            unless otherwise specified.
 Args     : none
See Also: newhits, oldhits, Classification of Hits
newhitscodeprevnextTop
 Title    : newhits
 Usage    : foreach( $obj->newhits() ) { ... };
 Purpose  : Provides access to hits that were not found in a previous iteration
            and may be either below or above the inclusion threshold.
            Corresponds to subset B in the "Classification of Hits"
            documentation section of this module.
 Returns  : An array containing Bio::Search::Hit::HitI objects.
            Hits will be ordered according to their occurrence in the report
            unless otherwise specified.
 Args     : none
See Also: hits, oldhits, newhits_below_threshold + newhits_not_below_threshold, Classification of Hits
oldhitscodeprevnextTop
 Title    : oldhits
 Usage    : foreach( $obj->oldhits() ) { ... };
 Purpose  : Provides access to hits that were found in a previous iteration
            and are either below or above the inclusion threshold in the current iteration.
            Corresponds to subset C in the "Classification of Hits"
            documentation section of this module.
 Returns  : An array containing Bio::Search::Hit::HitI objects.
            Hits will be ordered according to their occurrence in the report
            unless otherwise specified.
 Args     : none
See Also: hits, newhits, oldhits_below_threshold, oldhits_newly_below_threshold, oldhits_not_below_threshold, Classification of Hits
newhits_below_thresholdcodeprevnextTop
 Title   : newhits_below_threshold
 Usage   : foreach( $obj->newhits_below_threshold() ) { ... };
 Purpose : Provides access to hits that did not appear in a 
           previous iteration and are below threshold.
           Corresponds to subset D in the "Classification of Hits"
           documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: newhits_not_below_threshold, oldhits_newly_below_threshold, newhits, Classification of Hits
oldhits_below_thresholdcodeprevnextTop
 Title   : oldhits_below_threshold
 Usage   : foreach( $obj->oldhits_below_threshold() ) { ... };
 Purpose : Provides access to hits that appeared in a 
           previous iteration below inclusion threshold and are still below threshold.
           Corresponds to subset H in the "Classification of Hits"
           documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: oldhits_not_below_threshold, oldhits_newly_below_threshold, oldhits, Classification of Hits
oldhits_newly_below_thresholdcodeprevnextTop
 Title   : oldhits_newly_below_threshold
 Usage   : foreach( $obj->oldhits_newly_below_threshold() ) { ... };
 Purpose : Provides access to hits that appeared in a previous
           iteration above threshold but are below threshold in the 
           current iteration. Not applicable to the first iteration.
           Corresponds to subset I in the "Classification of Hits"
           documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: newhits_below_threshold, oldhits, Classification of Hits
oldhits_not_below_thresholdcodeprevnextTop
 Title   : oldhits_not_below_threshold
 Usage   : foreach( $obj->oldhits_not_below_threshold() ) { ... };
 Purpose : Provides access to hits that appeared in a previous iteration
           not below threshold and are still not below threshold.
           Corresponds to subset G in the "Classification of Hits"
           documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: oldhits_below_threshold, oldhits, Classification of Hits
newhits_not_below_thresholdcodeprevnextTop
 Title   : newhits_not_below_threshold
 Usage   : foreach( $obj->newhits_not_below_threshold() ) { ... };
 Purpose : Provides access to hits that did not appear in a 
           previous iteration and are not below threshold 
           in the current iteration.
           Corresponds to subset E in the "Classification of Hits"
           documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: newhits_below_threshold, newhits, Classification of Hits
hits_below_thresholdcodeprevnextTop
 Title   : hits_below_threshold
 Usage   : foreach( $obj->hits_below_threshold() ) { ... };
 Purpose : Provides access to all hits, old and new, that are below the inclusion threshold.
           Corresponds to the union of subset D and subset F in the 
           "Classification of Hits" documentation section of this module.
 Returns : An array containing Bio::Search::Hit::HitI objects.
           Hits will be returned in the order in which they occur in the report
           unless otherwise specified.
 Args    : none
See Also: newhits_below_threshold, oldhits_newly_below_threshold, oldhits_below_threshold, Classification of Hits
add_hitcodeprevnextTop
 Title   : add_hit
 Usage   : $report->add_hit(-hit             =>$hit_obj,
                            -old             =>$boolean,
                            -below_threshold =>$boolean,
                            -newly_below     =>$boolean )
 Purpose : Adds a HitI to the stored list of hits
 Returns : Number of HitI currently stored for the class of the added hit.
 Args    : Tagged values, the only required one is -hit. All others are used
           only for PSI-BLAST reports.
           -hit => Bio::Search::Hit::HitI object
           -old => boolean, true indicates that the hit was found in a previous 
                   iteration. Default=false.
           -below_threshold => boolean, true indicates that the hit is below
                   the inclusion threshold.
           -newly_below => boolean, true indicates that the hit is below
                   the inclusion threshold in this iteration but was above
                   the inclusion threshold in a previous iteration. Only appropriate
                   for old hits. Default=false.
 Throws  : Bio::Root::BadParameter if the hit is not a
           Bio::Search::Hit::HitI.
           Bio::Root::BadParameter if -old=>false and -newly_below=>true.
get_hitcodeprevnextTop
 Title   : get_hit
 Usage   : $hit = $report->get_hit( $hit_name )
 Purpose : Gets a HitI object given its name 
           if a hit with this name exists within this Iteration.
 Returns : Bio::Search::Hit::HitI object or undef if there is no such hit.
 Args    : $hit_name = string containing name of the hit
 Throws  : n/a
The name string must be the same as that returned by
Bio::Search::Hit::HitI::name().
The lookup should be case-insensitive.
Methods code
numberdescriptionprevnextTop
sub number {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}
convergeddescriptionprevnextTop
sub converged {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}
next_hitdescriptionprevnextTop
sub next_hit {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}
next_hit_newdescriptionprevnextTop
sub next_hit_new {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}
next_hit_olddescriptionprevnextTop
sub next_hit_old {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}
num_hitsdescriptionprevnextTop
sub num_hits {
   my ($self,@args) = @_;
   $self->throw_not_implemented();
}
num_hits_newdescriptionprevnextTop
sub num_hits_new {
   my ($self,@args) = @_;
   $self->throw_not_implemented();
}
num_hits_olddescriptionprevnextTop
sub num_hits_old {
   my ($self,@args) = @_;
   $self->throw_not_implemented();
}
hitsdescriptionprevnextTop
sub hits {
 shift->throw_not_implemented();
}
newhitsdescriptionprevnextTop
sub newhits {
 shift->throw_not_implemented();
}
oldhitsdescriptionprevnextTop
sub oldhits {
 shift->throw_not_implemented();
}
newhits_below_thresholddescriptionprevnextTop
sub newhits_below_threshold {
 shift->throw_not_implemented();
}
oldhits_below_thresholddescriptionprevnextTop
sub oldhits_below_threshold {
 shift->throw_not_implemented();
}
oldhits_newly_below_thresholddescriptionprevnextTop
sub oldhits_newly_below_threshold {
 shift->throw_not_implemented();
}
oldhits_not_below_thresholddescriptionprevnextTop
sub oldhits_not_below_threshold {
 shift->throw_not_implemented();
}
newhits_not_below_thresholddescriptionprevnextTop
sub newhits_not_below_threshold {
 shift->throw_not_implemented();
}
hits_below_thresholddescriptionprevnextTop
sub hits_below_threshold {
 shift->throw_not_implemented();
}
add_hitdescriptionprevnextTop
sub add_hit {
 shift->throw_not_implemented
}
get_hitdescriptionprevnextTop
sub get_hit {
 shift->throw_not_implemented
}
General documentation
FEEDBACKTop
Mailing ListsTop
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to one
of the Bioperl mailing lists. Your participation is much appreciated.
  bioperl-l@bioperl.org              - General discussion
  http://bio.perl.org/MailList.html  - About the mailing lists
Reporting BugsTop
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution.
Bug reports can be submitted via email or the web:
  bioperl-bugs@bio.perl.org
  http://bugzilla.bioperl.org/
AUTHOR Top
Steve Chervitz <sac@bioperl.org>
See the FEEDBACK section for where to send bug reports and comments.
COPYRIGHTTop
Copyright (c) 2003 Steve Chervitz. All Rights Reserved.
DISCLAIMERTop
This software is provided "as is" without warranty of any kind.
APPENDIXTop
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _