R::YapRI::Base.pm
A wrapper to interact with R/
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_command(); my $result_file = $rbase->get_result_file(); ## To work with blocks, check R::YapRI::Block
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_command(),
- 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.
Aureliano Bombarely <ab782@cornell.edu>
The following class methods are implemented:
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 });
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' });
R::YapRI has two switches to trace the R commands that has been run.
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();
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();
Three different accessors: cmddir, blocks and r_options
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();
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);
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();
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();
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');
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 });
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);
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');
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'; }
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');
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();
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.
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');
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');
Internal methods to create files in the cmddir.
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();
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.
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')
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();
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');
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();
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.
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');
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');
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.
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');
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 will delete the cmddir and the files contained by it if switch keepfiles is disabled.
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();
Lukas Mueller
Robert Buels
Naama Menda
Jonathan "Duke" Leto
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.
To install R::YapRI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm R::YapRI
CPAN shell
perl -MCPAN -e shell install R::YapRI
For more information on module installation, please visit the detailed CPAN module installation guide.