Vectors and arrays¶
Beside functions and environments, most of the objects an R user is interacting with are vectorlike. For example, this means that any scalar is in fact a vector of length one.
The class Vector
has a constructor:
>>> x = robjects.Vector(3)
 class rpy2.robjects.Vector(o)[source]¶
Bases:
RObjectMixin
Vector(seq) > Vector.
The parameter ‘seq’ can be an instance inheriting from rinterface.SexpVector, or an arbitrary Python object. In the later case, a conversion will be attempted using conversion.get_conversion().py2rpy().
R vectorlike object. Items can be accessed with:
the method “__getitem__” (“[” operator)
the delegators rx or rx2
 property names¶
Names for the items in the vector.
Creating vectors¶
Creating vectors can be achieved either from R or from Python.
When the vectors are created from R, one should not worry much
as they will be exposed as they should by rpy2.robjects
.
When one wants to create a vector from Python, either the
class Vector
or the convenience classes
IntVector
, FloatVector
, BoolVector
,
StrVector
can be used.
 class rpy2.robjects.vectors.BoolVector(obj)[source]¶
Bases:
Vector
,BoolSexpVector
Vector of boolean (logical) elements BoolVector(seq) > BoolVector.
The parameter ‘seq’ can be an instance inheriting from rinterface.SexpVector, or an arbitrary Python sequence. In the later case, all elements in the sequence should be either booleans, or have a bool() representation.
 class rpy2.robjects.vectors.IntVector(obj)[source]¶
Bases:
Vector
,IntSexpVector
Vector of integer elements IntVector(seq) > IntVector.
The parameter ‘seq’ can be an instance inheriting from rinterface.SexpVector, or an arbitrary Python sequence. In the later case, all elements in the sequence should be either integers, or have an int() representation.
 class rpy2.robjects.vectors.FloatVector(obj)[source]¶
Bases:
Vector
,FloatSexpVector
Vector of float (double) elements
FloatVector(seq) > FloatVector.
The parameter ‘seq’ can be an instance inheriting from rinterface.SexpVector, or an arbitrary Python sequence. In the later case, all elements in the sequence should be either float, or have a float() representation.
 class rpy2.robjects.vectors.StrVector(obj)[source]¶
Bases:
Vector
,StrSexpVector
Vector of string elements
StrVector(seq) > StrVector.
The parameter ‘seq’ can be an instance inheriting from rinterface.SexpVector, or an arbitrary Python sequence. In the later case, all elements in the sequence should be either strings, or have a str() representation.
 factor() FactorVector [source]¶
Construct a factor vector from a vector of strings.
 class rpy2.robjects.vectors.ListVector(obj)[source]¶
Bases:
Vector
,ListSexpVector
R list (vector of arbitray elements)
ListVector(iterable) > ListVector.
The parameter ‘iterable’ can be:
an object with a method items(), such for example a dict, a rpy2.rlike.container.TaggedList, an rpy2.rinterface.SexpVector of type VECSXP.
an iterable of (name, value) tuples
Sequences of date or time points can be stored in
POSIXlt
or POSIXct
objects. Both can be created
from Python sequences of time.struct_time
objects or
from R objects.
 class rpy2.robjects.vectors.POSIXlt(obj)[source]¶
Bases:
POSIXt
,ListVector
Representation of dates with a 11component structure (similar to Python’s time.struct_time).
POSIXlt(seq) > POSIXlt.
The constructor accepts either an R vector or a sequence (an object with the Python sequence interface) of time.struct_time objects.
 class rpy2.robjects.vectors.POSIXct(obj)[source]¶
Bases:
POSIXt
,FloatVector
Representation of dates as seconds since Epoch. This form is preferred to POSIXlt for inclusion in a DataFrame.
POSIXlt(seq) > POSIXlt.
The constructor accepts either an R vector floats or a sequence (an object with the Python sequence interface) of time.struct_time objects.
New in version 2.2.0: Vectors for date or time points
FactorVector¶
R’s factors are somewhat peculiar: they aim at representing a memoryefficient vector of labels, and in order to achieve it are implemented as vectors of integers to which are associated a (presumably shorter) vector of labels. Each integer represents the position of the label in the associated vector of labels.
For example, the following vector of labels
a 
b 
a 
b 
b 
c 
will become
1 
2 
1 
2 
2 
3 
and
a 
b 
c 
>>> sv = ro.StrVector('ababbc')
>>> fac = ro.FactorVector(sv)
>>> print(fac)
[1] a b a b b c
Levels: a b c
>>> tuple(fac)
(1, 2, 1, 2, 2, 3)
>>> tuple(fac.levels)
('a', 'b', 'c')
Since a FactorVector
is an IntVector
with attached
metadata (the levels), getting items Pythonstyle was not changed from
what happens when gettings items from a IntVector
.
A consequence to that is that information about the
levels is then lost.
>>> item_i = 0
>>> fac[item_i]
1
Getting the level corresponding to an item requires using the levels
,:
>>> fac.levels[fac[item_i]  1]
'a'
Warning
Do not forget to subtract one to the value in the FactorVector
.
Indexing in Python starts at zero while indexing R starts at one,
and recovering the level for an item requires an adjustment between the two.
When extracting elements from a FactorVector
a sensible default
might be to use Rstyle extracting (see Extracting items),
as it preserves the integer/string duality.
 class rpy2.robjects.vectors.FactorVector(obj)[source]¶
Bases:
IntVector
Vector of ‘factors’.
 FactorVector(obj,
levels = rinterface.MissingArg, labels = rinterface.MissingArg, exclude = rinterface.MissingArg, ordered = rinterface.MissingArg) > FactorVector
obj: StrVector or StrSexpVector levels: StrVector or StrSexpVector labels: StrVector or StrSexpVector (of same length as levels) exclude: StrVector or StrSexpVector ordered: boolean
 property isordered¶
are the levels in the factor ordered ?
 iter_labels()[source]¶
Iterate the over the labels, that is iterate over the items returning associated label for each item
 property nlevels¶
number of levels
Extracting items¶
Extracting elements of sequence/vector can become a thorny issue as Python and R differ on a number of points (index numbers starting at zero / starting at one, negative index number meaning index from the end / everything except, names cannot / can be used for subsettting).
In order to solve this, the Python way and the R way were made available through two different routes.
Extracting, Pythonstyle¶
The python __getitem__()
method behaves like a Python user would expect
it for a vector (and indexing starts at zero).
>>> x = robjects.r.seq(1, 5)
>>> tuple(x)
(1, 2, 3, 4, 5)
>>> x.names = robjects.StrVector('abcde')
>>> print(x)
a b c d e
1 2 3 4 5
>>> x[0]
1
>>> x[4]
5
>>> x[1]
5
Extracting, Rstyle¶
Access to Rstyle extracting/subsetting is granted though the two delegators rx and rx2, representing the R functions [ and [[ respectively (See the note below about [[, and $).
In short, Rstyle extracting has the following characteristics:
indexing starts at one (while Python indexing starts at zero).
the argument to subset on can be a vector of
integers (negative integers meaning exlusion of the elements)
booleans
strings (whenever the vector has names for its elements)
>>> print(x.rx(1))
[1] 1
>>> print(x.rx('a'))
a
1
R can extract several elements at once:
>>> i = robjects.IntVector((1, 3))
>>> print(x.rx(i))
[1] 1 3
>>> b = robjects.BoolVector((False, True, False, True, True))
>>> print(x.rx(b))
[1] 2 4 5
When a boolean extract vector is of smaller length than the vector, is expanded as necessary (this is know in R as the recycling rule):
>>> print(x.rx(True))
1:5
>>> b = robjects.BoolVector((False, True))
>>> print(x.rx(b))
[1] 2 4
In R, negative indices are understood as element exclusion.
>>> print(x.rx(1))
2:5
>>> i = robjects.IntVector((1, 3))
>>> print(x.rx(i))
[1] 2 4 5
That last example could also be written:
>>> i =  robjects.IntVector((1, 3)).ro
>>> print(x.rx(i))
[1] 2 4 5
This extraction system is quite expressive, as it allows a very simple writting of very common tasks in data analysis such as reordering and random sampling.
>>> from rpy2.robjects.packages import importr
>>> base = importr('base')
>>> x = robjects.IntVector((5,3,2,1,4))
>>> o_i = base.order(x)
>>> print(x.rx(o_i))
[1] 1 2 3 4 5
>>> rnd_i = base.sample(x)
>>> x_resampled = x.rx(o_i)
R operators are vector operations, with the operator applied to each element in the vector. This can be used to build extraction indexes.
>>> i = x.ro > 3 # extract values > 3
>>> i = (x.ro >= 2 ).ro & (x.ro <= 4) # extract values between 2 and 4
(More on R operators in Section Operators).
R/S also have particularities, in which some see consistency issues. For example although the indexing starts at 1, indexing on 0 does not return an index out of bounds error but a vector of length 0:
>>> print(x.rx(0))
integer(0)
Note
What about the R operator $ ? In R, elements of a list can be extracted with [, or if only one element is wanted [[ or $ (with [[ able to extract on index, that is position in the list, or on name while $ can only extract on name).
In R, the 3 ways to extract one element out of a list are:
> l < list(a = 1:3, b = 4:6)
> l[[1]]
[1] 1 2 3
> l[["a"]]
[1] 1 2 3
> l$a
[1] 1 2 3
With rpy2, it is looking like:
>>> elt = l.rx2(1) # This is the R `[[`, so oneoffset indexing
>>> elt = l.rx2('a')
Assigning items¶
Assigning, Pythonstyle¶
Since vectors are exposed as Python mutable sequences, the assignment works as for regular Python lists.
>>> x = robjects.IntVector((1,2,3))
>>> print(x)
[1] 1 2 3
>>> x[0] = 9
>>> print(x)
[1] 9 2 3
In R vectors can be named, that is elements of the vector have a name.
This is notably the case for R lists. Assigning based on names can be made
easily by using the method Vector.index()
, as shown below.
>>> x = robjects.ListVector({'a': 1, 'b': 2, 'c': 3})
>>> x[x.names.index('b')] = 9
Note
Vector.index()
has a complexity linear in the length of the vector’s length;
this should be remembered if performance issues are met.
Assigning, Rstyle¶
Differences between the two languages require few adaptations, and in
appearance complexify a little the task.
Should other Pythonbased systems for the representation of (mostly numerical)
data structure, such a numpy
be preferred, one will be encouraged to expose
our rpy2 R objects through those structures.
The attributes rx and rx2 used previously can again be used:
>>> x = robjects.IntVector(range(1, 4))
>>> print(x)
[1] 1 2 3
>>> x.rx[1] = 9
>>> print(x)
[1] 9 2 3
For the sake of complete compatibility with R, arguments can be named
(and passed as a dict
or rpy2.rlike.container.TaggedList
).
>>> x = robjects.ListVector({'a': 1, 'b': 2, 'c': 3})
>>> x.rx2[{'i': x.names.index('b')}] = 9
Missing values¶
Anyone with experience in the analysis of real data knows that
some of the data might be missing. In S/Splus/R special NA values can be used
in a data vector to indicate that fact, and rpy2.robjects
makes aliases for
those available as data objects NA_Logical
, NA_Real
,
NA_Integer
, NA_Character
, NA_Complex
.
>>> x = robjects.IntVector(range(3))
>>> x[0] = robjects.NA_Integer
>>> print(x)
[1] NA 1 2
The translation of NA types is done at the item level, returning a pointer to the corresponding NA singleton class.
>>> x[0] is robjects.NA_Integer
True
>>> x[0] == robjects.NA_Integer
True
>>> [y for y in x if y is not robjects.NA_Integer]
[1, 2]
Note
NA_Logical
is the alias for R’s NA.
Note
The NA objects are imported from the corresponding
rpy2.rinterface
objects.
Operators¶
Mathematical operations on two vectors: the following operations are performed elementwise in R, recycling the shortest vector if, and as much as, necessary.
To expose that to Python, a delegating attribute ro
is provided
for vectorlike objects.
Python 
R 

























>>> x = robjects.r.seq(1, 10)
>>> print(x.ro + 1)
2:11
Note
In Python, using the operator +
on two sequences
concatenates them and this behavior has been conserved:
>>> print(x + 1)
[1] 1 2 3 4 5 6 7 8 9 10 1
Note
The boolean operator not
cannot be redefined in Python (at least up to
version 2.5), and its behavior could not be made to mimic R’s behavior
Names¶
R
vectors can have a name given to all or some of the elements.
The property names
can be used to get, or set, those names.
>>> x = robjects.r.seq(1, 5)
>>> x.names = robjects.StrVector('abcde')
>>> x.names[0]
'a'
>>> x.names[0] = 'z'
>>> tuple(x.names)
('z', 'b', 'c', 'd', 'e')
Array
¶
In R, arrays are simply vectors with a dimension attribute. That fact
was reflected in the class hierarchy with robjects.Array
inheriting
from robjects.Vector
.
 class rpy2.robjects.vectors.Array(obj)[source]¶
Bases:
Vector
An R array
 property dim¶
Get or set the dimension of the array.
 property dimnames: Sexp¶
Return a list of name vectors (like the R function ‘dimnames’ does).
 property names: Sexp¶
Return a list of name vectors (like the R function ‘dimnames’ does).
Matrix
¶
A Matrix
is a special case of Array
. As with arrays,
one must remember that this is just a vector with dimension attributes
(number of rows, number of columns).
>>> m = robjects.r.matrix(robjects.IntVector(range(10)), nrow=5)
>>> print(m)
[,1] [,2]
[1,] 0 5
[2,] 1 6
[3,] 2 7
[4,] 3 8
[5,] 4 9
Note
In R, matrices are columnmajor ordered, although the constructor
matrix()
accepts a boolean argument byrow that, when true,
will build the matrix as if rowmajor ordered.
Computing on matrices¶
Regular operators work elementwise on the underlying vector.
>>> m = robjects.r.matrix(robjects.IntVector(range(4)), nrow=2)
>>> print(m.ro + 1)
[,1] [,2]
[1,] 1 3
[2,] 2 4
For more on operators, see Operators.
Matrix multiplication is available as Matrix.dot()
,
transposition as Matrix.transpose()
. Common
operations such as crossproduct, eigen values computation
, and singular value decomposition are also available through
method with explicit names.
>>> print( m.crossprod(m) )
[,1] [,2]
[1,] 1 3
[2,] 3 13
>>> print( m.transpose().dot(m) )
[,1] [,2]
[1,] 1 3
[2,] 3 13
 class rpy2.robjects.vectors.Matrix(obj)[source]¶
Bases:
Array
An R matrix
 property colnames¶
Column names
 property ncol¶
Number of columns
 property nrow¶
Number of rows
 property rownames¶
Row names
Extracting¶
Extracting can still be performed Pythonstyle or Rstyle.
>>> m = ro.r.matrix(ro.IntVector(range(2, 8)), nrow=3)
>>> print(m)
[,1] [,2]
[1,] 2 5
[2,] 3 6
[3,] 4 7
>>> m[0]
2
>>> m[5]
7
>>> print(m.rx(1))
[1] 2
>>> print(m.rx(6))
[1] 7
Matrixes are twodimensional arrays, and elements can be extracted according to two indexes:
>>> print(m.rx(1, 1))
[1] 2
>>> print(m.rx(3, 2))
[1] 7
Extracting a whole row, or column can be achieved by replacing an index number by True or False
Extract the first column:
>>> print(m.rx(True, 1))
Extract the second row:
>>> print(m.rx(2, True))
DataFrame
¶
Data frames are a common way in R to represent the data to analyze.
A data frame can be thought of as a tabular representation of data, with one variable per column, and one data point per row. Each column is an R vector, which implies one type for all elements in one given column, and which allows for possibly different types across different columns.
If we consider for example tre data about pharmacokinetics of theophylline in different subjects, the data table could look like this:
Subject 
Weight 
Dose 
Time 
conc 

1 
79.6 
4.02 
0.00 
0.74 
1 
79.6 
4.02 
0.25 
2.84 
1 
79.6 
4.02 
0.57 
6.57 
2 
72.4 
4.40 
7.03 
5.40 
… 
… 
… 
… 
… 
Such data representation shares similarities with a table in a relational database: the structure between the variables, or columns, is given by other column. In the example above, the grouping of measures by subject is given by the column Subject.
In rpy2.robjects
,
DataFrame
represents the R class data.frame.
Creating objects¶
Creating a DataFrame
can be done by:
Using the constructor for the class
Create the data.frame through R
Read data from a file using the instance method
from_csvfile()
The DataFrame
constructor accepts either an
rinterface.SexpVector
(with typeof
equal to VECSXP, that is, an R list)
or any Python object implementing the method items()
(for example dict
or rpy2.rlike.container.OrdDict
).
Empty data.frame:
>>> dataf = robjects.DataFrame({})
data.frame with 2 two columns (not that the order of
the columns in the resulting DataFrame
can be different
from the order in which they are declared):
>>> d = {'a': robjects.IntVector((1,2,3)), 'b': robjects.IntVector((4,5,6))}
>>> dataf = robject.DataFrame(d)
To create a DataFrame
and be certain of the clumn order order,
an ordered dictionary can be used:
>>> import rpy2.rlike.container as rlc
>>> od = rlc.OrdDict([('value', robjects.IntVector((1,2,3))),
('letter', robjects.StrVector(('x', 'y', 'z')))])
>>> dataf = robjects.DataFrame(od)
>>> print(dataf.colnames)
[1] "letter" "value"
Creating the data.frame in R can otherwise be achieved in numerous ways, as many R functions do return a data.frame, such as the function data.frame().
Note
When creating a DataFrame
, vectors of strings are automatically
converted by R into instances of class Factor
. This behavior
can be prevented by wrapping the call into the R base function I.
from rpy2.robjects.vectors import DataFrame, StrVector
from rpy2.robjects.packages import importr
base = importr('base')
dataf = DataFrame({'string': base.I(StrVector('abbab')),
'factor': StrVector('abbab')})
Here the DataFrame
dataf now has two columns, one as
a Factor
, the other one as a StrVector
>>> dataf.rx2('string')
<StrVector  Python:0x95fe5ec / R:0x9646ea0>
>>> dataf.rx2('factor')
<FactorVector  Python:0x95fe86c / R:0x9028138>
Extracting elements¶
Here again, Python’s __getitem__()
will work
as a Python programmer will expect it to:
>>> len(dataf)
2
>>> dataf[0]
<Vector  Python:0x8a58c2c / R:0x8e7dd08>
The DataFrame
is composed of columns,
with each column being possibly of a different type:
>>> [column.rclass[0] for column in dataf]
['factor', 'integer']
Using Rstyle access to elements is a little richer, with the rx2 accessor taking more importance than earlier.
Like with Python’s __getitem__()
above,
extracting on one index selects columns:
>>> dataf.rx(1)
<DataFrame  Python:0x8a584ac / R:0x95a6fb8>
>>> print(dataf.rx(1))
letter
1 x
2 y
3 z
Note that the result is itself
of class DataFrame
. To get the column as
a vector, use rx2:
>>> dataf.rx2(1)
<Vector  Python:0x8a4bfcc / R:0x8e7dd08>
>>> print(dataf.rx2(1))
[1] x y z
Levels: x y z
Since data frames are tablelike structure, they can be thought of as twodimensional arrays and can therefore be extracted on two indices.
>>> subdataf = dataf.rx(1, True)
>>> print(subdataf)
letter value
1 x 1
>>> rows_i < robjects.IntVector((1,3))
>>> subdataf = dataf.rx(rows_i, True)
>>> print(subdataf)
letter value
1 x 1
3 z 3
That last example is extremely common in R. A vector of indices,
here rows_i, is used to take a subset of the DataFrame
.
Python docstrings¶
 class rpy2.robjects.vectors.DataFrame(tlist)[source]¶
Bases:
ListVector
R ‘data.frame’.
 classmethod from_csvfile(path, header=True, sep=',', quote='"', dec='.', row_names=<rpy2.rinterface._MissingArgType object> [RTYPES.SYMSXP], col_names=<rpy2.rinterface._MissingArgType object> [RTYPES.SYMSXP], fill=True, comment_char='', na_strings=[], as_is=False)[source]¶
Create an instance from data in a .csv file.
 Parameters:
path – string with a path
header – boolean (heading line with column names or not)
sep – separator character
quote – quote character
row_names – column name, or column index for column names (warning: indexing starts at one in R)
fill – boolean (fill the lines when less entries than columns)
comment_char – comment character
na_strings – a list of strings which are interpreted to be NA values
as_is – boolean (keep the columns of strings as such, or turn them into factors)
 property ncol¶
Number of columns. :rtype: integer
 property nrow¶
Number of rows. :rtype: integer
 property rownames¶
Row names
 to_csvfile(path, quote=True, sep=',', eol='\n', na='NA', dec='.', row_names=True, col_names=True, qmethod='escape', append=False)[source]¶
Save the data into a .csv file.
:param path : string with a path :param quote : quote character :param sep : separator character :param eol : endofline character(s) :param na : string for missing values :param dec : string for decimal separator :param row_names : boolean (save row names, or not) :param col_names : boolean (save column names, or not) :param comment_char : method to ‘escape’ special characters :param append : boolean (append if the file in the path is already existing, or not)