File Coverage

Bio/Search/Result/PullResultI.pm
Criterion Covered Total %
statement 58 74 78.3
branch 18 32 56.2
condition 1 3 33.3
subroutine 23 26 88.4
pod 21 21 100.0
total 121 156 77.5


line stmt bran cond sub pod time code
1             #
2             # BioPerl module Bio::Search::Result::PullResultI
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Sendu Bala
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
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 2     2   9 use strict;
  2         4  
  2         47  
113              
114 2     2   794 use Bio::Search::GenericStatistics;
  2         2  
  2         43  
115 2     2   833 use Bio::Tools::Run::GenericParameters;
  2         3  
  2         68  
116              
117 2     2   8 use base qw(Bio::PullParserI Bio::Search::Result::ResultI);
  2         3  
  2         939  
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 20     20   37 my ($self, @args) = @_;
132            
133             # fields most subclasses probably will want
134 20         157 $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 20         72 my ($parent, $chunk, $params, $stats) = $self->_rearrange([qw(PARENT
144             CHUNK
145             PARAMETERS
146             STATISTICS)],
147             @args);
148 20 50 33     67 $self->throw("Need -parent or -chunk to be defined") unless $parent || $chunk;
149            
150 20 50       70 $self->parent($parent) if $parent;
151            
152 20 50       40 if ($chunk) {
153 20         26 my ($io, $start, $end) = (undef, 0, undef);
154 20 50       64 if (ref($chunk) eq 'ARRAY') {
155 20         19 ($io, $start, $end) = @{$chunk};
  20         38  
156             }
157             else {
158 0         0 $io = $chunk;
159             }
160 20         68 $self->chunk($io, -start => $start, -end => $end);
161             }
162            
163 20 50       53 if (defined $params) {
164 0 0       0 if (ref($params) !~ /hash/i) {
165 0         0 $self->throw("Must specify a hash reference with the the parameter '-parameters");
166             }
167 0         0 while (my ($key,$value) = each %{$params}) {
  0         0  
168 0         0 $self->add_parameter($key, $value);
169             }
170             }
171 20 50       67 if (defined $stats) {
172 0 0       0 if (ref($stats) !~ /hash/i) {
173 0         0 $self->throw("Must specify a hash reference with the the parameter '-statistics");
174             }
175 0         0 while (my ($key,$value) = each %{$stats}) {
  0         0  
176 0         0 $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 0     0 1 0 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 19     19 1 69 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 2     2 1 4 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 8     8 1 28 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 2     2 1 6 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 6     6 1 26 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 8     8 1 25 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 8     8 1 33 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 15     15 1 1239 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 8     8 1 29 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 2     2 1 3 my ($self) = @_;
370 2         5 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 2     2 1 797 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
396              
397             =cut
398              
399             sub hits {
400 0     0 1 0 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 2     2 1 807 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 0     0 1 0 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 17     17 1 21 my ($self, $param) = @_;
454 17 50       31 $param || return;
455 17 100       37 return unless defined $self->{_parameters};
456 15         33 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 2     2 1 4 my $self = shift;
471 2 50       9 return () unless defined $self->{_parameters};
472 0         0 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 16     16 1 29 my ($self, $key, $value) = @_;
488 16 100       29 unless (exists $self->{_parameters}) {
489 4         30 $self->{_parameters} = Bio::Tools::Run::GenericParameters->new();
490             }
491 16         31 $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 54     54 1 60 my ($self, $stat) = @_;
507 54 50       81 $stat || return;
508 54 100       102 return unless defined $self->{_statistics};
509 52         110 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 2     2 1 3 my $self = shift;
524 2 50       9 return () unless defined $self->{_statistics};
525 0         0 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 105     105 1 142 my ($self, $key, $value) = @_;
541 105 100       149 unless (exists $self->{_statistics}) {
542 4         29 $self->{_statistics} = Bio::Search::GenericStatistics->new();
543             }
544 105         173 $self->{_statistics}->set_statistic($key => $value);
545             }
546              
547             1;