| 1 | # | ||
| 2 | # BioPerl module for Bio::AnalysisI | ||
| 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::AnalysisI - An 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 C<Bio::Tools::Run::Analysis> module: | ||
| 20 | |||
| 21 | use Bio::Tools::Run::Analysis; | ||
| 22 | my $tool = Bio::Tools::Run::Analysis->new(@args); | ||
| 23 | |||
| 24 | =head1 DESCRIPTION | ||
| 25 | |||
| 26 | This interface contains all public methods for accessing and | ||
| 27 | controlling local and remote analysis tools. It is meant to be used on | ||
| 28 | the client side. | ||
| 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://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 | http://www.ebi.ac.uk/Tools/webservices/soaplab/guide | ||
| 79 | |||
| 80 | =head1 APPENDIX | ||
| 81 | |||
| 82 | This is actually the main documentation... | ||
| 83 | |||
| 84 | If you try to call any of these methods directly on this | ||
| 85 | C<Bio::AnalysisI> object you will get a I<not implemented> error | ||
| 86 | message. You need to call them on a C<Bio::Tools::Run::Analysis> object instead. | ||
| 87 | |||
| 88 | =cut | ||
| 89 | |||
| 90 | |||
| 91 | # Let the code begin... | ||
| 92 | |||
| 93 | package Bio::AnalysisI; | ||
| 94 | 2 | $Bio::AnalysisI::VERSION = '1.7.8'; | |
| 95 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 96 | |||
| 97 | 2 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 98 | |||
| 99 | # ----------------------------------------------------------------------------- | ||
| 100 | |||
| 101 | =head2 analysis_name | ||
| 102 | |||
| 103 | Usage : $tool->analysis_name; | ||
| 104 | Returns : a name of this analysis | ||
| 105 | Args : none | ||
| 106 | |||
| 107 | =cut | ||
| 108 | |||
| 109 | 0 | ▶ | sub analysis_name { shift->throw_not_implemented(); } |
|
Subroutine
analysis_name: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 110 | |||
| 111 | # ----------------------------------------------------------------------------- | ||
| 112 | |||
| 113 | =head2 analysis_spec | ||
| 114 | |||
| 115 | Usage : $tool->analysis_spec; | ||
| 116 | Returns : a hash reference describing this analysis | ||
| 117 | Args : none | ||
| 118 | |||
| 119 | The returned hash reference uses the following keys (not all of them always | ||
| 120 | present, perhaps others present as well): C<name>, C<type>, C<version>, | ||
| 121 | C<supplier>, C<installation>, C<description>. | ||
| 122 | |||
| 123 | Here is an example output: | ||
| 124 | |||
| 125 | Analysis 'edit.seqret': | ||
| 126 | installation => EMBL-EBI | ||
| 127 | description => Reads and writes (returns) sequences | ||
| 128 | supplier => EMBOSS | ||
| 129 | version => 2.6.0 | ||
| 130 | type => edit | ||
| 131 | name => seqret | ||
| 132 | |||
| 133 | =cut | ||
| 134 | |||
| 135 | 0 | ▶ | sub analysis_spec { shift->throw_not_implemented(); } |
|
Subroutine
analysis_spec: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 136 | |||
| 137 | # ----------------------------------------------------------------------------- | ||
| 138 | |||
| 139 | =head2 describe | ||
| 140 | |||
| 141 | Usage : $tool->analysis_spec; | ||
| 142 | Returns : an XML detailed description of this analysis | ||
| 143 | Args : none | ||
| 144 | |||
| 145 | The returned XML string contains metadata describing this analysis | ||
| 146 | service. It includes also metadata returned (and easier used) by | ||
| 147 | method C<analysis_spec>, C<input_spec> and C<result_spec>. | ||
| 148 | |||
| 149 | The DTD used for returned metadata is based on the adopted standard | ||
| 150 | (BSA specification for analysis engine): | ||
| 151 | |||
| 152 | <!ELEMENT DsLSRAnalysis (analysis)+> | ||
| 153 | |||
| 154 | <!ELEMENT analysis (description?, input*, output*, extension?)> | ||
| 155 | |||
| 156 | <!ATTLIST analysis | ||
| 157 | type CDATA #REQUIRED | ||
| 158 | name CDATA #IMPLIED | ||
| 159 | version CDATA #IMPLIED | ||
| 160 | supplier CDATA #IMPLIED | ||
| 161 | installation CDATA #IMPLIED> | ||
| 162 | |||
| 163 | <!ELEMENT description ANY> | ||
| 164 | <!ELEMENT extension ANY> | ||
| 165 | |||
| 166 | <!ELEMENT input (default?, allowed*, extension?)> | ||
| 167 | |||
| 168 | <!ATTLIST input | ||
| 169 | type CDATA #REQUIRED | ||
| 170 | name CDATA #REQUIRED | ||
| 171 | mandatory (true|false) "false"> | ||
| 172 | |||
| 173 | <!ELEMENT default (#PCDATA)> | ||
| 174 | <!ELEMENT allowed (#PCDATA)> | ||
| 175 | |||
| 176 | <!ELEMENT output (extension?)> | ||
| 177 | |||
| 178 | <!ATTLIST output | ||
| 179 | type CDATA #REQUIRED | ||
| 180 | name CDATA #REQUIRED> | ||
| 181 | |||
| 182 | But the DTD may be extended by provider-specific metadata. For | ||
| 183 | example, the EBI experimental SOAP-based service on top of EMBOSS uses | ||
| 184 | DTD explained at C<http://www.ebi.ac.uk/~senger/applab>. | ||
| 185 | |||
| 186 | =cut | ||
| 187 | |||
| 188 | 0 | ▶ | sub describe { shift->throw_not_implemented(); } |
|
Subroutine
describe: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 189 | |||
| 190 | # ----------------------------------------------------------------------------- | ||
| 191 | |||
| 192 | =head2 input_spec | ||
| 193 | |||
| 194 | Usage : $tool->input_spec; | ||
| 195 | Returns : an array reference with hashes as elements | ||
| 196 | Args : none | ||
| 197 | |||
| 198 | The analysis input data are named, and can be also associated with a | ||
| 199 | default value, with allowed values and with few other attributes. The | ||
| 200 | names are important for feeding the service with the input data (the | ||
| 201 | inputs are given to methods C<create_job>, C<Bio::AnalysisI|run>, and/or | ||
| 202 | C<Bio::AnalysisI|wait_for> as name/value pairs). | ||
| 203 | |||
| 204 | Here is a (slightly shortened) example of an input specification: | ||
| 205 | |||
| 206 | $input_spec = [ | ||
| 207 | { | ||
| 208 | 'mandatory' => 'false', | ||
| 209 | 'type' => 'String', | ||
| 210 | 'name' => 'sequence_usa' | ||
| 211 | }, | ||
| 212 | { | ||
| 213 | 'mandatory' => 'false', | ||
| 214 | 'type' => 'String', | ||
| 215 | 'name' => 'sequence_direct_data' | ||
| 216 | }, | ||
| 217 | { | ||
| 218 | 'mandatory' => 'false', | ||
| 219 | 'allowed_values' => [ | ||
| 220 | 'gcg', | ||
| 221 | 'gcg8', | ||
| 222 | ... | ||
| 223 | 'raw' | ||
| 224 | ], | ||
| 225 | 'type' => 'String', | ||
| 226 | 'name' => 'sformat' | ||
| 227 | }, | ||
| 228 | { | ||
| 229 | 'mandatory' => 'false', | ||
| 230 | 'type' => 'String', | ||
| 231 | 'name' => 'sbegin' | ||
| 232 | }, | ||
| 233 | { | ||
| 234 | 'mandatory' => 'false', | ||
| 235 | 'type' => 'String', | ||
| 236 | 'name' => 'send' | ||
| 237 | }, | ||
| 238 | { | ||
| 239 | 'mandatory' => 'false', | ||
| 240 | 'type' => 'String', | ||
| 241 | 'name' => 'sprotein' | ||
| 242 | }, | ||
| 243 | { | ||
| 244 | 'mandatory' => 'false', | ||
| 245 | 'type' => 'String', | ||
| 246 | 'name' => 'snucleotide' | ||
| 247 | }, | ||
| 248 | { | ||
| 249 | 'mandatory' => 'false', | ||
| 250 | 'type' => 'String', | ||
| 251 | 'name' => 'sreverse' | ||
| 252 | }, | ||
| 253 | { | ||
| 254 | 'mandatory' => 'false', | ||
| 255 | 'type' => 'String', | ||
| 256 | 'name' => 'slower' | ||
| 257 | }, | ||
| 258 | { | ||
| 259 | 'mandatory' => 'false', | ||
| 260 | 'type' => 'String', | ||
| 261 | 'name' => 'supper' | ||
| 262 | }, | ||
| 263 | { | ||
| 264 | 'mandatory' => 'false', | ||
| 265 | 'default' => 'false', | ||
| 266 | 'type' => 'String', | ||
| 267 | 'name' => 'firstonly' | ||
| 268 | }, | ||
| 269 | { | ||
| 270 | 'mandatory' => 'false', | ||
| 271 | 'default' => 'fasta', | ||
| 272 | 'allowed_values' => [ | ||
| 273 | 'gcg', | ||
| 274 | 'gcg8', | ||
| 275 | 'embl', | ||
| 276 | ... | ||
| 277 | 'raw' | ||
| 278 | ], | ||
| 279 | 'type' => 'String', | ||
| 280 | 'name' => 'osformat' | ||
| 281 | } | ||
| 282 | ]; | ||
| 283 | |||
| 284 | =cut | ||
| 285 | |||
| 286 | 0 | ▶ | sub input_spec { shift->throw_not_implemented(); } |
|
Subroutine
input_spec: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 287 | |||
| 288 | # ----------------------------------------------------------------------------- | ||
| 289 | |||
| 290 | =head2 result_spec | ||
| 291 | |||
| 292 | Usage : $tool->result_spec; | ||
| 293 | Returns : a hash reference with result names as keys | ||
| 294 | and result types as values | ||
| 295 | Args : none | ||
| 296 | |||
| 297 | The analysis results are named and can be retrieved using their names | ||
| 298 | by methods C<results> and C<result>. | ||
| 299 | |||
| 300 | Here is an example of the result specification (again for the service | ||
| 301 | I<edit.seqret>): | ||
| 302 | |||
| 303 | $result_spec = { | ||
| 304 | 'outseq' => 'String', | ||
| 305 | 'report' => 'String', | ||
| 306 | 'detailed_status' => 'String' | ||
| 307 | }; | ||
| 308 | |||
| 309 | =cut | ||
| 310 | |||
| 311 | 0 | ▶ | sub result_spec { shift->throw_not_implemented(); } |
|
Subroutine
result_spec: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 312 | |||
| 313 | # ----------------------------------------------------------------------------- | ||
| 314 | |||
| 315 | =head2 create_job | ||
| 316 | |||
| 317 | Usage : $tool->create_job ( {'sequence'=>'tatat'} ) | ||
| 318 | Returns : Bio::Tools::Run::Analysis::Job | ||
| 319 | Args : data and parameters for this execution | ||
| 320 | (in various formats) | ||
| 321 | |||
| 322 | Create an object representing a single execution of this analysis | ||
| 323 | tool. | ||
| 324 | |||
| 325 | Call this method if you wish to "stage the scene" - to create a job | ||
| 326 | with all input data but without actually running it. This method is | ||
| 327 | called automatically from other methods (C<Bio::AnalysisI|run> and | ||
| 328 | C<Bio::AnalysisI|wait_for>) so usually you do not need to call it directly. | ||
| 329 | |||
| 330 | The input data and prameters for this execution can be specified in | ||
| 331 | various ways: | ||
| 332 | |||
| 333 | =over | ||
| 334 | |||
| 335 | =item array reference | ||
| 336 | |||
| 337 | The array has scalar elements of the form | ||
| 338 | |||
| 339 | name = [[@]value] | ||
| 340 | |||
| 341 | where C<name> is the name of an input data or input parameter (see | ||
| 342 | method C<input_spec> for finding what names are recognized by this | ||
| 343 | analysis) and C<value> is a value for this data/parameter. If C<value> | ||
| 344 | is missing a 1 is assumed (which is convenient for the boolean | ||
| 345 | options). If C<value> starts with C<@> it is treated as a local | ||
| 346 | filename, and its contents is used as the data/parameter value. | ||
| 347 | |||
| 348 | =item hash reference | ||
| 349 | |||
| 350 | The same as with the array reference but now there is no need to use | ||
| 351 | an equal sign. The hash keys are input names and hash values their | ||
| 352 | data. The values can again start with a C<@> sign indicating a local | ||
| 353 | filename. | ||
| 354 | |||
| 355 | =item scalar | ||
| 356 | |||
| 357 | In this case, the parameter represents a job ID obtained in some | ||
| 358 | previous invocation - such job already exists on the server side, and | ||
| 359 | we are just re-creating it here using the same job ID. | ||
| 360 | |||
| 361 | I<TBD: here we should allow the same by using a reference to the | ||
| 362 | Bio::Tools::Run::Analysis::Job object.> | ||
| 363 | |||
| 364 | =item undef | ||
| 365 | |||
| 366 | Finally, if the parameter is undefined, ask server to create an empty | ||
| 367 | job. The input data may be added later using C<set_data...> | ||
| 368 | method(s) - see scripts/papplmaker.PLS for details. | ||
| 369 | |||
| 370 | =back | ||
| 371 | |||
| 372 | =cut | ||
| 373 | |||
| 374 | 0 | ▶ | sub create_job { shift->throw_not_implemented(); } |
|
Subroutine
create_job: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 375 | |||
| 376 | # ----------------------------------------------------------------------------- | ||
| 377 | |||
| 378 | =head2 run | ||
| 379 | |||
| 380 | Usage : $tool->run ( ['sequence=@my.seq', 'osformat=embl'] ) | ||
| 381 | Returns : Bio::Tools::Run::Analysis::Job, | ||
| 382 | representing started job (an execution) | ||
| 383 | Args : the same as for create_job | ||
| 384 | |||
| 385 | Create a job and start it, but do not wait for its completion. | ||
| 386 | |||
| 387 | =cut | ||
| 388 | |||
| 389 | 0 | ▶ | sub run { shift->throw_not_implemented(); } |
|
Subroutine
run: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 390 | |||
| 391 | # ----------------------------------------------------------------------------- | ||
| 392 | |||
| 393 | =head2 wait_for | ||
| 394 | |||
| 395 | Usage : $tool->wait_for ( { 'sequence' => '@my,file' } ) | ||
| 396 | Returns : Bio::Tools::Run::Analysis::Job, | ||
| 397 | representing finished job | ||
| 398 | Args : the same as for create_job | ||
| 399 | |||
| 400 | Create a job, start it and wait for its completion. | ||
| 401 | |||
| 402 | Note that this is a blocking method. It returns only after the | ||
| 403 | executed job finishes, either normally or by an error. | ||
| 404 | |||
| 405 | Usually, after this call, you ask for results of the finished job: | ||
| 406 | |||
| 407 | $analysis->wait_for (...)->results; | ||
| 408 | |||
| 409 | =cut | ||
| 410 | |||
| 411 | 0 | ▶ | sub wait_for { shift->throw_not_implemented(); } |
|
Subroutine
wait_for: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 412 | |||
| 413 | # ----------------------------------------------------------------------------- | ||
| 414 | # | ||
| 415 | # Bio::AnalysisI::JobI | ||
| 416 | # | ||
| 417 | # ----------------------------------------------------------------------------- | ||
| 418 | |||
| 419 | package Bio::AnalysisI::JobI; | ||
| 420 | 2 | $Bio::AnalysisI::JobI::VERSION = '1.7.8'; | |
| 421 | =head1 Module Bio::AnalysisI::JobI | ||
| 422 | |||
| 423 | An interface to the public methods provided by C<Bio::Tools::Run::Analysis::Job> | ||
| 424 | objects. | ||
| 425 | |||
| 426 | The C<Bio::Tools::Run::Analysis::Job> objects represent a created, | ||
| 427 | running, or finished execution of an analysis tool. | ||
| 428 | |||
| 429 | The factory for these objects is module C<Bio::Tools::Run::Analysis> | ||
| 430 | where the following methods return an | ||
| 431 | C<Bio::Tools::Run::Analysis::Job> object: | ||
| 432 | |||
| 433 | create_job (returning a prepared job) | ||
| 434 | run (returning a running job) | ||
| 435 | wait_for (returning a finished job) | ||
| 436 | |||
| 437 | =cut | ||
| 438 | |||
| 439 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 440 | 2 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 441 | |||
| 442 | # ----------------------------------------------------------------------------- | ||
| 443 | |||
| 444 | =head2 id | ||
| 445 | |||
| 446 | Usage : $job->id; | ||
| 447 | Returns : this job ID | ||
| 448 | Args : none | ||
| 449 | |||
| 450 | Each job (an execution) is identifiable by this unique ID which can be | ||
| 451 | used later to re-create the same job (in other words: to re-connect to | ||
| 452 | the same job). It is useful in cases when a job takes long time to | ||
| 453 | finish and your client program does not want to wait for it within the | ||
| 454 | same session. | ||
| 455 | |||
| 456 | =cut | ||
| 457 | |||
| 458 | 0 | ▶ | sub id { shift->throw_not_implemented(); } |
|
Subroutine
id: not called CC=1 SCAR=6.9
| |||
| 459 | |||
| 460 | # ----------------------------------------------------------------------------- | ||
| 461 | |||
| 462 | =head2 Bio::AnalysisI::JobI::run | ||
| 463 | |||
| 464 | Usage : $job->run | ||
| 465 | Returns : itself | ||
| 466 | Args : none | ||
| 467 | |||
| 468 | It starts previously created job. The job already must have all input | ||
| 469 | data filled-in. This differs from the method of the same name of the | ||
| 470 | C<Bio::Tools::Run::Analysis> object where the C<Bio::AnalysisI::JobI::run> method | ||
| 471 | creates also a new job allowing to set input data. | ||
| 472 | |||
| 473 | =cut | ||
| 474 | |||
| 475 | 0 | ▶ | sub run { shift->throw_not_implemented(); } |
|
Subroutine
run: not called CC=1 SCAR=6.9
| |||
| 476 | |||
| 477 | # ----------------------------------------------------------------------------- | ||
| 478 | |||
| 479 | =head2 Bio::AnalysisI::JobI::wait_for | ||
| 480 | |||
| 481 | Usage : $job->wait_for | ||
| 482 | Returns : itself | ||
| 483 | Args : none | ||
| 484 | |||
| 485 | It waits until a previously started execution of this job finishes. | ||
| 486 | |||
| 487 | =cut | ||
| 488 | |||
| 489 | 0 | ▶ | sub wait_for { shift->throw_not_implemented(); } |
|
Subroutine
wait_for: not called CC=1 SCAR=6.9
| |||
| 490 | |||
| 491 | # ----------------------------------------------------------------------------- | ||
| 492 | |||
| 493 | =head2 terminate | ||
| 494 | |||
| 495 | Usage : $job->terminate | ||
| 496 | Returns : itself | ||
| 497 | Args : none | ||
| 498 | |||
| 499 | Stop the currently running job (represented by this object). This is a | ||
| 500 | definitive stop, there is no way to resume it later. | ||
| 501 | |||
| 502 | =cut | ||
| 503 | |||
| 504 | 0 | ▶ | sub terminate { shift->throw_not_implemented(); } |
|
Subroutine
terminate: not called CC=1 SCAR=6.9
| |||
| 505 | |||
| 506 | # ----------------------------------------------------------------------------- | ||
| 507 | |||
| 508 | =head2 last_event | ||
| 509 | |||
| 510 | Usage : $job->last_event | ||
| 511 | Returns : an XML string | ||
| 512 | Args : none | ||
| 513 | |||
| 514 | It returns a short XML document showing what happened last with this | ||
| 515 | job. This is the used DTD: | ||
| 516 | |||
| 517 | <!-- place for extensions --> | ||
| 518 | <!ENTITY % event_body_template "(state_changed | heartbeat_progress | percent_progress | time_progress | step_progress)"> | ||
| 519 | |||
| 520 | <!ELEMENT analysis_event (message?, (%event_body_template;)?)> | ||
| 521 | |||
| 522 | <!ATTLIST analysis_event | ||
| 523 | timestamp CDATA #IMPLIED> | ||
| 524 | |||
| 525 | <!ELEMENT message (#PCDATA)> | ||
| 526 | |||
| 527 | <!ELEMENT state_changed EMPTY> | ||
| 528 | <!ENTITY % analysis_state "created | running | completed | terminated_by_request | terminated_by_error"> | ||
| 529 | <!ATTLIST state_changed | ||
| 530 | previous_state (%analysis_state;) "created" | ||
| 531 | new_state (%analysis_state;) "created"> | ||
| 532 | |||
| 533 | <!ELEMENT heartbeat_progress EMPTY> | ||
| 534 | |||
| 535 | <!ELEMENT percent_progress EMPTY> | ||
| 536 | <!ATTLIST percent_progress | ||
| 537 | percentage CDATA #REQUIRED> | ||
| 538 | |||
| 539 | <!ELEMENT time_progress EMPTY> | ||
| 540 | <!ATTLIST time_progress | ||
| 541 | remaining CDATA #REQUIRED> | ||
| 542 | |||
| 543 | <!ELEMENT step_progress EMPTY> | ||
| 544 | <!ATTLIST step_progress | ||
| 545 | total_steps CDATA #IMPLIED | ||
| 546 | steps_completed CDATA #REQUIRED> | ||
| 547 | |||
| 548 | Here is an example what is returned after a job was created and | ||
| 549 | started, but before it finishes (note that the example uses an | ||
| 550 | analysis 'showdb' which does not need any input data): | ||
| 551 | |||
| 552 | use Bio::Tools::Run::Analysis; | ||
| 553 | print new Bio::Tools::Run::Analysis (-name => 'display.showdb') | ||
| 554 | ->run | ||
| 555 | ->last_event; | ||
| 556 | |||
| 557 | It prints: | ||
| 558 | |||
| 559 | <?xml version = "1.0"?> | ||
| 560 | <analysis_event> | ||
| 561 | <message>Mar 3, 2003 5:14:46 PM (Europe/London)</message> | ||
| 562 | <state_changed previous_state="created" new_state="running"/> | ||
| 563 | </analysis_event> | ||
| 564 | |||
| 565 | The same example but now after it finishes: | ||
| 566 | |||
| 567 | use Bio::Tools::Run::Analysis; | ||
| 568 | print new Bio::Tools::Run::Analysis (-name => 'display.showdb') | ||
| 569 | ->wait_for | ||
| 570 | ->last_event; | ||
| 571 | |||
| 572 | <?xml version = "1.0"?> | ||
| 573 | <analysis_event> | ||
| 574 | <message>Mar 3, 2003 5:17:14 PM (Europe/London)</message> | ||
| 575 | <state_changed previous_state="running" new_state="completed"/> | ||
| 576 | </analysis_event> | ||
| 577 | |||
| 578 | =cut | ||
| 579 | |||
| 580 | 0 | ▶ | sub last_event { shift->throw_not_implemented(); } |
|
Subroutine
last_event: not called CC=1 SCAR=6.9
| |||
| 581 | |||
| 582 | # ----------------------------------------------------------------------------- | ||
| 583 | |||
| 584 | =head2 status | ||
| 585 | |||
| 586 | Usage : $job->status | ||
| 587 | Returns : string describing the job status | ||
| 588 | Args : none | ||
| 589 | |||
| 590 | It returns one of the following strings (and perhaps more if a server | ||
| 591 | implementation extended possible job states): | ||
| 592 | |||
| 593 | CREATED | ||
| 594 | RUNNING | ||
| 595 | COMPLETED | ||
| 596 | TERMINATED_BY_REQUEST | ||
| 597 | TERMINATED_BY_ERROR | ||
| 598 | |||
| 599 | =cut | ||
| 600 | |||
| 601 | 0 | ▶ | sub status { shift->throw_not_implemented(); } |
|
Subroutine
status: not called CC=1 SCAR=6.9
| |||
| 602 | |||
| 603 | # ----------------------------------------------------------------------------- | ||
| 604 | |||
| 605 | =head2 created | ||
| 606 | |||
| 607 | Usage : $job->created (1) | ||
| 608 | Returns : time when this job was created | ||
| 609 | Args : optional | ||
| 610 | |||
| 611 | Without any argument it returns a time of creation of this job in | ||
| 612 | seconds, counting from the beginning of the UNIX epoch | ||
| 613 | (1.1.1970). With a true argument it returns a formatted time, using | ||
| 614 | rules described in C<Bio::Tools::Run::Analysis::Utils::format_time>. | ||
| 615 | |||
| 616 | =cut | ||
| 617 | |||
| 618 | 0 | ▶ | sub created { shift->throw_not_implemented(); } |
|
Subroutine
created: not called CC=1 SCAR=6.9
| |||
| 619 | |||
| 620 | # ----------------------------------------------------------------------------- | ||
| 621 | |||
| 622 | =head2 started | ||
| 623 | |||
| 624 | Usage : $job->started (1) | ||
| 625 | Returns : time when this job was started | ||
| 626 | Args : optional | ||
| 627 | |||
| 628 | See C<created>. | ||
| 629 | |||
| 630 | =cut | ||
| 631 | |||
| 632 | 0 | ▶ | sub started { shift->throw_not_implemented(); } |
|
Subroutine
started: not called CC=1 SCAR=6.9
| |||
| 633 | |||
| 634 | # ----------------------------------------------------------------------------- | ||
| 635 | |||
| 636 | =head2 ended | ||
| 637 | |||
| 638 | Usage : $job->ended (1) | ||
| 639 | Returns : time when this job was terminated | ||
| 640 | Args : optional | ||
| 641 | |||
| 642 | See C<created>. | ||
| 643 | |||
| 644 | =cut | ||
| 645 | |||
| 646 | 0 | ▶ | sub ended { shift->throw_not_implemented(); } |
|
Subroutine
ended: not called CC=1 SCAR=6.9
| |||
| 647 | |||
| 648 | # ----------------------------------------------------------------------------- | ||
| 649 | |||
| 650 | =head2 elapsed | ||
| 651 | |||
| 652 | Usage : $job->elapsed | ||
| 653 | Returns : elapsed time of the execution of the given job | ||
| 654 | (in milliseconds), or 0 of job was not yet started | ||
| 655 | Args : none | ||
| 656 | |||
| 657 | Note that some server implementations cannot count in millisecond - so | ||
| 658 | the returned time may be rounded to seconds. | ||
| 659 | |||
| 660 | =cut | ||
| 661 | |||
| 662 | 0 | ▶ | sub elapsed { shift->throw_not_implemented(); } |
|
Subroutine
elapsed: not called CC=1 SCAR=6.9
| |||
| 663 | |||
| 664 | # ----------------------------------------------------------------------------- | ||
| 665 | |||
| 666 | =head2 times | ||
| 667 | |||
| 668 | Usage : $job->times ('formatted') | ||
| 669 | Returns : a hash reference with all time characteristics | ||
| 670 | Args : optional | ||
| 671 | |||
| 672 | It is a convenient method returning a hash reference with the following | ||
| 673 | keys: | ||
| 674 | |||
| 675 | created | ||
| 676 | started | ||
| 677 | ended | ||
| 678 | elapsed | ||
| 679 | |||
| 680 | See C<create> for remarks on time formatting. | ||
| 681 | |||
| 682 | An example - both for unformatted and formatted times: | ||
| 683 | |||
| 684 | use Data::Dumper; | ||
| 685 | use Bio::Tools::Run::Analysis; | ||
| 686 | my $rh = Bio::Tools::Run::Analysis->new(-name => 'nucleic_cpg_islands.cpgplot') | ||
| 687 | ->wait_for ( { 'sequence_usa' => 'embl:hsu52852' } ) | ||
| 688 | ->times (1); | ||
| 689 | print Data::Dumper->Dump ( [$rh], ['Times']); | ||
| 690 | $rh = Bio::Tools::Run::Analysis->new(-name => 'nucleic_cpg_islands.cpgplot') | ||
| 691 | ->wait_for ( { 'sequence_usa' => 'embl:AL499624' } ) | ||
| 692 | ->times; | ||
| 693 | print Data::Dumper->Dump ( [$rh], ['Times']); | ||
| 694 | |||
| 695 | $Times = { | ||
| 696 | 'ended' => 'Mon Mar 3 17:52:06 2003', | ||
| 697 | 'started' => 'Mon Mar 3 17:52:05 2003', | ||
| 698 | 'elapsed' => '1000', | ||
| 699 | 'created' => 'Mon Mar 3 17:52:05 2003' | ||
| 700 | }; | ||
| 701 | $Times = { | ||
| 702 | 'ended' => '1046713961', | ||
| 703 | 'started' => '1046713926', | ||
| 704 | 'elapsed' => '35000', | ||
| 705 | 'created' => '1046713926' | ||
| 706 | }; | ||
| 707 | |||
| 708 | =cut | ||
| 709 | |||
| 710 | 0 | ▶ | sub times { shift->throw_not_implemented(); } |
|
Subroutine
times: not called CC=1 SCAR=6.9
| |||
| 711 | |||
| 712 | # ----------------------------------------------------------------------------- | ||
| 713 | |||
| 714 | =head2 results | ||
| 715 | |||
| 716 | Usage : $job->results (...) | ||
| 717 | Returns : one or more results created by this job | ||
| 718 | Args : various, see belou | ||
| 719 | |||
| 720 | This is a complex method trying to make sense for all kinds of | ||
| 721 | results. Especially it tries to help to put binary results (such as | ||
| 722 | images) into local files. Generally it deals with fhe following facts: | ||
| 723 | |||
| 724 | =over | ||
| 725 | |||
| 726 | =item * | ||
| 727 | |||
| 728 | Each analysis tool may produce more results. | ||
| 729 | |||
| 730 | =item * | ||
| 731 | |||
| 732 | Some results may contain binary data not suitable for printing into a | ||
| 733 | terminal window. | ||
| 734 | |||
| 735 | =item * | ||
| 736 | |||
| 737 | Some results may be split into variable number of parts (this is | ||
| 738 | mainly true for the image results that can consist of more *.png | ||
| 739 | files). | ||
| 740 | |||
| 741 | =back | ||
| 742 | |||
| 743 | Note also that results have names to distinguish if there are more of | ||
| 744 | them. The names can be obtained by method C<result_spec>. | ||
| 745 | |||
| 746 | Here are the rules how the method works: | ||
| 747 | |||
| 748 | Retrieving NAMED results: | ||
| 749 | ------------------------- | ||
| 750 | results ('name1', ...) => return results as they are, no storing into files | ||
| 751 | |||
| 752 | results ( { 'name1' => 'filename', ... } ) => store into 'filename', return 'filename' | ||
| 753 | results ( 'name1=filename', ...) => ditto | ||
| 754 | |||
| 755 | results ( { 'name1' => '-', ... } ) => send result to the STDOUT, do not return anything | ||
| 756 | results ( 'name1=-', ...) => ditto | ||
| 757 | |||
| 758 | results ( { 'name1' => '@', ... } ) => store into file whose name is invented by | ||
| 759 | this method, perhaps using RESULT_NAME_TEMPLATE env | ||
| 760 | results ( 'name1=@', ...) => ditto | ||
| 761 | |||
| 762 | results ( { 'name1' => '?', ... } ) => find of what type is this result and then use | ||
| 763 | {'name1'=>'@' for binary files, and a regular | ||
| 764 | return for non-binary files | ||
| 765 | results ( 'name=?', ...) => ditto | ||
| 766 | |||
| 767 | Retrieving ALL results: | ||
| 768 | ----------------------- | ||
| 769 | results() => return all results as they are, no storing into files | ||
| 770 | |||
| 771 | results ('@') => return all results, as if each of them given | ||
| 772 | as {'name' => '@'} (see above) | ||
| 773 | |||
| 774 | results ('?') => return all results, as if each of them given | ||
| 775 | as {'name' => '?'} (see above) | ||
| 776 | |||
| 777 | Misc: | ||
| 778 | ----- | ||
| 779 | * any result can be returned as a scalar value, or as an array reference | ||
| 780 | (the latter is used for results consisting of more parts, such images); | ||
| 781 | this applies regardless whether the returned result is the result itself | ||
| 782 | or a filename created for the result | ||
| 783 | |||
| 784 | * look in the documentation of the C<panalysis[.PLS]> script for examples | ||
| 785 | (especially how to use various templates for inventing file names) | ||
| 786 | |||
| 787 | =cut | ||
| 788 | |||
| 789 | 0 | ▶ | sub results { shift->throw_not_implemented(); } |
|
Subroutine
results: not called CC=1 SCAR=6.9
| |||
| 790 | |||
| 791 | # ----------------------------------------------------------------------------- | ||
| 792 | |||
| 793 | =head2 result | ||
| 794 | |||
| 795 | Usage : $job->result (...) | ||
| 796 | Returns : the first result | ||
| 797 | Args : see 'results' | ||
| 798 | |||
| 799 | =cut | ||
| 800 | |||
| 801 | 0 | ▶ | sub result { shift->throw_not_implemented(); } |
|
Subroutine
result: not called CC=1 SCAR=6.9
| |||
| 802 | |||
| 803 | # ----------------------------------------------------------------------------- | ||
| 804 | |||
| 805 | =head2 remove | ||
| 806 | |||
| 807 | Usage : $job->remove | ||
| 808 | Returns : 1 | ||
| 809 | Args : none | ||
| 810 | |||
| 811 | The job object is not actually removed in this time but it is marked | ||
| 812 | (setting 1 to C<_destroy_on_exit> attribute) as ready for deletion when | ||
| 813 | the client program ends (including a request to server to forget the job | ||
| 814 | mirror object on the server side). | ||
| 815 | |||
| 816 | =cut | ||
| 817 | |||
| 818 | 0 | ▶ | sub remove { shift->throw_not_implemented(); } |
|
Subroutine
remove: not called CC=1 SCAR=6.9
| |||
| 819 | |||
| 820 | # ----------------------------------------------------------------------------- | ||
| 821 | |||
| 822 | 2 | 1; | |
| 823 | __END__ | ||