Overview

Background

Python is a popular all-purpose scripting language, while R (an open source implementation of the S/Splus language) is a scripting language mostly popular for data analysis, statistics, and graphics. If you are reading this, there are good chances that you are at least familiar with one or both.

Having an interface between both languages to benefit from the libraries of one language while working in the other appeared desirable; an early option to achieve it was the RSPython project, itself part of the Omegahat project.

A bit later, the RPy project appeared and focused on providing simple and robust access to R from within Python, with the initial Unix-only releases quickly followed by Microsoft and MacOS compatible versions. This project is referred to as RPy-1.x in the rest of this document.

The present documentation describes RPy2, an evolution of RPy-1.x. Naturally RPy2 is inspired by RPy, but also by Alexander Belopolsky’s contributions that were waiting to be included into RPy.

This effort can be seen as a redesign and rewrite of the RPy package, and this unfortunately means there is not enough left in common to ensure compatibility.

Installation

Docker image

There are few Docker images available to try rpy2 out without even reading about requirements (e.g., R installed compiled with the shared library flag). The Docker images can also be an easy start for Windows users.

More information is available here: https://github.com/rpy2/rpy2-docker

Requirements

Currently the development is done on UNIX-like operating systems with the following software versions. Those are the recommended versions to run rpy2 with.

Software

Versions

Python

>=3.6

R

>=3.5

Running Rpy2 will require compiled libraries for R, Python, and readline; building rpy2 will require the corresponding development headers (check the documentation for more information about builing rpy2).

Note

Running rpy2 on Windows is currently not supported although relative success was recently reported with the lastest in the 3.3.x series.

Alternative Python implementations

CPython is the target implementation, and because of presence of C code in rpy2 is it currently not possible to run the package on Jython. For that same reason, running it with Pypy is expected to require some effort.

Upgrading from an older release of rpy2

In order to upgrade one will have to first remove older installed rpy2 packages then and only then install a version of rpy2.

To do so, or to check whether you have an earlier version of rpy2 installed, do the following in a Python console:

import rpy2
rpy2.__path__

An error during execution means that you do not have any older version of rpy2 installed and you should proceed to the next section.

If this returns a string containing a path, you should go to that path and remove all files and directories starting with rpy2. To make sure that the cleaning is complete, open a new Python session and check that the above code results in an error.

Download

The following options are available for download:

  • Source packages. Released versions are available on Pypi (Sourceforge is no longer used). Snapshots of the development version can be downloaded from github

    Note

    The repository on bitbucket has several release branches starting with v.

  • Pre-compiled binary packages for

    • Apple’s MacOS X are now also available on pypi

    • Linux distributions are sometimes available. Check with your distribution

Linux precompiled binaries

Linux distribution have packaging systems, and rpy2 is present in a number of them, either as a pre-compiled package or a source package compiled on-the-fly.

Note

Those versions will often be older than the latest rpy2 release.

Known distributions are: Debian and related (such as Ubuntu - often the most recent thanks to Dirk Eddelbuettel), Suse, RedHat, Mandrake, Gentoo.

OS X (MacOS) precompiled binaries

rpy2 is in Macports, Homebrew, and Fink. Binary are now also availabe on pypi.

Install from source

easy_install and pip

The source package is on the PYthon Package Index (PYPI), and the pip or easy_install scripts can be used whenever available. The shell command will then just be:

# minimal
pip install rpy2

# or
# to run tests
pip install rpy2[test]

# or
# all dependencies
pip install rpy2[all]

Upgrading an existing installation is done with:

      # recommended:
pip install rpy2 --upgrade

Both utilities have a list of options and their respective documentation should be checked for details.

Note

Starting with rpy2 3.2.0, rpy2 can built and used with cffi’s ABI or API modes (releases 3.0.x and 3.1.x were using the ABI mode exclusively). At the time of writing the default is still the ABI mode but the choice can be controlled through the environment variable RPY2_CFFI_MODE. If set, possible values are ABI (default if the environment variable is not set), API, or BOTH. When the latter, both API and ABI modes are built, and the choice of which one to use can be made at run time.

source archive

To install from a downloaded source archive <rpy_package>, do in a shell:

tar -xzf <rpy_package>.tar.gz
cd <rpy_package>


python setup.py build install
# or
pip install .
# or (to install requirements to test
pip install .[test]

This will build the package, guessing the R HOME from the R executable found in the PATH.

Compiling on Linux

Given that you have the libraries and development headers listed above, this should be butter smooth.

The most frequent errors seem to be because of missing headers.

Compiling on OS X

XCode tools will be required in order to build rpy2 in API mode. Please refer to the documentation on the Apple site for more details about what they are and how to install them.

Test an installation

An installation can be tested for functionalities, and whenever necessary the different layers constituting the packages can be tested independently.

pytest --pyargs 'rpy2.tests'

The documentation for pytest should be consulted to customize how tests are run.

Contents

The package is made of several sub-packages or modules:

rpy2.rinterface

Low-level interface to R, when speed and flexibility matter most. Close to R’s C-level API.

rpy2.robjects

High-level interface, when ease-of-use matters most. Should be the right pick for casual and general use. Based on the previous one.

rpy2.interactive

High-level interface, with an eye for interactive work. Largely based on rpy2.robjects.

rpy2.rlike

Data structures and functions to mimic some of R’s features and specificities in pure Python (no embedded R process).

Design notes

When designing rpy2, attention was given to:

  • render the use of the module simple from both a Python or R user’s perspective,

  • minimize the need for knowledge about R, and the need for tricks and workarounds,

  • allow to customize a lot while remaining at the Python level (without having to go down to C-level).

rpy2.robjects implements an extension to the interface in rpy2.rinterface by extending the classes for R objects defined there with child classes.

The choice of inheritance was made to facilitate the implementation of mostly inter-exchangeable classes between rpy2.rinterface and rpy2.robjects. For example, an rpy2.rinterface.SexpClosure can be given any rpy2.robjects.RObject as a parameter while any rpy2.robjects.Function can be given any rpy2.rinterface.Sexp. Because of R’s functional basis, a container-like extension is also present.

However, inheritance is not the only choice. Any custome class implementing the interface rpy2.rinterface.SupportsSEXP can integrate seamlessly and be used with the rest of rpy2.

Acknowledgements

Acknowledgements for contributions, support, and early testing go to (alphabetical order):

Philipp A., Alexander Belopolsky, Dan Brown, Beau Bruce, Brad Buran, Erik Cederstrand, Brad Chapman, Evgeny Cherkashin, Dav Clark, Peter Cock, Michaël Defferrard, Dirk Eddelbuettel, Isuru Fernando, Daniel Ge, Christoph Gohlke, Dale Jung, Thomas Kluyver, David Koppstein, Michał Krassowski, Antony Lee, Kenneth Lyons, Mikolaj Magnuski, Gijs Molenaar, Walter Moreira, Laurent Oget, Pablo Oliveira, John Owens, Fabian Philips, Andrey Portnoy, Nicolas Rapin, Brad Reisfeld, Joon Ro, Andy Shapiro, Justin Shenk, Grzegorz Slodkowicz, Joan Smith, Nathaniel J. Smith, Jeff Tratner, Gregory Warnes, Liang-Bo Wang, as well as the JRI author(s), the R authors, R-help list responders, Numpy list responders, and other contributors.