NAME
    Statistics::R - Perl interface to control the R statistical program

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
            A directory where temporary files necessary for the bridge
            between R and Perl will be stored.

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

            *By default this will be a folder called Statistics-R and placed
            in a temporary directory of the system*

        r_bin
            The path to the R binary. See *INSTALLATION*.

    set()
        Set the value of an R variable, e.g.

          $R->set( 'x', "apple" );

        or

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

    get( $)
        Get the value of an R variable, e.g.

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

        or

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

    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()*. Prefer the run() command.

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

    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.

INSTALLATION
    To install this package you need to install R on your system first,
    since *Statistics::R* need to find R path to work. 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 do not
    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. Your last recourse if *Statistics::R* does not find
    R is to specify its full path when calling new():

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

    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
    File::Which

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->run('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