File Coverage

Bio/Search/Result/ResultI.pm
Criterion Covered Total %
statement 6 58 10.3
branch 0 6 0.0
condition n/a
subroutine 2 24 8.3
pod 21 21 100.0
total 29 109 26.6


line stmt bran cond sub pod time code
1             #-----------------------------------------------------------------
2             #
3             # BioPerl module Bio::Search::Result::ResultI
4             #
5             # Please direct questions and support issues to
6             #
7             # Cared for by Steve Chervitz
8             #
9             # Originally created by Aaron Mackey
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
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 Eamackey@virginia.eduE (original author)
96              
97             Steve Chervitz Esac@bioperl.orgE
98              
99             See L 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 29     29   188 use strict;
  29         51  
  29         777  
122              
123              
124 29     29   131 use base qw(Bio::AnalysisResultI);
  29         48  
  29         10628  
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 0     0 1   my ($self,@args) = @_;
141 0           $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 0     0 1   my ($self, $coderef) = @_;
164 0           my @sorted_hits;
165              
166 0 0         if ($coderef) {
167 0 0         $self->throw('sort_hits requires a sort function passed as a subroutine reference')
168             unless (ref($coderef) eq 'CODE');
169             }
170             else {
171 0           $coderef = \&_default_sort_hits;
172             # throw a warning?
173             }
174              
175 0           my @hits = $self->hits();
176            
177 0           eval {@sorted_hits = sort $coderef @hits };
  0            
178              
179 0 0         if ($@) {
180 0           $self->throw("Unable to sort hits: $@");
181             }
182             else {
183 0           $self->{'_hits'} = \@sorted_hits;
184 0           $self->{'_no_iterations'} = 1; # to bypass iteration checking in hits() method
185 0           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 0     0     $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 0     0 1   my ($self,@args) = @_;
219 0           $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 0     0 1   my ($self,@args) = @_;
234 0           $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 0     0 1   my ($self,@args) = @_;
251 0           $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 0     0 1   my ($self,@args) = @_;
267 0           $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 0     0 1   my ($self,@args) = @_;
284              
285 0           $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 0     0 1   my ($self,@args) = @_;
303 0           $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 0     0 1   my ($self,@args) = @_;
320              
321 0           $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 0     0 1   my ($self,@args) = @_;
337 0           $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 0     0 1   my ($self) = @_;
352 0           $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 0     0 1   my ($self,@args) = @_;
368 0           $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 0     0 1   my ($self) = @_;
383 0           $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 0     0 1   my ($self) = @_;
398 0           $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 0     0 1   my ($self) = @_;
413 0           $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 0     0 1   my ($self) = @_;
432 0           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 0     0 1   my ($self) = @_;
451 0           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 0     0 1   my ($self,@args) = @_;
467 0           $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
479              
480             =cut
481              
482             sub hits{
483 0     0 1   my ($self,@args) = @_;
484 0           $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 0     0 1   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 0     0 1   sub set_no_hits_found { shift->throw_not_implemented }
522              
523             1;
524              
525