       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, but it should compile on
any POSIX system.  It has been reported successful compilations on
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 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) 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 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.

Compiling RPy under Windows
---------------------------

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

Step 0:  Unpack the rpywin source package

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

         I put R 1.8.1 into C:\Program Files\R\rw1018

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

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

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 -> 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. 

	 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:  Modify the first few lines of the rpywin "setup.py" file to
         give the paths where you installed the R binary and source code.

Step 6:  Create a windows library file to use during linking:

         in the rpywin directory do

	    set RSRC=C:\Program Files\R\src\R-1.8.1
	    set RHOME=C:\Program Files\R\rw1018

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

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

Step 7:  Build rpy:

	 in the rpywin directory do:

	    python setup.py build

Step 8:  Install rpy:

	    python setup.py install

All done!

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.  CONTACT INFO

Please, report bugs, comments and suggestions to the email below.  If you
prefer, you can fill a bug or feature request form on the Sourceforge project
page.  Also, if you success in compiling this module under a platform other
than Linux, please, send us a note.

Author: Walter Moreira
email: walterm@cmat.edu.uy

Maintainer: Gregory Warnes
email: gregory_r_warnes@groton.pfizer.com

web: http://rpy.sourceforge.net

6.  LICENSE

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