File Coverage

Bio/SimpleAnalysisI.pm
Criterion Covered Total %
statement 6 14 42.8
branch n/a
condition n/a
subroutine 2 10 20.0
pod 8 8 100.0
total 16 32 50.0


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::SimpleAnalysisI
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Martin Senger
7             # For copyright and disclaimer see below.
8             #
9              
10             # POD documentation - main docs before the code
11              
12             =head1 NAME
13              
14             Bio::SimpleAnalysisI - A simple interface to any (local or remote) analysis tool
15              
16             =head1 SYNOPSIS
17              
18             This is an interface module - you do not instantiate it.
19             Use other modules instead (those that implement this interface).
20              
21             =head1 DESCRIPTION
22              
23             This interface contains public methods for accessing and controlling
24             local and remote analysis tools. It is meant to be used on the client
25             side. The interface consists only of a necessary set of methods for
26             synchronous invocation of analysis tools. For more complex set,
27             including an asynchronous access, see interface C
28             (which inherits from this one, by the way).
29              
30             =head1 FEEDBACK
31              
32             =head2 Mailing Lists
33              
34             User feedback is an integral part of the evolution of this and other
35             Bioperl modules. Send your comments and suggestions preferably to
36             the Bioperl mailing list. Your participation is much appreciated.
37              
38             bioperl-l@bioperl.org - General discussion
39             http://bioperl.org/wiki/Mailing_lists - About the mailing lists
40              
41             =head2 Support
42              
43             Please direct usage questions or support issues to the mailing list:
44              
45             I
46              
47             rather than to the module maintainer directly. Many experienced and
48             reponsive experts will be able look at the problem and quickly
49             address it. Please include a thorough description of the problem
50             with code and data examples if at all possible.
51              
52             =head2 Reporting Bugs
53              
54             Report bugs to the Bioperl bug tracking system to help us keep track
55             of the bugs and their resolution. Bug reports can be submitted via the
56             web:
57              
58             https://github.com/bioperl/bioperl-live/issues
59              
60             =head1 AUTHOR
61              
62             Martin Senger (martin.senger@gmail.com)
63              
64             =head1 COPYRIGHT
65              
66             Copyright (c) 2003, Martin Senger and EMBL-EBI.
67             All Rights Reserved.
68              
69             This module is free software; you can redistribute it and/or modify
70             it under the same terms as Perl itself.
71              
72             =head1 DISCLAIMER
73              
74             This software is provided "as is" without warranty of any kind.
75              
76             =head1 SEE ALSO
77              
78             =over
79              
80             =item *
81              
82             http://www.ebi.ac.uk/Tools/webservices/soaplab/guide
83              
84             =back
85              
86             =head1 APPENDIX
87              
88             This is actually the main documentation...
89              
90             If you try to call any of these methods directly on this
91             C object you will get a I error
92             message.
93              
94             =cut
95              
96              
97             # Let the code begin...
98              
99             package Bio::SimpleAnalysisI;
100 1     1   4 use strict;
  1         2  
  1         23  
101              
102 1     1   3 use base qw(Bio::Root::RootI);
  1         2  
  1         152  
103              
104             # -----------------------------------------------------------------------------
105              
106             =head2 analysis_name
107              
108             Usage : $tool->analysis_name;
109             Returns : a name of this analysis
110             Args : none
111              
112             =cut
113              
114 0     0 1   sub analysis_name { shift->throw_not_implemented(); }
115              
116             # -----------------------------------------------------------------------------
117              
118             =head2 analysis_spec
119              
120             Usage : $tool->analysis_spec;
121             Returns : a hash reference describing this analysis
122             Args : none
123              
124             The returned hash reference uses the following keys (not all of them always
125             present, perhaps others present as well): C, C, C,
126             C, C, C.
127              
128             =cut
129              
130 0     0 1   sub analysis_spec { shift->throw_not_implemented(); }
131              
132             # -----------------------------------------------------------------------------
133              
134             =head2 input_spec
135              
136             Usage : $tool->input_spec;
137             Returns : an array reference with hashes as elements
138             Args : none
139              
140             The analysis input data are named, and can be also associated with a
141             default value, with allowed values and with few other attributes. The
142             names are important for feeding the analysis with the input data (the
143             inputs are given to methods C and C as name/value
144             pairs).
145              
146             =cut
147              
148 0     0 1   sub input_spec { shift->throw_not_implemented(); }
149              
150             # -----------------------------------------------------------------------------
151              
152             =head2 result_spec
153              
154             Usage : $tool->result_spec;
155             Returns : a hash reference with result names as keys
156             and result types as values
157             Args : none
158              
159             An analysis can produce several results, or the same result in several
160             different formats. All such results are named and can be retrieved
161             using their names by metod C.
162              
163             Here is an example of the result specification:
164              
165             $result_spec = {
166             'outseq' => 'String',
167             'report' => 'String',
168             'detailed_status' => 'String'
169             };
170              
171             =cut
172              
173 0     0 1   sub result_spec { shift->throw_not_implemented(); }
174              
175             # -----------------------------------------------------------------------------
176              
177             =head2 run
178              
179             Usage : $tool->run ( ['sequence=@my.seq', 'osformat=embl'] )
180             Returns : $self
181             Args : data and parameters for this execution
182             (in various formats)
183              
184             Create a job, start it, and wait for its completion. The method is
185             identical to the method C. Why there are two methods doing
186             the same? Because it is expected that the sub-classes may implement
187             them differently (an example is an interface C which
188             uses method C for an asynchronous execution and method
189             C for a synchronous one.
190              
191             Usually, after this call, you ask for results of the finished job:
192              
193             $analysis->run (...)->result;
194              
195             The input data and prameters for this execution can be specified in
196             various ways:
197              
198             =over
199              
200             =item array reference
201              
202             The array has scalar elements of the form
203              
204             name = [[@]value]
205              
206             where C is the name of an input data or input parameter (see
207             method C for finding what names are recognized by this
208             analysis) and C is a value for this data/parameter. If C
209             is missing a 1 is assumed (which is convenient for the boolean
210             options). If C starts with C<@> it is treated as a local
211             filename, and its contents is used as the data/parameter value.
212              
213             =item hash reference
214              
215             The same as with the array reference but now there is no need to use
216             an equal sign. The hash keys are input names and hash values their
217             data. The values can again start with a C<@> sign indicating a local
218             filename.
219              
220             =back
221              
222             =cut
223              
224 0     0 1   sub run { shift->throw_not_implemented(); }
225              
226             # -----------------------------------------------------------------------------
227              
228             =head2 wait_for
229              
230             Usage : $tool->wait_for ( { 'sequence' => '@my,file' } )
231             Returns : $self
232             Args : the same as for method 'run'
233              
234             Create a job, start it and wait for its completion. The method is
235             identical to the method C. See details in the C method.
236              
237             =cut
238              
239 0     0 1   sub wait_for { shift->throw_not_implemented(); }
240              
241             # -----------------------------------------------------------------------------
242              
243             =head2 status
244              
245             Usage : $tool->status
246             Returns : string describing a status of the execution
247             Args : none
248              
249             It returns one of the following strings (and perhaps more if a server
250             implementation extended possible job states):
251              
252             CREATED (not run yet)
253             COMPLETED (run and finished normally)
254             TERMINATED_BY_ERROR (run and finished with an error or a signal)
255              
256             =cut
257              
258 0     0 1   sub status { shift->throw_not_implemented(); }
259              
260             # -----------------------------------------------------------------------------
261              
262             =head2 result
263              
264             Usage : $job->result (...)
265             Returns : a result created by running an analysis
266             Args : none (but an implementation may choose
267             to add arguments for instructions how to process
268             the raw result)
269              
270             The method returns a scalar representing a result of an executed
271             job. If the job was terminated by an error the result may contain an
272             error message instead of the real data (or both, depending on the
273             implementation).
274              
275             =cut
276              
277 0     0 1   sub result { shift->throw_not_implemented(); }
278              
279             # -----------------------------------------------------------------------------
280              
281             1;
282             __END__