branch-1-6/Bio/SimpleAnalysisI.pm

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