BPpsilite documentation.

  use Bio::Tools::BPpsilite;
  open FH, "t/psiblastreport.out";
  $report = Bio::Tools::BPpsilite->new(-fh=>\*FH);

  # determine number of iterations executed by psiblast
  $total_iterations = $report->number_of_iterations;
  $last_iteration = $report->round($total_iterations);

  # Process only hits found in last iteration ...
   $oldhitarray_ref = $last_iteration->oldhits;
   HIT: while($sbjct = $last_iteration->nextSbjct) {
  	  $id = $sbjct->name;
  	  $is_old =  grep  /\Q$id\E/, @$oldhitarray_ref;
  	  if ($is_old ){next HIT;}
  #  do something with new hit...
  }

BPpsilite is a package for parsing multiple iteration PSIBLAST
reports. It is based closely on Ian Korf's BPlite.pm module for
parsing single iteration BLAST reports (as modified by Lorenz Pollak).
Two of the four basic objects of BPpsilite.pm are identical to the
corresponding objects in BPlite - the "HSP.pm" and "Sbjct.pm" objects.
This DESCRIPTION documents only the one new object, the "iteration",
as well as the additional methods that are implemented in BPpsilite
that are not in BPlite. See the BPlite documentation for information
on the BPlite, SBJCT and HSP objects.
The essential difference between PSIBLAST and the other BLAST programs
(in terms of report parsing) is that PSIBLAST performs multiple
iterations of the BLASTing of the database and the results of all of
these iterations are stored in a single PSIBLAST report. (For general
information on PSIBLAST see the README.bla file in the standalone
BLAST distribution and references therein). PSIBLAST's use of multiple
iterations imposes additional demands on the report parser: * There
are several iterations of hits. Many of those hits will be repeated
in more than one iteration. Often only the last iteration will be of
interest. * Each iteration will list two different kinds of hits -
repeated hits that were used in the model and newly identified hits -
which may need to be processed in different manners * The total number
of iterations performed is not displayed in the report until (almost)
the very end of the report. (The user can specify a maximum number of
iterations for the PSIBLAST search, but the program may perform fewer
iterations if convergence is reached)
BPpsilite addresses these issues by offering the following methods:
* The total number of iteration used is given by the method
number_of_iterations as in:

	$total_iterations = $report->number_of_iterations;

* Results from an arbitrary iteration round can be accessed by using
the 'round' method:

	$iteration3_report = $report->round(3);

* The ids of the sequences which passed the significance threshold for
the first time in the "nth" iteration can be identified by using the
newhits method. Previously identified hits are identified by using
the oldhits method, as in:

 	$oldhitarray_ref = $iteration3_report->oldhits;
 	$newhitarray_ref = $iteration3_report->newhits;

BPpsilite.pm should work equally well on reports generated by the
StandAloneBlast.pm local BLAST module as with reports generated by
remote psiblast searches. For examples of usage of BPpsilite.pm, the
user is referred to the BPpsilite.t script in the "t" directory.

sub _parseHeader {

  my ($self) = @_;

  
  while(defined ($_ = $self->_readline) ) {
    if ($_ =~ /^Query=\s+([^\(]+)/)    {
      my $query = $1;
      while(defined ($_ = $self->_readline)) {
        last if $_ !~ /\S/;
	$query .= $_;
      }
      $query =~ s/\s+/ /g;
      $query =~ s/^>//;
      $query =~ /\((\d+)\s+\S+\)\s*$/;
      my $length = $1;
      $self->{'QUERY'} = $query;
      $self->{'LENGTH'} = $length;
    }
    elsif ($_ =~ /^Database:\s+(.+)/) {$self->{'DATABASE'} = $1}
    elsif ($_ =~ /^\s*pattern\s+(\S+).*position\s+(\d+)\D/) 
    {   # For PHIBLAST reports
	$self->{'PATTERN'} = $1;
	push (@{$self->{'QPATLOCATION'}}, $2);
    } elsif ($_ =~ /^>|^Results from round 1/)    {
	$self->_pushback($_); 
	return 1;
    } elsif ($_ =~ /^Parameters|^\s+Database:/) {
	$self->_pushback($_); 
	return 0; # there's nothing in the report
    }
  }

}

sub _preprocess {

    my $self = shift;
#	$self->throw(" PSIBLAST report preprocessing not implemented yet!");

    my  $oldround = 0;
    my ($currentline, $currentfile, $round);

# open output file for data from iteration round #1
    $round = 1;
    $currentfile = Bio::Root::IO->catfile($self->{'_tempdir'}, 
					  "iteration$round.tmp");
    open (FILEHANDLE, ">$currentfile") || 
	$self->throw("cannot open filehandle to write to file $currentfile");

    while(defined ($currentline = $self->_readline()) ) {
	if ($currentline =~ /^Results from round\s+(\d+)/) {
	    if ($oldround) { close (FILEHANDLE) ;}
	    $round = $1;
	    $currentfile = Bio::Root::IO->catfile($self->{'_tempdir'}, 
						  "iteration$round.tmp");

	    close FILEHANDLE;
	    open (FILEHANDLE, ">$currentfile") || 
		$self->throw("cannot open filehandle to write to file $currentfile");
	    $oldround = $round;
	}elsif ($currentline =~ /CONVERGED/){ # This is a fix for psiblast parsing with -m 6 /AE
	    $round--;
	}
	print FILEHANDLE $currentline ;
	
    }
    $self->{'TOTAL_ITERATION_NUMBER'}= $round;
# It is necessary to close filehandle otherwise the whole
# file will not be read later !!
    close FILEHANDLE;
}

1;

__END__

}

sub new {

  my ($class, @args) = @_; 
  my $self = $class->SUPER::new(@args);
  
  # initialize IO
  $self->_initialize_io(@args);
  $self->{'_tempdir'} = $self->tempdir('CLEANUP' => 1);
  $self->{'QPATLOCATION'} = [];  # Anonymous array of query pattern locations for PHIBLAST
  $self->{'NEXT_ITERATION_NUMBER'} = 1;
  $self->{'TOTAL_ITERATION_NUMBER'} = -1;  # -1 indicates preprocessing not yet done

  if ($self->_parseHeader) {$self->{'REPORT_DONE'} = 0} # there are alignments
  else                     {$self->{'REPORT_DONE'} = 1} # empty report
  
  return $self; # success - we hope!

}

_parseHeader	No description	Code
_preprocess	Description	Code
database	Description	Code
new	No description	Code
number_of_iterations	Description	Code
pattern	Description	Code
qlength	Description	Code
query	Description	Code
query_pattern_location	Description	Code
round	Description	Code