NAME

       Statistics::R - Perl interface with the R statistical program

DESCRIPTION

       Statistics::R is a module to controls the R interpreter (R project for statistical
       computing: http://www.r-project.org/ <http://www.r-project.org/>). It lets you start R,
       pass commands to it and retrieve the output. A shared mode allow to have several instances
       of Statistics::R talk to the same R process.

       The current Statistics::R implementation uses pipes (for stdin, stdout and and stderr) to
       communicate with R. This implementation should be more efficient and reliable than that in
       previous version, which relied on reading and writing files. As before, this module works
       on GNU/Linux, MS Windows and probably many more systems.

SYNOPSIS

         use Statistics::R;

         # Create a communication bridge with R and start R
         my $R = Statistics::R->new();

         # Run simple R commands
         my $output_file = "file.ps";
         $R->run(qq`postscript("$output_file" , horizontal=FALSE , width=500 , height=500 , pointsize=1)`);
         $R->run(q`plot(c(1, 5, 10), type = "l")`);
         $R->run(q`dev.off()`);

         # Pass and retrieve data (scalars or arrays)
         my $input_value = 1;
         $R->set('x', $input_value);
         $R->run(q`y <- x^2`);
         my $output_value = $R->get('y');
         print "y = $output_value\n";

         $R->stop();

METHODS

       new()
           Build a Statistics::R bridge object between Perl and R. Available options are:

           r_bin
               Specify the full path to R if it is not automatically found. See INSTALLATION.

           shared
               Start a shared bridge. When using a shared bridge, several instances of
               Statistics::R can communicate with the same unique R instance. Example:

                  use Statistics::R;

                  my $R1 = Statistics::R->new( shared => 1);
                  my $R2 = Statistics::R->new( shared => 1);

                  $R1->set( 'x', 'pear' );
                  my $x = $R2->get( 'x' );
                  print "x = $x\n";

               Do not call the stop() method is you still have processes that need to interact
               with R.

       run()
           First, start() R if it is not yet running. Then, execute R commands passed as a string
           and return the output as a string. If your command fails to run in R, an error message
           will be displayed.

           Example:

              my $out = $R->run( q`print( 1 + 2 )` );

           If you intend on running many R commands, it may be convenient to pass an array of
           commands or put multiple commands in an here-doc:

              # Array of R commands:
              my $out1 = $R->run(
                 q`a <- 2`,
                 q`b <- 5`,
                 q`c <- a * b`,
                 q`print("ok")`
              );

              # Here-doc with multiple R commands:
              my $cmds = <<EOF;
              a <- 2
              b <- 5
              c <- a * b
              print('ok')
              EOF
              my $out2 = $R->run($cmds);

           To run commands from a file, see the run_from_file() method.

           The output you get from run() is the combination of what R would display on the
           standard output and the standard error, but the order may differ. When loading
           modules, some may write numerous messages on standard error. You can disable this
           behavior using the following R command:

              suppressPackageStartupMessages(library(library_to_load))

       run_from_file()
           Similar to run() but reads the R commands from the specified file. Internally, this
           method uses the R source() command to read the file.

       set()
           Set the value of an R variable (scalar or arrayref). Example:

             $R->set( 'x', 'pear' );

           or

             $R->set( 'y', [1, 2, 3] );

       get()
           Get the value of an R variable (scalar or arrayref). Example:

             my $x = $R->get( 'x' );  # $y is an scalar

           or

             my $y = $R->get( 'y' );  # $x is an arrayref

       start()
           Explicitly start R. Most times, you do not need to do that because the first execution
           of run() or set() will automatically call start().

       stop()
           Stop a running instance of R.

       restart()
           stop() and start() R.

       bin()
           Get or set the path to the R executable.

       is_shared()
           Was R started in shared mode?

       is_started()
           Is R running?

       pid()
           Return the pid of the running R process

INSTALLATION

       Since Statistics::R relies on R to work, you need to install R first. See this page for
       downloads, http://www.r-project.org/ <http://www.r-project.org/>. If R is in your PATH
       environment variable, then it should be available from a terminal and be detected
       automatically by Statistics::R. This means that you don't have to do anything on Linux
       systems to get Statistics::R working. On Windows systems, in addition to the folders
       described in PATH, the usual suspects will be checked for the presence of the R binary,
       e.g. C:\Program Files\R. If Statistics::R does not find R installation, your last recourse
       is to specify its full path when calling new():

           my $R = Statistics::R->new( r_bin => $fullpath );

       You also need to have the following CPAN Perl modules installed:

       Text::Balanced (>= 1.97)
       Regexp::Common
       IPC::Run

SEE ALSO

       •   Statistics::R::Win32

       •   Statistics::R::Legacy

       •   The R-project web site: http://www.r-project.org/ <http://www.r-project.org/>

       •   Statistics:: modules for Perl:
           <http://search.cpan.org/search?query=Statistics&mode=module>

AUTHORS

       Florent Angly <florent.angly@gmail.com> (2011 rewrite)

       Graciliano M. P. <gm@virtuasites.com.br> (original code)

MAINTAINER

       Brian Cassidy <bricas@cpan.org>

COPYRIGHT & LICENSE

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

BUGS

       All complex software has bugs lurking in it, and this program is no exception.  If you
       find a bug, please report it on the CPAN Tracker of Statistics::R:
       http://rt.cpan.org/Dist/Display.html?Name=Statistics-R
       <http://rt.cpan.org/Dist/Display.html?Name=Statistics-R>

       Bug reports, suggestions and patches are welcome. The Statistics::R code is developed on
       Github (http://github.com/bricas/statistics-r <http://github.com/bricas/statistics-r>) and
       is under Git revision control. To get the latest revision, run:

          git clone git@github.com:bricas/statistics-r.git