Bio::T...andExts(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ NAME ✨

okay bestie, welcome to Bio::T...andExts(3pm) — the manual page for Bio::Tools::Run::WrapperBase::CommandExts, aka Extensions to WrapperBase for handling programs with commands *ALPHA*. yes, *ALPHA* is literally right there, so you know this is experimental, no cap.

🦋 SYNOPSIS 🦋

Devs, see "DEVELOPER INTERFACE". Users, see "USER INTERFACE".

💖 DESCRIPTION 💖

This is a developer-focused experimental module. The main idea is to extend Bio::Tools::Run::WrapperBase to make it relatively easy to create run wrappers around suites of related programs, like samtools or blast+.

Some definitions:

  • program — The program is the command-line frontend application. samtools, for example, is run from the command line as follows:
$ samtools view -bS in.bam > out.sam
$ samtools faidx
  • command — The command is the specific component of a suite run by executing the program. In the example above, view and faidx are commands.
  • command prefix — The command prefix is an abbreviation of the command name used internally by CommandExts method, and sometimes by the user of the factory for specifying command line parameters to subcommands of composite commands.
  • composite command — A composite command is a pipeline or script representing a series of separate executions of different commands. Composite commands can be specified by configuring CommandExts appropriately; the composite command can be run by the user from a factory in the same way as ordinary commands.
  • options, parameters, switches and filespecs — An option is any command-line option; i.e., a specification set off by a command-line by a specifier (like -v or --outfile). Parameters are command-line options that accept a value (-title mydb); switches are boolean flags (--no-filter). Filespecs are barewords at the end of the command line that usually indicate input or output files. In this module, this includes files that capture STDIN, STDOUT, or STDERR via redirection.
  • pseudo-program — A "pseudo-program" is a way to refer to a collection of related applications that are run independently from the command line, rather than via a frontend program. The blast+ suite of programs is an example: blastn, makeblastdb, etc. CommandExts can be configured to create a single factory for a suite of related, independent programs that treats each independent program as a "pseudo-program" command.

This module essentially adds the non-assembler-specific wrapper machinery of fangly's Bio::Tools::Run::AssemblerBase to the Bio::Tools::Run::WrapperBase namespace, adding the general command-handling capability of Bio::Tools::Run::BWA. It creates run factories that are automatically Bio::ParameterBaseI compliant, meaning that available_parameters(), set_parameters(), get_parameters, reset_parameters(), and parameters_changed() are available.

👑 DEVELOPER INTERFACE 👑

CommandExts is currently set up to read particular package globals which define the program, the commands available, command-line options for those commands, and human-readable aliases for those options.

The easiest way to use CommandExts is probably to create two modules:

 Bio::Tools::Run::YourRunPkg
 Bio::Tools::Run::YourRunPkg::Config

The package globals should be defined in the Config module, and the run package itself should begin with the following mantra:

 use YourRunPkg::Config;
 use Bio::Tools::Run::WrapperBase;
 use Bio::Tools::Run::WrapperBase::CommandExts;
 sub new {
     my $class = shift;
     my @args = @_;
     my $self = $class->SUPER::new(@args);
     ...
     return $self;
 }

The following globals can/should be defined in the Config module:

  $program_name
  $program_dir
  $use_dash
  $join
  @program_commands
  %command_prefixes
  @program_params
  @program_switches
  %param_translation
  %composite_commands
  %command_files

See "Config Globals" for detailed descriptions.

The work of creating a run wrapper with CommandExts lies mainly in setting up the globals. The key methods for the developer interface are:

  • program_dir($path_to_programs) — Set this to point the factory to the executables.
  • _run(@file_args) — Runs an instantiated factory with the given file args. Use in the run() method override.
  • _create_factory_set() — Returns a hash of instantiated factories for each true command from a composite command factory. The hash keys are the true command names, so you could do
 $cmds = $composite_fac->_create_factory_set;
 for (@true_commands) {
    $cmds->{$_}->_run(@file_args);
 }
  • executables($cmd,[$fullpath]) — For pseudo-programs, this gets/sets the full path to the executable of the true program corresponding to the command $cmd.

🌈 Implementing Composite Commands 🌈

bestie, this heading is here, but the source doesn't drop any extra prose under it — so we're not inventing anything, periodt.

🧚 Implementing Pseudo-programs 🧚

To indicate that a package wraps disparate programs under a single pseudo program, use an asterisk before the program name:

 package Bio::Tools::Run::YourPkg::Config;
 ...
 our $program_name = '*blast+';

and _run will know what to do. Specify the rest of the globals as if the desired programs were commands. Use the basename of the programs for the command names.

If all the programs can be found in a single directory, just specify that directory in program_dir(). If not, use executables() to set the paths to each program explicitly:

 foreach (keys %cmdpaths) {
    $self->executables($_, $cmdpaths{$_});
 }

🍓 Config Globals 🍓

Here is an example config file. Further details in prose are below.

 package Dummy::Config;
 use strict;
 use warnings;
 no warnings qw(qw);
 use Exporter;
 our (@ISA, @EXPORT, @EXPORT_OK);
 push @ISA, 'Exporter';
 @EXPORT = qw(
              $program_name
              $program_dir
              $use_dash
              $join
              @program_commands
              %command_prefixes
              @program_params
              @program_switches
              %param_translation
              %command_files
              %composite_commands
             );

 our $program_name = '*flurb';
 our $program_dir = 'C:\cygwin\usr\local\bin';
 our $use_dash = 'mixed';
 our $join = ' ';

 our @program_commands = qw(
  rpsblast
  find
  goob
  blorb
  multiglob
   );

 our %command_prefixes = (
     blastp => 'blp',
     tblastn => 'tbn',
     goob => 'g',
     blorb => 'b',
     multiglob => 'm'
     );

 our @program_params = qw(
     command
     g|narf
     g|schlurb
     b|scroob
     b|frelb
     m|trud
 );

 our @program_switches = qw(
     g|freen
     b|klep
 );

 our %param_translation = (
     'g|narf'     => 'n',
     'g|schlurb'  => 'schlurb',
     'g|freen'    => 'f',
     'b|scroob'   => 's',
     'b|frelb'    => 'frelb'
     );

 our %command_files = (
     'goob'       => [qw( fas faq )],
     );

 our %composite_commands = (
     'multiglob' => [qw( blorb goob )]
     );
 1;

$use_dash can be one of single, double, or mixed. See Bio::Tools::Run::WrapperBase.

There is a syntax for the %command_files specification. The token matching [a-zA-Z0-9_]+ in each element of each arrayref becomes the named filespec parameter for the _run() method in the wrapper class. Additional symbols surrounding this token indicate how this argument should be handled. Some examples:

>out  : stdout is redirected into the file
        specified by (..., -out => $file,... )
<in   : stdin is accepted from the file
        specified by (..., -in => $file,... )
2>log : stderr is redirected into the file
        specified by (..., -log => $file,... )
#opt  : this filespec argument is optional
        (no throw if -opt => $option is missing)
2>#log: if -log is not specified in the arguments, the stderr()
        method will capture stderr
*lst  : this filespec can take multiple arguments,
        specify using an arrayref (..., -lst => [$file1, $file2], ...)
*#lst : an optional list

The tokens above are examples; they can be anything matching the above regexp.

💖 USER INTERFACE 💖

So you've got a wrapper built with Bio::Tools::Run::WrapperBase::CommandExts and now you wanna actually drive it? Bestie, same. Here's the whole vibe, step by step. 🦋

🌸 Getting a list of available commands, parameters, and filespecs

Wanna know what commands exist? Literally just:

@commands = Bio::Tools::Run::ThePkg->available_commands;

The wrapper usually ships with human-readable aliases for every single command-line option belonging to the wrapped program and its commands — so it's not giving cryptic-goblin energy, it's giving readable. ✨

Wanna know which parameters and switches a specific command has? Say less:

$factory = Bio::Tools::Run::ThePkg->new( -command => 'glurb' );
@params = $factory->available_parameters('params');
@switches = $factory->available_parameters('switches');
@filespec = $factory->available_parameters('filespec');
@filespec = $factory->filespec; # alias
Note the little alias moment at the end — filespec is just available_parameters('filespec') wearing a cuter outfit. 💅

🌈 Create factories

A factory is your handle on the program and the command you wanna run. Make one with new and pass it your command-line parameters:

$factory = Bio::Tools::Run::ThePkg->new( -command => 'glurb',
                                         -freen => 1,
                                         -furschlugginer => 'vreeble' );

And because typing -command => 'glurb' every single time is so much effort, there's a shorthand, and honestly? Iconic:

$factory = Bio::Tools::Run::ThePkg->new_glurb(
                                             -freen => 1,
                                             -furschlugginer => 'vreeble' );

🎀 Running programs

Time to actually run the thing. Use the run method and hand it your filespecs as arguments:

$factory = Bio::Tools::Run::ThePkg->new_assemble( -min_qual => 63 );
$factory->run( -faq1 => 'read1.fq', -faq2 => 'read2.fq',
               -ref => 'refseq.fas', -out => 'new.sam' );
# do another
$factory->run( -faq1 => 'read-old1.fq', -faq2 => 'read-old2.fq',
               -ref => 'refseq.fas', -out => 'old.sam' );

Everything the program yells onto STDOUT and STDERR gets dumped into their own respective attributes, so you can go peek whenever:

$stdout = $factory->stdout;
$stderr = $factory->stderr;

...unless STDOUT and/or STDERR are part of the named files in the filespec. (Then they're off doing their own thing, as they should. 🙈)

⭐ Setting/getting/resetting/polling parameters

A CommandExts-based factory is always Bio::ParameterBaseI compliant. Periodt. That means you can:

  • set parameters with set_parameters()
  • get parameters with get_parameters()
  • reset parameters with reset_parameters

And if you're nosy (affectionate) about whether anything changed since the last time you looked, hit up the predicate parameters_changed. Full deets live over in Bio::ParameterBaseI. 📚

Once set, parameters become attributes of the factory. So you can grab their values like this:

if ($factory->freen) {
   $furs = $factory->furshlugginer;
   #...
}

💌 FEEDBACK

📬 Mailing Lists

User feedback is, like, an integral part of the evolution of this and other Bioperl modules — so don't be shy, bestie. Send your comments and suggestions (preferably) to the Bioperl mailing list. Your participation is much appreciated. 🫶

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

🛟 Support

Please direct usage questions and support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. There are so many experienced and responsive experts who will be able to look at the problem and quickly address it — and honestly, that's the whole point. If at all possible, please include a thorough description of the problem along with code and data examples. The more context, the faster the slay. 🔥

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolution. Bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

👑 AUTHOR - Mark A. Jensen

Email maj -at- fortinbras -dot- us

Describe contact details here

🌟 CONTRIBUTORS

Dan Kortschak ( dan -dot- kortschak -at- adelaide -dot- edu -dot- au )

🦋 APPENDIX 🦋

okay bestie, here's the deep-lore part — every single object method gets its own lil spotlight. Internal methods usually start with an underscore (_), so if you see that, you're in the engine room now. 🔧

new()

  • Title: new
  • Usage:
  • Function: the constructor for WrapperBase::CommandExts, and it does the cute little job of correctly binding configuration variables onto the WrapperBase object ✨
  • Returns: a Bio::Tools::Run::WrapperBase object, now with command extensions 💅
  • Args: (none)
  • Note: this method subsumes the old _register_program_commands and _set_program_options, and it leaves out the assembler-specific parms $qual_param and out_type(). so yeah, it ate their lunch 🍓

program_name

  • Title: program_name
  • Usage: $factory->program_name($name)
  • Function: get or set the executable name
  • Returns: string
  • Args: string

program_dir

  • Title: program_dir
  • Usage: $factory->program_dir($dir)
  • Function: get or set the program dir
  • Returns: string
  • Args: string

_register_program_commands()

  • Title: _register_program_commands
  • Usage: $factory->_register_program_commands( \@commands, \%prefixes )
  • Function: registers the commands a program accepts — this is for programs that act as frontends for a whole set of commands, where each command has its own little set of params/switches 👑
  • Returns: true on success
  • Args:
    • an arrayref to a list of commands (scalar strings)
    • a hashref to a translation table shaped like { $prefix1 => $command1, ... } [optional]
  • Note: to implement a program with this kind of calling structure, include a parameter called 'command' in the @program_params global
  • Note: the translation table is what associates parameters and switches specified in _set_program_options with the correct program command. In the globals @program_params and @program_switches, you specify elements as 'prefix1|param' and 'prefix1|switch', etc.

_set_program_options

  • Title: _set_program_options
  • Usage: $factory->_set_program_options( \@ args );
  • Function: registers the parameters and flags that an assembler takes
  • Returns: 1 for success
  • Args:
    • arguments passed by the user
    • parameters that the program accepts, optional (default: none)
    • switches that the program accepts, optional (default: none)
    • parameter translation, optional (default: no translation occurs)
    • dash option for the program parameters, [1|single|double|mixed], optional (default: yes, use single dashes only)
    • join, optional (default: ' ')

_translate_params

  • Title: _translate_params
  • Usage: @options = @{$assembler->_translate_params( )};
  • Function: translates the Bioperl arguments into the arguments you actually pass to the program on the command line 🔥
  • Returns: arrayref of arguments
  • Args: none

executable()

  • Title: executable
  • Usage:
  • Function: finds the full path to the main executable, or to the command executable if we're dealing with pseudo-programs
  • Returns: full path, if found
  • Args:
    • [optional] explicit path to the executable (this will set the appropriate command exec if applicable)
    • [optional] boolean flag for whether or not to warn when the exe isn't found
  • Note: overrides WrapperBase.pm

executables()

  • Title: executables
  • Usage:
  • Function: finds the full path to a command's executable
  • Returns: full path (scalar string)
  • Args:
    • command (scalar string)
    • [optional] explicit path to this command exe
    • [optional] boolean flag for whether or not to warn when the exe isn't found

_find_executable()

  • Title: _find_executable
  • Usage: my $exe_path = $fac->_find_executable($exe, $warn);
  • Function: finds the full path to a named executable
  • Returns: full path, if found
  • Args:
    • name of the executable to find
    • [optional] boolean flag for whether or not to warn when the exe isn't found
  • Note: it differs from executable and executables because it sets no object attributes at all — it's just here to find things and dip 🧚

_register_composite_commands()

  • Title: _register_composite_commands
  • Usage:
  • Function: adds subcommand params and switches for composite commands
  • Returns: true on success
  • Args:
    • \%composite_commands
    • \@program_params
    • \@program_switches

_create_factory_set()

  • Title: _create_factory_set
  • Usage: @facs = $self->_create_factory_set
  • Function: instantiates a set of individual command factories for a given composite command. Each factory will have the correct parameter fields set for its own subcommand 🎀
  • Returns: hash of factories: ( $subcmd_prefix => $subcmd_factory, ... )
  • Args: none

_collate_subcmd_args()

  • Title: _collate_subcmd_args
  • Usage: $args_hash = $self->_collate_subcmd_args
  • Function: collates parameters and switches into command-specific arg lists, so they can be passed to new()
  • Returns: hash of named argument lists
  • Args:
    • [optional] composite cmd prefix (scalar string)
    • [default is 'run']

_run

  • Title: _run
  • Usage: $fac->_run( @file_args )
  • Function: runs a command as specified during object construction
  • Returns: true on success
  • Args: a specification of the files to operate on, according to the filespec

no_throw_on_crash()

  • Title: no_throw_on_crash
  • Usage:
  • Function: prevents the throw on execution error
  • Returns:
  • Args: [optional] boolean

last_execution()

  • Title: last_execution
  • Usage:
  • Function: returns the last executed command along with its options
  • Returns: string of the command line sent to IPC::Run
  • Args:

_dash_switch()

  • Title: _dash_switch
  • Usage: $version = $fac->_dash_switch( $switch )
  • Function: returns an appropriately dashed switch for the executable
  • Args: a string containing a switch without dashes
  • Returns: a string containing an appropriately dashed switch for the current executable ✨

stdout()

  • Title: stdout
  • Usage: $fac->stdout()
  • Function: stores the output from STDOUT for the run, if no file was specified in the _run arguments
  • Example:
  • Returns: scalar string
  • Args: on set, the new value (a scalar or undef, optional)

stderr()

  • Title: stderr
  • Usage: $fac->stderr()
  • Function: stores the output from STDERR for the run, if no file is specified in the _run arguments
  • Example:
  • Returns: scalar string
  • Args: on set, the new value (a scalar or undef, optional)

is_pseudo()

  • Title: is_pseudo
  • Usage: $obj->is_pseudo($newval)
  • Function: returns true if this factory represents a pseudo-program 👀
  • Example:
  • Returns: value of is_pseudo (boolean)
  • Args: on set, the new value (a scalar or undef, optional)

AUTOLOAD

AUTOLOAD permits this:

$class->new_yourcommand(@args);

as an alias for this:

$class->new( -command => 'yourcommand', @args );

so you get a lil nickname for your command constructor, no cap 💅

🫶 Bio:ParameterBaseI compliance 🫶

yes bestie, it plays nice with the interface. here's the whole compliance era:

set_parameters()

  • Title: set_parameters
  • Usage: $pobj->set_parameters(%params);
  • Function: sets the parameters listed in the hash or array
  • Returns: true on success
  • Args: [optional] hash or array of parameter/values

reset_parameters()

  • Title: reset_parameters
  • Usage: resets values
  • Function: resets parameters to either undef or to the value in the passed hash
  • Returns: none
  • Args: [optional] hash of parameter-value pairs

parameters_changed()

  • Title: parameters_changed
  • Usage: if ($pobj->parameters_changed) {...}
  • Function: returns boolean true (1) if the parameters have changed
  • Returns: Boolean (0 or 1)
  • Args: [optional] Boolean

available_parameters()

  • Title: available_parameters
  • Usage: @params = $pobj->available_parameters()
  • Function: returns a list of the available parameters
  • Returns: Array of parameters
  • Args:
    • 'params' for settable program parameters
    • 'switches' for boolean program switches
    • default: all

get_parameters()

  • Title: get_parameters
  • Usage: %params = $pobj->get_parameters;
  • Function: returns a list of key-value pairs of parameter => value
  • Returns: List of key-value pairs
  • Args: [optional] a string is allowed if subsets are wanted, or (if a parameter subset is default) 'all' to return all parameters

and that's the whole thing, bestie 🎀 you made it to the very end, which is iconic behavior. this beauty lives in perl v5.32.1, dated 2021-08-15, and it's filed under Bio::T...andExts(3pm) — go forth and run your programs, you absolute legend 💖✨🦋

📦 where this page comes from