Revision: 460
http://rpy.svn.sourceforge.net/rpy/?rev=460&view=rev
Author: lgautier
Date: 2008-03-23 04:10:57 -0700 (Sun, 23 Mar 2008)
Log Message:
-----------
Documentation: first stab
Added Paths:
-----------
branches/rpy_nextgen/doc/
branches/rpy_nextgen/doc/rpy.texi
Added: branches/rpy_nextgen/doc/rpy.texi
===================================================================
--- branches/rpy_nextgen/doc/rpy.texi (rev 0)
+++ branches/rpy_nextgen/doc/rpy.texi 2008-03-23 11:10:57 UTC (rev 460)
@@ -0,0 +1,542 @@
+\input texinfo @c -*-texinfo-*-
+
[EMAIL PROTECTED] %**start of header
[EMAIL PROTECTED] rpy.info
[EMAIL PROTECTED] @RPy{} Reference Manual
[EMAIL PROTECTED] %**end of header
[EMAIL PROTECTED] Programming
[EMAIL PROTECTED]
+* RPy v2: (rpy2). RPy2, Python extension module for R.
[EMAIL PROTECTED] direntry
+
[EMAIL PROTECTED] version
+2.0.0-dev
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] Python
+Python
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] RPy
+RPy
[EMAIL PROTECTED] macro
[EMAIL PROTECTED] RPy2
+RPy2
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] R
+R
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] C
+C
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED]
+This file documents @RPy2{} @version{}
+
+Copyright -
+Permission is granted to make and distribute verbatim
+copies of this manual provided the copyright notice and
+this permission notice are preserved on all copies.
+
[EMAIL PROTECTED]
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
[EMAIL PROTECTED] ignore
+
+Permission is granted to copy and distribute modified
+versions of this manual under the conditions for
+verbatim copying, provided also that the sections
+entitled ``Copying'' and ``GNU General Public License''
+are included exactly as in the original, and provided
+that the entire resulting derived work is distributed
+under the terms of a permission notice identical to this
+one.
+
+Permission is granted to copy and distribute
+translations of this manual into another language,
+under the above conditions for modified versions,
+except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
[EMAIL PROTECTED] ifinfo
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] @RPy2{} Reference Manual
[EMAIL PROTECTED] (version @version{})
[EMAIL PROTECTED] Laurent Gautier
[EMAIL PROTECTED]
[EMAIL PROTECTED] 0pt plus 1filll
+Copyright @copyright{} 2008
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the sections entitled ``Copying'' and ``GNU General Public License''
+are included exactly as in the original, and provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
[EMAIL PROTECTED] titlepage
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] Top, Overview, (dir), (dir)
[EMAIL PROTECTED] @RPy{} Reference Manual (version @version{})
+
+This is the reference manual for @RPy{} version @version{}, a @Python{}
+extension module for using the @R{} programming language.
[EMAIL PROTECTED] ifnottex
+
[EMAIL PROTECTED]
+* Preface::
+* Overview::
+* robjects::
+* rinterface::
+* Acknowledgements::
[EMAIL PROTECTED] menu
+
+
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] iftex
+
[EMAIL PROTECTED] Preface, Overview, , Top
[EMAIL PROTECTED] Preface
+
+This presentation describes @RPy2{}, a close-to-complete rewrite of
+the @RPy{} package.
+
+It is developped for R-2.7 (and is not expected to work
+with a previous version), together with @Python{} 2.5. Compatibility
+with @Python{} 2.4 is expected but not tested when writing
+those lines.
+
+The contributed code of Alexander Belopolsky, who contributed
+a rewrite to @RPy{} is acknowledged.
+The original work of Walter Moreira, and Gregory Warnes, is also
+acknowledged here.
+
+
[EMAIL PROTECTED] Overview, , Preface, Top
[EMAIL PROTECTED] Overview
+
+
[EMAIL PROTECTED]://www.python.org, @Python{}} is a popular
+all-purpose scripting language, while @uref{http://www.r-project.org, @R{}}
+is a scripting language mostly popular for data analysis, statistics, and
+graphics.
+
+
+The @RPy{} project is an effort to have access to @R{} from within @Python{},
+
+The @RPy{} code is initially inspired in RSPython, which is part of
+the @uref{http://www.omegahat.org/RSPython, Omegahat project}.
+
[EMAIL PROTECTED] is inspired by @RPy{} and A. Belopolskys's contributions to
@RPy.
+Backward compatibility with @RPy{} is limited.
+
+FIXME: write a section about what changed
+
+
+
+The package is made of several elements:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] robjects
+Higher-level interface, for when ease-of-use matters most
+(@xref{robjects})
+
[EMAIL PROTECTED] rinterface
+How-level interface to R, for when speed and flexibility
+matter most (@xref{rinterface})
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] robjects
[EMAIL PROTECTED] robjects
+
[EMAIL PROTECTED] Overview
+This module is intended for casual and general use.
+Its aim is to abstracts some of the details and provide an
+intuitive interface to R.
+
[EMAIL PROTECTED]
+>>> import rpy2.robjects as robjects
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] is written on the top of @code{rinterface}, and one
+not satisfied with it could easily build one's own flavor of a
[EMAIL PROTECTED]@R{} interface by modifying it.
+
+
[EMAIL PROTECTED] Classes
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] Robject
+Parent class for @R{} objects.
+
[EMAIL PROTECTED] Rvector
+An @R{} vector
+
[EMAIL PROTECTED] Renvironment
+An @R{} environment.
+
[EMAIL PROTECTED] Rfunction
+An @R{} function.
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] R
+
+This class is currently a singleton, with
+its one representation instanciated when the
+module is loaded:
+
[EMAIL PROTECTED]
+>>> robjects.r
+>>> print(robjects.r)
[EMAIL PROTECTED] example
+
+The instance can be seen as a window to an
+embedded @R{} process.
+Readers familiar with the ctypes module for @Python
+
[EMAIL PROTECTED] vectors:
[EMAIL PROTECTED]
+>>> pi = robjects.r.pi
+>>> letters = robjects.r.letters
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] functions:
+
[EMAIL PROTECTED]
+>>> plot = robjects.r.plot
+>>> dir = robjects.r.dir
[EMAIL PROTECTED] example
+
+The evaluation of @R{} code in a string can also be performed
+FIXME: (not yet implemented/tested)
+
[EMAIL PROTECTED] Robject
+
+
[EMAIL PROTECTED] Rvector
+
+Outside enviromnents and functions, most of the objects
+an @R{} user is interacting with are vector-like.
+For example, this means that any scalar is in fact a vector
+of length one.
+
+The class @code{Rvector} has a constructor:
[EMAIL PROTECTED]
+>>> x = robjects.Rvector(3)
[EMAIL PROTECTED] example
+
+Operations on vectors:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] +
+Add
[EMAIL PROTECTED] -
+Subtract
[EMAIL PROTECTED] *
+Multiply
[EMAIL PROTECTED] /
+Divide
[EMAIL PROTECTED] table
+
+FIXME:
+Indexing
+
+This class is using the class @code{rinterface.SexpVector}
+(@xref{SexpVector}).
+
+
+
[EMAIL PROTECTED] Renvironment
+
[EMAIL PROTECTED] environments can be described to the @Python user as
+an hybrid of a dictionary and a scope.
+
+The first of all environments is called the Global Environment,
+that can also be referred to as the R workspace (@xref{globalEnv}).
[EMAIL PROTECTED]
+>>> globalEnv = robjects.globalEnv
[EMAIL PROTECTED] example
+
+Assigning a value to a symbol in an environment has been
+made as simple as assign a value to a key in a @Python{}
+dictionary:
[EMAIL PROTECTED]
+>>> robjects.r.ls(globalEnv)
+>>> globalEnv["a"] = 123
+>>> robjects.r.ls(globalEnv)
[EMAIL PROTECTED] example
+
+Care must be taken when assigning objects into an environment
+such as the Global Environment, as it can hide other objects
+with an identical name.
+For example
[EMAIL PROTECTED]
+>>> globalEnv["pi"] = 123
+>>> robjects.r.pi
+123L
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED]
+>>> robjects.r.rm("pi")
+>>> robjects.r.pi
+3.1415926535897931
[EMAIL PROTECTED] example
+
+This class is using the class @code{rinterface.SexpEnvironment}
+(@xref{SexpEnvironment}).
+
+
[EMAIL PROTECTED] Rfunction
+
[EMAIL PROTECTED]
+>>> plot = robjects.r.plot
+>>> rnorm = robjects.r.rnorm
+>>> plot(rnorm(100), ylab="random")
[EMAIL PROTECTED] example
+
+This class is using the class @code{rinterface.SexpClosure}
+(@xref{SexpClosure}).
+
+
[EMAIL PROTECTED] Mapping
+
+The mapping between low-level objects is performed by the
+functions XXX and XXX.
+
+A developper can easily add his own mapping XXX.
+
[EMAIL PROTECTED] Examples
+
[EMAIL PROTECTED]
+>>> import array
+
+>>> r = robjects.r
+
+>>> x = array.array('i', range(10))
+>>> y = r.rnorm(10)
+
+>>> r.X11()
+
+>>> r.par(mfrow=array.array('i', [2,2]))
+>>> r.plot(x, y, ylab="foo/bar", col="red")
+
+>>> kwargs = {'ylab':"foo/bar", 'type':"b", 'col':"blue", 'log':"x"}
+>>> r.plot(x, y, **kwargs)
+
+>>> m = r.matrix(r.rnorm(100), ncol=5)
+>>> pca = r.princomp(m)
+>>> r.plot(pca, main="Eigen values")
+>>> r.biplot(pca, main="biplot")
+
+>>> if not r.require("GO")[0]:
+... raise(Exception("Bioconductor Package GO missing"))
+...
+
+>>> goItem = r.GOTERM["GO:0000001"]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] rinterface
[EMAIL PROTECTED] rinterface
+
[EMAIL PROTECTED] Overview
+A lower-level interface is provided for cases where
+the use-cases addressed by @code{robjects} are not covered,
+and for the cases where the layer in @code{robjects}
+has an excessive cost on the performances.
+
[EMAIL PROTECTED]
+>>> import rpy2.rinterface as rinterface
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] initEmbeddedR
[EMAIL PROTECTED] initEmbeddedR
+
+One has to initialize R before much can be done.
+The function @code{initEmbeddedR} lets one initialize
+the embedded R, and take the same parameters as one
+would give when starting an R terminal from the command
+line:
[EMAIL PROTECTED]
+>>> rinterface.initEmbeddedR("--no-save", "--quiet")
[EMAIL PROTECTED] example
+
+Initialization should only be performed once and in the case
+of a second call to initEmbeddedR, to avoid unpredictable results
+when using the embedded R, an exception is be fired.
+
[EMAIL PROTECTED] Rspace
[EMAIL PROTECTED] @R{} space and @Python{} space
+
+When using the @RPy2{} package, two realms are co-existing: @R{} and @Python{}.
+
+The @code{Sexp_Type} objects can be considered as @Python{} shells pointing
+to data stored and administered in the @R{} space.
+
+
[EMAIL PROTECTED] globalEnv
[EMAIL PROTECTED] globalEnv
+
+The global environment can be seen as the topmost environment,
+and is in fact a list, that is a sequence, of environments.
+
+When an @R{} library (package in @R{}'s terminology) is loaded,
+is it added to the existing sequence of environments. Unless
+specified, it is inserted in second position. The first position
+always remains attributed to the global environment
+(FIXME: there is a bit of circulariry in this definition - check
+how to present it a clear(er) way).
+The library is said to be attached to the current search path.
+
[EMAIL PROTECTED] Sexp
[EMAIL PROTECTED] Sexp
+
+Methods:
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] do_slot([name])
+Access attribute @code{name} for the object
[EMAIL PROTECTED] typeof()
+Type of the object
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] do_slot
[EMAIL PROTECTED] do_slot
+
[EMAIL PROTECTED] objects can be geiven attributes. In @R{} the function
[EMAIL PROTECTED] lets one access attribute, while called @code{do_slot}
+in the @C{} interface to @R{}.
+
[EMAIL PROTECTED]
+>>> matrix = rinterface.globalEnv.get("matrix")
+>>> letters = rinterface.globalEnv.get("letters")
+>>> ncol = rinterface.SexpVector([2, ], rinterface.INTSXP)
+>>> m = matrix(letters, ncol = ncol)
+>>> [x for x in m.do_slot("dim")]
+[13, 2]
[EMAIL PROTECTED] example
+
+
[EMAIL PROTECTED] SexpVector
[EMAIL PROTECTED] SexpVector
+
+In @R{} all scalars are in fact vectors.
+
+To use again the constant @code{pi}:
[EMAIL PROTECTED]
+>>> pi = rinterface.globalEnv.get("pi")
+>>> len(pi)
+1
+>>> pi
+<rinterface.SexpVector - Python:0x2b20325d2660 / R:0x16d5248>
+>>> pi[0]
+3.1415926535897931
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED]
+>>> letters = rinterface.globalEnv.get("letters")
+>>> len(letters)
+26
+>>> LETTERS = rinterface.globalEnv.get("LETTERS")
[EMAIL PROTECTED] example
+
+
[EMAIL PROTECTED]
+>>> options = rinterface.globalEnv.get("options")()
+>>> option_names = options.do_slot("names")
+>>> [x for x in options_names]
[EMAIL PROTECTED] example
+(to know more about @code{do_slot}, @xref{do_slot}).
+
+
[EMAIL PROTECTED] SexpEnvironment
[EMAIL PROTECTED] SexpEnvironment
+
[EMAIL PROTECTED] get
+Whenever a search for a symbol is performed, the whole
+search path is considered: the environments in the list
+are inspected in sequence and the value for the first symbol found
+matching is returned.
+
[EMAIL PROTECTED]
+>>> rinterface.globalEnv.get("pi")
[EMAIL PROTECTED] example
+
+The constant pi is defined in the package base, that
+is by default in the search path.
+
+
[EMAIL PROTECTED] __getitem__, __setitem__
+
+The @code{[} operator will only look for a symbol in the environment
+(FIXME: first in the list then ?),
+without looking into other elements in the list.
+
+The following will return an expection @code{LookupError}:
[EMAIL PROTECTED]
+>>> rinterface.globalEnv["pi"]
[EMAIL PROTECTED] example
+The constant @code{pi} is defined in @R{}'s @code{base} package,
+and therefore cannot be found in the Global Environment.
+
+The assignment of a value to a symbol in an environment is as
+simple as assigning a value to a key in a @Python{} dictionary:
[EMAIL PROTECTED]
+>>> x = rinterface.Sexp_Vector([123, ], rinterface.INTSXP)
+>>> rinterface.globalEnv["x"] = x
[EMAIL PROTECTED] example
+note: a copy of the @R{} object is made in the @R{} space.
+
+
[EMAIL PROTECTED] SexpClosure
[EMAIL PROTECTED] SexpClosure
+
+In @R{} terminology, a closure is a function (with its enclosing
+environment).
+
[EMAIL PROTECTED] closureEnv
+
+In the example below, we inspect the environment for the
+function @code{plot}, that is the namespace for the
+package @code{graphics}.
[EMAIL PROTECTED]
+>>> plot = rinterface.globalEnv.get("plot")
+>>> ls = rinterface.globalEnv.get("ls")
+>>> envplot_list = ls(plot.closureEnv())
+>>> [x for x in envplot_ls]
[EMAIL PROTECTED] example
+
+
[EMAIL PROTECTED] Acknowledgements, , , Top
[EMAIL PROTECTED] Acknowledgements
+
+This is an attempt at rewritting and extending
+the @RPy{} project. Acknowledgements go to:
+(FIXME: names are probably forgotten)
+
[EMAIL PROTECTED] @asis
+
[EMAIL PROTECTED] Walter Moreira
+for the orignal implementation of @RPy{}.
+
[EMAIL PROTECTED] Gregory Warnes
+for maintaining @RPy{} across the years, bringing it
+a version 1.0, and fixing it to accomodate changes in R.
+
[EMAIL PROTECTED] Alexander Belopolsky
+for his very nice contributed code to RPy (that code was a cornerstone
+in rewriting RPy).
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED]
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
rpy-list mailing list
rpy-list@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rpy-list
