Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       Bio::Tools::Run::WrapperBase::CommandExts - Extensions to WrapperBase
       for handling programs with commands *ALPHA*

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

       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:

       o   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

       o   command

	   The command is the specific component of a suite run	by executing
	   the program.	In the example above, "view" and "faidx" are commands.

       o   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.

       o   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.

       o   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.

       o   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.

       "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:


       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:


       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

       o   program_dir($path_to_programs)

	   Set this to point the factory to the	executables.

       o   _run(@file_args)

	   Runs	an instantiated	factory	with the given file args. Use in the
	    "run()" method override.

       o   _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) {

       o   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
   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;
	push @ISA, 'Exporter';
	@EXPORT	= qw(

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

	our @program_commands =	qw(

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

	our @program_params = qw(

	our @program_switches =	qw(

	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 )]

       $use_dash can be	one of "single", "double", or "mixed". See

       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

       Using a wrapper created with

       o   Getting a list of available commands, parameters, and filespecs:

	   To get a list of commands, simply:

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

	   The wrapper will generally have human-readable aliases for each of
	   the command-line options for	the wrapped program and	commands. To
	   obtain a list of the	parameters and switches	available for a
	   particular command, do

	    $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

       o   Create factories

	   The factory is a handle on the program and command you wish to run.
	   Create a factory using "new"	to set command-line parameters:

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

	   A shorthand for this	is:

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

       o   Running programs

	   To run the program, use the "run" method, providing filespecs as

	    $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' );

	   Messages on STDOUT and STDERR are dumped into their respective

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

	   unless STDOUT and/or	STDERR are part	of the named files in the

       o   Setting/getting/resetting/polling parameters.

	   A "CommandExts"-based factory is always Bio::ParameterBaseI
	   compliant. That means that you may set, get,	and reset parameters
	   using "set_parameters()", "get_parameters()", and
	   "reset_parameters". You can ask whether parameters have changed
	   since they were last	accessed by using the predicate
	   "parameters_changed". See Bio::ParameterBaseI for more details.

	   Once	set, parameters	become attributes of the factory. Thus,	you
	   can get their values	as follows:

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

   Mailing Lists
       User feedback is	an integral part of the	evolution of this and other
       Bioperl modules.	Send your comments and suggestions preferably to the
       Bioperl mailing list.  Your participation is much appreciated.			- General discussion  -	About the mailing lists

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

       rather than to the module maintainer directly. Many experienced and
       reponsive experts will be able look at the problem and quickly address
       it. Please include a thorough description of the	problem	with code and
       data examples if	at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of
       the bugs	and their resolution. Bug reports can be submitted via the

AUTHOR - Mark A. Jensen
       Email maj -at- fortinbras -dot- us

       Describe	contact	details	here

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

       The rest	of the documentation details each of the object	methods.
       Internal	methods	are usually preceded with a _

	Title	: new
	Usage	:
	Function: constructor for WrapperBase::CommandExts ;
		  correctly binds configuration	variables
		  to the WrapperBase object
	Returns	: Bio::Tools::Run::WrapperBase object with command extensions
	Args	:
	Note	: this method subsumes the old _register_program_commands and
		  _set_program_options,	leaving	out the	assembler-specific
		  parms	($qual_param and out_type())

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

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

	Title	: _register_program_commands
	Usage	: $factory->_register_program_commands(	\@commands, \%prefixes )
	Function: Register the commands	a program accepts (for programs	that act
		  as frontends for a set of commands, each command having its own
		  set of params/switches)
	Returns	: true on success
	Args	: arrayref to a	list of	commands (scalar strings),
		  hashref to a translation table of the	form
		  { $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 used	to associate parameters	and
		  switches specified in	_set_program_options with the correct
		  program command. In the globals @program_params and
		  @program_switches, specify elements as 'prefix1|param' and
		  'prefix1|switch', etc.

	Title	: _set_program_options
	Usage	: $factory->_set_program_options( \@ args );
	Function: Register 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: ' ')

	Title	: _translate_params
	Usage	: @options = @{$assembler->_translate_params( )};
	Function: Translate the	Bioperl	arguments into the arguments to	pass to	the
		  program on the command line
	Returns	: Arrayref of arguments
	Args	: none

	Title	: executable
	Usage	:
	Function: find the full	path to	the main executable,
		  or to	the command executable for pseudo-programs
	Returns	: full path, if	found
	Args	: [optional] explicit path to the executable
		  (will	set the	appropriate command exec if
		  [optional] boolean flag whether or not to warn when exe no found
	Note	: overrides

	Title	: executables
	Usage	:
	Function: find 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 whether or not to warn when exe no found

	Title	: _find_executable
	Usage	: my $exe_path = $fac->_find_executable($exe, $warn);
	Function: find the full	path to	a named	executable,
	Returns	: full path, if	found
	Args	: name of executable to	find
		  [optional] boolean flag whether or not to warn when exe no found
	Note	: differs from executable and executables in not
		  setting any object attributes

	Title	: _register_composite_commands
	Usage	:
	Function: adds subcomand params	and switches for composite commands
	Returns	: true on success
	Args	: \%composite_commands,

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

	Title	: _collate_subcmd_args
	Usage	: $args_hash = $self->_collate_subcmd_args
	Function: collate parameters and switches into command-specific
		  arg lists for	passing	to new()
	Returns	: hash of named	argument lists
	Args	: [optional] composite cmd prefix (scalar string)
		  [default is 'run']

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

	Title	: no_throw_on_crash
	Usage	:
	Function: prevent throw	on execution error
	Returns	:
	Args	: [optional] boolean

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

	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	: string containing an appropriately dashed switch for the current executable

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

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

	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, new value (a scalar or undef,	optional)

       AUTOLOAD	permits


       as an alias for

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

Bio:ParameterBaseI compliance
	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.

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

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

	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

	Title	: get_parameters
	Usage	: %params = $pobj->get_parameters;
	Function: Returns 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

perl v5.32.0			  Bio::Tools::Run::WrapperBase::CommandExts(3)


Want to link to this manual page? Use this URL:

home | help