RPy - Python interface to the R Programming Language

1.  WHAT IS RPy?

RPy is a very simple, yet robust, Python interface to the R
Programming Language (http://www.r-project.org).  It can manage all
kinds of R objects and can execute arbitrary R functions (including
the graphic functions).  All the errors from the R language are
converted to Python exceptions.  Any module that later were installed
on the R system, can easily be used from within Python, without
introducing any changes.

Versions 0.1 and 0.2 work only on POSIX systems.  Version 0.3 also
includes Windows support (although, some capabilities are missing, see
the reference manual for details).

See the file NEWS for details on the lastest changes.

This code is inspired in RSPython from the Omegahat project
(http://www.omegahat.org/RSPython).


2.  INSTALLATION

You need Python and R interpreters.  At least, Python 2.1 and R
1.5.0 is required.  I have tested it only on Linux and Solaris, but
it should compile on any POSIX system.  It has been reported
successful compilations on Linux, Solaris, FreeBSD and MacOS X.
Please, send me a note if you can compile it with other versions or
under other platforms.

Linux and Unix Binary Installation
----------------------------------

Binary packages for rpy are available for Debian GNU/Linux via the
standard mechanisms.

Other binary packages may be available from the rpy download site.


Linux and Unix Source Installation:
----------------------------

If you have Numeric (NumPy) installed, it can be used by RPy; normally it is
autodetected, you don't have to do anything.  If Numeric cannot be found, then
R arrays will be converted to Python lists, which are a lot more inefficient
than Numeric arrays.  I strongly suggest to install Numeric.

If you have installed some previous version of RPy, just go to (c).

To install RPy follow the steps:

(a) First of all, you *must* check that you have built R with the configure
    option '--enable-R-shlib', in order to make R as a shared library.  If
    not, the following steps should be enough:

        <go to the R source directory>
        make distclean
        ./configure --enable-R-shlib
        make
        make install

    (Solaris users, please, see the note (a) below.)

(b) Then, configure the path to the R library.  You have several ways to do
    this (substitute RHOME with the path where R is installed, usually
    /usr/local/lib/R):

        o make a link to RHOME/bin/libR.so in /usr/local/lib or /usr/lib, then
          run 'ldconfig',

        o or, put the following line in your .bashrc (or equivalent):

            export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:RHOME/bin

        o or, edit the file /etc/ld.so.conf and add the following line:

            RHOME/bin

          and then, run 'ldconfig'.

(c) Ensure that you have the necessary header files for the version of R you are 
    compiling against.  You can check the version of R by running:

 	R --version

    which will yeild something like:

	[warneg@glnx010 rpy]$ R --version
	R 2.0.0 (2004-10-04).
	Copyright (C) 2004 R Development Core Team
	
	R is free software and comes with ABSOLUTELY NO WARRANTY.
	You are welcome to redistribute it under the terms of the GNU
	General Public License.  For more information about these matters,
	see http://www.gnu.org/copyleft/gpl.html.

    There should be a subdirectory of the Rpy package with the names

   	R-<version>

    e.g., for the example above,

        R-2.0.0

    If this correct version directory does not exist, you will need
    to download the R source tarball R-$(VERSION).tgz from CRAN
    (http://cran.r-project.org).  From within the rpy package
    directory you can then do:

	tar -xvzf <path>/R-<version>.tgz R-<version>/src/include

    to extract the necessary files.

(d) Now, just type:

        python setup.py install

    and that's all!

If you want, you can run the regression tests located in the 'tests'
directory, just read the README file in that directory.  For a quickier test,
launch the Python interpreter and import the module 'rpy':

    Python 2.2 (#2, Dec 23 2001, 16:30:35)
    [GCC 2.95.4 20010703 (Debian prerelease)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import rpy
    >>>

If you get some error, refer to TROUBLESHOOTING below.  If you want to test
the module without installing it, do:

    python setup.py build

Then, cd to build/lib.<platform>-<version>/ and try to import the module.

*** NOTES ***

(a) Solaris users must change the line:

        LIBR_LDFLAGS = -shared

    in the file 'Makeconf' on the R source directory, for the line:

        LIBR_LDFLAGS = -shared -symbolic

    before recompiling the R library.

(b) It has been reported that it may be necessary, in some situations,
    to completely remove the R sources, to unpack it again, and to
    compile to R library with the new options.


Windows Binary Installation:
----------------------------

The Windows version of RPy is provided as a binary bundle.  It is
compiled with Python 2.3 and with Numeric support.

Before installing RPy, make sure you have installed:

    o Python 2.2
    o R (a recent version)
    o Numeric  (http://numpy.sf.net)
    o win32all, windows extensions from Mark Hammond
      (http://starship.python.net/crew/mhammond/win32/Downloads.html)

Then, just download the file 'rpy-0.3.win32-py2.2.exe', and execute
it.  You may want to download the documentation, also, which is in a
separate bundle.

Finally, make sure that the R bin directory is in your path.  This holds
the R.dll that python needs to load for rpy to work.  For R version
1.6.1 this path is (by default)

    C:\Program Files\R\rw1061\bin\

For windows 98 or ME it is easier to use the path
C:\Progra~1\R\rw1061\bin instead.

Under Windows 2000 right click on "My Computer" select properties.  Now
click the Advanced tab and select environment variables.  Finally edit
the path variable under system variables and add

    C:\Program Files\R\rw1061\bin\

to your path.  Make sure that all paths are seperated by semi-colons.

All others need to edit the Autoexec.bat file and add a line similar to:

    set PATH=%PATH%;C:\Progra~1\R\rw1061\bin

near the end.

*** NOTES ***

Please, read the section 'Caveat and bugs' of the reference manual,
for details on some limitations of the Windows version.

Many thanks to Rene Hagendoorn, who provides the patches for making
the Windows version.

Windows Source Installation
---------------------------

To build RPy for Windows from scratch using Visual C++:

Step 0:  Unpack the rpywin source package (rpy-X.YY.zip)

Step 1:  Install the latest version of Windows R from cran.r-project.org

         I put R 2.0.0 into C:\Program Files\R\rw2000

Step 2:  Install the latest source code for R from cran.r-project.org

         I put this into C:\Program Files\R\src\R-2.0.0

Step 3:  Install the tools described on the "Building R for Windows"
         web portal: http://www.stats.ox.ac.uk/pub/Rtools

         I installed MinGW into C:\Program Files\MinGW

         I installed the "tools bundle" into C:\Program Files\R\tools

Step 4:  Modify the system path to include all of the tools you will
         need.  I did this on Win2000 using Start -> Settings ->
         Control Panel -> System -> Advanced -> Environment Variables

         My path [with a newline added after each ';' for clarity,
         remove these for the actual variable value!] is:

            C:\Progra~1\Micros~3\Common\MSDev98\Bin;
            C:\Progra~1\Micros~3\VC98\BIN;
            C:\Progra~1\Micros~3\Common\TOOLS;
            C:\Progra~1\Micros~3\Common\TOOLS\WINNT;
            C:\Progra~1\Micros~2\Office;
            C:\WINNT\system32;
            C:\WINNT;
            C:\WINNT\System32\Wbem;
            C:\Progra~1\R\rw1081\bin;
            C:\Progra~1\R\tools;
            C:\Progra~1\R\tools\bin;
            C:\python23;

         IMPORTANT: Use the alternative 8 character name for any long
         names or names that contain spaces anywhere in the path.

         Note that this list includes several Visual C directories,
         the bin directory of the installed version of R, the tools
         directory, the MinGW bin directory, and the python directory.

Step 5:  Create a windows library entry point (lib) file from the R 
         symbols file to use during linking.

         Open a command window, and change to the rpy directory.
         Then do

            set RHOME=C:\Progra~1\R\rw2000

            lib /def:%RHOME%\src\gnuwin32\R.exp /machine:ix86
                /out:%RHOME%/bin/Rdll.lib

         [The lib command should be all on one line.]

           ALTERNATIVE (added by Matjaz Kukar)
           You may also using pexports, see distutils documentation or
           http://starship.python.net/crew/kernr/mingw32/Notes.html):

           pexports %RHOME%/bin/R.dll > %RHOME%/bin/Rdll.def
           lib/def:%RHOME%/bin/Rdll.def /out:%RHOME%/bin/Rdll.lib /machine:ix86

           Somehow, by this approach more external variables from R.dll
           may be linked with, if declared as

           __declspec(dllimport) FILE *R_Outputfile;
           __declspec(dllimport) int UserBreak;

           Puzzling fact: UserBreak can be linked with in both cases,
           whereas R_Outputfile only in the second (pexports) case.


Step 6:  Build rpy:

         in the rpy directory, set the environment variable R_SRC 
         to point to the path where you installed the R source code.

            set RSRC=C:\Progra~1\R\src\R-2.0.0

        and then start the compilation with

            python setup.py build

Step 7:  Install rpy:

            python setup.py install

Step 8: Create binary install file (optional)

            python setup.py bdist --formats=windist

        The installer will be placed in the dist/ subdirectory.

All done!

***NOTE*** 
------------------------------------------------------
For Visual C++ 7 for Python 2.3,  you may get the following error message:

	"Python was built with version 6 of Visual Studio,
	and extensions need to be built with the same
	version of the compiler, but it isn't installed."

This is a bug in how msvccompiler.py (distutils module) handles 
VC7.  To correct this change line 212 from

	if len (self.__paths) == 0:

to

	if False: # len (self.__paths) == 0:


3.  USING RPy

For details see the documentation in the 'doc' directory.  As a quick example,
try the following session:

    >>> from rpy import *
    >>>
    >>> values = [r.dchisq(x, 4) for x in r.seq(0, 10, by=0.1)]
    >>> r.par(ask=1, ann=0)
    >>> r.plot(values, type='lines')

and voila!, the graph of the density of a chi squared distribution with four
degrees of freedom should appear.  Some more sofisticated examples can be
found in the 'examples' directory.  Refer to the RPy documentation for more
info on the interface, and to the R Programming Language manuals, which can be
found on

    http://www.r-project.org

In general, every line of the R manuals can be translated almost directly to
Python.


4.  TROUBLESHOOTING

If you get a Distutils execution error which says that R couldn't be executed:

    Traceback (most recent call last):
    ...
    distutils.errors.DistutilsExecError: couldn't execute the R interpreter.
    Check whether R is in the execution path

then make sure that you have R installed and that it is in the execution
path. The setup.py script uses the command 'R RHOME' to find out the location
of the R libraries. You should check that this command returns the correct
path.

If you get errors from the C compiler or linker, then you should check that
the headers files are under ${RHOME}/include and that 'libR.so' is under
${RHOME}/bin, where RHOME is what the execution of 'R RHOME' returns.

If you get an error when importing the 'rpy' module from Python, check that
you have built R with the configure option '--enable-R-shlib'.  Make sure that
you followed steps (a) and (b) of the installation procedure, described in
section 2.

If you have other problems, please, check the FAQ on the website or
send me a message to the address below.

5. MAILING LIST

Please report bugs, comments, questions, and suggestions to the rpy mailing
list (rpy-list@lists.sourceforge.net).  Subscription information  and 
archives are available at: 
  http://lists.sourceforge.net/lists/listinfo/rpy-list

6.  CONTACT INFO

Please, report bugs, comments and suggestions to the rpy mailing list.

If you prefer, you can fill a bug or feature request form on the 
Sourceforge project page, http://rpy.sourceforge.net

If both of these methods fail to resolve your problem, _then_ you may contact
the maintainer. (He does have other work and a life, you know.)

7.  LICENSE

This software is licensed under GPL. See the file COPYING for details.
The R Programming Language is licensed under GPL.

======

- Walter Moreira (Author)
- Gregory Warnes <Gregory.R.Warnes@Pfizer.com> (Maintainer) 
- Nitin Jain <Nitin.Jain@Pfizer.com> (Assistant Maintainer)