Bio/SimpleAnalysisI.pm

   1 #
   2 # BioPerl module for Bio::SimpleAnalysisI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Martin Senger <martin.senger@gmail.com>
   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<Bio::AnalysisI>
  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<bioperl-l@bioperl.org>
  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://redmine.open-bio.org/projects/bioperl/
  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<Bio::SimpleAnalysisI> object you will get a I<not implemented> error
  92 message.
  93
  94 =cut
  95
  96
  97 # Let the code begin...
  98
  99 package Bio::SimpleAnalysisI;
 100 use strict;
 101
 102 use base qw(Bio::Root::RootI);
 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 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<name>, C<type>, C<version>,
 126 C<supplier>, C<installation>, C<description>.
 127
 128 =cut
 129
 130 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<run> and C<wait_for> as name/value
 144 pairs).
 145
 146 =cut
 147
 148 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<result>.
 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 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<wait_for>. 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<Bio::AnalysisI> which
 188 uses method C<run> for an asynchronous execution and method
 189 C<wait_for> 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<name> is the name of an input data or input parameter (see
 207 method C<input_spec> for finding what names are recognized by this
 208 analysis) and C<value> is a value for this data/parameter. If C<value>
 209 is missing a 1 is assumed (which is convenient for the boolean
 210 options). If C<value> 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 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<run>. See details in the C<run> method.
 236
 237 =cut
 238
 239 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 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 sub result { shift->throw_not_implemented(); }
 278
 279 # -----------------------------------------------------------------------------
 280
 281 1;
 282 __END__
 283