Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::Search::IterationUsereContributed PeBio::Search::Iteration::IterationI(3)

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

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.

       o   newhits_below_threshold() [subset D]

	   Hits	that did not appear in a previous iteration and	are below
	   threshold in	the current iteration.

       o   newhits_not_below_threshold() [subset E]

	   Hits	that did not appear in a previous iteration and	are not	below
	   threshold in	the current iteration.

       o   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].

       o   oldhits_below_threshold() [subset H]

	   Hits	that appeared in a previous iteration below threshold and are
	   still below threshold in the	current	iteration.

       o   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.)

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

       o   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.)

       o   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].

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

       o   next_hit_new(), num_hits_new() [subset B]

       o   next_hit_old(), num_hits_old() [subset C]

       o   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

   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.

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

perl v5.24.1			  2017-07Bio::Search::Iteration::IterationI(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR | COPYRIGHT | DISCLAIMER | APPENDIX

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Search::Iteration::IterationI&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help