Bio/AlignIO/bl2seq.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::AlignIO::bl2seq
   4
   5 #   based on the Bio::SeqIO modules
   6 #       by Ewan Birney <birney@ebi.ac.uk>
   7 #       and Lincoln Stein  <lstein@cshl.org>
   8 #
   9 #   the Bio::Tools::BPlite modules by
  10 #   Ian Korf (ikorf@sapiens.wustl.edu, http://sapiens.wustl.edu/~ikorf),
  11 #   Lorenz Pollak (lorenz@ist.org, bioperl port)
  12 #
  13 #       and the SimpleAlign.pm module of Ewan Birney
  14 #
  15 # Copyright Peter Schattner
  16 #
  17 # You may distribute this module under the same terms as perl itself
  18 # _history
  19 # September 5, 2000
  20 # POD documentation - main docs before the code
  21
  22 =head1 NAME
  23
  24 Bio::AlignIO::bl2seq - bl2seq sequence input/output stream
  25
  26 =head1 SYNOPSIS
  27
  28 Do not use this module directly.  Use it via the L<Bio::AlignIO> class, as in:
  29
  30     use Bio::AlignIO;
  31
  32     $in  = Bio::AlignIO->new(-file   => "inputfilename" ,
  33                              -format => "bl2seq",
  34                              -report_type => "blastn");
  35     $aln = $in->next_aln();
  36
  37
  38 =head1 DESCRIPTION
  39
  40 This object can create L<Bio::SimpleAlign> sequence alignment objects (of
  41 two sequences) from C<bl2seq> BLAST reports.
  42
  43 A nice feature of this module is that - in combination with
  44 L<Bio::Tools::Run::StandAloneBlast.pm> or a remote BLAST - it can be used to
  45 align two sequences and make a L<Bio::SimpleAlign> object from them which
  46 can then be manipulated using any L<Bio::SimpleAlign> methods, eg:
  47
  48    # Get two sequences
  49    $str = Bio::SeqIO->new(-file=>'t/amino.fa' , '-format' => 'Fasta', );
  50    my $seq3 = $str->next_seq();
  51    my $seq4 = $str->next_seq();
  52
  53    # Run bl2seq on them
  54    $factory = Bio::Tools::StandAloneBlast->new('program' => 'blastp',
  55                                                'outfile' => 'bl2seq.out');
  56    my $bl2seq_report = $factory->bl2seq($seq3, $seq4);
  57    # Note that report is a Bio::SearchIO object
  58
  59    # Use AlignIO.pm to create a SimpleAlign object from the bl2seq report
  60    $str = Bio::AlignIO->new(-file=> 'bl2seq.out','-format' => 'bl2seq');
  61    $aln = $str->next_aln();
  62
  63 =head1 FEEDBACK
  64
  65 =head2 Mailing Lists
  66
  67 User feedback is an integral part of the evolution of this and other
  68 Bioperl modules. Send your comments and suggestions preferably to one
  69 of the Bioperl mailing lists.  Your participation is much appreciated.
  70
  71   bioperl-l@bioperl.org                  - General discussion
  72   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  73
  74 =head2 Support
  75
  76 Please direct usage questions or support issues to the mailing list:
  77
  78 L<bioperl-l@bioperl.org>
  79
  80 rather than to the module maintainer directly. Many experienced and
  81 reponsive experts will be able look at the problem and quickly
  82 address it. Please include a thorough description of the problem
  83 with code and data examples if at all possible.
  84
  85 =head2 Reporting Bugs
  86
  87 Report bugs to the Bioperl bug tracking system to help us keep track
  88 the bugs and their resolution.  Bug reports can be submitted via the
  89 web:
  90
  91   http://bugzilla.open-bio.org/
  92
  93 =head1 AUTHOR - Peter Schattner
  94
  95 Email: schattner@alum.mit.edu
  96
  97 =head1 APPENDIX
  98
  99 The rest of the documentation details each of the object
 100 methods. Internal methods are usually preceded with a _
 101
 102 =cut
 103
 104 # Let the code begin...
 105
 106 package Bio::AlignIO::bl2seq;
 107 use strict;
 108
 109 use Bio::SearchIO;
 110
 111 use base qw(Bio::AlignIO);
 112
 113 =head2 new
 114
 115  Title   : new
 116  Usage   : my $alignio = Bio::SimpleAlign->new(-format => 'bl2seq',
 117                                                -file   => 'filename',
 118                                                -report_type => 'blastx');
 119  Function: Get a L<Bio::SimpleAlign>
 120  Returns : L<Bio::SimpleAlign> object
 121  Args    : -report_type => report type (blastn,blastx,tblastx,tblastn,blastp)
 122
 123 =cut
 124
 125 sub _initialize {
 126     my ($self, @args) = @_;
 127     $self->SUPER::_initialize(@args);
 128     my ($rt) = $self->_rearrange([qw(REPORT_TYPE)],@args);
 129     defined $rt && $self->report_type($rt);
 130 }
 131
 132 =head2 next_aln
 133
 134  Title   : next_aln
 135  Usage   : $aln = $stream->next_aln()
 136  Function: returns the next alignment in the stream.
 137  Returns : L<Bio::Align::AlignI> object on success,
 138            undef on error or end of file
 139  Args    : none
 140
 141 =cut
 142
 143 sub next_aln {
 144     my $self = shift;
 145     unless (exists $self->{'_searchio'}) {
 146         $self->{'_searchio'} = Bio::SearchIO->new(-fh => $self->_fh,
 147                    -format => 'blast',
 148                    -report_type => $self->report_type);
 149     }
 150     while (1) {
 151         if (!exists $self->{'_result'}) {
 152             $self->{'_result'} = $self->{'_searchio'}->next_result;
 153         }
 154         return if !defined $self->{'_result'};
 155         if (!exists $self->{'_hit'}) {
 156             $self->{'_hit'} = $self->{'_result'}->next_hit;
 157         }
 158         # out of hits for this result?
 159         if (!defined $self->{'_hit'}) {
 160             delete $self->{'_result'};
 161             next;
 162         }
 163         my $hsp = $self->{'_hit'}->next_hsp;
 164         # out of hsps for this hit?
 165         if (!defined $hsp) {
 166             delete $self->{'_hit'};
 167             next;
 168         }
 169         $hsp ? return $hsp->get_aln: return;
 170     }
 171 }
 172
 173
 174 =head2 write_aln (NOT IMPLEMENTED)
 175
 176  Title   : write_aln
 177  Usage   : $stream->write_aln(@aln)
 178  Function: writes the $aln object into the stream in bl2seq format
 179  Returns : 1 for success and 0 for error
 180  Args    : L<Bio::Align::AlignI> object
 181
 182
 183 =cut
 184
 185 sub write_aln {
 186     my ($self,@aln) = @_;
 187     $self->throw_not_implemented();
 188 }
 189
 190 =head2 report_type
 191
 192  Title   : report_type
 193  Usage   : $obj->report_type($newval)
 194  Function: Sets the report type (blastn, blastp...)
 195  Returns : value of report_type (a scalar)
 196  Args    : on set, new value (a scalar or undef, optional)
 197
 198
 199 =cut
 200
 201 sub report_type{
 202     my $self = shift;
 203     return $self->{'report_type'} = shift if @_;
 204     return $self->{'report_type'};
 205 }
 206
 207 1;