view release on metacpan or  search on metacpan

Bio/Search/Iteration/IterationI.pm  view on Meta::CPAN

#-----------------------------------------------------------------
#
# BioPerl module Bio::Search::Iteration::IterationI
#
# Please direct questions and support issues to <bioperl-l@bioperl.org> 
#
# Cared for by Steve Chervitz <sac@bioperl.org>
#
# You may distribute this module under the same terms as perl itself
#-----------------------------------------------------------------

# POD documentation - main docs before the code

=head1 NAME

Bio::Search::Iteration::IterationI - Abstract interface to an
iteration from an iterated search result, such as PSI-BLAST.

=head1 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 <BLAST-report-file>\n";
    my $in = Bio::SearchIO->new(-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);


=head1 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.

=head2 Classification of Hits

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)
               _______________|_________________
               |                               |

Bio/Search/Iteration/IterationI.pm  view on Meta::CPAN

#'
# Let the code begin...


package Bio::Search::Iteration::IterationI;

use strict;


use base qw(Bio::Root::RootI);

=head2 number

 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

=cut

sub number {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 converged

 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

=cut

sub converged {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 next_hit

 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: L<hits>, L<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 L<Bio::Search::Hit::HitI::found_again>
to determine whether it is new or old.

To get just the new hits, use L<next_hit_new>.
To get just the old hits, use L<next_hit_old>.

=cut

sub next_hit {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 next_hit_new

 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: L<next_hit>, L<next_hit_old>, L<newhits>, L<Classification of Hits>

=cut

sub next_hit_new {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 next_hit_old

 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: L<next_hit>, L<next_hit_old>, L<oldhits>, L<Classification of Hits>

=cut

sub next_hit_old {
    my ($self,@args) = @_;
    $self->throw_not_implemented;
}

=head2 num_hits