Statistics::R(3pm)

📦
version 0.34 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Statistics::R 💖

okay bestie, listen — this is a page from User Contributed Perl Documentation, and it's all about Statistics::R, the Perl interface to the R statistical program. buckle up, it's giving ✨bridge between two worlds✨ and i'm obsessed.

🌸 NAME 🌸

Statistics::R — Perl interface with the R statistical program. periodt. 💅

🦋 DESCRIPTION 🦋

so like, Statistics::R is a module that controls the R interpreter (that's the R project for statistical computing, over at <http://www.r-project.org/>). it lets you start R, yeet commands at it, and get the output back. and there's a shared mode where several instances of Statistics::R can all talk to the same R process. group chat energy fr fr. 🫶

the current Statistics::R implementation uses pipes (stdin, stdout and stderr) to talk to R. this is more efficient and reliable than the versions < 0.20, which were out here reading and writing intermediary files like it's 2009 😭. as before, this module works on GNU/Linux, MS Windows and probably a bunch more systems. Statistics::R has been tested with R version 2 and 3. iconic behavior only. 👑

✨ SYNOPSIS ✨

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('x', $input_value);
$R->run(q`y <- x^2`);
my $output_value = $R->get('y');
print "y = $output_value\n";

$R->stop();

look at that. a whole relationship built in ten lines. 💖

💅 METHODS 💅

new()

Build a Statistics::R bridge object connecting Perl and R. available options are:

  • bin — specify the full path to the R executable, if it's not automatically found. see INSTALLATION below bestie.
  • shared — start a shared bridge. when you use a shared bridge, several instances of Statistics::R can communicate with the same unique R instance. example:
use Statistics::R;

my $R1 = Statistics::R->new( shared => 1);
my $R2 = Statistics::R->new( shared => 1);

$R1->set( 'x', 'pear' );
my $x = $R2->get( 'x' );
print "x = $x\n";

$R1->stop; # or $R2->stop
⚠️ note that in shared mode, you are responsible for calling the stop() method from one of your Statistics::R instances when you're finished. but be careful — do not call stop() if you still have processes that need to interact with R! that's a vibe kill and also a bug. 😭

run()

first, start() R if it isn't running yet. 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. rude of it, but okay. 💀

example:

my $out = $R->run( q`print( 1 + 2 )` );

if you're planning to run many R commands, it may be convenient to pass a list of commands or put multiple commands in a here-doc:

# 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('ok')
EOF
my $out2 = $R->run($cmds);

alternatively, to run commands from a file, use the run_from_file() method. we love options. 🌈

the return value you get from run() is a combination of what R would display on the standard output and the standard error, but the exact order may differ. so don't come for me about ordering. 🙈

when loading modules, some may write numerous messages on standard error. you can disable this behavior using the following R command:

suppressPackageStartupMessages(library(library_to_load))
🚨 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: '\0' is an unrecognized escape in character string starting "...

in this case, try to break down your R code into several smaller, more manageable statements. alternatively, adding newline characters "\n" at strategic places in the R statements will work around the issue. slay and strategize. 🎀

run_from_file()

similar to run() 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 source() command to read the file and execute the commands. it's giving delegation. 👑

result()

get the results from the last R command. that's it. that's the whole method. ✨

set()

set the value of an R variable (scalar or vector). example:

# Create an R scalar
$R->set( 'x', 'pear' );

or

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

get()

get the value of an R variable (scalar or vector). example:

# Retrieve an R scalar. $x is a Perl scalar.
my $x = $R->get( 'x' );

or

# Retrieve an R list. $x is a Perl arrayref.
my $y = $R->get( 'y' );

start()

explicitly start R. most times you do not need to do that, because the first execution of run() or set() will automatically call start(). she's independent, she starts herself. 💅

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 stop() is automatically called when the Statistics::R object goes out of scope. she cleans up after herself, main character energy. ✨

restart()

stop() and start() R. that's the whole thing. rebirth. 🦋

bin()

get or set the path to the R executable. note that the path will be available only after start() has been called. patience bestie. 🧚

version()

get the version number of R.

is_shared()

was R started in shared mode?

is_started()

is R running?

pid()

return the PID of the running R process. yes, the actual PID. we're tracking her. 🔥

🌈 INSTALLATION 🌈

since Statistics::R 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 PATH environment variable, then it should be available from a terminal and be detected automatically by Statistics::R. this means you don't 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. if Statistics::R does not find where R is installed, your last recourse is to specify its full path when calling new():

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

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

  • IPC::Run
  • Regexp::Common
  • Text::Balanced (>= 1.97)
  • Text::Wrap
  • version (>= 0.77)

🫶 SEE ALSO 🫶

👑 AUTHORS 👑

  • Florent Angly <florent.angly@gmail.com> (2011 rewrite)
  • Graciliano M. P. <gm@virtuasites.com.br> (original code)

💜 MAINTAINERS 💜

  • Florent Angly <florent.angly@gmail.com>
  • Brian Cassidy <bricas@cpan.org>

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. i know, heartbreaking. 😭

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

okay that's the whole page bestie, no cap. 💖 this was generated from perl v5.38.2, dated 2024-05-16 — stay hydrated, go clone the repo, and remember: if R isn't running, start() will handle it for you. periodt. ✨💅🦋

📦 where this page comes from