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/>). It lets you start R, pass commands to it and
       retrieve their output. A shared mode allows several instances of Statistics::R to talk to
       the same R process.

       The current Statistics::R implementation uses pipes (stdin, stdout and stderr) to
       communicate with R. This implementation is more efficient and reliable than that in
       versions < 0.20, which relied on reading and writing intermediary files.  As before, this
       module works on GNU/Linux, MS Windows and probably many more systems. Statistics::R has
       been tested with R version 2 and 3.

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)`);
         $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 connecting Perl and R. Available options are:

           bin Specify the full path to the R executable, 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";

                  $R1->stop; # or $R2->stop

               Note that in shared mode, you are responsible for calling the stop() method from
               one of your Statistics::R instances when you are finished. But be careful not to
               call the stop() method if 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 commands failed 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 a list of
           commands or put multiple commands in an here-doc:

              # List 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);

           Alternatively, to run commands from a file, use the run_from_file() method.

           The return value you get from run() is a combination of what R would display on the
           standard output and the standard error, but the exact 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))

           Note that older versions of R impose a limit on how many characters can be contained
           on a line: about 4076 bytes maximum. You will be warned if this occurs, with an error
           message stating:

             '\0' is an unrecognized escape in character string starting "...

           In this case, try to break down your R code into several smaller, more manageable
           statements. Alternatively, adding newline characters "\n" at strategic places in the R
           statements will work around the issue.

       run_from_file()
           Similar to run() but reads the R commands from the specified file.  Internally, this
           method converts the filename to a format compatible with R and then passes it to the R
           source() command to read the file and execute the commands.

       result()
           Get the results from the last R command.

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

             # Create an R scalar
             $R->set( 'x', 'pear' );

           or

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

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

             # Retrieve an R scalar. $x is a Perl scalar.
             my $x = $R->get( 'x' );

           or

             # Retrieve an R list. $x is a Perl arrayref.
             my $y = $R->get( 'y' );

       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. You need to call this method after running a shared
           bridge. For a simple bridge, you do not need to do this because stop() is
           automatically called when the Statistics::R object goes out of scope.

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

       bin()
           Get or set the path to the R executable. Note that the path will be available only
           after start() has been called.

       version()
           Get the version number of R.

       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/>. 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 where R is installed, your last recourse is to specify its full path when calling
       new():

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

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

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

SEE ALSO

       •   Statistics::R::Win32

       •   Statistics::R::Legacy

       •   The R-project web site: <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)

MAINTAINERS

       Florent Angly <florent.angly@gmail.com>

       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>

       Bug reports, suggestions and patches are welcome. The Statistics::R code is developed on
       Github (<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