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