Bio/Search/Result/ResultI.pm

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