Debian Codegraph @

README

raw
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