NAME
R::YapRI::Base.pm
A wrapper to interact with R/
SYNOPSIS
use R::YapRI::Base;
## WORKING WITH THE DEFAULT MODE:
my $rbase = R::YapRI::Base->new();
$rbase->add_command('bmp(filename="myfile.bmp", width=600, height=800)');
$rbase->add_command('dev.list()');
$rbase->add_command('plot(c(1, 5, 10), type = "l")');
$rbase->add_command('dev.off()');
$rbase->run_commands();
my $result_file = $rbase->get_result_file();
## To work with blocks, check R::YapRI::BlockDESCRIPTION
Yet another perl wrapper to interact with R.
This module is the central module to use R::YapRI.
If R executable is in the PATH or in RBASE environment variables of your system, R commands can be run using this perl module with four methods:
- new(),
- add_command('my R command'),
- run_commands(),
- get_result_file();
The mechanism is simple, it write R commands into a command file and executate it using the R as command line:
R [options] < infile > outfile
R::YapRI, is a package to manage the infile as command_file and outfile as result_file, with some other tools (blocks, interpreters, switches...).
It can work with a block system to create, combine and run different blocks (every one with a command file and result file associated, see R::YapRI::Block)
It uses two switches to trace the R commands that you are running:
- disable_keepfiles/enable_keepfiles, to do not delete the command files and the result files after the executation of the code.
- disable_debug/enable_debug, to print as STDERR the R commands from the command file before executate them.
AUTHOR
Aureliano Bombarely <aurebg@vt.edu>
CLASS METHODS
The following class methods are implemented:
(*) CONSTRUCTORS:
R::YapRI::Base has just one constructor: new(). It can be used in three different ways:
1) With default arguments:
- It will create cmddir in the temp folder: RiPerldir_XXXXXXXX
- It will create the 'default' block with the command file RiPerl_cmd_XXXXXXXX into the cmddir.
- It will run R with --vanilla option.
- 'keepfiles' and 'debug' switches will be disabled.
Example: my $rbase = R::YapRI::Base->new();
2) With user arguments:
Any of the following arguments can be used:
cmddir, r_options, debug and keepfiles
These arguments will overwrite default arguments except if use_defaults => 0 is used. In this case no initial 'default block' will be created, and if no 'cmddir' is used, it will not be created (see empty object below)
Example: my $rbase = R::YapRI::Base->new({ cmddir => 'mydir' });
3) With use_default => 0, an empty object will be created without
cmddir, blocks or r_options.
debug and keepfile switches will be disabled.
Example: my $rbase = R::YapRI::Base->new({ use_defaults => 0 });
constructor new
Usage: my $rbase = R::YapRI::Base->new($arguments_href);
Desc: Create a new R interfase object.
Ret: a R::YapRI::Base object
Args: A hash reference with the following parameters:
cmddir => A string, a dir to store the command files
r_options => A string with the R options passed to run_commands
use_defaults => 0|1 to disable/enable use_default.
debug => 0|1 to disable/enable debug for run commands.
keepfiles => 0|1 to disable/enable keepfiles after DESTROY rbase
Side_Effects: Die if the argument used is not a hash or its values arent
right.
By default it will use set_default_cmddir(),
and set_default_r_options();
Example: ## Default method:
my $rih = R::YapRI::Base->new();
## Create an empty object
my $rih = R::YapRI::Base->new({ use_defaults => 0 });
## Defining own dir
my $rih = R::YapRI::Base->new({ cmddir => '/home/user/R' });(*) DEBUGGING SWITCH METHODS:
R::YapRI has two switches to trace the R commands that has been run.
enable/disable_keepfiles
Usage: $rbase->enable_keepfiles();
$rbase->disable_keepfiles();
Desc: Enable or disable keep the command files and the result files
during the destruction of the rbase object.
Ret: None
Args: None
Side_Effects: None
Example: $rbase->enable_keepfiles();
$rbase->disable_keepfiles();enable/disable_debug
Usage: $rbase->enable_debug();
$rbase->disable_debug();
Desc: Enable or disable debug option that print as STDERR the R command
when run_commands or run_block methods are used.
Ret: None
Args: None
Side_Effects: None
Example: $rbase->enable_debug();
$rbase->disable_debug();(*) ACCESSORS:
Three different accessors: cmddir, blocks and r_options
get_cmddir
Usage: my $cmddir = $rbase->get_cmddir();
Desc: Get the command dir used by the r interfase object
Ret: $cmddir, a scalar
Args: None
Side_Effects: None
Example: my $cmddir = $rbase->get_cmddir(); set_cmddir
Usage: $rbase->set_cmddir($cmddir);
Desc: Set the command dir used by the r interfase object
Ret: None
Args: $cmddir, a scalar
Side_Effects: Die if no argument is used.
Die if the cmddir doesnt exists
Example: $rbase->set_cmddir($cmddir); set_default_cmddir
Usage: $rbase->set_default_cmddir();
Desc: Set the command dir used by the r interfase object with a default value
such as RiPerldir_XXXXXXXX
Ret: None
Args: None
Side_Effects: Create the perl_ri_XXXXXXXX folder in the tmp dir
Example: $rbase->set_default_cmddir(); delete_cmddir
Usage: my $cmddir = $rbase->delete_cmddir();
Desc: Delete the command dir used by the r interfase object
Ret: $cmddir, deleted cmddir
Args: None
Side_Effects: Die if no argument is used.
Example: $rbase->delete_cmddir(); get_blocks
Usage: my $block_href = $rbase->get_blocks();
Desc: Get the blocks objects used by the r interfase object
Ret: $block_href, a hash reference with key=blockname, value=rblock object.
Args: $blockname [optional]
Side_Effects: None
Example: my %blocks = %{$rbase->get_blocks()};
my $block1 = $rbase->get_blocks('block1');set_blocks
Usage: $rbase->set_blocks($block_href);
Desc: Set the blocks objects used by the r interfase object
Ret: None
Args: $block_href, a hash reference with key=blockname, value=rblock object.
Side_Effects: Die if no argument is used.
Die if argument is not hash ref.
Die if the values are not R::YapRI::Block objects.
Example: $rbase->set_blocks({ $block->get_blockname() => $block }); add_block
Usage: $rbase->add_block($block);
Desc: Add a new block object to the rbase object
Ret: None
Args: $block, a R::YapRI::Block object.
Side_Effects: Die if no argument is used.
Die if block is not a R::YapRI::Block object.
Die if block has not set blockname.
Example: $rbase->add_block('BLOCK1', $block1); delete_block
Usage: $rbase->delete_block($blockname);
Desc: Delete a block from the rbase object.
Ret: None
Args: $blockname, a blockname.
Side_Effects: Die if no argument is used.
If switch keepfiles is dissable it will delete the files
associated with that block too.
Example: $rbase->delete_block('BLOCK1'); get_r_options
Usage: my $r_options = $rih->get_r_options();
Desc: Get the r_opts_pass variable (options used with the R command)
when run_commands function is used
Ret: $r_opts_pass, a string
Args: None
Side_Effects: None
Example: my $r_opts_pass = $rbase->get_r_options();
if ($r_opts_pass !~ m/vanilla/) {
$r_opts_pass .= ' --vanilla';
}set_r_options
Usage: $rbase->set_r_options($r_opts_pass);
Desc: Set the r_opts_pass variable (options used with the R command)
when run_commands function is used. Use R -help for more info.
The most common options used:
--save Do save workspace at the end of the session
--no-save Don't save it
--no-environ Don't read the site and user environment files
--no-site-file Don't read the site-wide Rprofile
--no-init-file Don't read the user R profile
--restore Do restore previously saved objects at startup
--no-restore-data Don't restore previously saved objects
--no-restore-history Don't restore the R history file
--no-restore Don't restore anything
--vanilla Combine --no-save, --no-restore, --no-site-file,
--no-init-file and --no-environ
-q, --quiet Don't print startup message
--silent Same as --quiet
--slave Make R run as quietly as possible
--interactive Force an interactive session
--verbose Print more information about progress
The only opt that can not be set using set_r_opts_pass is --file,
it is defined by the commands stored as cmdfiles.
Ret: None
Args: $r_opts_pass, a string
Side_Effects: Remove '--file=' from the r_opts_pass string
Example: $rbase->set_r_options('--verbose');set_default_r_options
Usage: $rih->set_default_r_options();
Desc: Set the default R options for R::YapRI::Base (R --slave --vanilla)
Ret: None
Args: None
Side_Effects: None
Example: $rih->set_default_r_options(); (*) WRAPPERS FOR BLOCK ACCESSORS:
These methods are wrappers to access to the rblock objects through rbase object. They have the same name than the methods for R::YapRI::Block.
If no argument is used it will access to 'default' rblock.
get_command_file, set_command_file
Usage: my $command_file = $rbase->get_command_file($blockname);
$rbase->get_command_file($command_file, $blockname);
Desc: Get/Set a command file associated to a block. Command file associated
with the 'default' block will be got if no blockname argument is used.
Ret: Get: $command_file, a file path for the command file.
Set: none
Args: Get: $blockname, optional.
Set: $command_file, a file path for the command file, and $blockname.
Side_Effects: Get: 'default' blockname will be used if no blockname is used.
undef will be returned if no blockname exist in the rbase
object with that name.
Set: Same than the original method (die if no command_file
argument is used or if the file does not exist) and die
if the blockname used does note exist in rbase
Example: my $command_file = $rbase->get_command_file('block1');
my $default_command_file = $rbase->get_command_file();
$rbase->get_command_file($command_file, 'block1');get_result_file, set_result_file
Usage: my $result_file = $rbase->get_result_file($blockname);
$rbase->get_result_file($result_file, $blockname);
Desc: Get/Set a result file associated to a block. Result file associated
with the 'default' block will be got if no blockname argument is used.
Ret: Get: $result_file, a file path for the result file.
Set: none
Args: Get: $blockname, optional.
Set: $result_file, a file path for the result file, and $blockname.
Side_Effects: Get: 'default' blockname will be used if no blockname is used.
undef will be returned if no blockname exist in the rbase
object with that name.
Set: Same than the original method (die if no result_file
argument is used or if the file does not exist) and die
if the blockname used does note exist in rbase
Example: my $result_file = $rbase->get_result_file('block1');
my $default_result_file = $rbase->get_result_file();
$rbase->get_result_file($result_file, 'block1');(*) FILE METHODS:
Internal methods to create files in the cmddir.
create_rfile
Usage: my $rfile = $rbase->create_rfile($basename);
Desc: Create a new file inside cmddir folder.
Ret: $rfile, a filename for the new file.
Args: $basename, a basename for the new file. It will add 8 random
characters to this basename.
Side_Effects: Die if cmddir is not set.
Use 'RiPerl_cmd_' as basename.
Example: my $rfile = $rbase->create_rfile();(*) COMMAND METHODS:
Methods to add,get or run command from the command files associated with the blocks.
If no blockname is used, it will assume that 'default' block is being used.
add_command
Usage: $rbase->add_command($r_command, $blockname);
Desc: Add a R command line to a cmdfile associated with an blockname.
If no filename is used, it will added to the 'default' blockname.
Ret: None
Args: $r_command, a string with a R command
$blockname, a alias with a cmdfile to add the command [optional]
Side_Effects: Die if the blockname used doesnt exist or doesnt have cmdfile
Add the command to the default if no filename is specified,
if doesnt exist default cmdfile, it will create it.
Example: $rbase->add_command('x <- c(10, 9, 8, 5)')
$rbase->add_command('x <- c(10, 9, 8, 5)', 'block1')get_commands
Usage: my @commands = $rbase->get_commands($blockname);
Desc: Read the cmdfile associated with an $blockname.
'default' blockname will be used by default.
Ret: None
Args: $blockname, a blockname [optional]
Side_Effects: Die if $blockname doesnt exist or doesnt have cmdfile
Get commands for default file, by default
Example: my @commands = $rbase->get_commands('block1');
my @def_commands = $rbase->get_commands(); run_commands
Usage: $rih->run_commands($blockname);
Desc: Run as command line the R command file
Ret: None
Args: $blockname, a blockname to run the commands.
'default' if no blockname is used.
$debug, 'debug' to print the command as STDERR.
Side_Effects: Die if no R executable path is not found.
Die if blockname used doesnt exist.
Die if block doesnt have set cmdfile.
Example: $rih->run_commands('BLOCK1'); _system_r
Usage: my $R = _system_r();
Desc: Get R executable path from $RBASE environment variable. If it doesnt
exist, it will search in $PATH.
Ret: $R, R executable path.
Args: None
Side_Effects: None
Example: my $R = _system_r();(*) BLOCK METHODS:
They are a collection of methods to enhance the usage of R::YapRI::Block through rbase object, like create new blocks, create blocks using another blocks as a base or combine blocks.
combine_blocks
Usage: my $block = $rbase->combine_blocks(\@blocks, $new_block);
Desc: Create a new block based in an array of defined blocks
Ret: None
Args: \@blocks, an array reference with the blocks (cmdfiles aliases) in the
same order that they will be concatenated.
Side_Effects: Die if the alias used doesnt exist or doesnt have cmdfile
Example: my $block = $rbase->combine_blocks(['block1', 'block3'], 'block43');create_block
Usage: my $block = $rbase->create_block($new_block, $base_block);
Desc: Create a new block object. A single block can be used as base.
Ret: $block, a new R::YapRI::Block object
Args: $new_block, new name/alias for this block
$base_block, base block name
Side_Effects: Die if the base alias used doesnt exist or doesnt have cmdfile
Example: my $newblock = $rbase->create_block('block43', 'block1');(*) R OBJECTS METHODS:
They are a collection of methods to interact with the R objects creating and running blocks to get some data from R, like class for an object or arguments for a function.
They will be moved to R::YapRI::Interpreter::R soon.
r_object_class
Usage: my $class = $rbase->r_object_class($block, $r_object);
Desc: Check if exists a r_object in the specified R block. Return
undef if the object doesnt exist or the class of the object
Ret: $class, a scalar with the class of the r_object
Args: $block, a scalar, R::YapRI::Base block
$r_object, name of the R object
Side_Effects: Die if the base alias used doesnt exist or doesnt have cmdfile
Example: my $class = $rbase->r_object_class('BLOCK1', 'mtx');r_function_args
Usage: my %rargs = $rbase->r_function_args($r_function);
Desc: Get the arguments for a concrete R function.
Ret: %rargs, a hash with key=r_function_argument,
value=function_default_value
Args: none
Side_Effects: Die if no R function argument is used
Return empty hash if the function doesnt exist
If the argument doesnt have any value, add <without.value>
Example: my %plot_args = $rbase->r_function_args('plot')(*) DESTRUCTOR:
Destructor will delete the cmddir and the files contained by it if switch keepfiles is disabled.
DESTROY
Usage: $rbase->DESTROY();
Desc: Destructor for rbase object. It also undef all the block objects
references contained in the rbase object.
If keepfiles switch is enabled it will not delete the files and the
cmddir.
Ret: None
Args: None
Side_Effects: None
Example: $rbase->DESTROY();ACKNOWLEDGEMENTS
Lukas Mueller
Robert Buels
Naama Menda
Jonathan "Duke" Leto
COPYRIGHT AND LICENCE
Copyright 2011 Boyce Thompson Institute for Plant Research
Copyright 2011 Sol Genomics Network (solgenomics.net)
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.