Revision: 667
http://rpy.svn.sourceforge.net/rpy/?rev=667&view=rev
Author: lgautier
Date: 2008-10-29 09:38:54 +0000 (Wed, 29 Oct 2008)
Log Message:
-----------
doc:
- more in the introduction
- cross-refs
Modified Paths:
--------------
branches/rpy_nextgen/doc/source/introduction.rst
branches/rpy_nextgen/doc/source/rinterface.rst
branches/rpy_nextgen/doc/source/robjects.rst
Modified: branches/rpy_nextgen/doc/source/introduction.rst
===================================================================
--- branches/rpy_nextgen/doc/source/introduction.rst 2008-10-28 19:28:14 UTC
(rev 666)
+++ branches/rpy_nextgen/doc/source/introduction.rst 2008-10-29 09:38:54 UTC
(rev 667)
@@ -3,7 +3,7 @@
********************
-This introduction aims at being a gentle start to rpy2,
+This introduction aims at making a gentle start to rpy2,
either when coming from R to Python/rpy2, from Python to rpy2/R,
or from elsewhere to Python/rpy2/R.
@@ -26,11 +26,17 @@
The object :data:`r` in :mod:`rpy2.robjects` represents the running embedded
`R` process.
-If familiar with R and the R console, :data:`r` is a little like your window
-to R from Python.
+If familiar with R and the R console, :data:`r` is a little like a
+communication channel from Python to R.
-The method :meth:`__getitem__` functions like calling a variable from the
+Getting R objects
+-----------------
+
+In Python the `[` operator is an alias for the ethod :meth:`__getitem__`.
+
+With :mod:`rpy2.robjects`,
+the method :meth:`__getitem__` functions like calling a variable from the
R console.
Example in R:
@@ -46,9 +52,15 @@
+Evaluating R code
+-----------------
+
The :data:`r` object is also callable, and the string passed to it evaluated
-as `R` code:
+as `R` code.
+This can be used to `get` variables, and provide an alternative to
+the method presented above.
+
Example in R:
.. code-block:: r
@@ -61,7 +73,19 @@
3.14159265358979
-The evaluation is performed in what is know to R users as the
+.. warning::
+
+ The result is an R vector. Reading Section
+ :ref:`introduction-vectors` is recommended as it will provide explanations
+ for the following behavior:
+
+ >>> robjects.r('pi') + 2
+ c(3.14159265358979, 2)
+ >>> robjects.r('pi')[0] + 2
+ 5.1415926535897931
+
+
+The evaluation is performed in what is known to R users as the
`Global Environment`, that is the place one starts at when starting
the R console. Whenever the `R` code creates variables, those
variables will be "located" in that `Global Environment` by default.
@@ -77,7 +101,8 @@
''')
-The expression above will return the value 18.85, but also create an R function
+The expression above will return the value 18.85,
+but first also creates an R function
`f`. That function `f` is present in the R `Global Environement`, and can
be accessed with the `__getitem__` mechanism outlined above:
@@ -88,7 +113,26 @@
2 * pi * r
}
+Interpolating R objects into R code strings
+-------------------------------------------
+Against the first impression one may get from the title
+of this section, simple and handy features of :mod:`rpy2` are
+presented here.
+
+An R object has a string representation that can be used
+directly into R code to be evaluated.
+
+Simple example:
+
+>>> letters = robjects.r['letters']
+>>> rcode = 'paste(%s, collapse="-")' %(repr(letters))
+>>> robjects.r(rcode)
+"a-b-c-d-e-f-g-h-i-j-k-l-m-n-o-p-q-r-s-t-u-v-w-x-y-z"
+
+
+.. _introduction-vectors:
+
R vectors
=========
@@ -101,7 +145,23 @@
>>> len(robjects.r['pi'])
1
+As such, the python method :meth:`add` will result in a concatenation
+(function `c()` in R), as this is the case for regular python lists.
+Accessing the one value in that vector will have to be stated
+explicitly:
+
+>>> robjects.r['pi'][0]
+3.1415926535897931
+
+There much that can be achieved with vector, having them to behave
+more like Python lists or R vectors.
+A comprehensive description of the behavior of vectors is found in
+:ref:`robjects-vectors`.
+
+Creating rpy2 vectors
+---------------------
+
Creating R vectors can be achieved simply:
>>> robjects.StrVector(['abc', 'def'])
@@ -112,7 +172,39 @@
c(1.1, 2.2, 3.3)
-R matrixes and arrays are just vector with a `dim` attribute.
+R matrixes and arrays are just vectors with a `dim` attribute.
+The easiest way to create such objects is to do it through
+R functions:
-
\ No newline at end of file
+>>> v = robjects.FloatVector([1.1, 2.2, 3.3, 4.4, 5.5, 6.6])
+>>> m = robjects.r['matrix'](v, nrow = 2)
+>>> print(m)
+ [,1] [,2] [,3]
+[1,] 1.1 3.3 5.5
+[2,] 2.2 4.4 6.6
+
+
+Calling R functions
+===================
+
+Calling R functions will be disappointingly similar to calling
+Python functions:
+
+>>> rsum = robjects.r['sum']
+>>> rsum(robjects.IntVector([1,2,3]))
+6L
+
+Keywords can be used with the same ease:
+
+>>> rsort = robjects.r['sort']
+>>> rsort(robjects.IntVector([1,2,3]), decreasing=True)
+c(3L, 2L, 1L)
+
+
+.. note::
+
+ By default, calling R functions will return R objects.
+
+
+More information on functions is in Section :ref:`robjects-functions`
Modified: branches/rpy_nextgen/doc/source/rinterface.rst
===================================================================
--- branches/rpy_nextgen/doc/source/rinterface.rst 2008-10-28 19:28:14 UTC
(rev 666)
+++ branches/rpy_nextgen/doc/source/rinterface.rst 2008-10-29 09:38:54 UTC
(rev 667)
@@ -406,6 +406,10 @@
:show-inheritance:
:members:
+.. autoclass:: rpy2.rinterface.BoolSexpVector
+ :show-inheritance:
+ :members:
+
.. index::
single: SexpEnvironment
single: rinterface; SexpEnvironment
@@ -603,9 +607,11 @@
pair: rinterface; function
-:class:`SexpClosure`
---------------------
+.. _rinterface-functions:
+Functions
+---------
+
.. rubric:: A function with a context
In R terminology, a closure is a function (with its enclosing
Modified: branches/rpy_nextgen/doc/source/robjects.rst
===================================================================
--- branches/rpy_nextgen/doc/source/robjects.rst 2008-10-28 19:28:14 UTC
(rev 666)
+++ branches/rpy_nextgen/doc/source/robjects.rst 2008-10-29 09:38:54 UTC
(rev 667)
@@ -143,6 +143,8 @@
.. index::
pair: robjects;RVector
+.. _robjects-vectors:
+
Vectors
=======
@@ -172,7 +174,24 @@
:class:`IntVector`, :class:`FloatVector`, :class:`BoolVector`,
:class:`StrVector` can
used.
+.. autoclass:: rpy2.robjects.BoolVector
+ :show-inheritance:
+ :members:
+.. autoclass:: rpy2.robjects.IntVector
+ :show-inheritance:
+ :members:
+
+.. autoclass:: rpy2.robjects.FloatVector
+ :show-inheritance:
+ :members:
+
+.. autoclass:: rpy2.robjects.StrVector
+ :show-inheritance:
+ :members:
+
+
+
.. index::
pair: RVector;indexing
@@ -300,6 +319,8 @@
A :class:`RMatrix` is a special case of :class:`RArray`.
+.. _robjects-dataframes:
+
Data frames
-----------
@@ -337,9 +358,8 @@
In this example, will use the R function `data.frame()`, that
constructs a data.frame from named arguments
->>> import array
->>> d = {'value': robjects.IntSexpVector((1,2,3)),
- 'letter': robjects.StrSexpVector(('x', 'y', 'z'))}
+>>> d = {'value': robjects.IntVector((1,2,3)),
+ 'letter': robjects.StrVector(('x', 'y', 'z'))}
>>> dataf = robjects.r['data.frame'](**d)
>>> dataf.colnames()
c("letter", "value")
@@ -411,16 +431,32 @@
pair: robjects; RFunction
pair: robjects; function
+.. _robjects-functions:
+
Functions
=========
+R functions are callable objects, and be called almost like any regular
+Python function:
+
>>> plot = robjects.r.plot
>>> rnorm = robjects.r.rnorm
>>> plot(rnorm(100), ylab="random")
+In Python, arguments to a function are split into two groups:
+* A first group for which parameters are in defined order
+
+* A second group for which parameters are associated a name/keyword,
+ and a default value. In that second group the order is lost, as it is
+ passed as a Python dictionary.
+
+Those two groups can be used in function calls.
+
+
The class inherits from the class
-:class:`rpy2.rinterface.SexpClosure`.
+:class:`rpy2.rinterface.SexpClosure`, and further documentation
+on the behavior of function can be found in Section
:ref:`rinterface-functions`.
.. index::
pair: robjects; RFormula
@@ -588,12 +624,11 @@
.. code-block:: python
import rpy2.robjects as robjects
- import array
r = robjects.r
- ctl = array.array('f', [4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14])
- trt = array.array('f', [4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69])
+ ctl =
robjects.FloatVector([4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14])
+ trt =
robjects.FloatVector([4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69])
group = r.gl(2, 10, 20, labels = ["Ctl","Trt"])
weight = ctl + trt
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
