NAME
R::YapRI::Base.pm A wrapper to interact with R/
SYNOPSIS
use R::YapRI::Base;
## WORKING WITH THE DEFAULT MODE:
my $rih = R::YapRI::Base->new();
$rih->add_command('bmp(filename="myfile.bmp", width=600, height=800)');
$rih->add_command('dev.list()');
$rih->add_command('plot(c(1, 5, 10), type = "l")');
$rih->add_command('dev.off()');
$rih->run_command();
my $result_file = $rih->get_resultfiles('default');
## To work with blocks, check R::YapRI::BlockDESCRIPTION
Another yet perl wrapper to interact with RAUTHOR
Aureliano Bombarely <ab782@cornell.edu>
CLASS METHODS
The following class methods are implemented:
(*) CONSTRUCTORS:
---------------
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_command
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:
---------------------------
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:
------------
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_command 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_command 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(); (*) FILE METHODS:
---------------
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:
------------------
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 use R::YapRI::Blockcombine_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_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')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();