NAME
    Statistics::R - Controls the R interpreter through Perl.

DESCRIPTION
    This module controls the R interpreter (R project for statistical
    computing: <http://www.r-project.org/>). Multiple architectures and OS
    are supported and a single instance of R can be accessed by several Perl
    processes.

SYNOPSIS
      use Statistics::R;
  
      # Create a communication bridge with R and start R
      my $R = Statistics::R->new();
  
      # Run simple R commands
      $R->run(q`postscript("file.ps" , 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
      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()
        Create a Statistics::R bridge object between Perl and R and start()
        R. Available options are:

        shared
            Start a shared bridge. See start().

        log_dir
            The directory where the bridge between R and Perl will be
            created.

            R and Perl need to have read and write access to the directory
            and Perl will change to this directory!

            *By default it will be created at *%TMP_DIR%/Statistics-R*.*

        r_bin
            The path to the R binary.

            *By default the path will be searched in the default
            installation path of R in the OS.*

        r_dir
            The directory of R.

        tmp_dir
            A temporary directory.

            *By default the temporary directory of the OS will be used*

    start()
        Start R and set the communication bridge between Perl and R. Pass
        the option shared => 1 to use an already running bridge.

    stop()
        Stop R and stop the bridge.

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

    bin()
        Return the path to the R binary (executable).

    send($CMD)
        Send some command to be executed inside R. Note that *$CMD* will be
        loaded by R with *source()*

    receive($TIMEOUT)
        Get the output of R for the last group of commands sent to R by
        *send()*.

    lock()
        Lock the bridge for your PID.

    unlock()
        Unlock the bridge if your PID have locked it.

    is_locked()
        Return *TRUE* if the bridge is locked for your PID.

        In other words, returns *TRUE* if other process has *lock()ed* the
        bridge.

    is_started()
        Return *TRUE* if the R interpreter is started, or still started.

    clean_up()
        Clean up the environment, removing all the objects.

INSTALL
    To install this package you need to install R on your system first,
    since *Statistics::R* need to find R path to work.

    A standard installation of R on Win32 or Linux will work fine and be
    detected automatically by *Statistics::R*.

    Download page of R: <http://cran.r-project.org/banner.shtml>

    Or go to the R web site: <http://www.r-project.org/>

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

    Text::Balanced
    Regexp::Common

EXECUTION FOR MULTIPLE PROCESSES
    The main purpose of *Statistics::R* is to start a single R interpreter
    that listens to multiple Perl processes.

    Note that to do that R and Perl need to be running with the same
    user/group level.

    To start the *Statistics::R* bridge, you can use the script
    *statistics-r.pl*:

      $> statistics-r.pl start

    From your script you need to use the *start()* option in shared mode:

      use Statistics::R;
  
      my $R = Statistics::R->new();
  
      $R->start( shared => 1 );
  
      $R->send('x = 123');
  
      exit;

    Note that in the example above the method *stop()* wasn't called, since
    it will close the bridge.

SEE ALSO
    *   Statistics::R::Bridge

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

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

AUTHOR
    Graciliano M. P. <gm@virtuasites.com.br>

MAINTAINERS
    Brian Cassidy <bricas@cpan.org>

    Florent Angly <florent.angly@gmail.com>

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