| 1 |
NAME |
| 2 |
Statistics::R - Perl interface with the R statistical program |
| 3 |
|
| 4 |
DESCRIPTION |
| 5 |
*Statistics::R* is a module to controls the R interpreter (R project for |
| 6 |
statistical computing: <http://www.r-project.org/>). It lets you start |
| 7 |
R, pass commands to it and retrieve their output. A shared mode allows |
| 8 |
several instances of *Statistics::R* to talk to the same R process. |
| 9 |
|
| 10 |
The current *Statistics::R* implementation uses pipes (stdin, stdout and |
| 11 |
stderr) to communicate with R. This implementation is more efficient and |
| 12 |
reliable than that in versions < 0.20, which relied on reading and |
| 13 |
writing intermediary files. As before, this module works on GNU/Linux, |
| 14 |
MS Windows and probably many more systems. *Statistics::R* has been |
| 15 |
tested with R version 2 and 3. |
| 16 |
|
| 17 |
SYNOPSIS |
| 18 |
use Statistics::R; |
| 19 |
|
| 20 |
# Create a communication bridge with R and start R |
| 21 |
my $R = Statistics::R->new(); |
| 22 |
|
| 23 |
# Run simple R commands |
| 24 |
my $output_file = "file.ps"; |
| 25 |
$R->run(qq`postscript("$output_file", horizontal=FALSE, width=500, height=500)`); |
| 26 |
$R->run(q`plot(c(1, 5, 10), type = "l")`); |
| 27 |
$R->run(q`dev.off()`); |
| 28 |
|
| 29 |
# Pass and retrieve data (scalars or arrays) |
| 30 |
my $input_value = 1; |
| 31 |
$R->set('x', $input_value); |
| 32 |
$R->run(q`y <- x^2`); |
| 33 |
my $output_value = $R->get('y'); |
| 34 |
print "y = $output_value\n"; |
| 35 |
|
| 36 |
$R->stop(); |
| 37 |
|
| 38 |
METHODS |
| 39 |
new() |
| 40 |
Build a *Statistics::R* bridge object connecting Perl and R. |
| 41 |
Available options are: |
| 42 |
|
| 43 |
bin Specify the full path to the R executable, if it is not |
| 44 |
automatically found. See "INSTALLATION". |
| 45 |
|
| 46 |
shared |
| 47 |
Start a shared bridge. When using a shared bridge, several |
| 48 |
instances of Statistics::R can communicate with the same unique |
| 49 |
R instance. Example: |
| 50 |
|
| 51 |
use Statistics::R; |
| 52 |
|
| 53 |
my $R1 = Statistics::R->new( shared => 1); |
| 54 |
my $R2 = Statistics::R->new( shared => 1); |
| 55 |
|
| 56 |
$R1->set( 'x', 'pear' ); |
| 57 |
my $x = $R2->get( 'x' ); |
| 58 |
print "x = $x\n"; |
| 59 |
|
| 60 |
$R1->stop; # or $R2->stop |
| 61 |
|
| 62 |
Note that in shared mode, you are responsible for calling the |
| 63 |
*stop()* method from one of your Statistics::R instances when |
| 64 |
you are finished. But be careful not to call the *stop()* method |
| 65 |
if you still have processes that need to interact with R! |
| 66 |
|
| 67 |
run() |
| 68 |
First, *start()* R if it is not yet running. Then, execute R |
| 69 |
commands passed as a string and return the output as a string. If |
| 70 |
your commands failed to run in R, an error message will be |
| 71 |
displayed. |
| 72 |
|
| 73 |
Example: |
| 74 |
|
| 75 |
my $out = $R->run( q`print( 1 + 2 )` ); |
| 76 |
|
| 77 |
If you intend on runnning many R commands, it may be convenient to |
| 78 |
pass a list of commands or put multiple commands in an here-doc: |
| 79 |
|
| 80 |
# List of R commands: |
| 81 |
my $out1 = $R->run( |
| 82 |
q`a <- 2`, |
| 83 |
q`b <- 5`, |
| 84 |
q`c <- a * b`, |
| 85 |
q`print("ok")` |
| 86 |
); |
| 87 |
|
| 88 |
# Here-doc with multiple R commands: |
| 89 |
my $cmds = <<EOF; |
| 90 |
a <- 2 |
| 91 |
b <- 5 |
| 92 |
c <- a * b |
| 93 |
print('ok') |
| 94 |
EOF |
| 95 |
my $out2 = $R->run($cmds); |
| 96 |
|
| 97 |
Alternatively, to run commands from a file, use the |
| 98 |
*run_from_file()* method. |
| 99 |
|
| 100 |
The return value you get from *run()* is a combination of what R |
| 101 |
would display on the standard output and the standard error, but the |
| 102 |
exact order may differ. |
| 103 |
|
| 104 |
When loading modules, some may write numerous messages on standard |
| 105 |
error. You can disable this behavior using the following R command: |
| 106 |
|
| 107 |
suppressPackageStartupMessages(library(library_to_load)) |
| 108 |
|
| 109 |
Note that older versions of R impose a limit on how many characters |
| 110 |
can be contained on a line: about 4076 bytes maximum. You will be |
| 111 |
warned if this occurs, with an error message stating: |
| 112 |
|
| 113 |
'\0' is an unrecognized escape in character string starting "... |
| 114 |
|
| 115 |
In this case, try to break down your R code into several smaller, |
| 116 |
more manageable statements. Alternatively, adding newline characters |
| 117 |
"\n" at strategic places in the R statements will work around the |
| 118 |
issue. |
| 119 |
|
| 120 |
run_from_file() |
| 121 |
Similar to *run()* but reads the R commands from the specified file. |
| 122 |
Internally, this method converts the filename to a format compatible |
| 123 |
with R and then passes it to the R *source()* command to read the |
| 124 |
file and execute the commands. |
| 125 |
|
| 126 |
result() |
| 127 |
Get the results from the last R command. |
| 128 |
|
| 129 |
set() |
| 130 |
Set the value of an R variable (scalar or vector). Example: |
| 131 |
|
| 132 |
# Create an R scalar |
| 133 |
$R->set( 'x', 'pear' ); |
| 134 |
|
| 135 |
or |
| 136 |
|
| 137 |
# Create an R list |
| 138 |
$R->set( 'y', [1, 2, 3] ); |
| 139 |
|
| 140 |
get() |
| 141 |
Get the value of an R variable (scalar or vector). Example: |
| 142 |
|
| 143 |
# Retrieve an R scalar. $x is a Perl scalar. |
| 144 |
my $x = $R->get( 'x' ); |
| 145 |
|
| 146 |
or |
| 147 |
|
| 148 |
# Retrieve an R list. $x is a Perl arrayref. |
| 149 |
my $y = $R->get( 'y' ); |
| 150 |
|
| 151 |
start() |
| 152 |
Explicitly start R. Most times, you do not need to do that because |
| 153 |
the first execution of *run()* or *set()* will automatically call |
| 154 |
*start()*. |
| 155 |
|
| 156 |
stop() |
| 157 |
Stop a running instance of R. You need to call this method after |
| 158 |
running a shared bridge. For a simple bridge, you do not need to do |
| 159 |
this because *stop()* is automatically called when the Statistics::R |
| 160 |
object goes out of scope. |
| 161 |
|
| 162 |
restart() |
| 163 |
*stop()* and *start()* R. |
| 164 |
|
| 165 |
bin() |
| 166 |
Get or set the path to the R executable. Note that the path will be |
| 167 |
available only after start() has been called. |
| 168 |
|
| 169 |
version() |
| 170 |
Get the version number of R. |
| 171 |
|
| 172 |
is_shared() |
| 173 |
Was R started in shared mode? |
| 174 |
|
| 175 |
is_started() |
| 176 |
Is R running? |
| 177 |
|
| 178 |
pid() |
| 179 |
Return the PID of the running R process |
| 180 |
|
| 181 |
INSTALLATION |
| 182 |
Since *Statistics::R* relies on R to work, you need to install R first. |
| 183 |
See this page for downloads, <http://www.r-project.org/>. If R is in |
| 184 |
your PATH environment variable, then it should be available from a |
| 185 |
terminal and be detected automatically by *Statistics::R*. This means |
| 186 |
that you don't have to do anything on Linux systems to get |
| 187 |
*Statistics::R* working. On Windows systems, in addition to the folders |
| 188 |
described in PATH, the usual suspects will be checked for the presence |
| 189 |
of the R binary, e.g. C:\Program Files\R. If *Statistics::R* does not |
| 190 |
find where R is installed, your last recourse is to specify its full |
| 191 |
path when calling new(): |
| 192 |
|
| 193 |
my $R = Statistics::R->new( bin => $fullpath ); |
| 194 |
|
| 195 |
You also need to have the following CPAN Perl modules installed: |
| 196 |
|
| 197 |
IPC::Run |
| 198 |
Regexp::Common |
| 199 |
Text::Balanced (>= 1.97) |
| 200 |
Text::Wrap |
| 201 |
version (>= 0.77) |
| 202 |
|
| 203 |
SEE ALSO |
| 204 |
* Statistics::R::Win32 |
| 205 |
|
| 206 |
* Statistics::R::Legacy |
| 207 |
|
| 208 |
* The R-project web site: <http://www.r-project.org/> |
| 209 |
|
| 210 |
* Statistics::* modules for Perl: |
| 211 |
<http://search.cpan.org/search?query=Statistics&mode=module> |
| 212 |
|
| 213 |
AUTHORS |
| 214 |
Florent Angly <[email protected]> (2011 rewrite) |
| 215 |
|
| 216 |
Graciliano M. P. <[email protected]> (original code) |
| 217 |
|
| 218 |
MAINTAINERS |
| 219 |
Florent Angly <[email protected]> |
| 220 |
|
| 221 |
Brian Cassidy <[email protected]> |
| 222 |
|
| 223 |
COPYRIGHT & LICENSE |
| 224 |
This program is free software; you can redistribute it and/or modify it |
| 225 |
under the same terms as Perl itself. |
| 226 |
|
| 227 |
BUGS |
| 228 |
All complex software has bugs lurking in it, and this program is no |
| 229 |
exception. If you find a bug, please report it on the CPAN Tracker of |
| 230 |
Statistics::R: <http://rt.cpan.org/Dist/Display.html?Name=Statistics-R> |
| 231 |
|
| 232 |
Bug reports, suggestions and patches are welcome. The Statistics::R code |
| 233 |
is developed on Github (<http://github.com/bricas/statistics-r>) and is |
| 234 |
under Git revision control. To get the latest revision, run: |
| 235 |
|
| 236 |
git clone git://github.com/bricas/statistics-r.git |
| 237 |
|