Bio::Search::Iteration::IterationI.3pm

Langue: en

Version: 2008-01-11 (mandriva - 01/05/08)

Section: 3 (Bibliothèques de fonctions)

NAME

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

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

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

FEEDBACK


Mailing Lists

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://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 
 

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via the web:

   http://bugzilla.open-bio.org/
 
 

AUTHOR

Steve Chervitz <sac@bioperl.org>

See the FEEDBACK section for where to send bug reports and comments.

Copyright (c) 2003 Steve Chervitz. All Rights Reserved.

DISCLAIMER

This software is provided ``as is'' without warranty of any kind.

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

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
 
 

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
 
 

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

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

num_hits

  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_new

  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_old

  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''

hits

  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''

newhits

  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''

oldhits

  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_threshold

  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_threshold

  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_threshold

  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_threshold

  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_threshold

  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_threshold

  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_hit

  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_hit

  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.