Bio/Index/Blast.pm

   1 #
   2 # BioPerl module for Bio::Index::Blast
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>
   7 #
   8 # Copyright Jason Stajich
   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::Blast - Indexes Blast reports and supports retrieval
  17 based on query accession(s)
  18
  19 =head1 SYNOPSIS
  20
  21   use strict;
  22   use Bio::Index::Blast;
  23
  24   my ($indexfile,$file1,$file2,$query);
  25   my $index = Bio::Index::Blast->new(-filename => $indexfile,
  26                                                          -write_flag => 1);
  27   $index->make_index($file1,$file2);
  28
  29   my $fh = $index->get_stream($query);
  30
  31   my $blast_report = Bio::SearchIO->new(-noclose => 1,
  32                                         -format  => 'blast',
  33                                         -fh      => $fh);
  34   my $result = $blast_report->next_result;
  35   print $result->algorithm, "\n";
  36   my $hit = $result->next_hit;
  37   print $hit->description, "\n";
  38   my $hsp = $hit->next_hsp;
  39   print $hsp->bits, "\n";
  40
  41 =head1 DESCRIPTION
  42
  43 This object allows one to build an index on a blast file (or files)
  44 and provide quick access to the blast report for that accession.
  45
  46 This also allows for ID parsing using a callback:
  47
  48    $inx->id_parser(\&get_id);
  49    # make the index
  50    $inx->make_index($file_name);
  51
  52    # here is where the retrieval key is specified
  53    sub get_id {
  54       my $line = shift;
  55       $line =~ /^gi\|(\d+)/;
  56       $1;
  57    }
  58
  59 The indexer is capable of indexing based on multiple IDs passed back from the
  60 callback; this is assuming of course all IDs are unique.
  61
  62 Note: for best results 'use strict'.
  63
  64 =head1 FEEDBACK
  65
  66 =head2 Mailing Lists
  67
  68 User feedback is an integral part of the evolution of this and other
  69 Bioperl modules. Send your comments and suggestions preferably to
  70 the Bioperl mailing list.  Your participation is much appreciated.
  71
  72   bioperl-l@bioperl.org                  - General discussion
  73   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  74
  75 =head2 Support
  76
  77 Please direct usage questions or support issues to the mailing list:
  78
  79 I<bioperl-l@bioperl.org>
  80
  81 rather than to the module maintainer directly. Many experienced and
  82 reponsive experts will be able look at the problem and quickly
  83 address it. Please include a thorough description of the problem
  84 with code and data examples if at all possible.
  85
  86 =head2 Reporting Bugs
  87
  88 Report bugs to the Bioperl bug tracking system to help us keep track
  89 of the bugs and their resolution. Bug reports can be submitted via the
  90 web:
  91
  92   https://github.com/bioperl/bioperl-live/issues
  93
  94 =head1 AUTHOR - Jason Stajich
  95
  96 Email jason-at-bioperl-dot-org
  97
  98 =head1 APPENDIX
  99
 100 The rest of the documentation details each of the object methods.
 101 Internal methods are usually preceded with a _
 102
 103 =cut
 104
 105 # Let the code begin...
 106
 107 package Bio::Index::Blast;
 108 use strict;
 109
 110 use IO::String;
 111 use Bio::SearchIO;
 112 use base qw(Bio::Index::Abstract Bio::Root::Root);
 113
 114 sub _version {
 115         return ${Bio::Root::Version::VERSION};
 116 }
 117
 118 =head2 new
 119
 120   Usage   : $index = Bio::Index::Abstract->new(
 121                 -filename    => $dbm_file,
 122                 -write_flag  => 0,
 123                 -dbm_package => 'DB_File',
 124                 -verbose     => 0);
 125
 126   Function: Returns a new index object.  If filename is
 127             specified, then open_dbm() is immediately called.
 128             Bio::Index::Abstract->new() will usually be called
 129             directly only when opening an existing index.
 130   Returns : A new index object
 131   Args    : -filename    The name of the dbm index file.
 132             -write_flag  TRUE if write access to the dbm file is
 133                          needed.
 134             -dbm_package The Perl dbm module to use for the
 135                          index.
 136             -verbose     Print debugging output to STDERR if
 137                          TRUE.
 138
 139 =cut
 140
 141 sub new {
 142     my($class,@args) = @_;
 143     my $self = $class->SUPER::new(@args);
 144     my ($type) = $self->_rearrange([qw(PARSER)], @args);
 145     $type && $self->blast_parser_type($type);
 146     $self;
 147 }
 148
 149 =head2 Bio::Index::Blast implemented methods
 150
 151 =cut
 152
 153 =head2 fetch_report
 154
 155  Title   : fetch_report
 156  Usage   : my $blastreport = $idx->fetch_report($id);
 157  Function: Returns a Bio::SearchIO report object
 158            for a specific blast report
 159  Returns : Bio::SearchIO
 160  Args    : valid id
 161
 162 =cut
 163
 164 sub fetch_report{
 165         my ($self,$id) = @_;
 166         my $fh = $self->get_stream($id);
 167         my $report = Bio::SearchIO->new(-noclose => 1,
 168                                     -format => $self->blast_parser_type,
 169                                     -fh => $fh);
 170         return $report->next_result;
 171 }
 172
 173 =head2 fetch_result
 174
 175  Title   : fetch_result
 176  Usage   : my $blastreport = $idx->fetch_result($id);
 177  Function: Returns a Bio::SearchIO report object
 178            for a specific blast report
 179  Returns : Bio::SearchIO
 180  Args    : valid id
 181  Note    : alias of fetch_report()
 182
 183 =cut
 184
 185 *fetch_result = \&fetch_report;
 186
 187 =head2 Require methods from Bio::Index::Abstract
 188
 189 =cut
 190
 191 =head2 _index_file
 192
 193   Title   : _index_file
 194   Usage   : $index->_index_file( $file_name, $i )
 195   Function: Specialist function to index BLAST report file(s).
 196             Is provided with a filename and an integer
 197             by make_index in its SUPER class.
 198   Example :
 199   Returns :
 200   Args    :
 201
 202 =cut
 203
 204 sub _index_file {
 205         my( $self,
 206                  $file, # File name
 207                  $i,    # Index-number of file being indexed
 208           ) = @_;
 209
 210         my( $begin,  # Offset from start of file of the start
 211                           # of the last found record.
 212           );
 213
 214         open my $BLAST, '<', $file or $self->throw("Could not read file '$file': $!");
 215
 216         my (@data, @records);
 217         my $indexpoint = 0;
 218         my $lastline = 0;
 219         my $prefix = '';
 220
 221         # In Windows, text files have '\r\n' as line separator, but when reading in
 222         # text mode Perl will only show the '\n'. This means that for a line "ABC\r\n",
 223         # "length $_" will report 4 although the line is 5 bytes in length.
 224         # We assume that all lines have the same line separator and only read current line.
 225         my $init_pos   = tell($BLAST);
 226         my $curr_line  = <$BLAST>;
 227         my $pos_diff   = tell($BLAST) - $init_pos;
 228         my $correction = $pos_diff - length $curr_line;
 229         seek $BLAST, $init_pos, 0; # Rewind position to proceed to read the file
 230
 231         # fencepost problem: we basically just find the top and the query
 232         while( my $line = <$BLAST> ) {
 233
 234                 # in recent RPS-BLAST output the only delimiter between result
 235                 # sections is '^Query=' - in other BLAST outputs you
 236                 # can use '^(RPS-|T?)BLAST(P?|N?|X?)'
 237
 238                 if ( $line =~ /^(RPS-|T?)BLAST(P?|N?|X?)/ ) {
 239                         $prefix = $1;
 240                         $indexpoint = tell($BLAST) - length($line) - $correction;
 241                 }
 242                 if ( $line =~ /^Query=\s*([^\n]+)$/ ) {
 243
 244                         $indexpoint = tell($BLAST) - length($line) - $correction if ( $prefix eq 'RPS-' );
 245
 246                         foreach my $id ($self->id_parser()->($1)) {
 247                                 $self->debug("id is $id, begin is $indexpoint\n");
 248                                 $self->add_record($id, $i, $indexpoint);
 249                         }
 250                 }
 251         }
 252 }
 253
 254 # shamelessly stolen from Bio::Index::Fasta
 255
 256 =head2 id_parser
 257
 258   Title   : id_parser
 259   Usage   : $index->id_parser( CODE )
 260   Function: Stores or returns the code used by record_id to
 261             parse the ID for record from a string.  Useful
 262             for (for instance) specifying a different
 263             parser for different flavours of blast dbs.
 264             Returns \&default_id_parser (see below) if not
 265             set. If you supply your own id_parser
 266             subroutine, then it should expect a fasta
 267             description line.  An entry will be added to
 268             the index for each string in the list returned.
 269   Example : $index->id_parser( \&my_id_parser )
 270   Returns : ref to CODE if called without arguments
 271   Args    : CODE
 272
 273 =cut
 274
 275 sub id_parser {
 276         my( $self, $code ) =@_;
 277
 278         if ($code) {
 279                 $self->{'_id_parser'} = $code;
 280         }
 281         return $self->{'_id_parser'} || \&default_id_parser;
 282 }
 283
 284 =head2 default_id_parser
 285
 286   Title   : default_id_parser
 287   Usage   : $id = default_id_parser( $header )
 288   Function: The default Blast Query ID parser for Bio::Index::Blast.pm
 289             Returns $1 from applying the regexp /^>\s*(\S+)/
 290             to $header.
 291   Returns : ID string
 292   Args    : a header line string
 293
 294 =cut
 295
 296 sub default_id_parser {
 297         if ($_[0] =~ /^\s*(\S+)/) {
 298                 return $1;
 299         } else {
 300                 return;
 301         }
 302 }
 303
 304 =head2 blast_parser_type
 305
 306   Title   : blast_parser_type
 307   Usage   : $index->blast_parser_type() # returns
 308   Function: Get/Set SearchIO-based text (-m0) BLAST parser. Only values in
 309             local %VALID_PARSERS hash allowed.
 310   Returns : String
 311   Args    : [optional]
 312   Note    : This only allows simple text-based parsing options; tabular, XML,
 313             or others are not supported (see Bio::Index::BlastTable for tab
 314             output).
 315
 316 =cut
 317
 318 my %VALID_PARSERS = map {$_ =>1} qw(blast blast_pull);
 319
 320 sub blast_parser_type {
 321     my ($self, $type) = @_;
 322     if ($type) {
 323         $self->throw("$type is not a supported BLAST text parser") unless
 324             exists $VALID_PARSERS{$type};
 325         $self->{_blast_parser_type} = $type;
 326     }
 327     return $self->{_blast_parser_type} || 'blast';
 328 }
 329
 330 =head2 Bio::Index::Abstract methods
 331
 332 =cut
 333
 334 =head2 filename
 335
 336  Title   : filename
 337  Usage   : $value = $self->filename();
 338            $self->filename($value);
 339  Function: Gets or sets the name of the dbm index file.
 340  Returns : The current value of filename
 341  Args    : Value of filename if setting, or none if
 342            getting the value.
 343
 344 =head2 write_flag
 345
 346  Title   : write_flag
 347  Usage   : $value = $self->write_flag();
 348            $self->write_flag($value);
 349  Function: Gets or sets the value of write_flag, which
 350            is whether the dbm file should be opened with
 351            write access.
 352  Returns : The current value of write_flag (default 0)
 353  Args    : Value of write_flag if setting, or none if
 354            getting the value.
 355
 356 =head2 dbm_package
 357
 358  Usage   : $value = $self->dbm_package();
 359            $self->dbm_package($value);
 360
 361  Function: Gets or sets the name of the Perl dbm module used.
 362            If the value is unset, then it returns the value of
 363            the package variable $USE_DBM_TYPE or if that is
 364            unset, then it chooses the best available dbm type,
 365            choosing 'DB_File' in preference to 'SDBM_File'.
 366            Bio::Abstract::Index may work with other dbm file
 367            types.
 368
 369  Returns : The current value of dbm_package
 370  Args    : Value of dbm_package if setting, or none if
 371            getting the value.
 372
 373
 374 =head2 get_stream
 375
 376  Title   : get_stream
 377  Usage   : $stream = $index->get_stream( $id );
 378  Function: Returns a file handle with the file pointer
 379            at the approprite place
 380
 381            This provides for a way to get the actual
 382            file contents and not an object
 383
 384            WARNING: you must parse the record deliminter
 385            *yourself*. Abstract won't do this for you
 386            So this code
 387
 388            $fh = $index->get_stream($myid);
 389            while( <$fh> ) {
 390               # do something
 391            }
 392            will parse the entire file if you do not put in
 393            a last statement in, like
 394
 395            while( <$fh> ) {
 396               /^\/\// && last; # end of record
 397               # do something
 398            }
 399
 400  Returns : A filehandle object
 401  Args    : string represents the accession number
 402  Notes   : This method should not be used without forethought
 403
 404
 405 =head2 open_dbm
 406
 407   Usage   : $index->open_dbm()
 408   Function: Opens the dbm file associated with the index
 409             object.  Write access is only given if explicitly
 410             asked for by calling new(-write => 1) or having set
 411             the write_flag(1) on the index object.  The type of
 412             dbm file opened is that returned by dbm_package().
 413             The name of the file to be is opened is obtained by
 414             calling the filename() method.
 415
 416   Example : $index->_open_dbm()
 417   Returns : 1 on success
 418
 419
 420 =head2 _version
 421
 422   Title   : _version
 423   Usage   : $type = $index->_version()
 424   Function: Returns a string which identifes the version of an
 425             index module.  Used to permanently identify an index
 426             file as having been created by a particular version
 427             of the index module.  Must be provided by the sub class
 428   Example :
 429   Returns :
 430   Args    : none
 431
 432 =head2 _filename
 433
 434   Title   : _filename
 435   Usage   : $index->_filename( FILE INT )
 436   Function: Indexes the file
 437   Example :
 438   Returns :
 439   Args    :
 440
 441 =head2 _file_handle
 442
 443   Title   : _file_handle
 444   Usage   : $fh = $index->_file_handle( INT )
 445   Function: Returns an open filehandle for the file
 446             index INT.  On opening a new filehandle it
 447             caches it in the @{$index->_filehandle} array.
 448             If the requested filehandle is already open,
 449             it simply returns it from the array.
 450   Example : $fist_file_indexed = $index->_file_handle( 0 );
 451   Returns : ref to a filehandle
 452   Args    : INT
 453
 454 =head2 _file_count
 455
 456   Title   : _file_count
 457   Usage   : $index->_file_count( INT )
 458   Function: Used by the index building sub in a sub class to
 459             track the number of files indexed.  Sets or gets
 460             the number of files indexed when called with or
 461             without an argument.
 462   Example :
 463   Returns : INT
 464   Args    : INT
 465
 466
 467 =head2 add_record
 468
 469   Title   : add_record
 470   Usage   : $index->add_record( $id, @stuff );
 471   Function: Calls pack_record on @stuff, and adds the result
 472             of pack_record to the index database under key $id.
 473             If $id is a reference to an array, then a new entry
 474             is added under a key corresponding to each element
 475             of the array.
 476   Example : $index->add_record( $id, $fileNumber, $begin, $end )
 477   Returns : TRUE on success or FALSE on failure
 478   Args    : ID LIST
 479
 480 =head2 pack_record
 481
 482   Title   : pack_record
 483   Usage   : $packed_string = $index->pack_record( LIST )
 484   Function: Packs an array of scalars into a single string
 485             joined by ASCII 034 (which is unlikely to be used
 486             in any of the strings), and returns it.
 487   Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
 488   Returns : STRING or undef
 489   Args    : LIST
 490
 491 =head2 unpack_record
 492
 493   Title   : unpack_record
 494   Usage   : $index->unpack_record( STRING )
 495   Function: Splits the sting provided into an array,
 496             splitting on ASCII 034.
 497   Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
 498   Returns : A 3 element ARRAY
 499   Args    : STRING containing ASCII 034
 500
 501 =head2 DESTROY
 502
 503  Title   : DESTROY
 504  Usage   : Called automatically when index goes out of scope
 505  Function: Closes connection to database and handles to
 506            sequence files
 507  Returns : NEVER
 508  Args    : NONE
 509
 510
 511 =cut
 512
 513 1;