|
0
|
1 #-----------------------------------------------------------------
|
|
|
2 # $Id: ResultI.pm,v 1.16 2002/11/13 11:23:11 sac Exp $
|
|
|
3 #
|
|
|
4 # BioPerl module Bio::Search::Result::ResultI
|
|
|
5 #
|
|
|
6 # Cared for by Steve Chervitz <sac@bioperl.org>
|
|
|
7 #
|
|
|
8 # Originally created by Aaron Mackey <amackey@virginia.edu>
|
|
|
9 #
|
|
|
10 # You may distribute this module under the same terms as perl itself
|
|
|
11 #-----------------------------------------------------------------
|
|
|
12
|
|
|
13 # POD documentation - main docs before the code
|
|
|
14
|
|
|
15 =head1 NAME
|
|
|
16
|
|
|
17 Bio::Search::Result::ResultI - Abstract interface to Search Result objects
|
|
|
18
|
|
|
19 =head1 SYNOPSIS
|
|
|
20
|
|
|
21 # Bio::Search::Result::ResultI objects cannot be instantiated since this
|
|
|
22 # module defines a pure interface.
|
|
|
23
|
|
|
24 # Given an object that implements the Bio::Search::Result::ResultI interface,
|
|
|
25 # you can do the following things with it:
|
|
|
26
|
|
|
27 use Bio::SearchIO;
|
|
|
28 my $io = new Bio::SearchIO(-format => 'blast',
|
|
|
29 -file => 't/data/HUMBETGLOA.tblastx');
|
|
|
30 my $result = $io->next_result;
|
|
|
31 while( $hit = $result->next_hit()) { # enter code here for hit processing
|
|
|
32 }
|
|
|
33
|
|
|
34 my $id = $result->query_name();
|
|
|
35
|
|
|
36 my $desc = $result->query_description();
|
|
|
37
|
|
|
38 my $dbname = $result->database_name();
|
|
|
39
|
|
|
40 my $size = $result->database_letters();
|
|
|
41
|
|
|
42 my $num_entries = $result->database_entries();
|
|
|
43
|
|
|
44 my $gap_ext = $result->get_parameter('gapext');
|
|
|
45
|
|
|
46 my @params = $result->available_parameters;
|
|
|
47
|
|
|
48 my $kappa = $result->get_statistic('kappa');
|
|
|
49
|
|
|
50 my @statnames = $result->available_statistics;
|
|
|
51
|
|
|
52 =head1 DESCRIPTION
|
|
|
53
|
|
|
54 Bio::Search::Result::ResultI objects are data structures containing
|
|
|
55 the results from the execution of a search algorithm. As such, it may
|
|
|
56 contain various algorithm specific information as well as details of
|
|
|
57 the execution, but will contain a few fundamental elements, including
|
|
|
58 the ability to return Bio::Search::Hit::HitI objects.
|
|
|
59
|
|
|
60 =head1 FEEDBACK
|
|
|
61
|
|
|
62 =head2 Mailing Lists
|
|
|
63
|
|
|
64 User feedback is an integral part of the evolution of this
|
|
|
65 and other Bioperl modules. Send your comments and suggestions preferably
|
|
|
66 to one of the Bioperl mailing lists.
|
|
|
67 Your participation is much appreciated.
|
|
|
68
|
|
|
69 bioperl-l@bioperl.org - General discussion
|
|
|
70 http://bio.perl.org/MailList.html - About the mailing lists
|
|
|
71
|
|
|
72 =head2 Reporting Bugs
|
|
|
73
|
|
|
74 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
75 the bugs and their resolution.
|
|
|
76 Bug reports can be submitted via email or the web:
|
|
|
77
|
|
|
78 bioperl-bugs@bio.perl.org
|
|
|
79 http://bugzilla.bioperl.org/
|
|
|
80
|
|
|
81 =head1 AUTHOR
|
|
|
82
|
|
|
83 Aaron Mackey E<lt>amackey@virginia.eduE<gt> (original author)
|
|
|
84
|
|
|
85 Steve Chervitz E<lt>sac@bioperl.orgE<gt>
|
|
|
86
|
|
|
87 See L<the FEEDBACK section | FEEDBACK> for where to send bug reports and comments.
|
|
|
88
|
|
|
89 =head1 COPYRIGHT
|
|
|
90
|
|
|
91 Copyright (c) 1999-2001 Aaron Mackey, Steve Chervitz. All Rights Reserved.
|
|
|
92
|
|
|
93 =head1 DISCLAIMER
|
|
|
94
|
|
|
95 This software is provided "as is" without warranty of any kind.
|
|
|
96
|
|
|
97 =head1 APPENDIX
|
|
|
98
|
|
|
99 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
|
|
|
100
|
|
|
101 =cut
|
|
|
102
|
|
|
103 #'
|
|
|
104 # Let the code begin...
|
|
|
105
|
|
|
106
|
|
|
107 package Bio::Search::Result::ResultI;
|
|
|
108
|
|
|
109 use strict;
|
|
|
110 use vars qw(@ISA);
|
|
|
111
|
|
|
112 use Bio::AnalysisResultI;
|
|
|
113
|
|
|
114 @ISA = qw( Bio::AnalysisResultI );
|
|
|
115
|
|
|
116
|
|
|
117 =head2 next_hit
|
|
|
118
|
|
|
119 Title : next_hit
|
|
|
120 Usage : while( $hit = $result->next_hit()) { ... }
|
|
|
121 Function: Returns the next available Hit object, representing potential
|
|
|
122 matches between the query and various entities from the database.
|
|
|
123 Returns : a Bio::Search::Hit::HitI object or undef if there are no more.
|
|
|
124 Args : none
|
|
|
125
|
|
|
126
|
|
|
127 =cut
|
|
|
128
|
|
|
129 sub next_hit {
|
|
|
130 my ($self,@args) = @_;
|
|
|
131 $self->throw_not_implemented;
|
|
|
132 }
|
|
|
133
|
|
|
134 =head2 query_name
|
|
|
135
|
|
|
136 Title : query_name
|
|
|
137 Usage : $id = $result->query_name();
|
|
|
138 Function: Get the string identifier of the query used by the
|
|
|
139 algorithm that performed the search.
|
|
|
140 Returns : a string.
|
|
|
141 Args : none
|
|
|
142
|
|
|
143 =cut
|
|
|
144
|
|
|
145 sub query_name {
|
|
|
146 my ($self,@args) = @_;
|
|
|
147 $self->throw_not_implemented;
|
|
|
148 }
|
|
|
149
|
|
|
150 =head2 query_accession
|
|
|
151
|
|
|
152 Title : query_accession
|
|
|
153 Usage : $id = $result->query_accession();
|
|
|
154 Function: Get the accession (if available) for the query sequence
|
|
|
155 Returns : a string
|
|
|
156 Args : none
|
|
|
157
|
|
|
158 =cut
|
|
|
159
|
|
|
160 sub query_accession {
|
|
|
161 my ($self,@args) = @_;
|
|
|
162 $self->throw_not_implemented;
|
|
|
163 }
|
|
|
164
|
|
|
165
|
|
|
166 =head2 query_length
|
|
|
167
|
|
|
168 Title : query_length
|
|
|
169 Usage : $id = $result->query_length();
|
|
|
170 Function: Get the length of the query sequence
|
|
|
171 used in the search.
|
|
|
172 Returns : a number
|
|
|
173 Args : none
|
|
|
174
|
|
|
175 =cut
|
|
|
176
|
|
|
177 sub query_length {
|
|
|
178 my ($self,@args) = @_;
|
|
|
179 $self->throw_not_implemented;
|
|
|
180 }
|
|
|
181
|
|
|
182 =head2 query_description
|
|
|
183
|
|
|
184 Title : query_description
|
|
|
185 Usage : $id = $result->query_description();
|
|
|
186 Function: Get the description of the query sequence
|
|
|
187 used in the search.
|
|
|
188 Returns : a string
|
|
|
189 Args : none
|
|
|
190
|
|
|
191 =cut
|
|
|
192
|
|
|
193 sub query_description {
|
|
|
194 my ($self,@args) = @_;
|
|
|
195 $self->throw_not_implemented;
|
|
|
196 }
|
|
|
197
|
|
|
198
|
|
|
199 =head2 database_name
|
|
|
200
|
|
|
201 Title : database_name
|
|
|
202 Usage : $name = $result->database_name()
|
|
|
203 Function: Used to obtain the name of the database that the query was searched
|
|
|
204 against by the algorithm.
|
|
|
205 Returns : a scalar string
|
|
|
206 Args : none
|
|
|
207
|
|
|
208 =cut
|
|
|
209
|
|
|
210 sub database_name {
|
|
|
211 my ($self,@args) = @_;
|
|
|
212
|
|
|
213 $self->throw_not_implemented;
|
|
|
214 }
|
|
|
215
|
|
|
216 =head2 database_letters
|
|
|
217
|
|
|
218 Title : database_letters
|
|
|
219 Usage : $size = $result->database_letters()
|
|
|
220 Function: Used to obtain the size of database that was searched against.
|
|
|
221 Returns : a scalar integer (units specific to algorithm, but probably the
|
|
|
222 total number of residues in the database, if available) or undef if
|
|
|
223 the information was not available to the Processor object.
|
|
|
224 Args : none
|
|
|
225
|
|
|
226
|
|
|
227 =cut
|
|
|
228
|
|
|
229 sub database_letters {
|
|
|
230 my ($self,@args) = @_;
|
|
|
231 $self->throw_not_implemented();
|
|
|
232 }
|
|
|
233
|
|
|
234 =head2 database_entries
|
|
|
235
|
|
|
236 Title : database_entries
|
|
|
237 Usage : $num_entries = $result->database_entries()
|
|
|
238 Function: Used to obtain the number of entries contained in the database.
|
|
|
239 Returns : a scalar integer representing the number of entities in the database
|
|
|
240 or undef if the information was not available.
|
|
|
241 Args : none
|
|
|
242
|
|
|
243
|
|
|
244 =cut
|
|
|
245
|
|
|
246 sub database_entries {
|
|
|
247 my ($self,@args) = @_;
|
|
|
248
|
|
|
249 $self->throw_not_implemented();
|
|
|
250 }
|
|
|
251
|
|
|
252 =head2 get_parameter
|
|
|
253
|
|
|
254 Title : get_parameter
|
|
|
255 Usage : my $gap_ext = $result->get_parameter('gapext')
|
|
|
256 Function: Returns the value for a specific parameter used
|
|
|
257 when running this result
|
|
|
258 Returns : string
|
|
|
259 Args : name of parameter (string)
|
|
|
260
|
|
|
261 =cut
|
|
|
262
|
|
|
263 sub get_parameter{
|
|
|
264 my ($self,@args) = @_;
|
|
|
265 $self->throw_not_implemented();
|
|
|
266 }
|
|
|
267
|
|
|
268 =head2 available_parameters
|
|
|
269
|
|
|
270 Title : available_parameters
|
|
|
271 Usage : my @params = $result->available_parameters
|
|
|
272 Function: Returns the names of the available parameters
|
|
|
273 Returns : Return list of available parameters used for this result
|
|
|
274 Args : none
|
|
|
275
|
|
|
276 =cut
|
|
|
277
|
|
|
278 sub available_parameters{
|
|
|
279 my ($self) = @_;
|
|
|
280 $self->throw_not_implemented();
|
|
|
281 }
|
|
|
282
|
|
|
283 =head2 get_statistic
|
|
|
284
|
|
|
285 Title : get_statistic
|
|
|
286 Usage : my $gap_ext = $result->get_statistic('kappa')
|
|
|
287 Function: Returns the value for a specific statistic available
|
|
|
288 from this result
|
|
|
289 Returns : string
|
|
|
290 Args : name of statistic (string)
|
|
|
291
|
|
|
292 =cut
|
|
|
293
|
|
|
294 sub get_statistic{
|
|
|
295 my ($self,@args) = @_;
|
|
|
296 $self->throw_not_implemented();
|
|
|
297 }
|
|
|
298
|
|
|
299 =head2 available_statistics
|
|
|
300
|
|
|
301 Title : available_statistics
|
|
|
302 Usage : my @statnames = $result->available_statistics
|
|
|
303 Function: Returns the names of the available statistics
|
|
|
304 Returns : Return list of available statistics used for this result
|
|
|
305 Args : none
|
|
|
306
|
|
|
307 =cut
|
|
|
308
|
|
|
309 sub available_statistics{
|
|
|
310 my ($self) = @_;
|
|
|
311 $self->throw_not_implemented();
|
|
|
312 }
|
|
|
313
|
|
|
314 =head2 algorithm
|
|
|
315
|
|
|
316 Title : algorithm
|
|
|
317 Usage : my $r_type = $result->algorithm
|
|
|
318 Function: Obtain the name of the algorithm used to obtain the Result
|
|
|
319 Returns : string (e.g., BLASTP)
|
|
|
320 Args : [optional] scalar string to set value
|
|
|
321
|
|
|
322 =cut
|
|
|
323
|
|
|
324 sub algorithm{
|
|
|
325 my ($self) = @_;
|
|
|
326 $self->throw_not_implemented();
|
|
|
327 }
|
|
|
328
|
|
|
329 =head2 algorithm_version
|
|
|
330
|
|
|
331 Title : algorithm_version
|
|
|
332 Usage : my $r_version = $result->algorithm_version
|
|
|
333 Function: Obtain the version of the algorithm used to obtain the Result
|
|
|
334 Returns : string (e.g., 2.1.2)
|
|
|
335 Args : [optional] scalar string to set algorithm version value
|
|
|
336
|
|
|
337 =cut
|
|
|
338
|
|
|
339 sub algorithm_version{
|
|
|
340 my ($self) = @_;
|
|
|
341 $self->throw_not_implemented();
|
|
|
342 }
|
|
|
343
|
|
|
344
|
|
|
345 =head2 algorithm_reference
|
|
|
346
|
|
|
347 Title : algorithm_reference
|
|
|
348 Usage : $obj->algorithm_reference($newval)
|
|
|
349 Function:
|
|
|
350 Returns : value of the literature reference for the algorithm
|
|
|
351 Args : newvalue (optional)
|
|
|
352 Comments: The default implementation in ResultI returns an empty string
|
|
|
353 rather than throwing a NotImplemented exception, since
|
|
|
354 the ref may not always be available and is not critical.
|
|
|
355
|
|
|
356 =cut
|
|
|
357
|
|
|
358 sub algorithm_reference{
|
|
|
359 my ($self) = @_;
|
|
|
360 return '';
|
|
|
361 }
|
|
|
362
|
|
|
363 =head2 num_hits
|
|
|
364
|
|
|
365 Title : num_hits
|
|
|
366 Usage : my $hitcount= $result->num_hits
|
|
|
367 Function: returns the number of hits for this query result
|
|
|
368 Returns : integer
|
|
|
369 Args : none
|
|
|
370
|
|
|
371
|
|
|
372 =cut
|
|
|
373
|
|
|
374 sub num_hits{
|
|
|
375 my ($self,@args) = @_;
|
|
|
376 $self->throw_not_implemented();
|
|
|
377 }
|
|
|
378
|
|
|
379 =head2 hits
|
|
|
380
|
|
|
381 Title : hits
|
|
|
382 Usage : my @hits = $result->hits
|
|
|
383 Function: Returns the available hits for this Result
|
|
|
384 Returns : Array of L<Bio::Search::Hit::HitI> objects
|
|
|
385 Args : none
|
|
|
386
|
|
|
387
|
|
|
388 =cut
|
|
|
389
|
|
|
390 sub hits{
|
|
|
391 my ($self,@args) = @_;
|
|
|
392 $self->throw_not_implemented();
|
|
|
393 }
|
|
|
394
|
|
|
395 =head2 no_hits_found
|
|
|
396
|
|
|
397 Usage : $nohits = $blast->no_hits_found( [iteration_number] );
|
|
|
398 Purpose : Get boolean indicator indicating whether or not any hits
|
|
|
399 were present in the report.
|
|
|
400
|
|
|
401 This is NOT the same as determining the number of hits via
|
|
|
402 the hits() method, which will return zero hits if there were no
|
|
|
403 hits in the report or if all hits were filtered out during the parse.
|
|
|
404
|
|
|
405 Thus, this method can be used to distinguish these possibilities
|
|
|
406 for hitless reports generated when filtering.
|
|
|
407
|
|
|
408 Returns : Boolean
|
|
|
409 Argument : (optional) integer indicating the iteration number (PSI-BLAST)
|
|
|
410 If iteration number is not specified and this is a PSI-BLAST result,
|
|
|
411 then this method will return true only if all iterations had
|
|
|
412 no hits found.
|
|
|
413
|
|
|
414 =cut
|
|
|
415
|
|
|
416 #-----------
|
|
|
417 sub no_hits_found { shift->throw_not_implemented }
|
|
|
418
|
|
|
419
|
|
|
420
|
|
|
421 =head2 set_no_hits_found
|
|
|
422
|
|
|
423 Usage : $blast->set_no_hits_found( [iteration_number] );
|
|
|
424 Purpose : Set boolean indicator indicating whether or not any hits
|
|
|
425 were present in the report.
|
|
|
426 Returns : n/a
|
|
|
427 Argument : (optional) integer indicating the iteration number (PSI-BLAST)
|
|
|
428
|
|
|
429 =cut
|
|
|
430
|
|
|
431 sub set_no_hits_found { shift->throw_not_implemented }
|
|
|
432
|
|
|
433
|
|
|
434 =head2 iterations
|
|
|
435
|
|
|
436 Usage : $num_iterations = $blast->iterations; (get)
|
|
|
437 $blast->iterations($num_iterations); (set)
|
|
|
438 Purpose : Set/get the number of iterations in the Blast Report (PSI-BLAST).
|
|
|
439 Returns : Total number of iterations in the report
|
|
|
440 Argument : integer (when setting)
|
|
|
441
|
|
|
442 =cut
|
|
|
443
|
|
|
444 sub iterations { shift->throw_not_implemented }
|
|
|
445
|
|
|
446
|
|
|
447 =head2 psiblast
|
|
|
448
|
|
|
449 Usage : if( $blast->psiblast ) { ... }
|
|
|
450 Purpose : Set/get a boolean indicator whether or not the report
|
|
|
451 is a PSI-BLAST report.
|
|
|
452 Returns : 1 if PSI-BLAST, undef if not.
|
|
|
453 Argument : 1 (when setting)
|
|
|
454
|
|
|
455 =cut
|
|
|
456
|
|
|
457 sub psiblast { shift->throw_not_implemented }
|
|
|
458
|
|
|
459 1;
|
|
|
460
|
|
|
461
|
