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

💖 Bio::Search::Iteration::GenericIteration 💖

okay bestie, gather round, because this is Bio::Search::Iteration::GenericIteration — a generic implementation of the Bio::Search::Iteration::IterationI interface. no cap. it's giving container energy and we're obsessed. 🫶

---

✨ SYNOPSIS ✨

use Bio::Search::Iteration::GenericIteration;
my $it = Bio::Search::GenericIteration->new(
                          -number => 1,
                          -converged => 0,
                          -newhits_unclassified => [@newhits_unclass],
                          -newhits_below => [@newhits_below_threshold],
                          -newhits_not_below => [@newhits_not_below_threshold],
                          -oldhits_below => [@oldhits_below_threshold],
                          -oldhits_newly_below => [@oldhits_newly_below_threshold],
                          -oldhits_not_below => [@oldhits_not_below_threshold],
                                    );

# TODO: Describe how to configure a SearchIO stream so that it generates
#       GenericIteration objects.

that # TODO is literally in the source, bestie. we are NOT touching it. it's part of the lore. 🙈

---

🌸 DESCRIPTION 🌸

so basically this module is a container for Bio::Search::Hit::HitI objects, and what it lets a Search::Result::ResultI object do is partition its hits based on which iteration the hit showed up in (think: a PSI-BLAST round, iykyk). 🔥

real talk though — unless you're out here writing a parser, you will never need to create a GenericIteration or any other IterationI-implementing object. like, ever. if you use the SearchIO system, the IterationI objects get created automatically from a SearchIO stream that returns Bio::Search::Result::ResultI objects, and you get your IterationI objects through the ResultI API. it's giving main character energy, it just happens for you. ✨

for documentation on what you can actually do with GenericIteration (and the other IterationI objects), go read the API docs in Bio::Search::Iteration::IterationI. that's the vibe check you need. 💅

Bio::Search::Iteration::GenericIteration is similar in spirit to the deprecated Bio::Tools::BPlite::Iteration modules from bioperl releases prior to 1.6 — except that Bio::Search::Iteration::GenericIteration is a pure container, with no parsing functionality at all, unlike Bio::Tools::BPlite::Iteration. so yeah, the old one did the parsing AND the holding, and this one is just the holding. iconic behavior, honestly. 🎀

---

💌 FEEDBACK 💌

📬 Mailing Lists

user feedback is an integral part of the evolution of this and other Bioperl modules, fr fr. send your comments and suggestions preferably to the Bioperl mailing list. 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. so many experienced and responsive 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. the more detail the better, bestie, we're not mind readers. 🧚

🐛 Reporting Bugs

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

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

---

👑 AUTHOR - Steve Chervitz 👑

Email sac@bioperl.org

---

🦋 APPENDIX 🦋

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (you know the drill 💅).

⭐ new

Title   : new
Usage   : my $obj = Bio::Search::Iteration->new(%args);
Function: Builds a new Bio::Search::Iteration object
Returns : Bio::Search::Iteration::GenericIteration object
Args    : -number => integer for the number of this iteration (required)
          -converged => boolean value whether or not the iteration converged
          -newhits_unclassified => array reference to hits that were not found
                      in a previous iteration for the iteration and have not been
                      classified with regard to the inclusion threshold

          # The following are only used for PSI-BLAST reports:

          -newhits_below => array reference to hits were not found in a
                       previous iteration and are below the inclusion threshold.
          -newhits_not_below => array reference to hits that were not found in a
                       previous iteration below threshold that and are not below
                       the inclusion threshold threshold.
          -oldhits_below => array reference to hits that were found
                       in a previous iteration below inclusion threshold and are
                       still below threshold in the current iteration.
          -oldhits_newly_below => array reference to hits that were found
                       in a previous iteration above threshold but are below
                       threshold in the current iteration.
          -oldhits_not_below => array reference to hits that were found in a
                       previous iteration above threshold that and are still above
                       the inclusion threshold threshold.

          -hit_factory => Bio::Factory::ObjectFactoryI capable of making
                       Bio::Search::Hit::HitI objects

heads up bestie: -number is required. everything else? optional but very much invited to the party. 🎉

⭐ number

see documentation in Bio::Search::Iteration::IterationI.

⭐ converged

see documentation in Bio::Search::Iteration::IterationI.

⭐ hit_factory

Title   : hit_factory
Usage   : $hit->hit_factory($hit_factory)
Function: Get/set the factory used to build HitI objects if necessary.
Returns : Bio::Factory::ObjectFactoryI
Args    : Bio::Factory::ObjectFactoryI

⭐ next_hit

this iterates through all old hits as returned by oldhits followed by all new hits as returned by newhits. so old first, then new. in that order. no skipping. 💫

for more documentation see Bio::Search::Iteration::IterationI::next_hit().

⭐ next_hit_new

see documentation in Bio::Search::Iteration::IterationI::next_hit_new().

⭐ next_hit_old

see documentation in Bio::Search::Iteration::IterationI::next_hit_old().

⭐ rewind

Title   : rewind
Usage   : $iteration->rewind;
Function: Allow one to reset the Hit iterators to the beginning
          Since this is an in-memory implementation
Returns : none
Args    : none

⭐ num_hits

see documentation in Bio::Search::Iteration::IterationI::num_hits().

⭐ num_hits_new

see documentation in Bio::Search::Iteration::IterationI::num_hits_new().

⭐ num_hits_old

see documentation in Bio::Search::Iteration::IterationI::num_hits_old().

⭐ add_hit

see documentation in Bio::Search::Iteration::IterationI::add_hit().

⭐ hits

see Documentation in InterfaceI.

⭐ newhits

returns a list containing all newhits in this order:

newhits_below_threshold newhits_not_below_threshold newhits_unclassified

see more documentation in InterfaceI.

⭐ newhits_below_threshold

see documentation in Bio::Search::Iteration::IterationI::newhits_below_threshold().

⭐ newhits_not_below_threshold

see documentation in Bio::Search::Iteration::IterationI::newhits_not_below_threshold().

⭐ newhits_unclassified

Title   : newhits_unclassified
Usage   : foreach( $iteration->hits_unclassified ) {...}
Function: Gets all newhits that have not been partitioned into
          sets relative to the inclusion threshold.
Returns : Array of Bio::Search::Hit::HitI objects.
Args    : none

⭐ oldhits

returns a list containing all oldhits in this order:

oldhits_below_threshold oldhits_newly_below_threshold oldhits_not_below_threshold

see more documentation in InterfaceI.

⭐ oldhits_below_threshold

see documentation in Bio::Search::Iteration::IterationI::oldhits_below_threshold().

⭐ oldhits_newly_below_threshold

see documentation in Bio::Search::Iteration::IterationI::oldhits_newly_below_threshold().

⭐ oldhits_not_below_threshold

see documentation in Bio::Search::Iteration::IterationI::oldhits_not_below_threshold().

⭐ hits_below_threshold

see documentation in Bio::Search::Iteration::IterationI::hits_below_threshold().

⭐ get_hit

see documentation in Bio::Search::Iteration::IterationI::get_hit().

to free up the memory used by the get_hit() functionality, call free_hit_lookup().

this functionality might be useful at the Result level, too. BlastResult::get_hit() would return a list of HitI objects for hits that occur in multiple iterations. 👀

⭐ free_hit_lookup

Purpose : Frees up the memory used by the get_hit() functionality.
          For the memory-conscious.

for the memory-conscious ✨ — that's you if your process is sweating, bestie. free that lookup and breathe. 🧘

---

and that's the whole page, bestie!! this doc came to you courtesy of perl v5.32.1, dated 2021-08-15. go forth and partition your hits. slay. 💅💖🦋