Aureliano Bombarely > R-YapRI-0.08 > R::YapRI::Base

Download:
R-YapRI-0.08.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.05   Source  

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_command();
  
  my $result_file = $rbase->get_result_file();

  
  ## To work with blocks, check R::YapRI::Block

DESCRIPTION ^

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.

AUTHOR ^

Aureliano Bombarely <ab782@cornell.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_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: ^

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_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(); 

(*) 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.

syntax highlighting: