Bio/AlignIO/bl2seq.pm

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