/ 
Statistics-R-0.10
River stage one • 2 direct dependents • 2 total dependents
/ Statistics::R

NAME

Statistics::R - Perl interface to control the R statistical program

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

A directory where temporary files necessary for the bridge between R and Perl will be stored.

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

By default this will be a folder called Statistics-R and placed in a temporary directory of the system

r_bin

The path to the R binary. See INSTALLATION.

set()

Set the value of an R variable, e.g.

$R->set( 'x', "apple" );

or

$R->set( 'y', [1, 2, 3] );
get( $)

Get the value of an R variable, e.g.

my $x = $R->get( 'x' );  # $y is an scalar

or

my $y = $R->get( 'y' );  # $x is an arrayref
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(). Prefer the run() command.

receive($TIMEOUT)

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

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.

INSTALLATION

To install this package you need to install R on your system first, since Statistics::R need to find R path to work. If R is in your PATH environment variable, then it should be available from a terminal and be detected automatically by Statistics::R. This means that you do not have to do anything on Linux systems to get Statistics::R working. On Windows systems, in addition to the folders described in PATH, the usual suspects will be checked for the presence of the R binary, e.g. C:\Program Files\R. Your last recourse if Statistics::R does not find R is to specify its full path when calling new():

my $R = Statistics::R->new( r_bin => $fullpath );

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
File::Which

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->run('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