3 # BioPerl module for Bio::SimpleAnalysisI
5 # Cared for by Martin Senger <martin.senger@gmail.com>
6 # For copyright and disclaimer see below.
9 # POD documentation - main docs before the code
13 Bio::SimpleAnalysisI - A simple interface to any (local or remote) analysis tool
17 This is an interface module - you do not instantiate it.
18 Use other modules instead (those that implement this interface).
22 This interface contains public methods for accessing and controlling
23 local and remote analysis tools. It is meant to be used on the client
24 side. The interface consists only of a necessary set of methods for
25 synchronous invocation of analysis tools. For more complex set,
26 including an asynchronous access, see interface C<Bio::AnalysisI>
27 (which inherits from this one, by the way).
33 User feedback is an integral part of the evolution of this and other
34 Bioperl modules. Send your comments and suggestions preferably to
35 the Bioperl mailing list. Your participation is much appreciated.
37 bioperl-l@bioperl.org - General discussion
38 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
42 Report bugs to the Bioperl bug tracking system to help us keep track
43 of the bugs and their resolution. Bug reports can be submitted via the
46 http://bugzilla.open-bio.org/
50 Martin Senger (martin.senger@gmail.com)
54 Copyright (c) 2003, Martin Senger and EMBL-EBI.
57 This module is free software; you can redistribute it and/or modify
58 it under the same terms as Perl itself.
62 This software is provided "as is" without warranty of any kind.
70 http://www.ebi.ac.uk/soaplab/Perl_Client.html
76 This is actually the main documentation...
78 If you try to call any of these methods directly on this
79 C<Bio::SimpleAnalysisI> object you will get a I<not implemented> error
85 # Let the code begin...
87 package Bio
::SimpleAnalysisI
;
90 use base
qw(Bio::Root::RootI);
92 # -----------------------------------------------------------------------------
96 Usage : $tool->analysis_name;
97 Returns : a name of this analysis
102 sub analysis_name
{ shift->throw_not_implemented(); }
104 # -----------------------------------------------------------------------------
108 Usage : $tool->analysis_spec;
109 Returns : a hash reference describing this analysis
112 The returned hash reference uses the following keys (not all of them always
113 present, perhaps others present as well): C<name>, C<type>, C<version>,
114 C<supplier>, C<installation>, C<description>.
118 sub analysis_spec
{ shift->throw_not_implemented(); }
120 # -----------------------------------------------------------------------------
124 Usage : $tool->input_spec;
125 Returns : an array reference with hashes as elements
128 The analysis input data are named, and can be also associated with a
129 default value, with allowed values and with few other attributes. The
130 names are important for feeding the analysis with the input data (the
131 inputs are given to methods C<run> and C<wait_for> as name/value
136 sub input_spec
{ shift->throw_not_implemented(); }
138 # -----------------------------------------------------------------------------
142 Usage : $tool->result_spec;
143 Returns : a hash reference with result names as keys
144 and result types as values
147 An analysis can produce several results, or the same result in several
148 different formats. All such results are named and can be retrieved
149 using their names by metod C<result>.
151 Here is an example of the result specification:
154 'outseq' => 'String',
155 'report' => 'String',
156 'detailed_status' => 'String'
161 sub result_spec
{ shift->throw_not_implemented(); }
163 # -----------------------------------------------------------------------------
167 Usage : $tool->run ( ['sequence=@my.seq', 'osformat=embl'] )
169 Args : data and parameters for this execution
172 Create a job, start it, and wait for its completion. The method is
173 identical to the method C<wait_for>. Why there are two methods doing
174 the same? Because it is expected that the sub-classes may implement
175 them differently (an example is an interface C<Bio::AnalysisI> which
176 uses method C<run> for an asynchronous execution and method
177 C<wait_for> for a synchronous one.
179 Usually, after this call, you ask for results of the finished job:
181 $analysis->run (...)->result;
183 The input data and prameters for this execution can be specified in
188 =item array reference
190 The array has scalar elements of the form
194 where C<name> is the name of an input data or input parameter (see
195 method C<input_spec> for finding what names are recognized by this
196 analysis) and C<value> is a value for this data/parameter. If C<value>
197 is missing a 1 is assumed (which is convenient for the boolean
198 options). If C<value> starts with C<@> it is treated as a local
199 filename, and its contents is used as the data/parameter value.
203 The same as with the array reference but now there is no need to use
204 an equal sign. The hash keys are input names and hash values their
205 data. The values can again start with a C<@> sign indicating a local
212 sub run
{ shift->throw_not_implemented(); }
214 # -----------------------------------------------------------------------------
218 Usage : $tool->wait_for ( { 'sequence' => '@my,file' } )
220 Args : the same as for method 'run'
222 Create a job, start it and wait for its completion. The method is
223 identical to the method C<run>. See details in the C<run> method.
227 sub wait_for
{ shift->throw_not_implemented(); }
229 # -----------------------------------------------------------------------------
233 Usage : $tool->status
234 Returns : string describing a status of the execution
237 It returns one of the following strings (and perhaps more if a server
238 implementation extended possible job states):
240 CREATED (not run yet)
241 COMPLETED (run and finished normally)
242 TERMINATED_BY_ERROR (run and finished with an error or a signal)
246 sub status
{ shift->throw_not_implemented(); }
248 # -----------------------------------------------------------------------------
252 Usage : $job->result (...)
253 Returns : a result created by running an analysis
254 Args : none (but an implementation may choose
255 to add arguments for instructions how to process
258 The method returns a scalar representing a result of an executed
259 job. If the job was terminated by an error the result may contain an
260 error message instead of the real data (or both, depending on the
265 sub result
{ shift->throw_not_implemented(); }
267 # -----------------------------------------------------------------------------