UCS::R - UCS/Perl interface to R
use UCS::R;
UCS::R::Start(); # start R backend explicitly
UCS::R::Stop(); # terminate R backend (if possible)
@x = UCS::R::Exec($cmd); # execute R cmd (must return numeric vector)
UCS::R::LoadVector("my.x", \@data); # load numeric vector efficiently into R
$data = UCS::R::DumpVector("my.x"); # returns arrayref
# access to special functions and statistical distributions
# through the UCS::SFunc module
The UCS::R module provides an interface to the R statistical environment and the UCS/R libraries on an R interpreter running in the background. When available (as determined by the installation script), the RSPerl interface is used for efficient communication with the R interpreter. Otherwise, the system falls back on the Statistics::R bridge or a slow but portable solution that simulates an interactive R session through use of the Expect module. See the UCS::R::RSPerl, UCS::R::Expect and UCS::R::Statistics manpages for some details on the strengths and limitations of these backends.
The UCS::R interface is mainly used by the UCS::SFunc module to make the R implementations of special functions (binomial coefficients, Gamma function, Beta function) and statistical distributions (binomial, Poisson, normal, chi-squared, hypergeometric) available to UCS/Perl, without relying on an external maths library and/or compiled C code.
Starts the R interpreter. Normally, this function does not have to be called explicitly, as the backend is automatically launched when an R command is executed for the first time. Since this will block program execution for a few seconds, some scripts may prefer to call UCS::R::Start at start-up time before the R process is actually needed.
Terminate the R interpreter. Normally, this function does not have to be called explicitly, but it may be used to shut down an R process that is no longer needed and free memory resources. Note that this function is not supported by the UCS::R::RSPerl backend and will be silently ignored.
Executes the R command $cmd in the server process. The command must return a vector, which is passed back to the calling script in the form of a list @x. When command execution fails or its return value cannot be parsed, the UCS::R::Exec function will die with an error message.
At the moment, only numeric vectors are guaranteed to work (although the UCS::R::RSPerl backend should support all types of vectors). It is safe to execute any command when UCS::R::Exec is called in void context. When using the UCS::R::Expect backend, complex return values should be made invisible for reasons of speed and robustness.
NB: This interface is not efficient for exchanging large amounts of data with R and may hang if the input/output buffers overflow. Use the LoadVector and DumpVector functions for this purpose (see below). Moreover, $cmd must be a single-line command (separate multiple commands with ;), so that it leaves a single command prompt at the beginning of a line after execution. Avoid cat() and any functions that prompt for user input, otherwise UCS::R::Exec will become confused and may hang.
Efficiently loads a numeric vector into R (making use of a temporary file and the scan function in R). The data @data are passed in as an array reference and will be stored in the R variable $varname.
Efficiently reads a numeric vector from R (making use of a temporary file and the write() function). The data stored in the R variable $varname (which must be a numeric vector) are returned as an anonymous array reference $data.
The special functions and statistical distributions provided through the R interface are not exported by this module. Use UCS::SFunc instead. All available functions are documented in the UCS::SFunc manpage. They are available under the same names in the UCS::R package. For instance, the R implementation of the lgamma function can be accessed explicitly as UCS::R::lgamma.
Copyright 2004-2005 Stefan Evert.
This software is provided AS IS and the author makes no warranty as to its use and performance. You may use the software, redistribute and modify it under the same terms as Perl itself.