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 the output. A shared mode allow to
   8     have several instances of *Statistics::R* talk to the same R process.
   9
  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.
  15
  16 SYNOPSIS
  17       use Statistics::R;
  18
  19       # Create a communication bridge with R and start R
  20       my $R = Statistics::R->new();
  21
  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()`);
  27
  28       # Pass and retrieve data (scalars or arrays)
  29       my $input_value = 1;
  30       $R->set('x', $input_value);
  31       $R->run(q`y <- x^2`);
  32       my $output_value = $R->get('y');
  33       print "y = $output_value\n";
  34
  35       $R->stop();
  36
  37 METHODS
  38     new()
  39         Build a *Statistics::R* bridge object between Perl and R. Available
  40         options are:
  41
  42         r_bin
  43             Specify the full path to R if it is not automatically found. See
  44             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             Do not call the *stop()* method is you still have processes that
  61             need to interact with R.
  62
  63     run()
  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.
  67
  68         Example:
  69
  70            my $out = $R->run( q`print( 1 + 2 )` );
  71
  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:
  74
  75            # Array of R commands:
  76            my $out1 = $R->run(
  77               q`a <- 2`,
  78               q`b <- 5`,
  79               q`c <- a * b`,
  80               q`print("ok")`
  81            );
  82
  83            # Here-doc with multiple R commands:
  84            my $cmds = <<EOF;
  85            a <- 2
  86            b <- 5
  87            c <- a * b
  88            print('ok')
  89            EOF
  90            my $out2 = $R->run($cmds);
  91
  92         To run commands from a file, see the run_from_file() method.
  93
  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
  98         R command:
  99
 100            suppressPackageStartupMessages(library(library_to_load))
 101
 102     run_from_file()
 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
 105         file.
 106
 107     set()
 108         Set the value of an R variable (scalar or arrayref). Example:
 109
 110           $R->set( 'x', 'pear' );
 111
 112         or
 113
 114           $R->set( 'y', [1, 2, 3] );
 115
 116     get()
 117         Get the value of an R variable (scalar or arrayref). Example:
 118
 119           my $x = $R->get( 'x' );  # $y is an scalar
 120
 121         or
 122
 123           my $y = $R->get( 'y' );  # $x is an arrayref
 124
 125     start()
 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
 128         start().
 129
 130     stop()
 131         Stop a running instance of R.
 132
 133     restart()
 134         stop() and start() R.
 135
 136     bin()
 137         Get or set the path to the R executable.
 138
 139     is_shared()
 140         Was R started in shared mode?
 141
 142     is_started()
 143         Is R running?
 144
 145     pid()
 146         Return the pid of the running R process
 147
 148 INSTALLATION
 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
 158     calling new():
 159
 160         my $R = Statistics::R->new( r_bin => $fullpath );
 161
 162     You also need to have the following CPAN Perl modules installed:
 163
 164     Text::Balanced (>= 1.97)
 165     Regexp::Common
 166     IPC::Run
 167
 168 SEE ALSO
 169     *   Statistics::R::Win32
 170
 171     *   Statistics::R::Legacy
 172
 173     *   The R-project web site: <http://www.r-project.org/>
 174
 175     *   Statistics:: modules for Perl:
 176         <http://search.cpan.org/search?query=Statistics&mode=module>
 177
 178 AUTHORS
 179     Florent Angly <florent.angly@gmail.com> (2011 rewrite)
 180
 181     Graciliano M. P. <gm@virtuasites.com.br> (original code)
 182
 183 MAINTAINER
 184     Brian Cassidy <bricas@cpan.org>
 185
 186 COPYRIGHT & LICENSE
 187     This program is free software; you can redistribute it and/or modify it
 188     under the same terms as Perl itself.
 189
 190 BUGS
 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>
 194
 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:
 198
 199        git clone git@github.com:bricas/statistics-r.git
 200