README

   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 <florent.angly@gmail.com> (2011 rewrite)
 215
 216     Graciliano M. P. <gm@virtuasites.com.br> (original code)
 217
 218 MAINTAINERS
 219     Florent Angly <florent.angly@gmail.com>
 220
 221     Brian Cassidy <bricas@cpan.org>
 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