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 and later also include 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) 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.murdoch-sutherland.com/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: 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 RPy is subject to the Mozilla Public License Version 1.1 (the "License"); you may not use RPy except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/ (or see the file MPL_LICENSE) Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is the RPy python module. The Initial Developer of the Original Code is Walter Moreira. Portions created by the Initial Developer are Copyright (C) 2002 the Initial Developer. All Rights Reserved. Contributor(s): Gregory R. Warnes <greg@warnes.net> (Maintainer) Alternatively, RPy may be used under the terms of either the GNU General Public License Version 2 or later (the "GPL", see the file GPL_LICENSE), or the GNU Lesser General Public License Version 2.1 or later (the "LGPL", see the file LGPL_LICENSE), in which case the provisions of the GPL or the LGPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of either the GPL or the LGPL, and not to allow others to use your version of this file under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL or the LGPL. If you do not delete the provisions above, a recipient may use your version of this file under the terms of any one of the MPL, the GPL or the LGPL. ====== - Walter Moreira (Author) - Gregory Warnes <Gregory.R.Warnes@Pfizer.com> (Maintainer)