.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Search::Iteration::GenericIteration 3pm"
.TH Bio::Search::Iteration::GenericIteration 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Search::Iteration::GenericIteration \- A generic implementation of the Bio::Search::Iteration::IterationI interface.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\&    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],
\&                                        );
.Ve
.PP
# \s-1TODO:\s0 Describe how to configure a SearchIO stream so that it generates
#       GenericIteration objects.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module acts as a container for Bio::Search::Hit::HitI objects,
allowing a Search::Result::ResultI object to partition its hits based
on which iteration the hit occurred in (e.g., a PSI-BLAST round).
.PP
Unless you're writing a parser, you won't ever need to create a
GenericIteration or any other IterationI-implementing object. If you use
the SearchIO system, IterationI objects are created automatically from
a SearchIO stream which returns Bio::Search::Result::ResultI objects
and you get the IterationI objects via the ResultI \s-1API.\s0
.PP
For documentation on what you can do with GenericIteration (and other IterationI
objects), please see the \s-1API\s0 documentation in
Bio::Search::Iteration::IterationI.
.PP
Bio::Search::Iteration::GenericIteration is similar in spirit to the deprecated
Bio::Tools::BPlite::Iteration modules in bioperl releases prior to 1.6, except
that Bio::Search::Iteration::GenericIteration is a pure container, without any
parsing functionality as is in Bio::Tools::BPlite::Iteration.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Steve Chervitz"
.IX Header "AUTHOR - Steve Chervitz"
Email sac@bioperl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 9
\& 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
.Ve
.SS "number"
.IX Subsection "number"
See documentation in Bio::Search::Iteration::IterationI.
.SS "converged"
.IX Subsection "converged"
See documentation in Bio::Search::Iteration::IterationI.
.SS "hit_factory"
.IX Subsection "hit_factory"
.Vb 5
\& 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
.Ve
.SS "next_hit"
.IX Subsection "next_hit"
This iterates through all old hits as returned by oldhits 
followed by all new hits as returned by newhits.
.PP
For more documentation see \fBBio::Search::Iteration::IterationI::next_hit()\fR.
.SS "next_hit_new"
.IX Subsection "next_hit_new"
See documentation in \fBBio::Search::Iteration::IterationI::next_hit_new()\fR.
.SS "next_hit_old"
.IX Subsection "next_hit_old"
See documentation in \fBBio::Search::Iteration::IterationI::next_hit_old()\fR.
.SS "rewind"
.IX Subsection "rewind"
.Vb 6
\& 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
.Ve
.SS "num_hits"
.IX Subsection "num_hits"
See documentation in \fBBio::Search::Iteration::IterationI::num_hits()\fR.
.SS "num_hits_new"
.IX Subsection "num_hits_new"
See documentation in \fBBio::Search::Iteration::IterationI::num_hits_new()\fR.
.SS "num_hits_old"
.IX Subsection "num_hits_old"
See documentation in \fBBio::Search::Iteration::IterationI::num_hits_old()\fR.
.SS "add_hit"
.IX Subsection "add_hit"
See documentation in \fBBio::Search::Iteration::IterationI::add_hit()\fR.
.SS "hits"
.IX Subsection "hits"
See Documentation in InterfaceI.
.SS "newhits"
.IX Subsection "newhits"
Returns a list containing all newhits in this order:
.PP
newhits_below_threshold
newhits_not_below_threshold
newhits_unclassified
.PP
See more documentation in InterfaceI.
.SS "newhits_below_threshold"
.IX Subsection "newhits_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::newhits_below_threshold()\fR.
.SS "newhits_not_below_threshold"
.IX Subsection "newhits_not_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::newhits_not_below_threshold()\fR.
.SS "newhits_unclassified"
.IX Subsection "newhits_unclassified"
.Vb 6
\& 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
.Ve
.SS "oldhits"
.IX Subsection "oldhits"
Returns a list containing all oldhits in this order:
.PP
oldhits_below_threshold
oldhits_newly_below_threshold
oldhits_not_below_threshold
.PP
See more documentation in InterfaceI.
.SS "oldhits_below_threshold"
.IX Subsection "oldhits_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::oldhits_below_threshold()\fR.
.SS "oldhits_newly_below_threshold"
.IX Subsection "oldhits_newly_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::oldhits_newly_below_threshold()\fR.
.SS "oldhits_not_below_threshold"
.IX Subsection "oldhits_not_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::oldhits_not_below_threshold()\fR.
.SS "hits_below_threshold"
.IX Subsection "hits_below_threshold"
See documentation in \fBBio::Search::Iteration::IterationI::hits_below_threshold()\fR.
.SS "get_hit"
.IX Subsection "get_hit"
See documentation in \fBBio::Search::Iteration::IterationI::get_hit()\fR.
.PP
To free up the memory used by the \fBget_hit()\fR functionality, call \fBfree_hit_lookup()\fR.
.PP
This functionality might be useful at the Result level, too.
\&\fBBlastResult::get_hit()\fR would return a list of HitI objects for hits 
that occur in multiple iterations.
.SS "free_hit_lookup"
.IX Subsection "free_hit_lookup"
.Vb 2
\& Purpose : Frees up the memory used by the get_hit() functionality.
\&           For the memory\-conscious.
.Ve