Revision: 608 http://rpy.svn.sourceforge.net/rpy/?rev=608&view=rev Author: lgautier Date: 2008-08-03 09:16:24 +0000 (Sun, 03 Aug 2008)
Log Message: ----------- work on the documentation Modified Paths: -------------- branches/rpy_nextgen/doc/source/conf.py branches/rpy_nextgen/doc/source/index.rst branches/rpy_nextgen/doc/source/overview.rst branches/rpy_nextgen/doc/source/rinterface.rst branches/rpy_nextgen/doc/source/rlike.rst branches/rpy_nextgen/doc/source/robjects.rst Modified: branches/rpy_nextgen/doc/source/conf.py =================================================================== --- branches/rpy_nextgen/doc/source/conf.py 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/conf.py 2008-08-03 09:16:24 UTC (rev 608) @@ -24,7 +24,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.doctest', ] +extensions = ['sphinx.ext.doctest', 'sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -46,6 +46,7 @@ version = '2.0' # The full version, including alpha/beta/rc tags. release = '2.0.0a2' +releaselevel = 'alpha' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: Modified: branches/rpy_nextgen/doc/source/index.rst =================================================================== --- branches/rpy_nextgen/doc/source/index.rst 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/index.rst 2008-08-03 09:16:24 UTC (rev 608) @@ -1,24 +1,7 @@ -.. rpy2 documentation master file, created by sphinx-quickstart on Fri May 23 22:16:57 2008. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Documentation for rpy2 ====================== -This document describes RPy2, a 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 it was observed to segfault on rare occasions -(and the cause is not yet identified). - - - - -Contents: - .. toctree:: :maxdepth: 2 Modified: branches/rpy_nextgen/doc/source/overview.rst =================================================================== --- branches/rpy_nextgen/doc/source/overview.rst 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/overview.rst 2008-08-03 09:16:24 UTC (rev 608) @@ -27,10 +27,16 @@ .. _Omegahat project: http://www.omegahat.org/RSPython -The present documentation covers RPy2, an evolution of RPy-1.x. +The present documentation describes RPy2, an evolution of RPy-1.x. Naturally RPy2 is inspired by RPy, but also by A. Belopolskys's contributions that were waiting to be included into RPy. +This effort can be seen as a rewrite of the RPy package. +It is developped for R-2.7 (and it will not work +with a previous version), together with Python 2.5. Compatibility +with Python 2.4 is expected but it was observed to segfault on rare occasions +(and the cause is not yet identified). + Installation @@ -86,7 +92,7 @@ Test an installation ^^^^^^^^^^^^^^^^^^^^ -An installation can be tested as follows: +At any time, an installation can be tested as follows: .. code-block:: python @@ -108,7 +114,7 @@ ^^^^^^^^^^^^^^^^^^^^^^^ Higher-level interface similar to the one in RPy-1.x. -This is provided for compatibility reasons, and facilitate the migration +This is provided for compatibility reasons, as well as to facilitate the migration to RPy2. Modified: branches/rpy_nextgen/doc/source/rinterface.rst =================================================================== --- branches/rpy_nextgen/doc/source/rinterface.rst 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/rinterface.rst 2008-08-03 09:16:24 UTC (rev 608) @@ -1,3 +1,9 @@ +.. module:: rpy2.rinterface + :platform: Unix, Windows + :synopsis: Low-level interface with R + + + ********** rinterface ********** @@ -2,7 +8,3 @@ -.. module:: rpy2.rinterface - :platform: Unix, Windows - :synopsis: Low-level interface with R - Overview @@ -19,17 +21,23 @@ >>> import rpy2.rinterface as rinterface + .. index:: - single: initEmbeddedR - single: initialize + single: initialization -:func:`initEmbeddedR` ---------------------- +Initialization +-------------- One has to initialize R before much can be done. The function :func:`initEmbeddedR` lets one initialize -the embedded R: +the embedded R. +This is done with the function :meth:`initEmbeddedR`. + + +.. autofunction:: initEmbeddedR() + + >>> rinterface.initEmbeddedR() Initialization should only be performed once. In the unfortunate event @@ -48,6 +56,7 @@ your path (:envvar:`PATH` on unix-alikes, or :envvar:`Path` on Microsoft Windows) or have the environment variable :envvar:`R_HOME` defined. + R space and Python space ------------------------ @@ -108,74 +117,77 @@ # output from the R console will now be appended to the list 'buf' rinterface.setWriteConsole(f) +.. autofunction:: setWriteConsole(function) + :param function: function -:class:`Sexp` -============= +Classes +======= -Methods: +Sexp +---- -typeof() - Type of the object +The class :class:`Sexp` is the base class for all R objects. -do_slot([name]) - Access attribute *name* for the object -.. index:: - single: Sexp; typeof +.. class:: Sexp -:meth:`typeof` --------------- + .. method:: typeof() -The internal R type in which an object is stored can be -accessed with the method :meth:`typeof`. + The internal R type in which an object is stored can be + accessed with the method :meth:`typeof`. ->>> letters.typeof() + :rtype: integer -FIXME: talk about the all the types. -.. index:: - single: Sexp; do_slot + .. doctest:: -:meth:`do_slot` ---------------- + >>> letters.typeof() + 16 -R objects can be given attributes. In R the function -*attr* lets one access attribute, while called :meth:`do_slot` -in the C interface to R. + .. method:: do_slot(name) ->>> 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] ->>> + R objects can be given attributes. In R the function + *attr* lets one access attribute, while called :meth:`do_slot` + in the C interface to R. -.. index:: - single: Sexp; named + :param name: string + :rtype: Sexp (or Sexp-inheriting) object -:meth:`named` ---------------- + >>> 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] + >>> -`R` does not count references for its object. This method -returns the `NAMED` value (see the R-extensions manual). + .. method:: named() + `R` does not count references for its object. This method + returns the `NAMED` value (see the R-extensions manual). + :rtype: integer +.. .. autoclass:: rpy2.rinterface.Sexp +.. :members: + + + .. index:: single: SexpVector single: rinterface; SexpVector + :class:`SexpVector` -=================== +------------------- Overview --------- +^^^^^^^^ In R all scalars are in fact vectors. Anything like a one-value variable is a vector of @@ -204,7 +216,7 @@ pair: rinterface;indexing Indexing --------- +^^^^^^^^ The indexing is working like it would on regular `Python` tuples or lists. @@ -220,14 +232,14 @@ Common attributes ------------------ +^^^^^^^^^^^^^^^^^ .. index:: single: names;rinterface -Names -^^^^^ +.. rubric:: Names + In R, vectors can be named, that is each value in the vector can be given a name (that is be associated a string). The names are added to the other as an attribute (conveniently @@ -245,8 +257,7 @@ single: dimnames -Dim and dimnames -^^^^^^^^^^^^^^^^ +.. rubric:: Dim and dimnames In the case of an `array`, the names across the respective dimensions of the object are accessible @@ -258,7 +269,7 @@ pair: SexpVector; numpy Numpy ------ +^^^^^ The :class:`SexpVector` objects are made to behave like arrays as defined in the Python package :mod:`numpy`. @@ -282,16 +293,21 @@ 42 >>> +.. .. autoclass:: rpy2.rinterface.SexpVector +.. :members: + + + .. index:: single: SexpEnvironment single: rinterface; SexpEnvironment :class:`SexpEnvironment` -======================== +------------------------ :meth:`get` ------------ +^^^^^^^^^^^ Whenever a search for a symbol is performed, the whole search path is considered: the environments in the list @@ -305,7 +321,7 @@ :meth:`__getitem__` / :meth:`__setitem__` ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The *[* operator will only look for a symbol in the environment (FIXME: first in the list then ?), @@ -333,7 +349,7 @@ a copy of the R object is made in the R space. :meth:`__iter__` ----------------- +^^^^^^^^^^^^^^^^ The object is made iter-able. @@ -358,10 +374,9 @@ pair: rinterface; function :class:`SexpClosure` -==================== +-------------------- -A function with a context -------------------------- +.. rubric:: A function with a context In R terminology, a closure is a function (with its enclosing environment). That enclosing environment can be thought of as @@ -375,6 +390,9 @@ >>> +.. index:: + single: rcall + .. rubric:: Order for named parameters One point where function calls in R can differ from the ones in @@ -382,7 +400,8 @@ all parameters in R are passed in the order they are in the call (no matter whether the parameter is named or not), while in Python only parameters without a name are passed in order. -Using the class :class:`ArgsDict` in the module :mod:`rpy2.rlike.container` +Using the class :class:`ArgsDict` in the module :mod:`rpy2.rlike.container`, +together with the method :meth:`rcall`, permits calling a function the same way it would in R. For example:: import rpy2.rlike.container as rpc @@ -396,9 +415,12 @@ >>> [x for x in rl.do_slot("names")] ['x', '', 'y'] -closureEnv ----------- +.. index:: + single: closureEnv + +.. rubric:: closureEnv + In the example below, we inspect the environment for the function *plot*, that is the namespace for the package *graphics*. @@ -410,9 +432,6 @@ >>> - - - Misc. variables =============== Modified: branches/rpy_nextgen/doc/source/rlike.rst =================================================================== --- branches/rpy_nextgen/doc/source/rlike.rst 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/rlike.rst 2008-08-03 09:16:24 UTC (rev 608) @@ -21,6 +21,10 @@ >>> import rpy2.rlike.container as rlc + +.. index:: + single: ArgsDict + ArgsDict -------- @@ -47,11 +51,35 @@ >>> nl[None] = 'no name' +.. index:: + single: TaggedList - TaggedList ---------- -A :class:`TaggedList` is a Python list in which each item has -an associated tag. +A :class:`TaggedList` is a Python :class:`list` in which each item has +an associated `tag`. This is similar to `named` vectors in R. + +>>> tl = rlc.TaggedList([1,2,3]) +>>> tl +[1, 2, 3] +>>> tl.tags() +(None, None, None) +>>> tl.settag(0, 'a') +>>> tl.tags() +('a', None, None) + + +>>> tl = rlc.TaggedList([1,2,3], tags=('a', 'b', 'c')) +>>> tl +[1, 2, 3] +>>> tl.tags() +('a', 'b', 'c') +>>> tl.settag(0, 'c') +>>> tl.tags() +('c', 'b', 'c') +>>> it = tl.iterontag('c') +>>> [x for x in it] +[1, 3] + Modified: branches/rpy_nextgen/doc/source/robjects.rst =================================================================== --- branches/rpy_nextgen/doc/source/robjects.rst 2008-08-03 09:15:45 UTC (rev 607) +++ branches/rpy_nextgen/doc/source/robjects.rst 2008-08-03 09:16:24 UTC (rev 608) @@ -7,8 +7,6 @@ :platform: Unix, Windows :synopsis: High-level interface with R -.. testsetup:: robjects - import rpy2.robjects as robjects Overview ======== @@ -107,8 +105,8 @@ .. index:: pair: robjects;RVector -R vectors -========= +Vectors +======= Beside functions, and environemnts, most of the objects an R user is interacting with are vector-like. @@ -255,8 +253,8 @@ Currently, the constructor is flagged as experimental. It accepts either a :class:`rinterface.SexpVector` or a dictonnary which elements will be the columns of the `data.frame`. -R environments -============== +Environments +============ R environments can be described to the Python user as an hybrid of a dictionary and a scope. @@ -307,8 +305,8 @@ pair: robjects; RFunction pair: robjects; function -R functions -=========== +Functions +========= >>> plot = robjects.r.plot >>> rnorm = robjects.r.rnorm 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 the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ rpy-list mailing list rpy-list@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/rpy-list