File Coverage

Bio/Tools/AnalysisResult.pm
Criterion Covered Total %
statement 42 49 85.7
branch 8 14 57.1
condition n/a
subroutine 10 11 90.9
pod 6 7 85.7
total 66 81 81.4


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::Tools::AnalysisResult
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Hilmar Lapp
7             #
8             # Copyright Hilmar Lapp
9             #
10             # You may distribute this module under the same terms as perl itself
11              
12             # POD documentation - main docs before the code
13              
14             =head1 NAME
15              
16             Bio::Tools::AnalysisResult - Base class for analysis result objects and parsers
17              
18             =head1 SYNOPSIS
19              
20             # obtain a AnalysisResult derived object somehow
21              
22             print "Method ", $result->analysis_method(),
23             ", version ", $result->analysis_method_version(),
24             ", performed on ", $result->analysis_date(), "\n";
25              
26             # annotate a sequence utilizing SeqAnalysisParserI methods
27             while($feat = $result->next_feature()) {
28             $seq->add_SeqFeature($feat);
29             }
30             $result->close();
31              
32             # query object, e.g. a Bio::SeqI implementing object
33             $queryseq = $result->analysis_query();
34              
35             # Subject of the analysis -- may be undefined. Refer to derived module
36             # to find out what is returned.
37             $subject = $result->analysis_subject();
38              
39             =head1 DESCRIPTION
40              
41             The AnalysisResult module is supposed to be the base class for modules
42             encapsulating parsers and interpreters for the result of a analysis
43             that was carried out with a query sequence.
44              
45             The notion of an analysis represented by this base class is that of a
46             unary or binary operator, taking either one query or a query and a
47             subject and producing a result. The query is e.g. a sequence, and a
48             subject is either a sequence, too, or a database of sequences.
49              
50             This module also implements the Bio::SeqAnalysisParserI interface, and
51             thus can be used wherever such an object fits. See
52             L. Developers will
53             find a ready-to-use B method, but need to implement
54             B in an inheriting class. Support for initialization
55             with input file names and reading from streams is also ready to use.
56              
57             Note that this module does not provide support for B an
58             analysis. Rather, it is positioned in the subsequent parsing step
59             (concerned with turning raw results into BioPerl objects).
60              
61             =head1 FEEDBACK
62              
63             =head2 Mailing Lists
64              
65             User feedback is an integral part of the evolution of this and other
66             Bioperl modules. Send your comments and suggestions preferably to one
67             of the Bioperl mailing lists. Your participation is much appreciated.
68              
69             bioperl-l@bioperl.org - General discussion
70             http://bioperl.org/wiki/Mailing_lists - About the mailing lists
71              
72             =head2 Support
73              
74             Please direct usage questions or support issues to the mailing list:
75              
76             I
77              
78             rather than to the module maintainer directly. Many experienced and
79             reponsive experts will be able look at the problem and quickly
80             address it. Please include a thorough description of the problem
81             with code and data examples if at all possible.
82              
83             =head2 Reporting Bugs
84              
85             Report bugs to the Bioperl bug tracking system to help us keep track
86             the bugs and their resolution. Bug reports can be submitted via the
87             web:
88              
89             https://github.com/bioperl/bioperl-live/issues
90              
91             =head1 AUTHOR - Hilmar Lapp
92              
93             Email hlapp-at-gmx.net
94              
95             =head1 APPENDIX
96              
97             The rest of the documentation details each of the object
98             methods. Internal methods are usually preceded with a _
99              
100             =cut
101              
102              
103             # Let the code begin...
104              
105              
106             package Bio::Tools::AnalysisResult;
107 14     14   62 use strict;
  14         16  
  14         395  
108              
109 14     14   45 use base qw(Bio::Root::Root Bio::SeqAnalysisParserI Bio::AnalysisResultI Bio::Root::IO);
  14         17  
  14         4619  
110              
111             sub new {
112 22     22 1 66 my ($class, @args) = @_;
113 22         115 my $self = $class->SUPER::new(@args);
114 22         86 $self->_initialize(@args);
115 22         50 return $self;
116             }
117              
118             sub _initialize {
119 22     22   46 my($self,@args) = @_;
120              
121 22         83 my $make = $self->SUPER::_initialize(@args);
122              
123 22         78 $self->_initialize_state(@args);
124 22         31 return $make; # success - we hope!
125             }
126              
127             =head2 _initialize_state
128              
129             Title : _initialize_state
130             Usage : n/a; usually called by _initialize()
131             Function: This method is for BioPerl B only, as indicated by the
132             leading underscore in its name.
133              
134             Performs initialization or reset of the state of this object. The
135             difference to _initialize() is that it may be called at any time,
136             and repeatedly within the lifetime of this object. B, however,
137             that this is potentially dangerous in a multi-threading
138             environment. In general, calling this method twice is discouraged
139             for this reason.
140              
141             This method is supposed to reset the state such that any 'history'
142             is lost. State information that does not change during object
143             lifetime is not considered as history, e.g. parent, name, etc shall
144             not be reset. An inheriting object should only be concerned with
145             state information it introduces itself, and for everything else
146             call SUPER::_initialize_state(@args).
147              
148             An example is parsing an input file: a state reset implies
149             discarding any unread input, and the actual input itself, followed
150             by setting the new input.
151              
152             The argument syntax is the same as for L and L<_initialize()|_initialize>,
153             i.e., named parameters following the -name=>$value convention.
154             The following parameters are dealt with by the implementation
155             provided here:
156             -INPUT, -FH, -FILE
157             (tags are case-insensitive).
158             Example :
159             Returns :
160             Args :
161              
162             =cut
163              
164             sub _initialize_state {
165 22     22   42 my ($self,@args) = @_;
166              
167 22         101 $self->close();
168 22         100 $self->_initialize_io(@args);
169              
170 22         42 $self->{'_analysis_sbjct'} = undef;
171 22         28 $self->{'_analysis_query'} = undef;
172 22         50 $self->{'_analysis_prog'} = undef;
173 22         30 $self->{'_analysis_progVersion'} = undef;
174 22         28 $self->{'_analysis_date'} = undef;
175              
176 22         48 return 1;
177             }
178              
179             # =head2 parse
180             #
181             # Title : parse
182             # Usage : $obj->parse(-input=>$inputobj, [ -params=>[@params] ],
183             # [ -method => $method ] )
184             # Function: Sets up parsing for feature retrieval from an analysis file,
185             # or object.
186             #
187             # This method was originally required by SeqAnalysisParserI, but
188             # is now discouraged due to potential problems in a multi-
189             # threading environment (CORBA!). If called only once, it doesn't
190             # add any functionality to calling new() with the same
191             # parameters.
192             #
193             # The implementation provided here calls automatically
194             # _initialize_state() and passes on -input=>$inputobj and
195             # @params as final arguments.
196             # Example :
197             # Returns : void
198             # Args : B - object/file where analysis are coming from
199             # B - parameter to use when parsing/running analysis
200             # B - method of analysis
201             #
202             # =cut
203              
204             sub parse {
205 0     0 0 0 my ($self, @args) = @_;
206              
207 0         0 my ($input, $params, $method) =
208             $self->_rearrange([qw(INPUT
209             PARAMS
210             METHOD
211             )],
212             @args);
213              
214             # initialize with new input
215 0 0       0 if($params) {
216 0         0 $self->_initialize_state('-input' => $input, @$params);
217             } else {
218 0         0 $self->_initialize_state('-input' => $input);
219             }
220 0 0       0 $self->analysis_method($method) if $method;
221             }
222              
223             =head2 analysis_query
224              
225             Usage : $query_obj = $result->analysis_query();
226             Purpose : Set/Get the name of the query used to generate the result, that
227             is, the entity on which the analysis was performed. Will mostly
228             be a sequence object (Bio::PrimarySeq compatible).
229             Argument :
230             Returns : The object set before. Mostly a Bio::PrimarySeq compatible object.
231              
232             =cut
233              
234             #--------
235             sub analysis_query {
236 2     2 1 3 my ($self, $obj) = @_;
237 2 50       7 if($obj) {
238 0         0 $self->{'_analysis_query'} = $obj;
239             }
240 2         6 return $self->{'_analysis_query'};
241             }
242             #--------
243              
244             =head2 analysis_subject
245              
246             Usage : $result->analyis_subject();
247             Purpose : Set/Get the subject of the analysis against which it was
248             performed. For similarity searches it will probably be a database,
249             and for sequence feature predictions (exons, promoters, etc) it
250             may be a collection of models or homologous sequences that were
251             used, or undefined.
252             Returns : The object that was set before, or undef.
253             Argument :
254              
255             =cut
256              
257             #---------------
258             sub analysis_subject {
259             #---------------
260 5     5 1 14 my ($self, $sbjct_obj) = @_;
261 5 50       14 if($sbjct_obj) {
262 5         9 $self->{'_analysis_sbjct'} = $sbjct_obj;
263             }
264 5         7 return $self->{'_analysis_sbjct'};
265             }
266              
267              
268             =head2 analysis_date
269              
270             Usage : $result->analysis_date();
271             Purpose : Set/Get the date on which the analysis was performed.
272             Returns : String
273             Argument :
274             Comments :
275              
276             =cut
277              
278             #----------
279             sub analysis_date {
280 3     3 1 6 my ($self, $date) = @_;
281 3 100       8 if($date) {
282 2         4 $self->{'_analysis_date'} = $date;
283             }
284 3         7 return $self->{'_analysis_date'};
285             }
286             #----------
287              
288             =head2 analysis_method
289              
290             Usage : $result->analysis_method();
291             Purpose : Set/Get the name of the sequence analysis method that was used
292             to produce this result (BLASTP, FASTA, etc.). May also be the
293             actual name of a program.
294             Returns : String
295             Argument : n/a
296              
297             =cut
298              
299             #-------------
300             sub analysis_method {
301             #-------------
302 134     134 1 114 my ($self, $method) = @_;
303 134 100       181 if($method) {
304 14         23 $self->{'_analysis_prog'} = $method;
305             }
306 134         430 return $self->{'_analysis_prog'};
307             }
308              
309             =head2 analysis_method_version
310              
311             Usage : $result->analysis_method_version();
312             Purpose : Set/Get the version string of the analysis program.
313             : (e.g., 1.4.9MP, 2.0a19MP-WashU).
314             Returns : String
315             Argument : n/a
316              
317             =cut
318              
319             #---------------------
320             sub analysis_method_version {
321             #---------------------
322 8     8 1 16 my ($self, $version) = @_;
323 8 100       26 if($version) {
324 7         12 $self->{'_analysis_progVersion'} = $version;
325             }
326 8         18 return $self->{'_analysis_progVersion'};
327             }
328              
329              
330             1;