BP_PANALYSIS(1p)

📦

version 1.7.3 · 3 versions

1.7.3 · debian bookworm, ubuntu noble (latest)
1.7.3 · ubuntu jammy
1.7.3 · debian trixie

🎀 BP_PANALYSIS(1p) — `panalysis.PLS` 🎀

okay bestie, real talk: this page lives in the User Contributed Perl Documentation corner of the manual world, and it's about panalysis.PLS, an example/tutorial script. but don't let "example" fool you, she's got range. 💅

✨ NAME ✨

panalysis.PLS — an example/tutorial script how to access analysis tools 🧚

✨ SYNOPSIS ✨

# run an analysis with your sequence in a local file
  ./panalysis.PLS -n 'edit.seqret'-w -r \
                  sequence_direct_data=@/home/testdata/my.seq

See more examples in the text below.

and yes there are more examples further down, keep scrolling bestie 👑

✨ DESCRIPTION ✨

so this is a client showing you how to use the Bio::Tools::Run::Analysis module — the module that runs and controls local or remote analysis tools. she also calls methods from the Bio::Tools::Run::AnalysisFactory module, which is the one handing out lists of available analyses. two modules, one icon.

mainly this client exists as an example of how to use analysis modules, and also to test them. but lowkey? because it has a lot of options so it can cover as many methods as possible, it also works as a fully functional command-line client for accessing various analysis tools. it's giving tutorial, it's giving production tool, it's giving both. 🦋

🌸 Defining location and access method 🌸

panalysis.PLS does not care how you get to the remote analyses (aka the analyses running on a different machines). the method used to talk to them is set by the -A option, and the default value is soap. the other possible values are corba and local — not yet supported, but coming soon ✨.

each access method may give a different meaning to the -l parameter, which defines a location of services giving access to the analysis tools. for example, the soap access expects a URL of a Web Service in the -l option, while the corba access may find here a stringified Interoperable Object Reference (IOR). same flag, different lore depending on the method 💫

a default location for the soap access is http://www.ebi.ac.uk/soaplab/services, and that represents services running at European Bioinformatics Institute on top of over hundred EMBOSS analyses (and on top of few others). over a hundred!! 😭

🌸 Available analyses 🌸

panalysis.PLS can show you a list of available analyses (from the given location, using the given access method). here's the lineup:

the -L option shows all analyses
the -c option lists all available categories (a category is a group of analyses with similar functionality or processing similar type of data)
the -C option shows only analyses available within the given category

ngl, all of these functions are provided by the module Bio::Tools::Run::AnalysisFactory (or rather, by one of its access-dependent sub-classes). that module also has a factory method called create_analysis which is not used by this script. noted. 📝

🌸 Service 🌸

a "service" is a higher level of abstraction of an analysis tool. it understands a well defined interface (module Bio::AnalysisI), and that is the fact that lets this script be independent on the access protocol to various services. decoupling, we love to see it 💚

the service name must be given by the -n option. you can only skip this option if you invoked just the "factory" methods (the ones described above). periodt.

each service (representing an analysis tool, a program, or an application) has its description, available via these options:

-a — analysis name, type, etc.
-i, -I — specification of analysis input data, most important are their names
-o, -O — result names and their types
-d — gives the most detailed description in the XML format

the service description is nice, but the most important thing is to use the service for invoking an underlying analysis tool. for each invocation, the service creates a "job" and feeds it with input data. there are three stages:

(a) create a job
(b) run the job
(c) wait for its completion

and correspondingly there are three options:

-b — just creates (builds) a job
-x — creates a job and executes it
-w — creates a job, runs it, and blocks the client until the job is finished

always only one of these options is used (so it does not make sense to use more of them — panalysis.PLS priorities them in the order -x, -w, and -b). pick a lane bestie 🛣️

all of these options take input data from the command-line (see the next section about it) and all of them return (internally) an object representing a job. there are many methods (options) dealing with the job objects (see the section after next about them). 🔥

last note in this section: the -b option is actually optional — a job is created even without this option when there are some input data found on the command-line. you do have to use it, however, if you do not pass any data to an analysis tool (an example would be the famous Classic::HelloWorld service). 👑

🌸 Input data 🌸

input data are given as name/value pairs, put on the command-line with an equal sign between name and value. if the value part starts with an un-escaped character @, it is used as a local file name and panalysis.PLS reads the file and uses its contents instead. examples:

panalysis.PLS -n edit.seqret -w -r
              sequence_direct_data='tatatctcccc' osformat=embl

panalysis.PLS ...
            sequence_direct_data=@/my/data/my.seq

the names of input data come from the "input specification" that can be shown by the -i or -I options. the input specification (when using option -I) shows also — for some inputs — a list of allowed values. the spec, however, does not tell you what input data are mutually exclusive, or what other constrains apply. if there is a conflict, an error message is produced later (before the job starts). so you find out at the worst possible moment, as is tradition 😭

input data are used when any of the options -b, -x, or -w is present, but option -j is not present (see the next section about this job option).

🌸 Job 🌸

each service (defined by a name given in the -n option) can be executed one or more times, with the same, but usually with different input data. each execution creates a job object. actually, the job is created even before execution (remember that option -b builds a job but does not execute it yet). build first, run later ✨

any job, executed or not, is persistent and can be used again later from another invocation of the panalysis.PLS script. unless you explicitly destroy the job using option -z. that's the delete button, be careful 💀

a job created by options -b, -x and -w (and by input data) can be accessed in the same panalysis.PLS invocation using various job-related options — the most important are -r and -R for retrieving results from the finished job.

however, you can also re-create a job created by a previous invocation. assuming that you know the job ID (the panalysis.PLS prints it always on the standard error when a new job is created), use option -j to re-create the job.

example:

./panalysis.PLS -n 'edit.seqret'
              sequence_direct_data=@/home/testdata/my.seq

it prints:

JOB ID: edit.seqret/bb494b:ef55e47c99:-8000

next invocation (asking to run the job, to wait for its completion and to show job status) can be:

./panalysis.PLS -n 'edit.seqret'
              -j edit.seqret/bb494b:ef55e47c99:-800
              -w -s

and again later another invocation can ask for results:

./panalysis.PLS -n 'edit.seqret'
              -j edit.seqret/bb494b:ef55e47c99:-800
              -r

here is a list of all job options (except for results, they are in the next section):

💜 Job execution and termination 💜

there are the same options -x and -w for executing a job and for executing it and waiting for its completion, as they were described above. but now, the options act on a job given by the -j option, and now they do not use any input data from the command-line (the input data had to be used when the job was created).

additionally, there is a -k option to kill a running job. rip bozo 💀

💜 Job characteristics 💜

other options tell about:

-s — the job status
-t and -T — the job execution times
-e — the last available event what happened with the job

heads up: the event notification is not yet fully implemented, so this option will change in the future to reflect more notification capabilities. don't get too attached to -e 🙈

🌸 Results 🌸

of course, the most important on the analysis tools are their results. the results are named (in the similar way as the input data) and they can be retrieved all in one go using option -r (so you do not need to know their names actually), or by specifying (all or some) result names using the -R option. 👑

if a result does not exist (either not yet, or the name is wrong) an undef value is returned (no error message produced). silent. mysterious. a little unhinged. 😶

some results are better to save directly into files instead to show them in the terminal window (this applies to the binary results, mostly containing images). panalysis.PLS helps to deal with binary results by saving them automatically to local files (actually it is the module Bio::Tools::Run::Analysis and its submodules who do help with the binary data). 🖼️✨

so why not to use a traditional shell re-direction to a file? there are two reasons:

first, a job can produce more than one result, so they would be mixed together.
but mainly, because each result can consist of several parts whose number is not known in advance and which cannot be mixed together in one file.

again, this is typical for the binary data returning images — an invocation can produce many images. so many images 🌸

the -r option retrieves all available results and treat them as described by the ? format below.

the -R option has a comma-separated list of result names, each of the names can be either a simple name (as specified by the "result specification" obtainable using the -o or -O options), or a equal-sign-separated name/format construct suggesting what to do with the result. the possibilities are:

result-name — it prints given result on the standard output.
result-name=filename — it saves the given result into given file.
result-name=@ — it saves the given result into a file whose name is automatically invented, and it guarantees that the same name will not be used in the next invocation.
result=name=@template — it saves the given result into a file whose name is given by the template. the template can contain several strings which are substituted before using it as the filename:
- any * — will be replaced by a unique number
- $ANALYSIS or ${ANALYSIS} — will be replaced by the current analysis name
- $RESULT or ${RESULT} — will be replaced by the current result name
- how to tell what to do with results? each result name

additionally, a template can be given as an environment variable RESULT_FILENAME_TEMPLATE. such variable is used for any result having in its format a simple ? or @ character. 🫶

result-name=? — bestie, this one's smart. It peeks at the result you handed it and decides first whether that result is binary or not. If it's binary 💾, it gets saved into local files whose names are automatically invented (the audacity, the convenience). If it's not binary, it just goes straight to standard output. Simple as.
result-name=?template — same energy as above, but this time the filenames for the binary files get deduced from the template you gave it (using the exact same rules as described above, no new rules invented, promise 🫶).

Examples, because seeing it hits different:

-r
-R report
-R report,outseq
-R Graphics_in_PNG=@
-R Graphics_in_PNG=@$ANALYSIS-*-$RESULT

Heads up 👀 — the result formatting is gonna get enriched in the future by using existing data type parsers in bioperl. So it's giving ✨coming soon✨, not giving "already works like that." Don't come for me.

💌 FEEDBACK 💌

📬 Mailing Lists 📬

Okay so, user feedback is literally an integral part of the evolution of this module and other Bioperl modules — like, it's not optional, it's the whole vibe. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is so much appreciated, no cap. 🥹

bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🐛 Reporting Bugs 🐛

Found a bug? Report it to the Bioperl bug tracking system so we can keep track of the bugs and their resolution — because a bug without a paper trail is just chaos, and we don't do chaos here 💅. Bug reports can be submitted via the web:

http://redmine.open-bio.org/projects/bioperl/

👑 AUTHOR 👑

Martin Senger (martin.senger@gmail.com) — the icon, the moment, the whole reason this page exists fr fr.

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🍓

⚠️ DISCLAIMER ⚠️

This software is provided "as is" without warranty of any kind. That's it, that's the disclaimer — you get what you get, bestie, and there's no warranty coming to save you. 😭

💀 BUGS AND LIMITATIONS 💀

None known at the time of writing this. Zero. Nada. Not a single one. (At the time of writing, okay, let's not get carried away 🌸)

And that's the whole page, babe 💖 This one's from perl v5.36.0, dated 2023-01-22 — BP_PANALYSIS(1p), out. Go read some docs, you main character 🧚🌈⭐

📦 where this page comes from

debian bookworm: bioperl-run 1.7.3-9 · Perl
ubuntu noble: bioperl-run 1.7.3-9 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms