Bio/Search/Result/PullResultI.pm

   1 # $Id$
   2 #
   3 # BioPerl module Bio::Search::Result::PullResultI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Sendu Bala <bix@sendu.me.uk>
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Search::Result::PullResultI - Bio::Search::Result::ResultI interface for
  16                                   'pull' parsers
  17
  18 =head1 SYNOPSIS
  19
  20     # This is an interface and cannot be instantiated
  21
  22     # typically one gets Results from a SearchIO stream
  23     use Bio::SearchIO;
  24     my $io = Bio::SearchIO->new(-format => 'hmmer_pull',
  25                                 -file   => 't/data/hmmpfam.out');
  26
  27     my $result = $io->next_result;
  28
  29     while( $hit = $result->next_hit()) {
  30         # enter code here for hit processing
  31     }
  32
  33     my $id = $result->query_name();
  34     my $desc = $result->query_description();
  35     my $dbname = $result->database_name();
  36     my $size = $result->database_letters();
  37     my $num_entries = $result->database_entries();
  38     my $gap_ext = $result->get_parameter('gapext');
  39     my @params = $result->available_parameters;
  40     my $kappa = $result->get_statistic('kappa');
  41     my @statnames = $result->available_statistics;
  42
  43 =head1 DESCRIPTION
  44
  45 Bio::Search::Result::ResultI objects are data structures containing
  46 the results from the execution of a search algorithm.  As such, it may
  47 contain various algorithm specific information as well as details of
  48 the execution, but will contain a few fundamental elements, including
  49 the ability to return Bio::Search::Hit::HitI objects.
  50
  51 PullResultI is for fast implementations that only do parsing work on the result
  52 data when you actually request information by calling one of the ResultI
  53 methods.
  54
  55 Many methods of ResultI are implemented in a way suitable for inheriting classes
  56 that use Bio::PullParserI. It only really makes sense for PullResult modules to
  57 be created by (and have as a -parent) SearchIO modules written using
  58 PullParserI.
  59
  60 =head1 FEEDBACK
  61
  62 =head2 Mailing Lists
  63
  64 User feedback is an integral part of the evolution of this
  65 and other Bioperl modules. Send your comments and suggestions preferably
  66  to one of the Bioperl mailing lists.
  67 Your participation is much appreciated.
  68
  69   bioperl-l@bioperl.org                  - General discussion
  70   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  71
  72 =head2 Support
  73
  74 Please direct usage questions or support issues to the mailing list:
  75
  76 L<bioperl-l@bioperl.org>
  77
  78 rather than to the module maintainer directly. Many experienced and
  79 reponsive experts will be able look at the problem and quickly
  80 address it. Please include a thorough description of the problem
  81 with code and data examples if at all possible.
  82
  83 =head2 Reporting Bugs
  84
  85 Report bugs to the Bioperl bug tracking system to help us keep track
  86 the bugs and their resolution.  Bug reports can be submitted via the
  87 web:
  88
  89   http://bugzilla.open-bio.org/
  90
  91 =head1 AUTHOR Sendu Bala
  92
  93 Email bix@sendu.me.uk
  94
  95 =head1 COPYRIGHT
  96
  97 Copyright (c) 2006 Sendu Bala.
  98
  99 =head1 DISCLAIMER
 100
 101 This software is provided "as is" without warranty of any kind.
 102
 103 =head1 APPENDIX
 104
 105 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
 106
 107 =cut
 108
 109 # Let the code begin...
 110
 111 package Bio::Search::Result::PullResultI;
 112
 113 use strict;
 114
 115 use Bio::Search::GenericStatistics;
 116 use Bio::Tools::Run::GenericParameters;
 117
 118 use base qw(Bio::PullParserI Bio::Search::Result::ResultI);
 119
 120 =head2 _setup
 121
 122  Title   : _setup
 123  Usage   : $self->_setup(@args)
 124  Function: Implementers should call this to setup common fields and deal with
 125            common arguments to new().
 126  Returns : n/a
 127  Args    : @args received in new().
 128
 129 =cut
 130
 131 sub _setup {
 132     my ($self, @args) = @_;
 133
 134     # fields most subclasses probably will want
 135     $self->_fields( { ( next_hit => undef,
 136                         num_hits => undef,
 137                         hits => undef,
 138                         no_hits_found => undef,
 139                         query_name => undef,
 140                         query_accession => undef,
 141                         query_length => undef,
 142                         query_description => undef  ) } );
 143
 144     my ($parent, $chunk, $params, $stats) = $self->_rearrange([qw(PARENT
 145                                                                   CHUNK
 146                                                                   PARAMETERS
 147                                                                   STATISTICS)],
 148                                                               @args);
 149     $self->throw("Need -parent or -chunk to be defined") unless $parent || $chunk;
 150
 151         $self->parent($parent) if $parent;
 152
 153     if ($chunk) {
 154         my ($io, $start, $end) = (undef, 0, undef);
 155         if (ref($chunk) eq 'ARRAY') {
 156             ($io, $start, $end) = @{$chunk};
 157         }
 158         else {
 159             $io = $chunk;
 160         }
 161         $self->chunk($io, -start => $start, -end => $end);
 162     }
 163
 164     if (defined $params) {
 165         if (ref($params) !~ /hash/i) {
 166             $self->throw("Must specify a hash reference with the the parameter '-parameters");
 167         }
 168         while (my ($key,$value) = each %{$params}) {
 169             $self->add_parameter($key, $value);
 170         }
 171     }
 172     if (defined $stats) {
 173         if (ref($stats) !~ /hash/i) {
 174             $self->throw("Must specify a hash reference with the the parameter '-statistics");
 175         }
 176         while (my ($key,$value) = each %{$stats}) {
 177             $self->add_statistic($key, $value);
 178         }
 179     }
 180 }
 181
 182 #
 183 # Some of these methods are written explitely to avoid ResultI throwing not
 184 # implemented; if it didn't do that then PullParserI AUTOLOAD would have
 185 # cought all them.
 186 #
 187
 188 =head2 next_hit
 189
 190  Title   : next_hit
 191  Usage   : while( $hit = $result->next_hit()) { ... }
 192  Function: Returns the next available Hit object, representing potential
 193            matches between the query and various entities from the database.
 194  Returns : a Bio::Search::Hit::HitI object or undef if there are no more.
 195  Args    : none
 196
 197 =cut
 198
 199 sub next_hit {
 200     return shift->get_field('next_hit');
 201 }
 202
 203 =head2 sort_hits
 204
 205  Title          : sort_hits
 206  Usage          : $result->sort_hits(\&sort_function)
 207  Function       : Sorts the available hit objects by a user-supplied function.
 208               Defaults to sort by descending score.
 209  Returns        : n/a
 210  Args           : A coderef for the sort function. See the documentation on the Perl
 211               sort() function for guidelines on writing sort functions.
 212  Note           : To access the special variables $a and $b used by the Perl sort()
 213               function the user function must access Bio::Search::Result::ResultI namespace.
 214               For example, use :
 215               $result->sort_hits(sub{$Bio::Search::Result::ResultI::a->length <=>
 216                                                          $Bio::Search::Result::ResultI::b->length});
 217               NOT $result->sort_hits($a->length <=>$b->length);
 218
 219 =cut
 220
 221 # In ResultI. subclasses will probably want to override since sort_hits normally
 222 # calls hits().
 223
 224 =head2 query_name
 225
 226  Title   : query_name
 227  Usage   : $id = $result->query_name();
 228  Function: Get the string identifier of the query used by the
 229            algorithm that performed the search.
 230  Returns : a string.
 231  Args    : none
 232
 233 =cut
 234
 235 sub query_name {
 236     return shift->get_field('query_name');
 237 }
 238
 239 =head2 query_accession
 240
 241  Title   : query_accession
 242  Usage   : $id = $result->query_accession();
 243  Function: Get the accession (if available) for the query sequence
 244  Returns : a string
 245  Args    : none
 246
 247 =cut
 248
 249 sub query_accession {
 250     return shift->get_field('query_accession');
 251 }
 252
 253 =head2 query_length
 254
 255  Title   : query_length
 256  Usage   : $id = $result->query_length();
 257  Function: Get the length of the query sequence used in the search.
 258  Returns : a number
 259  Args    : none
 260
 261 =cut
 262
 263 sub query_length {
 264     return shift->get_field('query_length');
 265 }
 266
 267 =head2 query_description
 268
 269  Title   : query_description
 270  Usage   : $id = $result->query_description();
 271  Function: Get the description of the query sequence
 272            used in the search.
 273  Returns : a string
 274  Args    : none
 275
 276 =cut
 277
 278 sub query_description {
 279     return shift->get_field('query_description');
 280 }
 281
 282 =head2 database_name
 283
 284  Title   : database_name
 285  Usage   : $name = $result->database_name()
 286  Function: Used to obtain the name of the database that the query was searched
 287            against by the algorithm.
 288  Returns : a scalar string
 289  Args    : none
 290
 291 =cut
 292
 293 sub database_name {
 294     return shift->get_field('database_name');
 295 }
 296
 297 =head2 database_letters
 298
 299  Title   : database_letters
 300  Usage   : $size = $result->database_letters()
 301  Function: Used to obtain the size of database that was searched against.
 302  Returns : a scalar integer (units specific to algorithm, but probably the
 303            total number of residues in the database, if available) or undef if
 304            the information was not available to the Processor object.
 305  Args    : none
 306
 307 =cut
 308
 309 sub database_letters {
 310     return shift->get_field('database_letters');
 311 }
 312
 313 =head2 database_entries
 314
 315  Title   : database_entries
 316  Usage   : $num_entries = $result->database_entries()
 317  Function: Used to obtain the number of entries contained in the database.
 318  Returns : a scalar integer representing the number of entities in the database
 319            or undef if the information was not available.
 320  Args    : none
 321
 322 =cut
 323
 324 sub database_entries {
 325     return shift->get_field('database_entries');
 326 }
 327
 328 =head2 algorithm
 329
 330  Title   : algorithm
 331  Usage   : my $r_type = $result->algorithm
 332  Function: Obtain the name of the algorithm used to obtain the Result
 333  Returns : string (e.g., BLASTP)
 334  Args    : [optional] scalar string to set value
 335
 336 =cut
 337
 338 sub algorithm {
 339    return shift->get_field('algorithm');
 340 }
 341
 342 =head2 algorithm_version
 343
 344  Title   : algorithm_version
 345  Usage   : my $r_version = $result->algorithm_version
 346  Function: Obtain the version of the algorithm used to obtain the Result
 347  Returns : string (e.g., 2.1.2)
 348  Args    : [optional] scalar string to set algorithm version value
 349
 350 =cut
 351
 352 sub algorithm_version {
 353    return shift->get_field('algorithm_version');
 354 }
 355
 356 =head2 algorithm_reference
 357
 358  Title   : algorithm_reference
 359  Usage   : $obj->algorithm_reference($newval)
 360  Function:
 361  Returns : value of the literature reference for the algorithm
 362  Args    : newvalue (optional)
 363  Comments: The default implementation in ResultI returns an empty string
 364            rather than throwing a NotImplemented exception, since
 365            the ref may not always be available and is not critical.
 366
 367 =cut
 368
 369 sub algorithm_reference {
 370    my ($self) = @_;
 371    return '';
 372 }
 373
 374 =head2 num_hits
 375
 376  Title   : num_hits
 377  Usage   : my $hitcount= $result->num_hits
 378  Function: returns the number of hits for this query result
 379  Returns : integer
 380  Args    : none
 381
 382 =cut
 383
 384 sub num_hits {
 385    return shift->get_field('num_hits');
 386 }
 387
 388 =head2 hits
 389
 390  Title   : hits
 391  Usage   : my @hits = $result->hits
 392  Function: Returns the HitI objects contained within this Result
 393  Returns : Array of Bio::Search::Hit::HitI objects
 394  Args    : none
 395
 396 See Also: L<Bio::Search::Hit::HitI>
 397
 398 =cut
 399
 400 sub hits {
 401    return shift->get_field('hits');
 402 }
 403
 404 =head2 no_hits_found
 405
 406  Usage     : $nohits = $blast->no_hits_found();
 407  Function  : Get boolean indicator indicating whether or not any hits
 408              were present in the report.
 409
 410              This is NOT the same as determining the number of hits via
 411              the hits() method, which will return zero hits if there were no
 412              hits in the report or if all hits were filtered out during the
 413              parse.
 414
 415              Thus, this method can be used to distinguish these possibilities
 416              for hitless reports generated when filtering.
 417
 418  Returns   : Boolean
 419  Args      : none
 420
 421 =cut
 422
 423 sub no_hits_found {
 424     return shift->get_field('no_hits_found');
 425 }
 426
 427 =head2 rewind
 428
 429  Title   : rewind
 430  Usage   : $result->rewind;
 431  Function: Allow one to reset the Hit iterator to the beginning
 432            Since this is an in-memory implementation
 433  Returns : none
 434  Args    : none
 435
 436 =cut
 437
 438 sub rewind {
 439    shift->throw_not_implemented();
 440 }
 441
 442 =head2 get_parameter
 443
 444  Title   : get_parameter
 445  Usage   : my $gap_ext = $result->get_parameter('gapext')
 446  Function: Returns the value for a specific parameter used
 447            when running this result
 448  Returns : string
 449  Args    : name of parameter (string)
 450
 451 =cut
 452
 453 sub get_parameter {
 454     my ($self, $param) = @_;
 455     $param || return;
 456     return unless defined $self->{_parameters};
 457     return $self->{_parameters}->get_parameter($param);
 458 }
 459
 460 =head2 available_parameters
 461
 462  Title   : available_parameters
 463  Usage   : my @params = $result->available_parameters
 464  Function: Returns the names of the available parameters
 465  Returns : Return list of available parameters used for this result
 466  Args    : none
 467
 468 =cut
 469
 470 sub available_parameters {
 471     my $self = shift;
 472     return () unless defined $self->{_parameters};
 473     return $self->{_parameters}->available_parameters;
 474 }
 475
 476 =head2 add_parameter
 477
 478  Title   : add_parameter
 479  Usage   : $result->add_parameter('gapext', 11);
 480  Function: Adds a parameter
 481  Returns : none
 482  Args    : key  - key value name for this parama
 483            value - value for this parameter
 484
 485 =cut
 486
 487 sub add_parameter {
 488     my ($self, $key, $value) = @_;
 489     unless (exists $self->{_parameters}) {
 490         $self->{_parameters} = Bio::Tools::Run::GenericParameters->new();
 491     }
 492     $self->{_parameters}->set_parameter($key => $value);
 493 }
 494
 495 =head2 get_statistic
 496
 497  Title   : get_statistic
 498  Usage   : my $gap_ext = $result->get_statistic('kappa')
 499  Function: Returns the value for a specific statistic available
 500            from this result
 501  Returns : string
 502  Args    : name of statistic (string)
 503
 504 =cut
 505
 506 sub get_statistic {
 507     my ($self, $stat) = @_;
 508     $stat || return;
 509     return unless defined $self->{_statistics};
 510     return $self->{_statistics}->get_statistic($stat);
 511 }
 512
 513 =head2 available_statistics
 514
 515  Title   : available_statistics
 516  Usage   : my @statnames = $result->available_statistics
 517  Function: Returns the names of the available statistics
 518  Returns : Return list of available statistics used for this result
 519  Args    : none
 520
 521 =cut
 522
 523 sub available_statistics {
 524     my $self = shift;
 525     return () unless defined $self->{_statistics};
 526     return $self->{_statistics}->available_statistics;
 527 }
 528
 529 =head2 add_statistic
 530
 531  Title   : add_statistic
 532  Usage   : $result->add_statistic('lambda', 2.3);
 533  Function: Adds a statistic
 534  Returns : none
 535  Args    : key  - key value name for this statistic
 536            value - value for this statistic
 537
 538 =cut
 539
 540 sub add_statistic {
 541     my ($self, $key, $value) = @_;
 542     unless (exists $self->{_statistics}) {
 543         $self->{_statistics} = Bio::Search::GenericStatistics->new();
 544     }
 545     $self->{_statistics}->set_statistic($key => $value);
 546 }
 547
 548 1;