.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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::IterationI 3pm"
.TH Bio::Search::Iteration::IterationI 3pm "2021-08-15" "perl v5.32.1" "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::IterationI \- Abstract interface to an
iteration from an iterated search result, such as PSI\-BLAST.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    # 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>\en";
\&    my $in = Bio::SearchIO\->new(\-format => \*(Aqblast\*(Aq,
\&                               \-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\en", $in\->result_count, $result\->to_string;
\&        printf "Total Iterations: %d\en", $result\->num_iterations();
\&
\&        # Iterate over all iterations and process old and new hits
\&        # separately.
\&
\&        while( my $it = $result\->next_iteration) { 
\&            printf "\enIteration %d\en", $it\->number;
\&            printf "Converged: %d\en", $it\->converged;
\&
\&            # Print out the hits not found in previous iteration
\&            printf "New hits: %d\en", $it\->num_hits_new;
\&            while( my $hit = $it\->next_hit_new ) {
\&                printf "  %s, Expect=%g\en", $hit\->name, $hit\->expect; 
\&            }
\&
\&            # Print out the hits found in previous iteration
\&            printf "Old hits: %d\en", $it\->num_hits_old; 
\&            while( my $hit = $it\->next_hit_old ) {
\&                printf "  %s, Expect=%g\en", $hit\->name, $hit\->expect; 
\&            }
\&        }
\&        printf "%s\en\en", \*(Aq\-\*(Aq x 50;
\&    }
\&
\&    printf "Total Reports processed: %d: %s\en", $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);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SS "Classification of Hits"
.IX Subsection "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.
.PP
.Vb 10
\&                           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)
.Ve
.PP
Notes: The term \fIthreshold\fR in the diagram and descriptions below
refer to this inclusion threshold. \fIBelow threshold\fR actually means
\&\fIat or below threshold\fR.
.PP
The IterationI interface defines a number of methods for extracting
these subsets of hits.
.IP "\(bu" 4
\&\fBnewhits_below_threshold()\fR [subset D]
.Sp
Hits that did not appear in a previous iteration and are below
threshold in the current iteration.
.IP "\(bu" 4
\&\fBnewhits_not_below_threshold()\fR [subset E]
.Sp
Hits that did not appear in a previous iteration and are not below
threshold in the current iteration.
.IP "\(bu" 4
\&\fBnewhits()\fR [subset B]
.Sp
All newly found hits, below and above the inclusion threshold.  This
is the union of \fBnewhits_below_threshold()\fR + \fBnewhits_not_below_threshold()\fR
[subset D + subset E].
.IP "\(bu" 4
\&\fBoldhits_below_threshold()\fR [subset H]
.Sp
Hits that appeared in a previous iteration below threshold and are
still below threshold in the current iteration.
.IP "\(bu" 4
\&\fBoldhits_newly_below_threshold()\fR [subset I]
.Sp
Hits that appeared in a previous iteration above threshold but are
below threshold in the current iteration. (Not applicable to the first
iteration.)
.IP "\(bu" 4
\&\fBoldhits_not_below_threshold()\fR [subset G]
.Sp
Hits that appeared in a previous iteration not below threshold and
are still not below threshold in the current iteration.
.IP "\(bu" 4
\&\fBoldhits()\fR  [subset C]
.Sp
All hits that occurred in a previous iteration, whether below or above
threshold in the current iteration. Union of \fBoldhits_below_threshold()\fR
+ \fBoldhits_newly_below_threshold()\fR + \fBoldhits_not_below_threshold()\fR
[subset H + subset I + subset G]. (Not applicable to the first
iteration.)
.IP "\(bu" 4
\&\fBhits_below_threshold()\fR [subset D + subset F]
.Sp
All hits, old and new, that are below the inclusion threshold in this
iteration. This is the union of \fBnewhits_below_threshold()\fR +
\&\fBoldhits_below_threshold()\fR + \fBoldhits_newly_below_threshold()\fR
[subset D + subset H + subset I].
.IP "\(bu" 4
\&\fBhits()\fR [subset A]
.Sp
The union of \fBnewhits()\fR and \fBoldhits()\fR [subset B + subset C].
.PP
For the first iteration, the methods oldhits, oldhits_below_threshold,
oldhits_newly_below_threshold, and \fBoldhits_not_below_threshold()\fR
will return empty lists.
.PP
Iterator and numbers-of-hit methods are provided for subsets A, B, and C:
.IP "\(bu" 4
\&\fBnext_hit_new()\fR, \fBnum_hits_new()\fR [subset B]
.IP "\(bu" 4
\&\fBnext_hit_old()\fR, \fBnum_hits_old()\fR [subset C]
.IP "\(bu" 4
\&\fBnext_hit()\fR, \fBnum_hits()\fR [subset A]
.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 one
of the Bioperl mailing lists.  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
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"
.IX Header "AUTHOR"
Steve Chervitz <sac@bioperl.org>
.PP
See the \s-1FEEDBACK\s0 section  for where to send bug reports and comments.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 Steve Chervitz. All Rights Reserved.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This software is provided \*(L"as is\*(R" without warranty of any kind.
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "number"
.IX Subsection "number"
.Vb 6
\& 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
.Ve
.SS "converged"
.IX Subsection "converged"
.Vb 5
\& 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
.Ve
.SS "next_hit"
.IX Subsection "next_hit"
.Vb 11
\& 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
.Ve
.PP
See Also: hits, \*(L"Classification of Hits\*(R"
.PP
\&\fBnext_hit()\fR 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.
.PP
To get just the new hits, use next_hit_new.
To get just the old hits, use next_hit_old.
.SS "next_hit_new"
.IX Subsection "next_hit_new"
.Vb 10
\& 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
.Ve
.PP
See Also: next_hit, next_hit_old, newhits, \*(L"Classification of Hits\*(R"
.SS "next_hit_old"
.IX Subsection "next_hit_old"
.Vb 11
\& 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
.Ve
.PP
See Also: next_hit, next_hit_old, oldhits, \*(L"Classification of Hits\*(R"
.SS "num_hits"
.IX Subsection "num_hits"
.Vb 6
\& 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
.Ve
.PP
See Also: num_hits_new, num_hits_old, \*(L"Classification of Hits\*(R"
.SS "num_hits_new"
.IX Subsection "num_hits_new"
.Vb 11
\& 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.
.Ve
.PP
See Also: num_hits, num_hits_old, \*(L"Classification of Hits\*(R"
.SS "num_hits_old"
.IX Subsection "num_hits_old"
.Vb 11
\& 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.
.Ve
.PP
See Also: num_hits, num_hits_new, \*(L"Classification of Hits\*(R"
.SS "hits"
.IX Subsection "hits"
.Vb 10
\& 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
.Ve
.PP
See Also: newhits, oldhits, \*(L"Classification of Hits\*(R"
.SS "newhits"
.IX Subsection "newhits"
.Vb 10
\& 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
.Ve
.PP
See Also: hits, oldhits, newhits_below_threshold + newhits_not_below_threshold, \*(L"Classification of Hits\*(R"
.SS "oldhits"
.IX Subsection "oldhits"
.Vb 10
\& 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
.Ve
.PP
See Also: hits, newhits, oldhits_below_threshold, oldhits_newly_below_threshold, oldhits_not_below_threshold, \*(L"Classification of Hits\*(R"
.SS "newhits_below_threshold"
.IX Subsection "newhits_below_threshold"
.Vb 10
\& 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
.Ve
.PP
See Also: newhits_not_below_threshold, oldhits_newly_below_threshold, newhits, \*(L"Classification of Hits\*(R"
.SS "oldhits_below_threshold"
.IX Subsection "oldhits_below_threshold"
.Vb 10
\& 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
.Ve
.PP
See Also: oldhits_not_below_threshold, oldhits_newly_below_threshold, oldhits, \*(L"Classification of Hits\*(R"
.SS "oldhits_newly_below_threshold"
.IX Subsection "oldhits_newly_below_threshold"
.Vb 11
\& 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
.Ve
.PP
See Also: newhits_below_threshold, oldhits, \*(L"Classification of Hits\*(R"
.SS "oldhits_not_below_threshold"
.IX Subsection "oldhits_not_below_threshold"
.Vb 10
\& 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
.Ve
.PP
See Also: oldhits_below_threshold, oldhits, \*(L"Classification of Hits\*(R"
.SS "newhits_not_below_threshold"
.IX Subsection "newhits_not_below_threshold"
.Vb 11
\& 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
.Ve
.PP
See Also: newhits_below_threshold, newhits, \*(L"Classification of Hits\*(R"
.SS "hits_below_threshold"
.IX Subsection "hits_below_threshold"
.Vb 9
\& 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
.Ve
.PP
See Also: newhits_below_threshold, oldhits_newly_below_threshold, oldhits_below_threshold, \*(L"Classification of Hits\*(R"
.SS "add_hit"
.IX Subsection "add_hit"
.Vb 10
\& 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.
.Ve
.SS "get_hit"
.IX Subsection "get_hit"
.Vb 7
\& 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
.Ve
.PP
The name string must be the same as that returned by
\&\fBBio::Search::Hit::HitI::name()\fR.
.PP
The lookup should be case-insensitive.