2 Statistics::R - Perl interface with the R statistical program
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 the output. A shared mode allow to
8 have several instances of *Statistics::R* talk to the same R process.
10 The current *Statistics::R* implementation uses pipes (for stdin, stdout
11 and and stderr) to communicate with R. This implementation should be
12 more efficient and reliable than that in previous version, which relied
13 on reading and writing files. As before, this module works on GNU/Linux,
14 MS Windows and probably many more systems.
19 # Create a communication bridge with R and start R
20 my $R = Statistics::R->new();
22 # Run simple R commands
23 my $output_file = "file.ps";
24 $R->run(qq`postscript("$output_file" , horizontal=FALSE , width=500 , height=500 , pointsize=1)`);
25 $R->run(q`plot(c(1, 5, 10), type = "l")`);
26 $R->run(q`dev.off()`);
28 # Pass and retrieve data (scalars or arrays)
30 $R->set('x', $input_value);
32 my $output_value = $R->get('y');
33 print "y = $output_value\n";
39 Build a *Statistics::R* bridge object between Perl and R. Available
43 Specify the full path to R if it is not automatically found. See
47 Start a shared bridge. When using a shared bridge, several
48 instances of Statistics::R can communicate with the same unique
53 my $R1 = Statistics::R->new( shared => 1);
54 my $R2 = Statistics::R->new( shared => 1);
56 $R1->set( 'x', 'pear' );
57 my $x = $R2->get( 'x' );
60 Do not call the *stop()* method is you still have processes that
61 need to interact with R.
64 First, start() R if it is not yet running. Then, execute R commands
65 passed as a string and return the output as a string. If your
66 command fails to run in R, an error message will be displayed.
70 my $out = $R->run( q`print( 1 + 2 )` );
72 If you intend on runnning many R commands, it may be convenient to
73 pass an array of commands or put multiple commands in an here-doc:
75 # Array of R commands:
83 # Here-doc with multiple R commands:
90 my $out2 = $R->run($cmds);
92 To run commands from a file, see the run_from_file() method.
94 The output you get from run() is the combination of what R would
95 display on the standard output and the standard error, but the order
96 may differ. When loading modules, some may write numerous messages
97 on standard error. You can disable this behavior using the following
100 suppressPackageStartupMessages(library(library_to_load))
103 Similar to run() but reads the R commands from the specified file.
104 Internally, this method uses the R source() command to read the
108 Set the value of an R variable (scalar or arrayref). Example:
110 $R->set( 'x', 'pear' );
114 $R->set( 'y', [1, 2, 3] );
117 Get the value of an R variable (scalar or arrayref). Example:
119 my $x = $R->get( 'x' ); # $y is an scalar
123 my $y = $R->get( 'y' ); # $x is an arrayref
126 Explicitly start R. Most times, you do not need to do that because
127 the first execution of run() or set() will automatically call
131 Stop a running instance of R.
134 stop() and start() R.
137 Get or set the path to the R executable.
140 Was R started in shared mode?
146 Return the pid of the running R process
149 Since *Statistics::R* relies on R to work, you need to install R first.
150 See this page for downloads, <http://www.r-project.org/>. If R is in
151 your PATH environment variable, then it should be available from a
152 terminal and be detected automatically by *Statistics::R*. This means
153 that you don't have to do anything on Linux systems to get
154 *Statistics::R* working. On Windows systems, in addition to the folders
155 described in PATH, the usual suspects will be checked for the presence
156 of the R binary, e.g. C:\Program Files\R. If *Statistics::R* does not
157 find R installation, your last recourse is to specify its full path when
160 my $R = Statistics::R->new( r_bin => $fullpath );
162 You also need to have the following CPAN Perl modules installed:
164 Text::Balanced (>= 1.97)
169 * Statistics::R::Win32
171 * Statistics::R::Legacy
173 * The R-project web site: <http://www.r-project.org/>
175 * Statistics:: modules for Perl:
176 <http://search.cpan.org/search?query=Statistics&mode=module>
179 Florent Angly <florent.angly@gmail.com> (2011 rewrite)
181 Graciliano M. P. <gm@virtuasites.com.br> (original code)
184 Brian Cassidy <bricas@cpan.org>
187 This program is free software; you can redistribute it and/or modify it
188 under the same terms as Perl itself.
191 All complex software has bugs lurking in it, and this program is no
192 exception. If you find a bug, please report it on the CPAN Tracker of
193 Statistics::R: <http://rt.cpan.org/Dist/Display.html?Name=Statistics-R>
195 Bug reports, suggestions and patches are welcome. The Statistics::R code
196 is developed on Github (<http://github.com/bricas/statistics-r>) and is
197 under Git revision control. To get the latest revision, run:
199 git clone git@github.com:bricas/statistics-r.git