Bio::S...ationI(3pm)

📦

version 1.7.8 · 3 versions

1.7.8 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
1.7.8 · ubuntu stonking
1.7.8 · ubuntu resolute

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Bio::Search::Iteration::IterationI — bestie, this is the abstract interface to one single iteration out of an iterated search result, the way PSI-BLAST does it. That's the whole vibe. (Also hi, you're in the User Contributed Perl Documentation, section 3pm 💅)

🎀 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);

okay so real talk: that last chunk after __END__ is proposed functionality. It does not exist yet, but it might someday if enough people make a fuss about it. Do not go coding against it and then @ me, k? 😭

💅 DESCRIPTION 💅

Bio::Search::Result::ResultI objects are the data structures holding the results from running a search algorithm. So like, they can carry all kinds of algorithm-specific info plus details about the actual execution, but every one of them has a few fundamental elements — including the ability to hand you back Bio::Search::Hit::HitI objects. That's the core promise. 💖

🦋 Classification of Hits 🦋

Within any given iteration, the hits sort themselves into a bunch of genuinely useful subsets — depending on (a) whether or not the hit showed up in a previous iteration, and (b) whether or not the hit is below the threshold E-value for inclusion in the score matrix model. Slay.

                              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 word threshold in that diagram and in the descriptions below refers to this inclusion threshold. And "below threshold" actually means at or below threshold. iykyk. 👑

The IterationI interface defines a bunch of methods for pulling out these hit subsets:

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] — literally 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, bestie.)
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] — every hit that occurred 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. Not a bug, that's just the beginning of the story. 🌱

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, like, 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

🫶 Support 🫶

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. (fr fr, the more detail the better 💀)

🐛 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:

https://github.com/bioperl/bioperl-live/issues

👑 AUTHOR 👑

Steve Chervitz <sac@bioperl.org>

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

💜 COPYRIGHT 💜

🙈 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 _ (you know the vibe — underscore means stay out unless you're the module itself 💅)

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 the hits — the new ones for this iteration plus the ones found in previous iterations. You can interrogate each hit using Bio::Search::Hit::HitI::found_again to figure out whether it's 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: hands you the total number of hits for this query result — new ones, old ones, above the inclusion threshold, below it, all of them. no filtering, no gatekeeping 💅
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: counts the new hits in this iteration — the ones that were not found in a previous iteration, whether they're below or above the inclusion threshold. it's giving subset B energy, straight out of the "Classification of Hits" section of this module ✨
Returns: integer
Args: (optional) boolean — pass true if you only want the count of 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: counts the hits in this iteration that were already found in a previous iteration, below or above the inclusion threshold, doesn't matter. that's subset C btw, per the "Classification of Hits" section of this module 🫶
Returns: integer
Args: (optional) boolean — pass true if you just want the count of old hits sitting below the inclusion threshold.
See Also: num_hits, num_hits_new, "Classification of Hits"

✨ `hits`

Title: hits
Usage:

foreach( $obj->hits() ) { ... };

Purpose: your all-access pass to every hit — new and old, below the inclusion threshold or above it. this is subset A in the "Classification of Hits" section of this module 👑
Returns: an array holding all HitI objects. hits come ordered by how they show up in the report, unless it says otherwise somewhere.
Args: none

See Also: newhits, oldhits, "Classification of Hits"

💖 `newhits`

Title: newhits
Usage:

foreach( $obj->newhits() ) { ... };

Purpose: gives you the hits that were not found in a previous iteration, and they might be below the inclusion threshold or above it. that's subset B in the "Classification of Hits" section of this module 💅
Returns: an array containing Bio::Search::Hit::HitI objects. ordered by 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: the hits that showed up in a previous iteration and are either below or above the inclusion threshold in the current iteration. hi subset C, per the "Classification of Hits" section of this module 🌸
Returns: an array containing Bio::Search::Hit::HitI objects. ordered by 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: the hits that did not appear in a previous iteration and are below threshold. that's subset D in the "Classification of Hits" section of this module 💀
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: the hits that appeared in a previous iteration below the inclusion threshold and are still below threshold. that's subset H in the "Classification of Hits" section of this module 🫶
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: the hits that appeared in a previous iteration above threshold but are below threshold in the current iteration. glow-down era 😭 — and heads up, this one is not applicable to the first iteration. that's subset I in the "Classification of Hits" section of this module ✨
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: the hits that appeared in a previous iteration not below threshold and are still not below threshold. consistency, we love to see it. that's subset G in the "Classification of Hits" section of this module 💖
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: the hits that did not appear in a previous iteration and are not below threshold in the current iteration. subset E, as documented in the "Classification of Hits" section of this module 🌈
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: every hit, old and new, that's below the inclusion threshold. it's literally the union of subset D and subset F in the "Classification of Hits" section of this module 💅
Returns: an array containing Bio::Search::Hit::HitI objects. returned in the order 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: the number of HitI currently stored for the class of the added hit.
Args: tagged values — the only required one is -hit. every other one is used only for PSI-BLAST reports.
- -hit => Bio::Search::Hit::HitI object
- -old => boolean, true means the hit was found in a previous iteration. Default=false.
- -below_threshold => boolean, true means the hit is below the inclusion threshold.
- -newly_below => boolean, true means 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.

bestie, that second throw is a real trap — don't pass -newly_below=>true with -old=>false, the module will absolutely call you out 💀

🦋 `get_hit`

Title: get_hit
Usage:

$hit = $report->get_hit( $hit_name )

Purpose: grabs you a HitI object given its name — but only if a hit with this name actually exists within this Iteration 👀
Returns: a Bio::Search::Hit::HitI object, or undef if there's no such hit.
Args: $hit_name = string containing the name of the hit
Throws: n/a

The name string must be the same as the one returned by Bio::Search::Hit::HitI::name().

The lookup should be case-insensitive. 🔍

and that's a wrap on part 2, bestie 💖 this page came straight out of the Perl docs for perl v5.32.1, dated 2021-08-15 — go forth and classify your hits, you absolute icon 👑✨

📦 where this page comes from

debian bookworm: libbio-perl-perl 1.7.8-1 · Perl
debian trixie: libbio-perl-perl 1.7.8-1 · Perl
ubuntu jammy: libbio-perl-perl 1.7.8-1 · Perl
ubuntu noble: libbio-perl-perl 1.7.8-1 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Bio::S...ationI(3pm)

💖 NAME 💖

🎀 SYNOPSIS 🎀

💅 DESCRIPTION 💅

🦋 Classification of Hits 🦋

📬 FEEDBACK 📬

🌸 Mailing Lists 🌸

🫶 Support 🫶

🐛 Reporting Bugs 🐛

👑 AUTHOR 👑

💜 COPYRIGHT 💜

🙈 DISCLAIMER 🙈

🧚 APPENDIX 🧚

number

converged

next_hit

next_hit_new

next_hit_old

💜 num_hits

🌸 num_hits_new

🦋 num_hits_old

✨ hits

💖 newhits

🌈 oldhits

🎀 newhits_below_threshold

🍓 oldhits_below_threshold

🧚 oldhits_newly_below_threshold

👑 oldhits_not_below_threshold

⭐ newhits_not_below_threshold

🔥 hits_below_threshold

🫶 add_hit

🦋 get_hit