.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Statistics::R 3pm"
.TH Statistics::R 3pm "2011-11-22" "perl v5.12.4" "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/ <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
\&\fIStatistics::R\fR talk to the same R process.
.PP
The current \fIStatistics::R\fR 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, \s-1MS\s0 Windows and probably many
more systems.
.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 , 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(\*(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 "\fInew()\fR" 4
.IX Item "new()"
Build a \fIStatistics::R\fR bridge object between Perl and R. Available options are:
.RS 4
.IP "r_bin" 4
.IX Item "r_bin"
Specify the full path to R if it is not automatically found. See \s-1INSTALLATION\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";
.Ve
.Sp
Do not call the \fI\fIstop()\fI\fR method is you still have processes that need to interact
with R.
.RE
.RS 4
.RE
.IP "\fIrun()\fR" 4
.IX Item "run()"
First, \fIstart()\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 command fails 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 an array
of commands or put multiple commands in an here-doc:
.Sp
.Vb 7
\&   # 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(\*(Aqok\*(Aq)
\&   EOF
\&   my $out2 = $R\->run($cmds);
.Ve
.Sp
To run commands from a file, see the \fIrun_from_file()\fR method.
.Sp
The output you get from \fIrun()\fR 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:
.Sp
.Vb 1
\&   suppressPackageStartupMessages(library(library_to_load))
.Ve
.IP "\fIrun_from_file()\fR" 4
.IX Item "run_from_file()"
Similar to \fIrun()\fR but reads the R commands from the specified file. Internally,
this method uses the R \fIsource()\fR command to read the file.
.IP "\fIset()\fR" 4
.IX Item "set()"
Set the value of an R variable (scalar or arrayref). Example:
.Sp
.Vb 1
\&  $R\->set( \*(Aqx\*(Aq, \*(Aqpear\*(Aq );
.Ve
.Sp
or
.Sp
.Vb 1
\&  $R\->set( \*(Aqy\*(Aq, [1, 2, 3] );
.Ve
.IP "\fIget()\fR" 4
.IX Item "get()"
Get the value of an R variable (scalar or arrayref). Example:
.Sp
.Vb 1
\&  my $x = $R\->get( \*(Aqx\*(Aq );  # $y is an scalar
.Ve
.Sp
or
.Sp
.Vb 1
\&  my $y = $R\->get( \*(Aqy\*(Aq );  # $x is an arrayref
.Ve
.IP "\fIstart()\fR" 4
.IX Item "start()"
Explicitly start R. Most times, you do not need to do that because the first
execution of \fIrun()\fR or \fIset()\fR will automatically call \fIstart()\fR.
.IP "\fIstop()\fR" 4
.IX Item "stop()"
Stop a running instance of R.
.IP "\fIrestart()\fR" 4
.IX Item "restart()"
\&\fIstop()\fR and \fIstart()\fR R.
.IP "\fIbin()\fR" 4
.IX Item "bin()"
Get or set the path to the R executable.
.IP "\fIis_shared()\fR" 4
.IX Item "is_shared()"
Was R started in shared mode?
.IP "\fIis_started()\fR" 4
.IX Item "is_started()"
Is R running?
.IP "\fIpid()\fR" 4
.IX Item "pid()"
Return the pid 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/ <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 R installation, your last recourse is to specify its full path when calling
\&\fInew()\fR:
.PP
.Vb 1
\&    my $R = Statistics::R\->new( r_bin => $fullpath );
.Ve
.PP
You also need to have the following \s-1CPAN\s0 Perl modules installed:
.IP "Text::Balanced (>= 1.97)" 4
.IX Item "Text::Balanced (>= 1.97)"
.PD 0
.IP "Regexp::Common" 4
.IX Item "Regexp::Common"
.IP "IPC::Run" 4
.IX Item "IPC::Run"
.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/ <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 "MAINTAINER"
.IX Header "MAINTAINER"
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 <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 <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