NAME

Statistics::R - Controls the R interpreter through Perl.

DESCRIPTION

This module controls the R interpreter (R project for statistical computing: http://www.r-project.org/). Multiple architectures and OS are supported and a single instance of R can be accessed by several Perl processes.

SYNOPSIS

  use Statistics::R;
  
  # Create a communication bridge with R and start R
  my $R = Statistics::R->new();
  
  # Run simple R commands
  $R->run(q`postscript("file.ps" , horizontal=FALSE , width=500 , height=500 , pointsize=1)`);
  $R->run(q`plot(c(1, 5, 10), type = "l")`);
  $R->run(q`dev.off()`);

  # Pass and retrieve data
  my $input_value = 1;
  $R->set('x', $input_value);
  $R->run(q`y <- x^2`);
  my $output_value = $R->get('y');
  print "y = $output_value\n";

  $R->stop();

METHODS

new()

Create a Statistics::R bridge object between Perl and R and start() R. Available options are:

shared

Start a shared bridge. See start().

log_dir

The directory where the bridge between R and Perl will be created.

R and Perl need to have read and write access to the directory and Perl will change to this directory!

By default it will be created at %TMP_DIR%/Statistics-R.

r_bin

The path to the R binary.

By default the path will be searched in the default installation path of R in the OS.

r_dir

The directory of R.

tmp_dir

A temporary directory.

By default the temporary directory of the OS will be used

start()

Start R and set the communication bridge between Perl and R. Pass the option shared => 1 to use an already running bridge.

stop()

Stop R and stop the bridge.

restart()

stop() and start() R.

bin()

Return the path to the R binary (executable).

send($CMD)

Send some command to be executed inside R. Note that $CMD will be loaded by R with source()

receive($TIMEOUT)

Get the output of R for the last group of commands sent to R by send().

lock()

Lock the bridge for your PID.

unlock()

Unlock the bridge if your PID have locked it.

is_locked()

Return TRUE if the bridge is locked for your PID.

In other words, returns TRUE if other process has lock()ed the bridge.

is_started()

Return TRUE if the R interpreter is started, or still started.

clean_up()

Clean up the environment, removing all the objects.

INSTALL

To install this package you need to install R on your system first, since Statistics::R need to find R path to work.

A standard installation of R on Win32 or Linux will work fine and be detected automatically by Statistics::R.

Download page of R: http://cran.r-project.org/banner.shtml

Or go to the R web site: http://www.r-project.org/

You also need to have the following CPAN Perl modules installed:

Text::Balanced
Regexp::Common

EXECUTION FOR MULTIPLE PROCESSES

The main purpose of Statistics::R is to start a single R interpreter that listens to multiple Perl processes.

Note that to do that R and Perl need to be running with the same user/group level.

To start the Statistics::R bridge, you can use the script statistics-r.pl:

  $> statistics-r.pl start

From your script you need to use the start() option in shared mode:

  use Statistics::R;
  
  my $R = Statistics::R->new();
  
  $R->start( shared => 1 );
  
  $R->send('x = 123');
  
  exit;

Note that in the example above the method stop() wasn't called, since it will close the bridge.

SEE ALSO

AUTHOR

Graciliano M. P. <gm@virtuasites.com.br>

MAINTAINERS

Brian Cassidy <bricas@cpan.org>

Florent Angly <florent.angly@gmail.com>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

All complex software has bugs lurking in it, and this program is no exception. If you find a bug, please report it on the CPAN Tracker of Statistics::R: http://rt.cpan.org/Dist/Display.html?Name=Statistics-R

Bug reports, suggestions and patches are welcome. The Statistics::R code is developed on Github (http://github.com/bricas/statistics-r) and is under Git revision control. To get the latest revision, run:

   git clone git@github.com:bricas/statistics-r.git