Bio/Search/Result/ResultI.pm

filter: Statementstmt 13.3% 8 / 60 Branchbran 0.0% 0 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 8.3% 2 / 24 Podpod 100% 21 / 21 totaltotal 27.9% 31 / 111 CC 4 SCAR 15.2
CC
4
Cov
12%
sort_hits
20.0
next_hit
2.0
_default_sort_hits
2.0
CRAP 4.6
« Bio/Matrix/IO/mlagan.pm ↑ Summary Bio/Ontology/Relationship.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 36 $Bio::Search::Result::ResultI::VERSION = '1.7.8';
121 36 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
122  
123  
124 36 ▶use base qw(Bio::AnalysisResultI);
Subroutine BEGIN: called CC=1 SCAR=0.0
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 0 ▶sub next_hit {
Subroutine next_hit: not called CC=1 SCAR=6.9
Pod documented
140 0 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 0 ▶sub sort_hits {
Subroutine sort_hits: not called CC=4 SCAR=30.0
Pod documented
163 0 my ($self, $coderef) = @_;
164 0 my @sorted_hits;
165  
166 0 ▶ if ($coderef) {
Branch: 1 branch
BranchTrueFalseTotal
if ($coderef) { } 0 0 0
167 0 ▶ $self->throw('sort_hits requires a sort function passed as a subroutine reference')
Branch: 1 branch
BranchTrueFalseTotal
unless ref $coderef eq "CODE" 0 0 0
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 };
178  
179 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) { } 0 0 0
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 0 ▶sub _default_sort_hits {
Subroutine _default_sort_hits: not called CC=1 SCAR=6.9
201 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 0 ▶sub query_name {
Subroutine query_name: not called CC=1 SCAR=6.9
Pod documented
218 0 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 0 ▶sub query_accession {
Subroutine query_accession: not called CC=1 SCAR=6.9
Pod documented
233 0 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 0 ▶sub query_length {
Subroutine query_length: not called CC=1 SCAR=6.9
Pod documented
250 0 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 0 ▶sub query_description {
Subroutine query_description: not called CC=1 SCAR=6.9
Pod documented
266 0 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 0 ▶sub database_name {
Subroutine database_name: not called CC=1 SCAR=6.9
Pod documented
283 0 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 0 ▶sub database_letters {
Subroutine database_letters: not called CC=1 SCAR=6.9
Pod documented
302 0 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 0 ▶sub database_entries {
Subroutine database_entries: not called CC=1 SCAR=6.9
Pod documented
319 0 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 0 ▶sub get_parameter{
Subroutine get_parameter: not called CC=1 SCAR=6.9
Pod documented
336 0 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 0 ▶sub available_parameters{
Subroutine available_parameters: not called CC=1 SCAR=6.9
Pod documented
351 0 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 0 ▶sub get_statistic{
Subroutine get_statistic: not called CC=1 SCAR=6.9
Pod documented
367 0 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 0 ▶sub available_statistics{
Subroutine available_statistics: not called CC=1 SCAR=6.9
Pod documented
382 0 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 0 ▶sub algorithm{
Subroutine algorithm: not called CC=1 SCAR=6.9
Pod documented
397 0 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 0 ▶sub algorithm_version{
Subroutine algorithm_version: not called CC=1 SCAR=6.9
Pod documented
412 0 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 0 ▶sub algorithm_reference{
Subroutine algorithm_reference: not called CC=1 SCAR=6.9
Pod documented
431 0 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 0 ▶sub rid{
Subroutine rid: not called CC=1 SCAR=6.9
Pod documented
450 0 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 0 ▶sub num_hits{
Subroutine num_hits: not called CC=1 SCAR=6.9
Pod documented
466 0 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<Bio::Search::Hit::HitI>
479  
480 =cut
481  
482 0 ▶sub hits{
Subroutine hits: not called CC=1 SCAR=6.9
Pod documented
483 0 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 ▶sub no_hits_found { shift->throw_not_implemented }
Subroutine no_hits_found: not called CC=1 SCAR=6.9
Pod documented
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 ▶sub set_no_hits_found { shift->throw_not_implemented }
Subroutine set_no_hits_found: not called CC=1 SCAR=6.9
Pod documented
522  
523 36 1;
524  
525  
« Bio/Matrix/IO/mlagan.pm ↑ Summary Bio/Ontology/Relationship.pm »