maint: restructure to use Dist::Zilla
[bioperl-live.git] / lib / Bio / Search / Result / PullResultI.pm
blob5e78289499de1716d58ba826deab03ba7bbd4a92
2 # BioPerl module Bio::Search::Result::PullResultI
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Sendu Bala <bix@sendu.me.uk>
8 # You may distribute this module under the same terms as perl itself
10 # POD documentation - main docs before the code
12 =head1 NAME
14 Bio::Search::Result::PullResultI - Bio::Search::Result::ResultI interface for
15 'pull' parsers
17 =head1 SYNOPSIS
19 # This is an interface and cannot be instantiated
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');
26 my $result = $io->next_result;
28 while( $hit = $result->next_hit()) {
29 # enter code here for hit processing
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;
42 =head1 DESCRIPTION
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.
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.
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.
59 =head1 FEEDBACK
61 =head2 Mailing Lists
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.
68 bioperl-l@bioperl.org - General discussion
69 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
71 =head2 Support
73 Please direct usage questions or support issues to the mailing list:
75 I<bioperl-l@bioperl.org>
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.
82 =head2 Reporting Bugs
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:
88 https://github.com/bioperl/bioperl-live/issues
90 =head1 AUTHOR Sendu Bala
92 Email bix@sendu.me.uk
94 =head1 COPYRIGHT
96 Copyright (c) 2006 Sendu Bala.
98 =head1 DISCLAIMER
100 This software is provided "as is" without warranty of any kind.
102 =head1 APPENDIX
104 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
106 =cut
108 # Let the code begin...
110 package Bio::Search::Result::PullResultI;
112 use strict;
114 use Bio::Search::GenericStatistics;
115 use Bio::Tools::Run::GenericParameters;
117 use base qw(Bio::PullParserI Bio::Search::Result::ResultI);
119 =head2 _setup
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().
128 =cut
130 sub _setup {
131 my ($self, @args) = @_;
133 # fields most subclasses probably will want
134 $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 ) } );
143 my ($parent, $chunk, $params, $stats) = $self->_rearrange([qw(PARENT
144 CHUNK
145 PARAMETERS
146 STATISTICS)],
147 @args);
148 $self->throw("Need -parent or -chunk to be defined") unless $parent || $chunk;
150 $self->parent($parent) if $parent;
152 if ($chunk) {
153 my ($io, $start, $end) = (undef, 0, undef);
154 if (ref($chunk) eq 'ARRAY') {
155 ($io, $start, $end) = @{$chunk};
157 else {
158 $io = $chunk;
160 $self->chunk($io, -start => $start, -end => $end);
163 if (defined $params) {
164 if (ref($params) !~ /hash/i) {
165 $self->throw("Must specify a hash reference with the the parameter '-parameters");
167 while (my ($key,$value) = each %{$params}) {
168 $self->add_parameter($key, $value);
171 if (defined $stats) {
172 if (ref($stats) !~ /hash/i) {
173 $self->throw("Must specify a hash reference with the the parameter '-statistics");
175 while (my ($key,$value) = each %{$stats}) {
176 $self->add_statistic($key, $value);
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.
187 =head2 next_hit
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
196 =cut
198 sub next_hit {
199 return shift->get_field('next_hit');
202 =head2 sort_hits
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);
218 =cut
220 # In ResultI. subclasses will probably want to override since sort_hits normally
221 # calls hits().
223 =head2 query_name
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
232 =cut
234 sub query_name {
235 return shift->get_field('query_name');
238 =head2 query_accession
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
246 =cut
248 sub query_accession {
249 return shift->get_field('query_accession');
252 =head2 query_length
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
260 =cut
262 sub query_length {
263 return shift->get_field('query_length');
266 =head2 query_description
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
275 =cut
277 sub query_description {
278 return shift->get_field('query_description');
281 =head2 database_name
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
290 =cut
292 sub database_name {
293 return shift->get_field('database_name');
296 =head2 database_letters
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
306 =cut
308 sub database_letters {
309 return shift->get_field('database_letters');
312 =head2 database_entries
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
321 =cut
323 sub database_entries {
324 return shift->get_field('database_entries');
327 =head2 algorithm
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
335 =cut
337 sub algorithm {
338 return shift->get_field('algorithm');
341 =head2 algorithm_version
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
349 =cut
351 sub algorithm_version {
352 return shift->get_field('algorithm_version');
355 =head2 algorithm_reference
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.
366 =cut
368 sub algorithm_reference {
369 my ($self) = @_;
370 return '';
373 =head2 num_hits
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
381 =cut
383 sub num_hits {
384 return shift->get_field('num_hits');
387 =head2 hits
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
395 See Also: L<Bio::Search::Hit::HitI>
397 =cut
399 sub hits {
400 return shift->get_field('hits');
403 =head2 no_hits_found
405 Usage : $nohits = $blast->no_hits_found();
406 Function : Get boolean indicator indicating whether or not any hits
407 were present in the report.
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.
414 Thus, this method can be used to distinguish these possibilities
415 for hitless reports generated when filtering.
417 Returns : Boolean
418 Args : none
420 =cut
422 sub no_hits_found {
423 return shift->get_field('no_hits_found');
426 =head2 rewind
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
435 =cut
437 sub rewind {
438 shift->throw_not_implemented();
441 =head2 get_parameter
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)
450 =cut
452 sub get_parameter {
453 my ($self, $param) = @_;
454 $param || return;
455 return unless defined $self->{_parameters};
456 return $self->{_parameters}->get_parameter($param);
459 =head2 available_parameters
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
467 =cut
469 sub available_parameters {
470 my $self = shift;
471 return () unless defined $self->{_parameters};
472 return $self->{_parameters}->available_parameters;
475 =head2 add_parameter
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
484 =cut
486 sub add_parameter {
487 my ($self, $key, $value) = @_;
488 unless (exists $self->{_parameters}) {
489 $self->{_parameters} = Bio::Tools::Run::GenericParameters->new();
491 $self->{_parameters}->set_parameter($key => $value);
494 =head2 get_statistic
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)
503 =cut
505 sub get_statistic {
506 my ($self, $stat) = @_;
507 $stat || return;
508 return unless defined $self->{_statistics};
509 return $self->{_statistics}->get_statistic($stat);
512 =head2 available_statistics
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
520 =cut
522 sub available_statistics {
523 my $self = shift;
524 return () unless defined $self->{_statistics};
525 return $self->{_statistics}->available_statistics;
528 =head2 add_statistic
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
537 =cut
539 sub add_statistic {
540 my ($self, $key, $value) = @_;
541 unless (exists $self->{_statistics}) {
542 $self->{_statistics} = Bio::Search::GenericStatistics->new();
544 $self->{_statistics}->set_statistic($key => $value);