.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Statistics::R 3pm"
.TH Statistics::R 3pm "2022-09-17" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Statistics::R \- Perl interface with the R statistical program
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIStatistics::R\fR 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 \fIStatistics::R\fR to talk to the same R process.
.PP
The current \fIStatistics::R\fR 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, \s-1MS\s0 Windows and probably many more
systems. \fIStatistics::R\fR has been tested with R version 2 and 3.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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(\*(Aqx\*(Aq, $input_value);
\&  $R\->run(q\`y <\- x^2\`);
\&  my $output_value = $R\->get(\*(Aqy\*(Aq);
\&  print "y = $output_value\en";
\&
\&  $R\->stop();
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Build a \fIStatistics::R\fR bridge object connecting Perl and R. Available options
are:
.RS 4
.IP "bin" 4
.IX Item "bin"
Specify the full path to the R executable, if it is not automatically found. See
\&\*(L"\s-1INSTALLATION\*(R"\s0.
.IP "shared" 4
.IX Item "shared"
Start a shared bridge. When using a shared bridge, several instances of 
Statistics::R can communicate with the same unique R instance. Example:
.Sp
.Vb 1
\&   use Statistics::R;
\&
\&   my $R1 = Statistics::R\->new( shared => 1);
\&   my $R2 = Statistics::R\->new( shared => 1);
\&
\&   $R1\->set( \*(Aqx\*(Aq, \*(Aqpear\*(Aq );
\&   my $x = $R2\->get( \*(Aqx\*(Aq );
\&   print "x = $x\en";
\&
\&   $R1\->stop; # or $R2\->stop
.Ve
.Sp
Note that in shared mode, you are responsible for calling the \fI\f(BIstop()\fI\fR method
from one of your Statistics::R instances when you are finished. But be careful
not to call the \fI\f(BIstop()\fI\fR method if you still have processes that need to
interact with R!
.RE
.RS 4
.RE
.IP "\fBrun()\fR" 4
.IX Item "run()"
First, \fI\f(BIstart()\fI\fR 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.
.Sp
Example:
.Sp
.Vb 1
\&   my $out = $R\->run( q\`print( 1 + 2 )\` );
.Ve
.Sp
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:
.Sp
.Vb 7
\&   # 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(\*(Aqok\*(Aq)
\&   EOF
\&   my $out2 = $R\->run($cmds);
.Ve
.Sp
Alternatively, to run commands from a file, use the \fI\f(BIrun_from_file()\fI\fR method.
.Sp
The return value you get from \fI\f(BIrun()\fI\fR is a combination of what R would display
on the standard output and the standard error, but the exact order may differ.
.Sp
When loading modules, some may write numerous messages on standard error. You
can disable this behavior using the following R command:
.Sp
.Vb 1
\&   suppressPackageStartupMessages(library(library_to_load))
.Ve
.Sp
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:
.Sp
.Vb 1
\&  \*(Aq\e0\*(Aq is an unrecognized escape in character string starting "...
.Ve
.Sp
In this case, try to break down your R code into several smaller, more
manageable statements. Alternatively, adding newline characters \*(L"\en\*(R" at
strategic places in the R statements will work around the issue.
.IP "\fBrun_from_file()\fR" 4
.IX Item "run_from_file()"
Similar to \fI\f(BIrun()\fI\fR 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 \fI\f(BIsource()\fI\fR command to read the file and execute the
commands.
.IP "\fBresult()\fR" 4
.IX Item "result()"
Get the results from the last R command.
.IP "\fBset()\fR" 4
.IX Item "set()"
Set the value of an R variable (scalar or vector). Example:
.Sp
.Vb 2
\&  # Create an R scalar
\&  $R\->set( \*(Aqx\*(Aq, \*(Aqpear\*(Aq );
.Ve
.Sp
or
.Sp
.Vb 2
\&  # Create an R list
\&  $R\->set( \*(Aqy\*(Aq, [1, 2, 3] );
.Ve
.IP "\fBget()\fR" 4
.IX Item "get()"
Get the value of an R variable (scalar or vector). Example:
.Sp
.Vb 2
\&  # Retrieve an R scalar. $x is a Perl scalar.
\&  my $x = $R\->get( \*(Aqx\*(Aq );
.Ve
.Sp
or
.Sp
.Vb 2
\&  # Retrieve an R list. $x is a Perl arrayref.
\&  my $y = $R\->get( \*(Aqy\*(Aq );
.Ve
.IP "\fBstart()\fR" 4
.IX Item "start()"
Explicitly start R. Most times, you do not need to do that because the first
execution of \fI\f(BIrun()\fI\fR or \fI\f(BIset()\fI\fR will automatically call \fI\f(BIstart()\fI\fR.
.IP "\fBstop()\fR" 4
.IX Item "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
\&\fI\f(BIstop()\fI\fR is automatically called when the Statistics::R object goes out of
scope.
.IP "\fBrestart()\fR" 4
.IX Item "restart()"
\&\fI\f(BIstop()\fI\fR and \fI\f(BIstart()\fI\fR R.
.IP "\fBbin()\fR" 4
.IX Item "bin()"
Get or set the path to the R executable. Note that the path will be available
only after \fBstart()\fR has been called.
.IP "\fBversion()\fR" 4
.IX Item "version()"
Get the version number of R.
.IP "\fBis_shared()\fR" 4
.IX Item "is_shared()"
Was R started in shared mode?
.IP "\fBis_started()\fR" 4
.IX Item "is_started()"
Is R running?
.IP "\fBpid()\fR" 4
.IX Item "pid()"
Return the \s-1PID\s0 of the running R process
.SH "INSTALLATION"
.IX Header "INSTALLATION"
Since \fIStatistics::R\fR 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 \s-1PATH\s0
environment variable, then it should be available from a terminal and be
detected automatically by \fIStatistics::R\fR. This means that you don't have to do
anything on Linux systems to get \fIStatistics::R\fR working. On Windows systems,
in addition to the folders described in \s-1PATH,\s0 the usual suspects will be checked
for the presence of the R binary, e.g. C:\eProgram Files\eR. If \fIStatistics::R\fR
does not find where R is installed, your last recourse is to specify its full
path when calling \fBnew()\fR:
.PP
.Vb 1
\&    my $R = Statistics::R\->new( bin => $fullpath );
.Ve
.PP
You also need to have the following \s-1CPAN\s0 Perl modules installed:
.IP "IPC::Run" 4
.IX Item "IPC::Run"
.PD 0
.IP "Regexp::Common" 4
.IX Item "Regexp::Common"
.IP "Text::Balanced (>= 1.97)" 4
.IX Item "Text::Balanced (>= 1.97)"
.IP "Text::Wrap" 4
.IX Item "Text::Wrap"
.IP "version (>= 0.77)" 4
.IX Item "version (>= 0.77)"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Statistics::R::Win32
.IP "\(bu" 4
Statistics::R::Legacy
.IP "\(bu" 4
The R\-project web site: <http://www.r\-project.org/>
.IP "\(bu" 4
Statistics::* modules for Perl: <http://search.cpan.org/search?query=Statistics&mode=module>
.SH "AUTHORS"
.IX Header "AUTHORS"
Florent Angly <florent.angly@gmail.com> (2011 rewrite)
.PP
Graciliano M. P. <gm@virtuasites.com.br> (original code)
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
Florent Angly <florent.angly@gmail.com>
.PP
Brian Cassidy <bricas@cpan.org>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "BUGS"
.IX Header "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 \s-1CPAN\s0 Tracker of Statistics::R:
<http://rt.cpan.org/Dist/Display.html?Name=Statistics\-R>
.PP
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:
.PP
.Vb 1
\&   git clone git://github.com/bricas/statistics\-r.git
.Ve