Bio/Index/BlastTable.pm

   1 #
   2 # BioPerl module for Bio::Index::BlastTable
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Chris Fields <cjfields@uiuc.edu>
   7 #
   8 # Copyright Chris Fields
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Index::BlastTable - Indexes tabular Blast reports (-m 8 or -m 9 format) and
  17 supports retrieval based on query accession(s)
  18
  19 =head1 SYNOPSIS
  20
  21     use strict;
  22     use Bio::Index::BlastTable;
  23     my ($indexfile,$file1,$file2,$query);
  24     my $index = Bio::Index::BlastTable->new(-filename => $indexfile,
  25                                                           -write_flag => 1);
  26     $index->make_index($file1,$file2);
  27
  28     my $data = $index->get_stream($query);
  29
  30     my $blast_result = $index->fetch_report($query);
  31     print "query is ", $blast_result->query_name, "\n";
  32     while ( my $hit = $blast_result->next_hit ) {
  33         print "Name ", $hit->name,"\n";
  34         while ( my $hsp = $hit->next_hsp ) {
  35             print "Score ", $hsp->score;
  36         }
  37         print "\n";
  38     }
  39
  40 =head1 DESCRIPTION
  41
  42 This object allows one to build an index on a tabular BLAST file (or files)
  43 and provide quick access to the blast report for that accession.  This also
  44 allows for ID parsing using a callback:
  45
  46    $inx->id_parser(\&get_id);
  47    # make the index
  48    $inx->make_index($file_name);
  49
  50    # here is where the retrieval key is specified
  51    sub get_id {
  52       my $line = shift;
  53       $line =~ /^>.+gi\|(\d+)/;
  54       $1;
  55    }
  56
  57 The indexer is capable of indexing based on multiple IDs passed back from the
  58 callback; this is assuming of course all IDs are unique.
  59
  60 Note: for best results 'use strict'.
  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
  68 the Bioperl mailing list.  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 of the bugs and their resolution. Bug reports can be submitted via the
  88 web:
  89
  90   http://bugzilla.open-bio.org/
  91
  92 =head1 AUTHOR - Jason Stajich
  93
  94 Email jason-at-bioperl-dot-org
  95
  96 =head1 APPENDIX
  97
  98 The rest of the documentation details each of the object methods.
  99 Internal methods are usually preceded with a _
 100
 101 =cut
 102
 103 # Let the code begin...
 104
 105 package Bio::Index::BlastTable;
 106 use strict;
 107
 108 use IO::String;
 109 use Bio::SearchIO;
 110 use base qw(Bio::Index::Abstract Bio::Root::Root);
 111
 112 sub _version {
 113         return ${Bio::Root::Version::VERSION};
 114 }
 115
 116 =head2 new
 117
 118   Usage   : $index = Bio::Index::Abstract->new(
 119                 -filename    => $dbm_file,
 120                 -write_flag  => 0,
 121                 -dbm_package => 'DB_File',
 122                 -verbose     => 0);
 123
 124   Function: Returns a new index object.  If filename is
 125             specified, then open_dbm() is immediately called.
 126             Bio::Index::Abstract->new() will usually be called
 127             directly only when opening an existing index.
 128   Returns : A new index object
 129   Args    : -filename    The name of the dbm index file.
 130             -write_flag  TRUE if write access to the dbm file is
 131                          needed.
 132             -dbm_package The Perl dbm module to use for the
 133                          index.
 134             -verbose     Print debugging output to STDERR if
 135                          TRUE.
 136
 137 =cut
 138
 139 sub new {
 140   my($class,@args) = @_;
 141   my $self = $class->SUPER::new(@args);
 142 }
 143
 144 =head2 Bio::Index::Blast implemented methods
 145
 146 =cut
 147
 148 =head2 fetch_report
 149
 150  Title   : fetch_report
 151  Usage   : my $blastreport = $idx->fetch_report($id);
 152  Function: Returns a Bio::SearchIO report object
 153            for a specific blast report
 154  Returns : Bio::SearchIO
 155  Args    : valid id
 156
 157 =cut
 158
 159 sub fetch_report{
 160         my ($self,$id) = @_;
 161         my $fh = $self->get_stream($id);
 162         my $report = Bio::SearchIO->new(-noclose => 1,
 163                                                                         -format => 'blasttable',
 164                                                             -fh => $fh);
 165         return $report->next_result;
 166 }
 167
 168
 169 =head2 Require methods from Bio::Index::Abstract
 170
 171 =cut
 172
 173 =head2 _index_file
 174
 175   Title   : _index_file
 176   Usage   : $index->_index_file( $file_name, $i )
 177   Function: Specialist function to index BLAST report file(s).
 178             Is provided with a filename and an integer
 179             by make_index in its SUPER class.
 180   Example :
 181   Returns :
 182   Args    :
 183
 184 =cut
 185
 186 sub _index_file {
 187         my( $self,
 188                  $file, # File name
 189                  $i,    # Index-number of file being indexed
 190           ) = @_;
 191
 192         open(my $BLAST, '<', $file) or $self->throw("cannot open file $file\n");
 193         my $indexpoint = 0;
 194         my $lastline = 0;
 195     my $last_query = '';
 196     my $is_m9;
 197         while( <$BLAST> ) {
 198         if (m{^#}) {
 199             $is_m9 ||= 1;
 200             if(m{^#\s+T?BLAST[PNX]}i ) {
 201                 $indexpoint = tell($BLAST) - length($_);
 202             }
 203             next
 204         }
 205
 206         if (/^(?:([^\t]+)\t)(?:[^\t]+\t){7,}/) {
 207             next if $last_query eq $1;
 208             $indexpoint = tell($BLAST) - length($_) unless $is_m9;
 209             foreach my $id ($self->id_parser()->($1)) {
 210                                 $self->debug("id is $id, begin is $indexpoint\n");
 211                                 $self->add_record($id, $i, $indexpoint);
 212                         }
 213             $last_query = $1;
 214         }
 215         }
 216 }
 217
 218 # shamelessly stolen from Bio::Index::Fasta
 219
 220 =head2 id_parser
 221
 222   Title   : id_parser
 223   Usage   : $index->id_parser( CODE )
 224   Function: Stores or returns the code used by record_id to
 225             parse the ID for record from a string.  Useful
 226             for (for instance) specifying a different
 227             parser for different flavours of blast dbs.
 228             Returns \&default_id_parser (see below) if not
 229             set. If you supply your own id_parser
 230             subroutine, then it should expect a fasta
 231             description line.  An entry will be added to
 232             the index for each string in the list returned.
 233   Example : $index->id_parser( \&my_id_parser )
 234   Returns : ref to CODE if called without arguments
 235   Args    : CODE
 236
 237 =cut
 238
 239 sub id_parser {
 240         my( $self, $code ) =@_;
 241
 242         if ($code) {
 243                 $self->{'_id_parser'} = $code;
 244         }
 245         return $self->{'_id_parser'} || \&default_id_parser;
 246 }
 247
 248 =head2 default_id_parser
 249
 250   Title   : default_id_parser
 251   Usage   : $id = default_id_parser( $header )
 252   Function: The default Blast Query ID parser for Bio::Index::Blast.pm
 253             Returns $1 from applying the regexp /^>\s*(\S+)/
 254             to $header.
 255   Returns : ID string
 256   Args    : a header line string
 257
 258 =cut
 259
 260 sub default_id_parser
 261 {
 262         if ($_[0] =~ /^\s*(\S+)/) {
 263                 return $1;
 264         } else {
 265                 return;
 266         }
 267 }
 268
 269 =head2 Bio::Index::Abstract methods
 270
 271 =cut
 272
 273 =head2 filename
 274
 275  Title   : filename
 276  Usage   : $value = $self->filename();
 277            $self->filename($value);
 278  Function: Gets or sets the name of the dbm index file.
 279  Returns : The current value of filename
 280  Args    : Value of filename if setting, or none if
 281            getting the value.
 282
 283 =head2 write_flag
 284
 285  Title   : write_flag
 286  Usage   : $value = $self->write_flag();
 287            $self->write_flag($value);
 288  Function: Gets or sets the value of write_flag, which
 289            is wether the dbm file should be opened with
 290            write access.
 291  Returns : The current value of write_flag (default 0)
 292  Args    : Value of write_flag if setting, or none if
 293            getting the value.
 294
 295 =head2 dbm_package
 296
 297  Usage   : $value = $self->dbm_package();
 298            $self->dbm_package($value);
 299
 300  Function: Gets or sets the name of the Perl dbm module used.
 301            If the value is unset, then it returns the value of
 302            the package variable $USE_DBM_TYPE or if that is
 303            unset, then it chooses the best available dbm type,
 304            choosing 'DB_File' in preference to 'SDBM_File'.
 305            Bio::Abstract::Index may work with other dbm file
 306            types.
 307
 308  Returns : The current value of dbm_package
 309  Args    : Value of dbm_package if setting, or none if
 310            getting the value.
 311
 312
 313 =head2 get_stream
 314
 315  Title   : get_stream
 316  Usage   : $stream = $index->get_stream( $id );
 317  Function: Returns a file handle with the file pointer
 318            at the approprite place
 319
 320            This provides for a way to get the actual
 321            file contents and not an object
 322
 323            WARNING: you must parse the record deliminter
 324            *yourself*. Abstract wont do this for you
 325            So this code
 326
 327            $fh = $index->get_stream($myid);
 328            while( <$fh> ) {
 329               # do something
 330            }
 331            will parse the entire file if you do not put in
 332            a last statement in, like
 333
 334            while( <$fh> ) {
 335               /^\/\// && last; # end of record
 336               # do something
 337            }
 338
 339  Returns : A filehandle object
 340  Args    : string represents the accession number
 341  Notes   : This method should not be used without forethought
 342
 343
 344 =head2 open_dbm
 345
 346   Usage   : $index->open_dbm()
 347   Function: Opens the dbm file associated with the index
 348             object.  Write access is only given if explicitly
 349             asked for by calling new(-write => 1) or having set
 350             the write_flag(1) on the index object.  The type of
 351             dbm file opened is that returned by dbm_package().
 352             The name of the file to be is opened is obtained by
 353             calling the filename() method.
 354
 355   Example : $index->_open_dbm()
 356   Returns : 1 on success
 357
 358
 359 =head2 _version
 360
 361   Title   : _version
 362   Usage   : $type = $index->_version()
 363   Function: Returns a string which identifes the version of an
 364             index module.  Used to permanently identify an index
 365             file as having been created by a particular version
 366             of the index module.  Must be provided by the sub class
 367   Example :
 368   Returns :
 369   Args    : none
 370
 371 =head2 _filename
 372
 373   Title   : _filename
 374   Usage   : $index->_filename( FILE INT )
 375   Function: Indexes the file
 376   Example :
 377   Returns :
 378   Args    :
 379
 380 =head2 _file_handle
 381
 382   Title   : _file_handle
 383   Usage   : $fh = $index->_file_handle( INT )
 384   Function: Returns an open filehandle for the file
 385             index INT.  On opening a new filehandle it
 386             caches it in the @{$index->_filehandle} array.
 387             If the requested filehandle is already open,
 388             it simply returns it from the array.
 389   Example : $fist_file_indexed = $index->_file_handle( 0 );
 390   Returns : ref to a filehandle
 391   Args    : INT
 392
 393 =head2 _file_count
 394
 395   Title   : _file_count
 396   Usage   : $index->_file_count( INT )
 397   Function: Used by the index building sub in a sub class to
 398             track the number of files indexed.  Sets or gets
 399             the number of files indexed when called with or
 400             without an argument.
 401   Example :
 402   Returns : INT
 403   Args    : INT
 404
 405
 406 =head2 add_record
 407
 408   Title   : add_record
 409   Usage   : $index->add_record( $id, @stuff );
 410   Function: Calls pack_record on @stuff, and adds the result
 411             of pack_record to the index database under key $id.
 412             If $id is a reference to an array, then a new entry
 413             is added under a key corresponding to each element
 414             of the array.
 415   Example : $index->add_record( $id, $fileNumber, $begin, $end )
 416   Returns : TRUE on success or FALSE on failure
 417   Args    : ID LIST
 418
 419 =head2 pack_record
 420
 421   Title   : pack_record
 422   Usage   : $packed_string = $index->pack_record( LIST )
 423   Function: Packs an array of scalars into a single string
 424             joined by ASCII 034 (which is unlikely to be used
 425             in any of the strings), and returns it.
 426   Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
 427   Returns : STRING or undef
 428   Args    : LIST
 429
 430 =head2 unpack_record
 431
 432   Title   : unpack_record
 433   Usage   : $index->unpack_record( STRING )
 434   Function: Splits the sting provided into an array,
 435             splitting on ASCII 034.
 436   Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
 437   Returns : A 3 element ARRAY
 438   Args    : STRING containing ASCII 034
 439
 440 =head2 DESTROY
 441
 442  Title   : DESTROY
 443  Usage   : Called automatically when index goes out of scope
 444  Function: Closes connection to database and handles to
 445            sequence files
 446  Returns : NEVER
 447  Args    : NONE
 448
 449
 450 =cut
 451
 452 1;