Bio/Search/Result/PullResultI.pm

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