lib/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   https://github.com/bioperl/bioperl-live/issues
  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("Could not read file '$file': $!");
 193         my $indexpoint = 0;
 194         my $lastline = 0;
 195     my $last_query = '';
 196     my $is_m9;
 197
 198     # In Windows, text files have '\r\n' as line separator, but when reading in
 199     # text mode Perl will only show the '\n'. This means that for a line "ABC\r\n",
 200     # "length $_" will report 4 although the line is 5 bytes in length.
 201     # We assume that all lines have the same line separator and only read current line.
 202     my $init_pos   = tell($BLAST);
 203     my $curr_line  = <$BLAST>;
 204     my $pos_diff   = tell($BLAST) - $init_pos;
 205     my $correction = $pos_diff - length $curr_line;
 206     seek $BLAST, $init_pos, 0; # Rewind position to proceed to read the file
 207
 208         while( <$BLAST> ) {
 209         if (m{^#}) {
 210             $is_m9 ||= 1;
 211             if(m{^#\s+T?BLAST[PNX]}i ) {
 212                 $indexpoint = tell($BLAST) - length($_) - $correction;
 213             }
 214             next
 215         }
 216
 217         if (/^(?:([^\t]+)\t)(?:[^\t]+\t){7,}/) {
 218             next if $last_query eq $1;
 219             $indexpoint = tell($BLAST) - length($_) - $correction unless $is_m9;
 220             foreach my $id ($self->id_parser()->($1)) {
 221                                 $self->debug("id is $id, begin is $indexpoint\n");
 222                                 $self->add_record($id, $i, $indexpoint);
 223                         }
 224             $last_query = $1;
 225         }
 226         }
 227 }
 228
 229 # shamelessly stolen from Bio::Index::Fasta
 230
 231 =head2 id_parser
 232
 233   Title   : id_parser
 234   Usage   : $index->id_parser( CODE )
 235   Function: Stores or returns the code used by record_id to
 236             parse the ID for record from a string.  Useful
 237             for (for instance) specifying a different
 238             parser for different flavours of blast dbs.
 239             Returns \&default_id_parser (see below) if not
 240             set. If you supply your own id_parser
 241             subroutine, then it should expect a fasta
 242             description line.  An entry will be added to
 243             the index for each string in the list returned.
 244   Example : $index->id_parser( \&my_id_parser )
 245   Returns : ref to CODE if called without arguments
 246   Args    : CODE
 247
 248 =cut
 249
 250 sub id_parser {
 251         my( $self, $code ) =@_;
 252
 253         if ($code) {
 254                 $self->{'_id_parser'} = $code;
 255         }
 256         return $self->{'_id_parser'} || \&default_id_parser;
 257 }
 258
 259 =head2 default_id_parser
 260
 261   Title   : default_id_parser
 262   Usage   : $id = default_id_parser( $header )
 263   Function: The default Blast Query ID parser for Bio::Index::Blast.pm
 264             Returns $1 from applying the regexp /^>\s*(\S+)/
 265             to $header.
 266   Returns : ID string
 267   Args    : a header line string
 268
 269 =cut
 270
 271 sub default_id_parser
 272 {
 273         if ($_[0] =~ /^\s*(\S+)/) {
 274                 return $1;
 275         } else {
 276                 return;
 277         }
 278 }
 279
 280 =head2 Bio::Index::Abstract methods
 281
 282 =cut
 283
 284 =head2 filename
 285
 286  Title   : filename
 287  Usage   : $value = $self->filename();
 288            $self->filename($value);
 289  Function: Gets or sets the name of the dbm index file.
 290  Returns : The current value of filename
 291  Args    : Value of filename if setting, or none if
 292            getting the value.
 293
 294 =head2 write_flag
 295
 296  Title   : write_flag
 297  Usage   : $value = $self->write_flag();
 298            $self->write_flag($value);
 299  Function: Gets or sets the value of write_flag, which
 300            is whether the dbm file should be opened with
 301            write access.
 302  Returns : The current value of write_flag (default 0)
 303  Args    : Value of write_flag if setting, or none if
 304            getting the value.
 305
 306 =head2 dbm_package
 307
 308  Usage   : $value = $self->dbm_package();
 309            $self->dbm_package($value);
 310
 311  Function: Gets or sets the name of the Perl dbm module used.
 312            If the value is unset, then it returns the value of
 313            the package variable $USE_DBM_TYPE or if that is
 314            unset, then it chooses the best available dbm type,
 315            choosing 'DB_File' in preference to 'SDBM_File'.
 316            Bio::Abstract::Index may work with other dbm file
 317            types.
 318
 319  Returns : The current value of dbm_package
 320  Args    : Value of dbm_package if setting, or none if
 321            getting the value.
 322
 323
 324 =head2 get_stream
 325
 326  Title   : get_stream
 327  Usage   : $stream = $index->get_stream( $id );
 328  Function: Returns a file handle with the file pointer
 329            at the approprite place
 330
 331            This provides for a way to get the actual
 332            file contents and not an object
 333
 334            WARNING: you must parse the record deliminter
 335            *yourself*. Abstract won't do this for you
 336            So this code
 337
 338            $fh = $index->get_stream($myid);
 339            while( <$fh> ) {
 340               # do something
 341            }
 342            will parse the entire file if you do not put in
 343            a last statement in, like
 344
 345            while( <$fh> ) {
 346               /^\/\// && last; # end of record
 347               # do something
 348            }
 349
 350  Returns : A filehandle object
 351  Args    : string represents the accession number
 352  Notes   : This method should not be used without forethought
 353
 354
 355 =head2 open_dbm
 356
 357   Usage   : $index->open_dbm()
 358   Function: Opens the dbm file associated with the index
 359             object.  Write access is only given if explicitly
 360             asked for by calling new(-write => 1) or having set
 361             the write_flag(1) on the index object.  The type of
 362             dbm file opened is that returned by dbm_package().
 363             The name of the file to be is opened is obtained by
 364             calling the filename() method.
 365
 366   Example : $index->_open_dbm()
 367   Returns : 1 on success
 368
 369
 370 =head2 _version
 371
 372   Title   : _version
 373   Usage   : $type = $index->_version()
 374   Function: Returns a string which identifes the version of an
 375             index module.  Used to permanently identify an index
 376             file as having been created by a particular version
 377             of the index module.  Must be provided by the sub class
 378   Example :
 379   Returns :
 380   Args    : none
 381
 382 =head2 _filename
 383
 384   Title   : _filename
 385   Usage   : $index->_filename( FILE INT )
 386   Function: Indexes the file
 387   Example :
 388   Returns :
 389   Args    :
 390
 391 =head2 _file_handle
 392
 393   Title   : _file_handle
 394   Usage   : $fh = $index->_file_handle( INT )
 395   Function: Returns an open filehandle for the file
 396             index INT.  On opening a new filehandle it
 397             caches it in the @{$index->_filehandle} array.
 398             If the requested filehandle is already open,
 399             it simply returns it from the array.
 400   Example : $fist_file_indexed = $index->_file_handle( 0 );
 401   Returns : ref to a filehandle
 402   Args    : INT
 403
 404 =head2 _file_count
 405
 406   Title   : _file_count
 407   Usage   : $index->_file_count( INT )
 408   Function: Used by the index building sub in a sub class to
 409             track the number of files indexed.  Sets or gets
 410             the number of files indexed when called with or
 411             without an argument.
 412   Example :
 413   Returns : INT
 414   Args    : INT
 415
 416
 417 =head2 add_record
 418
 419   Title   : add_record
 420   Usage   : $index->add_record( $id, @stuff );
 421   Function: Calls pack_record on @stuff, and adds the result
 422             of pack_record to the index database under key $id.
 423             If $id is a reference to an array, then a new entry
 424             is added under a key corresponding to each element
 425             of the array.
 426   Example : $index->add_record( $id, $fileNumber, $begin, $end )
 427   Returns : TRUE on success or FALSE on failure
 428   Args    : ID LIST
 429
 430 =head2 pack_record
 431
 432   Title   : pack_record
 433   Usage   : $packed_string = $index->pack_record( LIST )
 434   Function: Packs an array of scalars into a single string
 435             joined by ASCII 034 (which is unlikely to be used
 436             in any of the strings), and returns it.
 437   Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
 438   Returns : STRING or undef
 439   Args    : LIST
 440
 441 =head2 unpack_record
 442
 443   Title   : unpack_record
 444   Usage   : $index->unpack_record( STRING )
 445   Function: Splits the sting provided into an array,
 446             splitting on ASCII 034.
 447   Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
 448   Returns : A 3 element ARRAY
 449   Args    : STRING containing ASCII 034
 450
 451 =head2 DESTROY
 452
 453  Title   : DESTROY
 454  Usage   : Called automatically when index goes out of scope
 455  Function: Closes connection to database and handles to
 456            sequence files
 457  Returns : NEVER
 458  Args    : NONE
 459
 460
 461 =cut
 462
 463 1;