Bio/SimpleAnalysisI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::SimpleAnalysisI
   4 #
   5 # Cared for by Martin Senger <martin.senger@gmail.com>
   6 # For copyright and disclaimer see below.
   7 #
   8
   9 # POD documentation - main docs before the code
  10
  11 =head1 NAME
  12
  13 Bio::SimpleAnalysisI - A simple interface to any (local or remote) analysis tool
  14
  15 =head1 SYNOPSIS
  16
  17 This is an interface module - you do not instantiate it.
  18 Use other modules instead (those that implement this interface).
  19
  20 =head1 DESCRIPTION
  21
  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).
  28
  29 =head1 FEEDBACK
  30
  31 =head2 Mailing Lists
  32
  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.
  36
  37   bioperl-l@bioperl.org                  - General discussion
  38   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  39
  40 =head2 Reporting Bugs
  41
  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
  44 web:
  45
  46   http://bugzilla.open-bio.org/
  47
  48 =head1 AUTHOR
  49
  50 Martin Senger (martin.senger@gmail.com)
  51
  52 =head1 COPYRIGHT
  53
  54 Copyright (c) 2003, Martin Senger and EMBL-EBI.
  55 All Rights Reserved.
  56
  57 This module is free software; you can redistribute it and/or modify
  58 it under the same terms as Perl itself.
  59
  60 =head1 DISCLAIMER
  61
  62 This software is provided "as is" without warranty of any kind.
  63
  64 =head1 SEE ALSO
  65
  66 =over
  67
  68 =item *
  69
  70 http://www.ebi.ac.uk/soaplab/Perl_Client.html
  71
  72 =back
  73
  74 =head1 APPENDIX
  75
  76 This is actually the main documentation...
  77
  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
  80 message.
  81
  82 =cut
  83
  84
  85 # Let the code begin...
  86
  87 package Bio::SimpleAnalysisI;
  88 use strict;
  89
  90 use base qw(Bio::Root::RootI);
  91
  92 # -----------------------------------------------------------------------------
  93
  94 =head2 analysis_name
  95
  96  Usage   : $tool->analysis_name;
  97  Returns : a name of this analysis
  98  Args    : none
  99
 100 =cut
 101
 102 sub analysis_name { shift->throw_not_implemented(); }
 103
 104 # -----------------------------------------------------------------------------
 105
 106 =head2 analysis_spec
 107
 108  Usage   : $tool->analysis_spec;
 109  Returns : a hash reference describing this analysis
 110  Args    : none
 111
 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>.
 115
 116 =cut
 117
 118 sub analysis_spec { shift->throw_not_implemented(); }
 119
 120 # -----------------------------------------------------------------------------
 121
 122 =head2 input_spec
 123
 124  Usage   : $tool->input_spec;
 125  Returns : an array reference with hashes as elements
 126  Args    : none
 127
 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
 132 pairs).
 133
 134 =cut
 135
 136 sub input_spec { shift->throw_not_implemented(); }
 137
 138 # -----------------------------------------------------------------------------
 139
 140 =head2 result_spec
 141
 142  Usage   : $tool->result_spec;
 143  Returns : a hash reference with result names as keys
 144            and result types as values
 145  Args    : none
 146
 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>.
 150
 151 Here is an example of the result specification:
 152
 153   $result_spec = {
 154           'outseq' => 'String',
 155           'report' => 'String',
 156           'detailed_status' => 'String'
 157         };
 158
 159 =cut
 160
 161 sub result_spec { shift->throw_not_implemented(); }
 162
 163 # -----------------------------------------------------------------------------
 164
 165 =head2 run
 166
 167  Usage   : $tool->run ( ['sequence=@my.seq', 'osformat=embl'] )
 168  Returns : $self
 169  Args    : data and parameters for this execution
 170            (in various formats)
 171
 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.
 178
 179 Usually, after this call, you ask for results of the finished job:
 180
 181     $analysis->run (...)->result;
 182
 183 The input data and prameters for this execution can be specified in
 184 various ways:
 185
 186 =over
 187
 188 =item array reference
 189
 190 The array has scalar elements of the form
 191
 192    name = [[@]value]
 193
 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.
 200
 201 =item hash reference
 202
 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
 206 filename.
 207
 208 =back
 209
 210 =cut
 211
 212 sub run { shift->throw_not_implemented(); }
 213
 214 # -----------------------------------------------------------------------------
 215
 216 =head2 wait_for
 217
 218  Usage   : $tool->wait_for ( { 'sequence' => '@my,file' } )
 219  Returns : $self
 220  Args    : the same as for method 'run'
 221
 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.
 224
 225 =cut
 226
 227 sub wait_for { shift->throw_not_implemented(); }
 228
 229 # -----------------------------------------------------------------------------
 230
 231 =head2 status
 232
 233  Usage   : $tool->status
 234  Returns : string describing a status of the execution
 235  Args    : none
 236
 237 It returns one of the following strings (and perhaps more if a server
 238 implementation extended possible job states):
 239
 240    CREATED              (not run yet)
 241    COMPLETED            (run and finished normally)
 242    TERMINATED_BY_ERROR  (run and finished with an error or a signal)
 243
 244 =cut
 245
 246 sub status { shift->throw_not_implemented(); }
 247
 248 # -----------------------------------------------------------------------------
 249
 250 =head2 result
 251
 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
 256            the raw result)
 257
 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
 261 implementation).
 262
 263 =cut
 264
 265 sub result { shift->throw_not_implemented(); }
 266
 267 # -----------------------------------------------------------------------------
 268
 269 1;
 270 __END__
 271