Bio/Search/Result/PullResultI.pm

filter: Statementstmt 65.7% 50 / 76 Branchbran 38.8% 14 / 36 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 61.5% 16 / 26 Podpod 100% 21 / 21 totaltotal 62.2% 102 / 164 CC 20 SCAR 25.0
CC
20
Cov
57%
_setup
39.3
available_parameters
6.0
available_statistics
6.0
CRAP 12.2
« Bio/Tools/Grail.pm ↑ Summary Bio/Seq/SimulatedRead.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 4 $Bio::Search::Result::PullResultI::VERSION = '1.7.8';
112 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
113  
114 4 ▶use Bio::Search::GenericStatistics;
Subroutine BEGIN: called CC=1 SCAR=0.0
115 4 ▶use Bio::Tools::Run::GenericParameters;
Subroutine BEGIN: called CC=1 SCAR=0.0
116  
117 4 ▶use base qw(Bio::PullParserI Bio::Search::Result::ResultI);
Subroutine BEGIN: called CC=1 SCAR=0.0
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 17 ▶sub _setup {
Subroutine _setup: called CC=12 SCAR=36.7
131 17 my ($self, @args) = @_;
132
133 # fields most subclasses probably will want
134 17 $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 17 my ($parent, $chunk, $params, $stats) = $self->_rearrange([qw(PARENT
144 CHUNK
145 PARAMETERS
146 STATISTICS)],
147 @args);
148 17 ▶ $self->throw("Need -parent or -chunk to be defined") unless $parent || $chunk;
Branch: 1 branch
BranchTrueFalseTotal
unless $parent or $chunk 0 17 17
Condition33%1/3
$parent or $chunk
l!l&&r!l&&!r
1700
MC/DC0%0/2
$parent or $chunk
$parent $chunk
Truth table33%1/3
A or B
A= $parentB= $chunk
ABresult
1X1
011
000
149
150 17 ▶ $self->parent($parent) if $parent;
Branch: 1 branch
BranchTrueFalseTotal
if $parent 17 0 17
151
152 17 ▶ if ($chunk) {
Branch: 1 branch
BranchTrueFalseTotal
if ($chunk) 17 0 17
153 17 my ($io, $start, $end) = (undef, 0, undef);
154 17 ▶ if (ref($chunk) eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $chunk eq 'ARRAY') { } 17 0 17
155 17 ($io, $start, $end) = @{$chunk};
156 }
157 else {
158 0 $io = $chunk;
159 }
160 17 $self->chunk($io, -start => $start, -end => $end);
161 }
162
163 17 ▶ if (defined $params) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $params) 0 17 17
164 0 ▶ if (ref($params) !~ /hash/i) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref($params) =~ /hash/i) 0 0 0
165 0 $self->throw("Must specify a hash reference with the the parameter '-parameters");
166 }
167 0 ▶ while (my ($key,$value) = each %{$params}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$params;}) 0 0 0
168 0 $self->add_parameter($key, $value);
169 }
170 }
171 17 ▶ if (defined $stats) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $stats) 0 17 17
172 0 ▶ if (ref($stats) !~ /hash/i) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref($stats) =~ /hash/i) 0 0 0
173 0 $self->throw("Must specify a hash reference with the the parameter '-statistics");
174 }
175 0 ▶ while (my ($key,$value) = each %{$stats}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$stats;}) 0 0 0
176 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 0 ▶sub next_hit {
Subroutine next_hit: not called CC=1 SCAR=6.9
Pod documented
199 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 10 ▶sub query_name {
Subroutine query_name: called CC=1 SCAR=0.0
Pod documented
235 10 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 0 ▶sub query_accession {
Subroutine query_accession: not called CC=1 SCAR=6.9
Pod documented
249 0 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 6 ▶sub query_length {
Subroutine query_length: called CC=1 SCAR=0.0
Pod documented
263 6 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 0 ▶sub query_description {
Subroutine query_description: not called CC=1 SCAR=6.9
Pod documented
278 0 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 4 ▶sub database_name {
Subroutine database_name: called CC=1 SCAR=0.0
Pod documented
293 4 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 6 ▶sub database_letters {
Subroutine database_letters: called CC=1 SCAR=0.0
Pod documented
309 6 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 6 ▶sub database_entries {
Subroutine database_entries: called CC=1 SCAR=0.0
Pod documented
324 6 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 6 ▶sub algorithm {
Subroutine algorithm: called CC=1 SCAR=0.0
Pod documented
338 6 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 6 ▶sub algorithm_version {
Subroutine algorithm_version: called CC=1 SCAR=0.0
Pod documented
352 6 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 0 ▶sub algorithm_reference {
Subroutine algorithm_reference: not called CC=1 SCAR=6.9
Pod documented
369 0 my ($self) = @_;
370 0 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 0 ▶sub num_hits {
Subroutine num_hits: not called CC=1 SCAR=6.9
Pod documented
384 0 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 0 ▶sub hits {
Subroutine hits: not called CC=1 SCAR=6.9
Pod documented
400 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 0 ▶sub no_hits_found {
Subroutine no_hits_found: not called CC=1 SCAR=6.9
Pod documented
423 0 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 0 ▶sub rewind {
Subroutine rewind: not called CC=1 SCAR=6.9
Pod documented
438 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 15 ▶sub get_parameter {
Subroutine get_parameter: called CC=3 SCAR=11.4
Pod documented
453 15 my ($self, $param) = @_;
454 15 ▶ $param || return;
Branch: 1 branch
BranchTrueFalseTotal
$param or return 15 0 15
455 15 ▶ return unless defined $self->{_parameters};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_parameters"} 0 15 15
456 15 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 0 ▶sub available_parameters {
Subroutine available_parameters: not called CC=2 SCAR=17.9
Pod documented
470 0 my $self = shift;
471 0 ▶ return () unless defined $self->{_parameters};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_parameters"} 0 0 0
472 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 16 ▶sub add_parameter {
Subroutine add_parameter: called CC=2 SCAR=6.9
Pod documented
487 16 my ($self, $key, $value) = @_;
488 16 ▶ unless (exists $self->{_parameters}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_parameters"}) 4 12 16
489 4 $self->{_parameters} = Bio::Tools::Run::GenericParameters->new();
490 }
491 16 $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 52 ▶sub get_statistic {
Subroutine get_statistic: called CC=3 SCAR=11.4
Pod documented
506 52 my ($self, $stat) = @_;
507 52 ▶ $stat || return;
Branch: 1 branch
BranchTrueFalseTotal
$stat or return 52 0 52
508 52 ▶ return unless defined $self->{_statistics};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_statistics"} 0 52 52
509 52 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 0 ▶sub available_statistics {
Subroutine available_statistics: not called CC=2 SCAR=17.9
Pod documented
523 0 my $self = shift;
524 0 ▶ return () unless defined $self->{_statistics};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_statistics"} 0 0 0
525 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 105 ▶sub add_statistic {
Subroutine add_statistic: called CC=2 SCAR=6.9
Pod documented
540 105 my ($self, $key, $value) = @_;
541 105 ▶ unless (exists $self->{_statistics}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_statistics"}) 4 101 105
542 4 $self->{_statistics} = Bio::Search::GenericStatistics->new();
543 }
544 105 $self->{_statistics}->set_statistic($key => $value);
545 }
546  
547 4 1;
« Bio/Tools/Grail.pm ↑ Summary Bio/Seq/SimulatedRead.pm »