Summary

Bio::Tools::BPbl2seq - Lightweight BLAST parser for pair-wise sequence
alignment using the BLAST algorithm.

Package variables

Included modules

Inherit

Bio::Root::IO Bio::Root::Root Bio::SeqAnalysisParserI

Synopsis

  use Bio::Tools::BPbl2seq;
  my $report = Bio::Tools::BPbl2seq->new(-file => 't/bl2seq.out');
  $report->sbjctName;
  $report->sbjctLength;
  while(my $hsp = $report->next_feature) {
         $hsp->score;
         $hsp->bits;
         $hsp->percent;
         $hsp->P;
         $hsp->match;
         $hsp->positive;
         $hsp->length;
	 $hsp->querySeq;
	 $hsp->sbjctSeq;
	 $hsp->homologySeq;
	 $hsp->query->start;
	 $hsp->query->end;
	 $hsp->sbjct->start;
	 $hsp->sbjct->end;
	 $hsp->sbjct->seq_id;
	 $hsp->sbjct->overlaps($exon);
 }

Description

NOTE: This module's functionality has been implemented in
Bio::SearchIO::blast and therefore is not actively maintained.
BPbl2seq is a package for parsing BLAST bl2seq reports. BLAST bl2seq
is a program for comparing and aligning two sequences using BLAST.
Although the report format is similar to that of a conventional BLAST,
there are a few differences so that BPlite is unable to read bl2seq
reports directly.
From the user's perspective, one difference between bl2seq and other
blast reports is that the bl2seq report does not print out the name of
the first of the two aligned sequences. (The second sequence name is
given in the report as the name of the "hit"). Consequently, BPbl2seq
has no way of identifying the name of the initial sequence unless it
is passed to constructor as a second argument as in:

	my $report = Bio::Tools::BPbl2seq->new(\*FH, "ALEU_HORVU");

If the name of the first sequence (the "query") is not passed to
BPbl2seq.pm in this manner, the name of the first sequence will be
left as "unknown". (Note that to preserve a common interface with the
other BLAST programs the two sequences being compared are referred to
in bl2seq as "query" and "subject" although this is perhaps a bit
misleading when simply comparing 2 sequences as opposed to querying a
database.)
In addition, since there will only be (at most) one "subject" (hit) in
a bl2seq report, one should use the method $report->next_feature,
rather than $report->nextSbjct->nextHSP to obtain the next
high scoring pair.
One should note that the previous (0.7) version of BPbl2seq used
slightly different syntax. That version had a bug and consequently the
old syntax has been eliminated. Attempts to use the old syntax will
return error messages explaining the (minor) recoding required to use
the current syntax.

Methods

Methods description

 Title   : new
 Function: Create a new Bio::Tools::BPbl2seq object
 Returns : Bio::Tools::BPbl2seq
 Args    : -file     input file (alternative to -fh)
           -fh       input stream (alternative to -file)
           -queryname    name of query sequence
           -report_type What type of BLAST was run (blastn,blastp,tblastn...)

 Title    :
 Usage    : $sbjct = $obj->getSbjct();
 Function : Method of obtaining single "subject" of a bl2seq report
 Example  : my $sbjct = $obj->getSbjct ) {}
 Returns  : Sbjct object or undef if finished
 Args     :

 Title   : next_feature
 Usage   : while( my $feat = $res->next_feature ) { # do something }
 Function: calls next_feature function from BPlite.
 Example :
 Returns : A Bio::SeqFeatureI compliant object, in this case a
           Bio::Tools::BPlite::HSP object, and FALSE if there are no more
           HSPs.
 Args    : None

 Title    :
 Usage    : $name = $report->queryName();
 Function : get /set the name of the query
 Example  :
 Returns  : name of the query
 Args     :

 Title    :
 Usage    : $name = $report->sbjctName();
 Function : returns the name of the Sbjct
 Example  :
 Returns  : name of the Sbjct
 Args     :

 Title    :  sbjctLength
 Usage    : $length = $report->sbjctLength();
 Function : returns the length of the Sbjct
 Example  :
 Returns  : name of the Sbjct
 Args     :

 Title    : P
 Usage    :
 Function : Syntax no longer supported, error message only

 Title    : percent
 Usage    : $hsp->percent();
 Function : Syntax no longer supported, error message only

 Title    : match
 Usage    : $hsp->match();
 Function : Syntax no longer supported, error message only

 Title    : positive
 Usage    : $hsp->positive();
 Function : Syntax no longer supported, error message only

 Title    : querySeq
 Usage    : $hsp->querySeq();
 Function : Syntax no longer supported, error message only

 Title    : sbjctSeq
 Usage    : $hsp->sbjctSeq();
 Function : Syntax no longer supported, error message only

 Title    : homologySeq
 Usage    : $hsp->homologySeq();
 Function : Syntax no longer supported, error message only

 Title    : qs
 Usage    : $hsp->qs();
 Function : Syntax no longer supported, error message only

 Title    : ss
 Usage    : $hsp->ss();
 Function : Syntax no longer supported, error message only

 Title    : hs
 Usage    : $hsp->hs();
 Function : Syntax no longer supported, error message only

Methods code

sub new {

    my ($class, @args) = @_;
    my $self = $class->SUPER::new(@args);
    $self->warn("Use of Bio::Tools::BPbl2seq is deprecated".
                   "Use Bio::SearchIO classes instead");
    # initialize IO
    $self->_initialize_io(@args);

    my ($queryname,$rt) = $self->_rearrange([qw(QUERYNAME 
						REPORT_TYPE)], @args);
    $queryname = 'unknown' if( ! defined $queryname );
    if( $rt && $rt =~ /BLAST/i ) {
	$self->{'BLAST_TYPE'} = uc($rt);
    } else { 
	$self->warn("Must provide which type of BLAST was run (blastp,blastn, tblastn, tblastx, blastx) if you want strand information to get set properly for DNA query or subjects");
    }
    my $sbjct = $self->getSbjct();
    $self->{'_current_sbjct'} = $sbjct;

    $self->{'_query'}->{'NAME'} = $queryname;
    return $self;

}

sub getSbjct {

  my ($self) = @_;
#  $self->_fastForward or return;

  #######################
  # get bl2seq "sbjct" name and length #
  #######################
  my $length;
  my $def;
 READLOOP: while(defined ($_ = $self->_readline) ) {
     if ($_ =~ /^>(.+)$/) {
	$def = $1;
	next READLOOP;
     }
    elsif ($_ =~ /^\s*Length\s.+\D(\d+)/i) {
	$length = $1;	
	next READLOOP;
     }
    elsif ($_ =~ /^\s{0,2}Score/) {
	$self->_pushback($_); 	
	last READLOOP;
     }
  }
  return if ! defined $def;
  $def =~ s/\s+/ /g;
  $def =~ s/\s+$//g;
  

  ####################
  # the Sbjct object #
  ####################
  my $sbjct = new Bio::Tools::BPlite::Sbjct('-name'=>$def,
					    '-length'=>$length,
					    '-parent'=>$self);
  return $sbjct;

}

sub next_feature {

   my ($self) = @_;
   my ($sbjct, $hsp);
   $sbjct = $self->{'_current_sbjct'};
   unless( defined $sbjct ) {
       $self->debug(" No hit object found for bl2seq report\n  ");
       return;
   }
   $hsp = $sbjct->nextHSP;
   return $hsp || undef;

}

sub queryName {

    my ($self, $queryname) = @_;
    if( $queryname ) {
	$self->{'_query'}->{'NAME'} = $queryname;
    }
    $self->{'_query'}->{'NAME'};

}

sub sbjctName {

	my $self = shift;
#	unless( defined  $self->{'_current_sbjct'} ) {
#       		my $sbjct = $self->{'_current_sbjct'} = $self->nextSbjct;
#       		return unless defined $sbjct;
#   	}
	$self->{'_current_sbjct'}->{'NAME'} || '';

}

sub sbjctLength {

	my $self = shift;
#	unless( defined  $self->{'_current_sbjct'} ) {
#       		my $sbjct = $self->{'_current_sbjct'} = $self->nextSbjct;
#       		return unless defined $sbjct;
#   	}
	$self->{'_current_sbjct'}->{'LENGTH'};

}

sub P {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ");

}

sub percent {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ");

}

sub match {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ");

}

sub positive {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub querySeq {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub sbjctSeq {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub homologySeq {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub qs {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub ss {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub hs {

	my $self = shift;
	$self->throw("Syntax used is no longer supported.\n  See BPbl2seq.pm documentation for current syntax.\n ") ;

}

sub _fastForward {

    my ($self) = @_;
    return 0 if $self->{'REPORT_DONE'}; # empty report
    while(defined( $_ = $self->_readline() ) ) {
	if ($_ =~ /^>|^Parameters|^\s+Database:|^\s+Posted date:|^\s*Lambda/) {
	    $self->_pushback($_);	
	    return 1;
	}
    }
    $self->warn("Possible error (1) while parsing BLAST report!");

}

sub DESTROY {

     my $self = shift; 
    if( defined  $self->{'_current_sbjct'} ) { 
	$self->{'_current_sbjct'}->{'PARENT'} = undef;
	$self->{'_current_sbjct'} = undef;
    }
    $self->_io_cleanup();

}

General documentation

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

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:

  http://bugzilla.open-bio.org/

Email: schattner@alum.mit.edu

Based on work of:
Ian Korf (ikorf@sapiens.wustl.edu, http://sapiens.wustl.edu/~ikorf), Lorenz Pollak (lorenz@ist.org, bioperl port)

Jason Stajich, jason-at-bioperl.org