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 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 runnning 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))

        Note that R imposes an upper limit on how many characters can be
        contained on a line: about 4076 bytes maximum. You will be warned if
        this occurs. Commands containing lines exceeding the limit may fail
        with an error message stating:

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

        If possible, 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 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 a 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/>. 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:

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

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)

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>

    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