# 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);
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]
Copyright (c) 2003 Steve Chervitz. All Rights Reserved.
This software is provided "as is" without warranty of any kind.