Bio/Tools/Run/Analysis.pm

filter: Statementstmt 18.4% 28 / 152 Branchbran 0.0% 0 / 78 Conditioncond 0.0% 0 / 13 MC/DCmcdc 0.0% 0 / 7 Subroutinesub 44.4% 8 / 18 Podpod 100% 1 / 1 totaltotal 13.7% 37 / 269 CC 50 SCAR 43.7
CC
50
Cov
12%
_prepare_inputs
156.0
_save_result
156.0
new
72.0
CRAP 79.4
« Bio/Seq/LargeLocatableSeq.pm ↑ Summary Bio/Tools/Lucy.pm »
1 #
2 # BioPerl module for Bio::Tools::Run::Analysis
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::Tools::Run::Analysis - Module representing any (remote or local)
15 analysis tool
16  
17 =head1 SYNOPSIS
18  
19 # run analysis 'seqret' using a default location and a default
20 # access method (which means using a Web Service at EBI)
21 use Bio::Tools::Run::Analysis;
22 print new Bio::Tools::Run::Analysis (-name => 'edit::seqret')
23 ->wait_for ({ sequence_direct_data => 'tatatacgtatacga',
24 osformat => 'embl'
25 })
26 ->result ('outseq');
27  
28 # run a longer job without waiting for its completion
29 use Bio::Tools::Run::Analysis;
30 my $job = Bio::Tools::Run::Analysis->new(-name => 'edit::seqret')
31 ->run ({ sequence_direct_data => 'tatatacgtatacga',
32 osformat => 'embl'
33 });
34 # ...and after a while
35 $job->result ('outseq');
36  
37 # get all results in the same invocation (as a hash reference
38 # with result names as keys) - let the module decide which
39 # results are binary (images in this examples) and save those
40 # in file (or files); it also shows how to tell that the module
41 # should read input data from a local file first
42 use Bio::Tools::Run::Analysis;
43 my $results =
44 Bio::Tools::Run::Analysis->new(-name => 'alignment_multiple::prettyplot')
45 ->wait_for ( { msf_direct_data => '@/home/testdata/my.seq' } )
46 ->results ('?');
47 use Data::Dumper;
48 print Dumper ($results);
49  
50 # get names, types of all inputs and results,
51 # get short and detailed (in XML) service description
52 use Bio::Tools::Run::Analysis;
53 my $service = Bio::Tools::Run::Analysis->new(-name => 'edit::seqret');
54 my $hash1 = $service->input_spec;
55 my $hash2 = $service->result_spec;
56 my $hash3 = $service->analysis_spec;
57 my $xml = $service->describe;
58  
59 # get current job status
60 use Bio::Tools::Run::Analysis;
61 print new Bio::Tools::Run::Analysis (-name => 'edit::seqret')
62 ->run ( { #...input data...
63 } )
64 ->status;
65  
66 # run a job and print its job ID, keep the job un-destroyed
67 use Bio::Tools::Run::Analysis;
68 my $job =
69 Bio::Tools::Run::Analysis->new(-name => 'edit::seqret',
70 -destroy_on_exit => 0)
71 ->run ( { sequence_direct_data => '@/home/testdata/mzef.seq' } );
72 print $job->id . "\n";
73 # ...it prints (for example):
74 # edit::seqret/c8ef56:ef535489ac:-7ff4
75  
76 # ...in another time, on another planet, you may say
77 use Bio::Tools::Run::Analysis;
78 my $job =
79 Bio::Tools::Run::Analysis::Job->new(-name => 'edit::seqret',
80 -id => 'edit::seqret/c8ef56:ef535489ac:-7ff4');
81 print join ("\n",
82 $job->status,
83 'Finished: ' . $job->ended (1), # (1) means 'formatted'
84 'Elapsed time: ' . $job->elapsed,
85 $job->last_event,
86 $job->result ('outseq')
87 );
88  
89 # ...or you may achieve the same keeping module
90 # Bio::Tools::Run::Analysis::Job invisible
91 use Bio::Tools::Run::Analysis;
92 my $job =
93 Bio::Tools::Run::Analysis->new(-name => 'edit::seqret')
94 ->create_job ('edit::seqret/c8ef56:ef535489ac:-7ff4');
95 print join ("\n",
96 $job->status,
97 # ...
98 );
99  
100 # ...and later you may free this job resources
101 $job->remove;
102  
103 #
104 # --- See DESCRIPTION for using generator 'applmaker.pl':
105 #
106  
107  
108 =head1 DESCRIPTION
109  
110 The module represents an access to the local and/or remote analysis
111 tools in a unified way that allows adding new access methods
112 (protocols) seamlessly.
113  
114 At the moment of writing, there is available a I<SOAP> access to
115 almost all EMBOSS applications, running at the
116 European Bioinformatics Institute.
117  
118 The documentation of all C<public> methods are to be found
119 in C<Bio::AnalysisI>. A tutorial (and examples how to call almost all
120 public methods) is in the script C<panalysis.PLS> (go to the C<scripts>
121 directory and type C<perldoc panalysis.PLS>).
122  
123 The module C<Bio::Tools::Run::Analysis> uses general approach allowing to set
124 arbitrary input data and to retrieve results by naming them. However,
125 sometimes is more convenient to use a specific module, representing
126 one analysis tool, that already knows about available input and result
127 names. Such analyses-specific Perl modules can be generated by
128 C<papplmaker.PLS> generator. Its features and usage are documented in
129 the generator (go to the C<scripts> directory and type C<perldoc
130 papplmaker.PLS>).
131  
132 # this will generate module Seqret.pm
133 perl papplmaker.PLS -n edit.seqret -m Seqret
134  
135 # ...which can be used with data-specific methods
136 use Seqret;
137 my $outseq = new Seqret
138 ->sequence_direct_data ('@/home/testdata/my.seq')
139 ->osformat ('embl')
140 ->wait_for
141 ->outseq
142 ;
143 print $outseq;
144  
145 =head1 FEEDBACK
146  
147 =head2 Mailing Lists
148  
149 User feedback is an integral part of the evolution of this and other
150 Bioperl modules. Send your comments and suggestions preferably to
151 the Bioperl mailing list. Your participation is much appreciated.
152  
153 bioperl-l@bioperl.org - General discussion
154 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
155  
156 =head2 Support
157  
158 Please direct usage questions or support issues to the mailing list:
159  
160 I<bioperl-l@bioperl.org>
161  
162 rather than to the module maintainer directly. Many experienced and
163 reponsive experts will be able look at the problem and quickly
164 address it. Please include a thorough description of the problem
165 with code and data examples if at all possible.
166  
167 =head2 Reporting Bugs
168  
169 Report bugs to the Bioperl bug tracking system to help us keep track
170 of the bugs and their resolution. Bug reports can be submitted via the
171 web:
172  
173 http://redmine.open-bio.org/projects/bioperl/
174  
175 =head1 AUTHOR
176  
177 Martin Senger (martin.senger@gmail.com)
178  
179 =head1 COPYRIGHT
180  
181 Copyright (c) 2003, Martin Senger and EMBL-EBI.
182 All Rights Reserved.
183  
184 This module is free software; you can redistribute it and/or modify
185 it under the same terms as Perl itself.
186  
187 =head1 DISCLAIMER
188  
189 This software is provided "as is" without warranty of any kind.
190  
191 =head1 SEE ALSO
192  
193 =over
194  
195 =item *
196  
197 http://www.ebi.ac.uk/soaplab/Perl_Client.html
198  
199 =back
200  
201 =head1 APPENDIX
202  
203 Here is the rest of the object methods. Internal methods are preceded
204 with an underscore _.
205  
206 =cut
207  
208  
209 # Let the code begin...
210  
211 package Bio::Tools::Run::Analysis;
212 1 $Bio::Tools::Run::Analysis::VERSION = '1.7.8';
213 1 ▶use vars qw(@ISA $Revision);
Subroutine BEGIN: called CC=1 SCAR=0.0
214 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
215  
216 1 ▶use Bio::Root::Root;
Subroutine BEGIN: called CC=1 SCAR=0.0
217 1 ▶use Bio::AnalysisI;
Subroutine BEGIN: called CC=1 SCAR=0.0
218 1 @ISA = qw(Bio::Root::Root Bio::AnalysisI);
219  
220 1 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
221 1 $Revision = q[$Id$];
222 }
223  
224 # -----------------------------------------------------------------------------
225  
226 =head2 new
227  
228 Usage : my $tool =
229 Bio::Tools::Run::Analysis->new(-access => 'soap',
230 -name => 'edit.seqret',
231 ...
232 );
233 Returns : a new Bio::Tools::Run::Analysis object representing the given tool
234 Args : There may be additional arguments which are specific
235 to the access method (see methods 'new' or '_initialize'
236 of the access-specific implementations (such as module
237 Bio::Tools::Run::Analysis::soap for a SOAP-based access).
238  
239 The recognised and used arguments are:
240 -access
241 -location
242 -name
243 -httpproxy
244 -timeout
245  
246 It builds, populates and returns a new C<Bio::Tools::Run::Analysis> object. This
247 is how it is seen from the outside. But in fact, it builds, populates
248 and returns a more specific lower-level object, for example
249 C<Bio::Tools::Run::Analysis::soap> object - which one it depends on the C<-access>
250 parameter.
251  
252 =over
253  
254 =item -access
255  
256 It indicates what lower-level module to load. Default is 'soap'.
257 Other (but future) possibilities may be:
258  
259 -access => 'novella'
260 -access => 'local'
261  
262 =item -location
263  
264 A location of the service. The contents is access-specific (see
265 details in the lower-level implementation modules).
266  
267 Default is C<http://www.ebi.ac.uk/soaplab/services> ( services running
268 at European Bioinformatics Institute on top of most of EMBOSS
269 analyses, and on few others).
270  
271 =item -name
272  
273 A name of an analysis tool, or a name of its higher-level abstraction,
274 possibly including a category where the analysis belong to. There is
275 no default value (which usually means that this parameter is mandatory
276 unless your I<-location> parameter includes also the name (but it is
277 then access-dependent).
278  
279 =item -destroy_on_exit =E<gt> '0'
280  
281 Default value is '1' which means that all Bio::Tools::Run::Analysis::Job
282 objects - when being finalised - will send a request
283 to the remote site to forget the results of these jobs.
284  
285 If you change it to '0' make sure that you know the job identification
286 - otherwise you will not be able to re-established connection with it
287 (later, when you use your program again). This can be done by calling
288 method C<id> on the job object (such object is returned by any of
289 these methods: C<create_job>, C<run>, C<wait_for>).
290  
291 =item -httpproxy
292  
293 In addition to the I<location> parameter, you may need to specify also
294 a location/URL of an HTTP proxy server (if your site requires
295 one). The expected format is C<http://server:port>. There is no
296 default value. It is also an access-specific parameter which may not
297 be used by all access methods.
298  
299 =item -timeout
300  
301 For long(er) running jobs the HTTP connection may be time-outed. In
302 order to avoid it (or, vice-versa, to call timeout sooner) you may
303 specify C<timeout> with the number of seconds the connection will be
304 kept alive. Zero means to keep it alive forever. The default value is
305 two minutes.
306  
307 =back
308  
309 =cut
310  
311 0 ▶sub new {
Subroutine new: not called CC=8 SCAR=42.8
Pod documented
312 0 my ($caller,@args) = @_;
313 0 ▶ my $class = ref($caller) || $caller;
Condition0%0/3
ref $caller || $caller
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $caller || $caller
ref $caller $caller
Truth table0%0/3
A || B
A= ref $callerB= $caller
ABresult
1X1
011
000
314
315 0 ▶ if ($class eq 'Bio::Tools::Run::Analysis') {
Branch: 1 branch
BranchTrueFalseTotal
if ($class eq 'Bio::Tools::Run::Analysis') { } 0 0 0
316  
317 # this is called only the first time when somebody calls: 'new
318 # Bio::Tools::Run::Analysis (...)', and it actually loads a 'real-work-doing'
319 # module and call this new() method again (unless the loaded
320 # module has its own new() method)
321  
322 0 my %param = @args;
323 0 @param { map { lc $_ } keys %param } = values %param; # lowercase keys
324 my $access =
325 0 ▶ $param {'-access'} || # use -access parameter
Condition0%0/5
$param{'-access'} || &Bio::Tools::Run::Analysis::Utils::_guess_access(\%param) || 'soap'
l!l
00
$param{"-access"} or &Bio::Tools::Run::Analysis::Utils::_guess_access(\%param)
l!l&&r!l&&!r
000
MC/DC0%0/2
$param{'-access'} || &Bio::Tools::Run::Analysis::Utils::_guess_access(\%param) || 'soap'
$param{"-access"} &Bio::Tools::Run::Analysis::Utils::_guess_access(\%param)
Truth table0%0/3
A or B
A= $param{"-access"}B= &Bio::Tools::Run::Analysis::Utils::_guess_access(\%param)
ABresult
1X1
011
000
326 &Bio::Tools::Run::Analysis::Utils::_guess_access ( \%param ) || # or guess from other parameters
327 'soap'; # or use a default access method
328 0 $access = "\L$access"; # normalize capitalization to lower case
329  
330 # remember the access method (putting it into @args means that the
331 # object - when created - will remember it)
332 0 ▶ push (@args, (-access => $access)) unless $param {'-access'};
Branch: 1 branch
BranchTrueFalseTotal
unless $param{"-access"} 0 0 0
333  
334 # load module with the real implementation - as defined in $access
335 0 ▶ return undef unless (&Bio::Tools::Run::Analysis::Utils::_load_access_module ($access));
Branch: 1 branch
BranchTrueFalseTotal
unless &Bio::Tools::Run::Analysis::Utils::_load_access_module($access) 0 0 0
336  
337 # this calls this same method new() - but now its object part
338 # (see the upper branche above) is called
339 0 return "Bio::Tools::Run::Analysis::$access"->new (@args);
340  
341 } else {
342  
343 # if $caller is an object, or if it is an underlying
344 # 'real-work-doing' class (e.g. Bio::Tools::Run::Analysis::soap) then
345 # we want to call SUPER to create and bless a new object
346  
347 0 my ($self) = $class->SUPER::new (@args);
348  
349 # now the $self is an empty object - we will populate it from
350 # the $caller - if $caller is an object (so we do cloning here)
351  
352 0 ▶ if (ref ($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $caller) 0 0 0
353 0 %{ $self } = %{ $caller };
354 }
355  
356 # and finally add values from '@args' into the newly created
357 # object (the values will overwrite the values copied above);
358 # this is done by calling '_initialize' of the 'real-work-doing'
359 # class (if there is no one there, there is always an empty one
360 # in Bio::Root::Root)
361  
362 0 $self->_initialize (@args);
363 0 return $self;
364 }
365  
366 }
367  
368 #
369 # Create a hash with named inputs, all extracted
370 # from the given data.
371 #
372 0 ▶sub _prepare_inputs {
Subroutine _prepare_inputs: not called CC=12 SCAR=50.5
373 0 my $self = shift;
374 0 my %inputs = (); # collect here input data
375  
376 0 foreach my $input (@_) {
377  
378 0 ▶ next unless defined $input;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 0 0 0
379  
380 # an element can be an array reference
381 # (with scalar elements: 'name = [[@]value]')
382 0 ▶ if (ref $input eq 'ARRAY') {
Branch: 3 branches
BranchTrueFalseTotal
if (ref $input eq 'ARRAY') { } 0 0 0
elsif (ref $input eq 'HASH') { } 0 0 0
elsif (ref \$input eq 'SCALAR') { } 0 0 0
383 0 foreach my $elem (@$input) {
384 0 ▶ unless (ref $elem) { # taking only scalars
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $elem) 0 0 0
385 0 my ($name, $value) = split (/\s*=\s*/, $elem, 2);
386 0 ▶ next unless $name; # am I paranoid ?
Branch: 1 branch
BranchTrueFalseTotal
unless $name 0 0 0
387 0 ▶ $value = 1 unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 0 0 0
388 0 $inputs{$name} = $value;
389 0 next;
390 }
391 }
392 }
393  
394 # ...or an element can be a hash
395 # (name => [@]value)
396 elsif (ref $input eq 'HASH') {
397 0 foreach my $name (keys %$input) {
398 0 my $value = $$input{$name};
399 0 $inputs{$name} = $value;
400 }
401 }
402  
403 # ...or an element can be a scalar (which means that it
404 # represents a name of a boolean parameter (an option)
405 elsif (ref \$input eq 'SCALAR') {
406 0 $input =~ s/^@/\\@/; # this cannot be a filename
407 0 $inputs{$input} = 1;
408 }
409  
410 # everything else is ignored
411 else {
412 0 warn "Unrecognized input data type: $input\n";
413 }
414 }
415  
416 # extracted inputs may be actually filenames and we want the
417 # contents of the files instead
418 # TBD: to support also filehandlers here?
419 0 foreach my $name (keys %inputs) {
420 0 $inputs{$name} = $self->_read_value ($inputs{$name});
421 }
422 0 return \%inputs;
423 }
424  
425 # --- if a $value is a filename, read it and return its contents
426 # otherwise return the $value itself; if $value start with
427 # an escaped '@', change it to a normal '@'
428 0 ▶sub _read_value {
Subroutine _read_value: not called CC=6 SCAR=37.4
429 0 my ($self, $value) = @_;
430 0 ▶ return unless defined $value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 0 0 0
431 0 ▶ if ($value =~ s/^\@//) {
Branch: 2 branches
BranchTrueFalseTotal
if ($value =~ s/^\@//) { } 0 0 0
elsif ($value =~ s/^\\\@/\@/) { } 0 0 0
432 0 my ($buf);
433 0 ▶ open (DATA, $value) || $self->throw ("Cannot read from '$value' ($!)");
Branch: 1 branch
BranchTrueFalseTotal
open DATA, $value or $self->throw("Cannot read from '${value}' ($!)") 0 0 0
434 0 binmode (DATA);
435 0 undef $value;
436 0 ▶ while (read (DATA, $buf, 8 * 2**10)) {
Branch: 1 branch
BranchTrueFalseTotal
if (read DATA, $buf, 8192) 0 0 0
437 0 $value .= $buf;
438 }
439 0 close DATA;
440 } elsif ($value =~ s/^\\\@/@/) {
441 }
442 0 $value;
443 }
444  
445 # --- save $value of result $name into file $filename + $seq;
446 # use some default filename if $filename not given
447  
448 #$part = $self->_save_result (-value => $part,
449 # -name => $name,
450 # -filename => $filename,
451 # -template => $template,
452 # -seq => $seq++);
453  
454 0 ▶sub _save_result {
Subroutine _save_result: not called CC=12 SCAR=50.5
455 0 my ($self, %params) = @_;
456 0 ▶ my $name = $params{'-name'} || 'result';
Condition0%0/2
$params{'-name'} || 'result'
l!l
00
MC/DC0%0/1
$params{'-name'} || 'result'
$params{'-name'}
Truth table0%0/2
A
A= $params{'-name'}
Aresult
11
00
457  
458 # invent filename (if not given) from the given or default template
459 0 my $filename = $params{'-filename'};
460 0 ▶ unless ($filename) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($filename) 0 0 0
461 0 $filename = $params{'-template'};
462 0 ▶ $filename = "\$ANALYSIS_*_$name" unless $filename;
Branch: 1 branch
BranchTrueFalseTotal
unless $filename 0 0 0
463  
464 # replace $ANALYSIS and $RESULT in the filename
465 0 ▶ if ($filename =~ /\$\{?ANALYSIS\}?/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($filename =~ /\$\{?ANALYSIS\}?/) 0 0 0
466 # (better to ask if we need it because getting
467 # the analysis name may require going to server)
468 0 my $analysis = $self->analysis_name;
469 0 $analysis =~ s/[:\/]/_/g; # would be troubles in filename
470 0 $filename =~ s/\$\{?ANALYSIS\}?/$analysis/ig;
471 }
472 0 $filename =~ s/\$\{?RESULT\}?/$name/ig;
473 }
474  
475 # include the sequential number before file extension (if any)
476 0 my $seq = $params{'-seq'};
477 0 ▶ if ($seq) {
Branch: 1 branch
BranchTrueFalseTotal
if ($seq) 0 0 0
478 0 my $pos = rindex ($filename, '.');
479 0 ▶ if ($pos > -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pos > -1) { } 0 0 0
480 0 substr ($filename, $pos, 0) = ".$seq"; # insert $seq
481 } else {
482 0 $filename .= ".$seq"; # add $seq
483 }
484 }
485  
486 # replace '*' in filename with a unique number
487 0 ▶ while ($filename =~ /\*/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($filename =~ /\*/) 0 0 0
488 0 my $unique_name;
489 0 my $number = 1;
490 0 while (1) {
491 0 ($unique_name = $filename) =~ s/\*/$number/;
492 0 ▶ last unless -e $unique_name;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $unique_name 0 0 0
493 0 $number++;
494 }
495 0 $filename = $unique_name;
496 }
497  
498 # and finally write the file
499 0 ▶ open (DATA, ">$filename") ||
Branch: 1 branch
BranchTrueFalseTotal
open DATA, ">$filename" or $self->throw("Error by saving result '${name}' into '${filename}' ($!)") 0 0 0
500 $self->throw ("Error by saving result '$name' into '$filename' ($!)");
501 0 binmode (DATA);
502 0 ▶ print (DATA $params{'-value'}) ||
Branch: 1 branch
BranchTrueFalseTotal
print DATA $params{"-value"} or $self->throw("Error by writing result '${name}' into '${filename}' ($!)") 0 0 0
503 $self->throw ("Error by writing result '$name' into '$filename' ($!)");
504 0 ▶ close DATA ||
Branch: 1 branch
BranchTrueFalseTotal
close DATA or $self->throw("Error by closing result '${name}' in '${filename}' ($!)") 0 0 0
505 $self->throw ("Error by closing result '$name' in '$filename' ($!)");
506  
507 0 return $filename;
508 }
509  
510  
511 =head2 VERSION and Revision
512  
513 Usage : print $Bio::Tools::Run::Analysis::VERSION;
514 print $Bio::Tools::Run::Analysis::Revision;
515  
516 =cut
517  
518 # -----------------------------------------------------------------------------
519 # Bio::Tools::Run::Analysis::Job
520 # A module representing an invocation (execution, job) of an analysis.
521 # -----------------------------------------------------------------------------
522  
523 package Bio::Tools::Run::Analysis::Job;
524 1 $Bio::Tools::Run::Analysis::Job::VERSION = '1.7.8';
525  
526 =head1 Module Bio::Tools::Run::Analysis::Job
527  
528 It represents a job, a single execution of an analysis tool. Usually
529 you do not instantiate these objects - they are returned by methods
530 C<create_job>, C<run>, and C<wait_for> of C<Bio::Tools::Run::Analysis> object.
531  
532 However, if you wish to re-create a job you need to know its ID
533 (method C<id> gives it to you). The ID can be passed directly to the
534 C<new> method, or again you may use C<create_job> of a
535 C<Bio::Tools::Run::Analysis> object with the ID as parameter. See SYNOPSIS above
536 for an example.
537  
538 Remember that all public methods of this module are described in
539 details in interface module C<Bio::AnalysisI> and in the tutorial in
540 the C<analysis.pl> script.
541  
542 =cut
543  
544  
545 1 ▶use vars qw(@ISA);
Subroutine BEGIN: called CC=1 SCAR=0.0
546 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
547  
548 1 ▶use Bio::Root::Root;
Subroutine BEGIN: called CC=1 SCAR=0.0
549 1 @ISA = qw(Bio::Root::Root Bio::AnalysisI::JobI);
550  
551 # -----------------------------------------------------------------------------
552  
553 =head2 new
554  
555 Usage : my $job = Bio::Tools::Run::Analysis::Job->new
556 (-access => 'soap',
557 -name => 'edit.seqret',
558 -id => 'xxxyyy111222333'
559 );
560 Returns : a re-created object representing a job
561 Args : The same arguments as for Bio::Tools::Run::Analysis object:
562 -access
563 -location
564 -name
565 -httpproxy
566 -timeout
567 (and perhaps others)
568 Additionally and specifically for this object:
569 -id
570 -analysis
571  
572 =over
573  
574 =item -id
575  
576 A job ID created some previous time and now used to re-create the same
577 job (in order to re-gain access to this job results, for example).
578  
579 =item -analysis
580  
581 A C<Bio::Tools::Run::Analysis> object whose properties (such as C<-access> and
582 C<-location> are used to re-create this job object.
583  
584 =back
585  
586 =cut
587  
588 0 ▶sub new {
Subroutine new: not called CC=6 SCAR=37.4
589 0 my ($caller, @args) = @_;
590 0 ▶ my $class = ref($caller) || $caller;
Condition0%0/3
ref $caller || $caller
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $caller || $caller
ref $caller $caller
Truth table0%0/3
A || B
A= ref $callerB= $caller
ABresult
1X1
011
000
591
592 0 ▶ if ($class eq 'Bio::Tools::Run::Analysis::Job') {
Branch: 1 branch
BranchTrueFalseTotal
if ($class eq 'Bio::Tools::Run::Analysis::Job') { } 0 0 0
593  
594 # this is called only the first time when somebody calls:
595 #'Bio::Tools::Run::Analysis::Job->new(...)'
596  
597 0 my %param = @args;
598 0 @param { map { lc $_ } keys %param } = values %param; # lowercase keys
599 0 ▶ if ($param {'-analysis'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($param{'-analysis'}) { } 0 0 0
600  
601 # usually a new Job object is created from an existing
602 # Analysis object - which means that the Analysis already
603 # loaded a 'real-work-doing' Job object, so we need just
604 # to create a Job object (by calling its new() method,
605 # which calls actually this new() method again - but its
606 # 'object' part - see below
607  
608 0 my $analysis = $param {'-analysis'};
609 0 ▶ return undef unless $analysis->{'_access'}; # TBD: error message here?
Branch: 1 branch
BranchTrueFalseTotal
unless $analysis->{"_access"} 0 0 0
610 0 my $access = $analysis->{'_access'};
611 0 return "Bio::Tools::Run::Analysis::Job::$access"->new (@args);
612  
613 } else {
614  
615 # if a new Job object is created directly (by a user, not
616 # by a parent Analysis object) we need to create the
617 # Analysis object first (because it is the Analysis object
618 # who knows how to contact the underlying analysis tool),
619 # and only then let the Analysis create this Job object
620 # (which may be an empty Job - if there is no 'id' in @args)
621  
622 0 return new Bio::Tools::Run::Analysis (@args)->create_job ($param {'-id'});
623 }
624  
625 } else {
626  
627 # if $caller is an object, or if it is an underlying
628 # 'real-work-doing' class (e.g. Bio::Tools::Run::Analysis::Job::soap) then
629 # we want to call SUPER to create and bless a new object
630  
631 0 my ($self) = $class->SUPER::new (@args);
632  
633 # now the $self is an empty object - we will populate it from
634 # the $caller - if $caller is an object (so we do cloning here)
635  
636 0 ▶ if (ref ($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $caller) 0 0 0
637 0 %{ $self } = %{ $caller };
638 }
639  
640 # and finally add values from '@args' into the newly created
641 # object (the values will overwrite the values copied above);
642 # this is done by calling '_initialize' of the 'real-work-doing'
643 # class (if there is no one there, there is always an empty one
644 # in Bio::Root::Root)
645  
646 0 $self->_initialize (@args);
647 0 return $self;
648 }
649  
650 }
651  
652 0 ▶sub id { shift->{'_id'}; }
Subroutine id: not called CC=1 SCAR=6.9
653  
654 # ---------------------------------------------------------------------
655 #
656 # A Utility module...
657 #
658 # ---------------------------------------------------------------------
659  
660 package Bio::Tools::Run::Analysis::Utils;
661 1 $Bio::Tools::Run::Analysis::Utils::VERSION = '1.7.8';
662  
663 =head1 Module Bio::Tools::Run::Analysis::Utils
664  
665 It contains several general utilities. These are C<functions>, not
666 methods. Therefore call them like, for example:
667  
668 &Bio::Tools::Run::Analysis::Utils::format_time (...);
669  
670 =cut
671  
672 # -----------------------------------------------------------------------------
673  
674 =head2 format_time
675  
676 Usage : Bio::Tools::Run::Analysis::Utils::format_time ($time);
677 Returns : Slightly formatted $time
678 Args : $time is number of seconds from the beginning of Epoch
679  
680 It returns what C<localtime> returns which means that return value is
681 different in the array and scalar context (see localtime). If C<$time>
682 is ``-1'' it returns 'n/a' (in the scalar context) or an empty array
683 (in the array context). If C<$time> is too small to represent the
684 distance from the beginning of the Epoch, it returns it unchanged (the
685 same in any contex) - this is reasonable for C<$time> representing an
686 elapsed time.
687  
688 The function is used to format times coming back from various job time
689 methods.
690  
691 =cut
692  
693 0 ▶sub format_time {
Subroutine format_time: not called CC=4 SCAR=30.0
694 0 my $time = shift;
695 0 ▶ return wantarray ? () : 'n/a' if "$time" eq '-1';
Branch: 2 branches
BranchTrueFalseTotal
if "$time" eq -1 0 0 0
wantarray ? : 0 0 0
696 0 ▶ return $time if $time < 1000000000;
Branch: 1 branch
BranchTrueFalseTotal
if $time < 1000000000 0 0 0
697 0 return localtime $time;
698 }
699  
700 # -----------------------------------------------------------------------------
701  
702 # It processes given result names which may be of various different
703 # types and returns a hash reference with result names as keys and
704 # values being result destinations (such as file names, or templates
705 # how to create filenames.
706 #
707 # Or, it returns a scalar ('@[template]' or '?[template]') if there
708 # were no real result names but only a global rule how to create
709 # result destinantions for all results.
710 #
711 # Or, it returns 'undef' if there were no result names at all.
712  
713 0 ▶sub normalize_names {
Subroutine normalize_names: not called CC=7 SCAR=40.3
714 0 ▶ return undef unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
715 0 my %names = ();
716 0 foreach (@_) {
717 0 ▶ if (ref $_ eq 'HASH') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $_ eq 'HASH') { } 0 0 0
elsif (not ref $_) { } 0 0 0
718 0 %names = (%names, %$_);
719 } elsif (not ref $_) {
720 0 my ($name, $dest) = split (/\s*=\s*/, $_, 2);
721 0 ▶ return $name if $name =~ /^@/; # special: it nullifies other rules
Branch: 1 branch
BranchTrueFalseTotal
if $name =~ /^@/ 0 0 0
722 0 ▶ return $name if $name =~ /^\?/; # ditto
Branch: 1 branch
BranchTrueFalseTotal
if $name =~ /^\?/ 0 0 0
723 0 $names{$name} = $dest; # $dest may be undef
724 }
725 }
726 0 \%names;
727 }
728  
729 # -----------------------------------------------------------------------------
730  
731 =head2 _load_access_module
732  
733 Usage : $class->_load_access_module ($access)
734 Returns : 1 on success, undef on failure
735 Args : 'access' should contain the last part of the
736 name of a module who does the real implementation
737  
738 It does (in the run-time) a similar thing as
739  
740 require Bio::Tools::Run::Analysis::$access
741  
742 It prints an error on STDERR if it fails to find and load the module
743 (for example, because of the compilation errors in the module).
744  
745 =cut
746  
747 0 ▶sub _load_access_module {
Subroutine _load_access_module: not called CC=2 SCAR=17.9
748 0 my ($access) = @_;
749  
750 0 my $load = "Bio/Tools/Run/Analysis/$access.pm";
751 0 eval {
752 0 require $load;
753 };
754  
755 0 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
756 0 Bio::Root::Root->throw (<<END);
757 $load: $access cannot be found or loaded
758 Exception $@
759 For more information about the Analysis system please see the Bio::Tools::Run::Analysis docs.
760 END
761 ;
762 0 return;
763 }
764 0 return 1;
765 }
766  
767 # -----------------------------------------------------------------------------
768  
769 =head2 _guess_access
770  
771 Usage : Bio::Tools::Run::Analysis::Utils::guess_access ($rh_params)
772 Returns : string with a guessed access protocol (e.g. 'soap'),
773 or undef if the guessing failed
774 Args : 'rh_params' is a hash reference containing parameters given
775 to the 'new' method.
776  
777 It makes an expert guess what kind of access/transport protocol should
778 be used to access the underlying analysis. The guess is based on the
779 parameters in I<rh_params>. Remember that this method is called only
780 if there was no I<-access> parameter which could tell directly what
781 access method to use.
782  
783 =cut
784  
785 0 ▶sub _guess_access {
Subroutine _guess_access: not called CC=1 SCAR=6.9
786 0 my ($rh_params) = @_;
787 0 return undef;
788 }
789  
790  
791  
792 1 1;
793 __END__
« Bio/Seq/LargeLocatableSeq.pm ↑ Summary Bio/Tools/Lucy.pm »