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

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 null 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);
    # 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 undef;

  #######################
  # 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 undef 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 undef;
   }
   $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 undef 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 undef 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!");

}

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://bio.perl.org/MailList.html             - 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
email or the web:

  bioperl-bugs@bio.perl.org
  http://bugzilla.bioperl.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@cgt.mc.duke.edu