Revision: 618 http://rpy.svn.sourceforge.net/rpy/?rev=618&view=rev Author: lgautier Date: 2008-08-05 11:00:11 +0000 (Tue, 05 Aug 2008)
Log Message: ----------- refactored a bit the documentation Modified Paths: -------------- branches/rpy_nextgen/doc/source/conf.py 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-05 10:57:00 UTC (rev 617) +++ branches/rpy_nextgen/doc/source/conf.py 2008-08-05 11:00:11 UTC (rev 618) @@ -94,7 +94,7 @@ -html_favicon = 'rpy.ico' +html_favicon = 'rpy_fav.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, Modified: branches/rpy_nextgen/doc/source/overview.rst =================================================================== --- branches/rpy_nextgen/doc/source/overview.rst 2008-08-05 10:57:00 UTC (rev 617) +++ branches/rpy_nextgen/doc/source/overview.rst 2008-08-05 11:00:11 UTC (rev 618) @@ -58,7 +58,7 @@ Choose files from the `rpy2` package, not `rpy`. .. note:: - MacOSX binaries may appear in the future (contributions to build them are welcome) + MacOSX binaries may appear in the future (help to build them is welcome) .. index:: @@ -173,3 +173,4 @@ Alexander Belopolsky. His code contribution to RPy is acknowledged. I have found great inspiration in reading that code. + Modified: branches/rpy_nextgen/doc/source/rinterface.rst =================================================================== --- branches/rpy_nextgen/doc/source/rinterface.rst 2008-08-05 10:57:00 UTC (rev 617) +++ branches/rpy_nextgen/doc/source/rinterface.rst 2008-08-05 11:00:11 UTC (rev 618) @@ -4,18 +4,18 @@ -********** -rinterface -********** +******************* +Low-level interface +******************* Overview ======== -A lower-level interface is provided for situations where -the use-cases addressed by :mod:`robjects` are not covered, -and for the cases where the layer in :mod:`robjects` -has an excessive cost in term of performances. +The package :mod:`rinterface` is provided as a lower-level interface, +for situations where either the use-cases addressed by :mod:`robjects` +are not covered, or for the cases where the layer in :mod:`robjects` +has an excessive cost in terms of performances. The package can be imported with: @@ -40,9 +40,9 @@ >>> rinterface.initEmbeddedR() -Initialization should only be performed once. In the unfortunate event -of a second call to :func:`initEmbeddedR`, and to avoid unpredictable results -when using the embedded R, an exception will be fired. +Initialization should only be performed once. +To avoid unpredictable results when using the embedded R, +subsequent calls to :func:`initEmbeddedR` will not have any effect. Parameters for the initialization are in the module variable `initOptions`. @@ -65,12 +65,32 @@ The :class:`Sexp_Type` objects can be considered as Python enveloppes pointing to data stored and administered in the R space. +R variables are existing within an embedded R workspace, and can be accessed +from Python through their python object representations. + +We distinguish two kind of R objects: named objects and anonymous objects. +Named objects have an associated symbol in the R workspace. + +Named objects +^^^^^^^^^^^^^ + +For example, the following R code is creating two objects, named `x` and `hyp` +respectively, in the `global environment`. +Those two objects could be accessed from Python using their names. + +.. code-block:: r + + x <- c(1,2,3) + + hyp <- function(x, y) sqrt(x^2 + y^2) + +Two environments are provided as :class:`rpy2.rinterface.SexpEnvironment` + .. index:: single: globalEnv single: SexpEnvironment; globalEnv -globalEnv ---------- +.. rubric:: globalEnv The global environment can be seen as the root (or topmost) environment, and is in fact a list, that is a sequence, of environments. @@ -87,26 +107,52 @@ pair: rinterface; baseNamespaceEnv single: SexpEnvironment; baseNamespaceEnv -baseNamespaceEnv ----------------- +.. rubric:: baseNamespaceEnv The base package has a namespace, that can be accessed as an environment. .. note:: Depending on what is in `globalEnv` and on the attached packages, base - objects can be masked when starting the search from `globalEnv`. Use this - environment when you want to be sure to access a function you know to be + objects can be masked when starting the search from `globalEnv`. + Use `baseNamespaceEnv` + when you want to be sure to access a function you know to be in the base namespace. -.. index:: - single: Sexp -Ouput from the R console ------------------------- +Anonymous objects +^^^^^^^^^^^^^^^^^ +Anonymous R objects do not have an associated symbol, yet are protected +from garbage collection. + +Such objects can be created when using the constructor for an `Sexp*` class. + + + +Interacting with the R console +------------------------------ + +Two functions can be used to set callbacks. + +.. autofunction:: setWriteConsole(function) + + :param function: function + +.. autofunction:: setReadConsole(function) + + :param function: function + + +Output from the console +^^^^^^^^^^^^^^^^^^^^^^^ + The function :meth:`setWriteConsole` let one specify what do with output from the R console with a callback function. +The callback function should accept one argument of type string +(that is the string output to the console) + + An example should make it obvious:: buf = [] @@ -117,12 +163,22 @@ # output from the R console will now be appended to the list 'buf' rinterface.setWriteConsole(f) -.. autofunction:: setWriteConsole(function) + rprint = rinterface.baseNamespaceEnv['print'] + rprint(rinterface.baseNamespaceEnv['date']) - :param function: function + # restore default function + rinterface.setWriteConsole(rinterface.consolePrint) +Input to the console +^^^^^^^^^^^^^^^^^^^^ +User input to the console can be can be customized the very same way. + +The callback function should accept one argument of type string (that is the +prompt string), and return a string (what was returned by the user). + + Classes ======= @@ -297,7 +353,20 @@ .. :members: +Convenience classes are provided to create vectors of a given type: +.. autoclass:: rpy2.rinterface.StrSexpVector + :show-inheritance: + :members: + +.. autoclass:: rpy2.rinterface.IntSexpVector + :show-inheritance: + :members: + +.. autoclass:: rpy2.rinterface.FloatSexpVector + :show-inheritance: + :members: + .. index:: single: SexpEnvironment single: rinterface; SexpEnvironment Modified: branches/rpy_nextgen/doc/source/rlike.rst =================================================================== --- branches/rpy_nextgen/doc/source/rlike.rst 2008-08-05 10:57:00 UTC (rev 617) +++ branches/rpy_nextgen/doc/source/rlike.rst 2008-08-05 11:00:11 UTC (rev 618) @@ -17,6 +17,7 @@ Containers ========== + .. module:: rpy2.rlike.container >>> import rpy2.rlike.container as rlc @@ -83,3 +84,8 @@ >>> [x for x in it] [1, 3] + +The Python docstring for the class is: + +.. autoclass:: rpy2.rlike.container.TaggedList + :members: \ No newline at end of file Modified: branches/rpy_nextgen/doc/source/robjects.rst =================================================================== --- branches/rpy_nextgen/doc/source/robjects.rst 2008-08-05 10:57:00 UTC (rev 617) +++ branches/rpy_nextgen/doc/source/robjects.rst 2008-08-05 11:00:11 UTC (rev 618) @@ -1,7 +1,7 @@ -************* -rpy2.robjects -************* +******************** +High-level interface +******************** .. module:: rpy2.robjects :platform: Unix, Windows @@ -33,7 +33,7 @@ `r`: the instance of `R` -============================== +======================== This class is currently a singleton, with its one representation instanciated when the @@ -335,7 +335,8 @@ fit <- lm(y ~ x) -In the call to `lm`, the argument is a `formula`. +In the call to `lm`, the argument is a `formula`, and it can read like +*model y using x*. A formula is a `R` language object, and the terms in the formula are evaluated in the environment it was defined in. Without further specification, that environment is the environment in which the @@ -418,6 +419,13 @@ >>> +The docstrings for :meth:`default_ri2py`, :meth:`default_py2ri`, and :meth:`ri2py` are: + +.. autofunction:: rpy2.robjects.default_ri2py +.. autofunction:: rpy2.robjects.default_py2ri +.. autofunction:: rpy2.robjects.default_py2ro + + Examples ======== 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