0
# Vector and Data Types
1

2
Comprehensive Python wrappers for R's vector types and data structures, providing seamless integration between Python and R data representations with automatic type conversion and Python-like operations.
3

4
## Capabilities
5

6
### Numeric Vectors
7

8
Python wrappers for R's numeric vector types with full mathematical operations support.
9

10
```python { .api }
11
class IntVector(Vector):
12
    """
13
    R integer vector with Python list-like interface.
14
    
15
    Supports R integer operations, indexing, and conversion
16
    to/from Python integers and lists.
17
    """
18
    def __init__(self, iterable): ...
19

20
class FloatVector(Vector):
21
    """
22
    R numeric (double) vector with Python list-like interface.
23
    
24
    Supports R numeric operations, mathematical functions,
25
    and conversion to/from Python floats and lists.
26
    """
27
    def __init__(self, iterable): ...
28

29
class ComplexVector(Vector):
30
    """
31
    R complex vector with Python list-like interface.
32
    
33
    Supports complex number operations and conversion
34
    to/from Python complex numbers.
35
    """
36
    def __init__(self, iterable): ...
37
```
38

39
### Logical and Character Vectors
40

41
Vectors for boolean and string data with R-specific behavior.
42

43
```python { .api }
44
class BoolVector(Vector):
45
    """
46
    R logical vector with Python list-like interface.
47
    
48
    Handles R's three-valued logic (TRUE/FALSE/NA) and
49
    conversion to/from Python booleans.
50
    """
51
    def __init__(self, iterable): ...
52

53
class StrVector(Vector):
54
    """
55
    R character vector with Python list-like interface.
56
    
57
    Supports R string operations and conversion to/from
58
    Python strings and lists of strings.
59
    """
60
    def __init__(self, iterable): ...
61

62
class ByteVector(Vector):
63
    """
64
    R raw (byte) vector with Python bytes-like interface.
65
    
66
    Handles raw binary data in R, similar to Python bytes
67
    objects with R vector operations.
68
    """
69
    def __init__(self, iterable): ...
70

71
class FactorVector(Vector):
72
    """
73
    R factor vector for categorical data.
74
    
75
    Represents categorical variables with defined levels,
76
    similar to pandas Categorical or R factors.
77
    """
78
    def __init__(self, iterable, levels=None, ordered=False): ...
79
    
80
    @property
81
    def levels(self) -> StrVector:
82
        """Get factor levels."""
83
    
84
    @property 
85
    def ordered(self) -> bool:
86
        """Check if factor is ordered."""
87
```
88

89
### Base Vector Class
90

91
Common functionality shared by all vector types.
92

93
```python { .api }
94
class Vector(RObject):
95
    """
96
    Base class for R vectors with Python sequence interface.
97
    
98
    Provides common vector operations including indexing,
99
    slicing, length, and mathematical operations.
100
    """
101
    def __len__(self) -> int: ...
102
    def __getitem__(self, key): ...
103
    def __setitem__(self, key, value): ...
104
    def __iter__(self): ...
105
    
106
    @property
107
    def names(self) -> StrVector:
108
        """Get or set vector element names."""
109
    
110
    @names.setter
111
    def names(self, value): ...
112
```
113

114
### Container Types
115

116
R lists and specialized container structures.
117

118
```python { .api }
119
class ListVector(Vector):
120
    """
121
    R list with Python dict-like interface.
122
    
123
    Named lists behave like Python dictionaries while
124
    maintaining R list semantics and operations.
125
    """
126
    def keys(self): ...
127
    def values(self): ...
128
    def items(self): ...
129

130
class PairlistVector(Vector):
131
    """
132
    R pairlist wrapper for argument lists and environments.
133
    
134
    Used internally by R for function arguments and
135
    environment contents.
136
    """
137
```
138

139
### Data Frames
140

141
R data.frame with pandas-like interface for tabular data.
142

143
```python { .api }
144
class DataFrame(ListVector):
145
    """
146
    R data.frame with pandas-like interface.
147
    
148
    Provides column access, row/column operations, and
149
    integration with pandas DataFrames when available.
150
    """
151
    def __init__(self, data): ...
152
    
153
    @property
154
    def rownames(self) -> StrVector:
155
        """Get or set row names."""
156
    
157
    @rownames.setter
158
    def rownames(self, value): ...
159
    
160
    @property
161
    def colnames(self) -> StrVector:
162
        """Get or set column names."""
163
    
164
    @colnames.setter  
165
    def colnames(self, value): ...
166
    
167
    @property
168
    def ncol(self) -> int:
169
        """Number of columns."""
170
    
171
    @property
172
    def nrow(self) -> int:
173
        """Number of rows."""
174
```
175

176
### Multi-dimensional Arrays
177

178
Matrices and higher-dimensional arrays with R semantics.
179

180
```python { .api }
181
class Matrix(Vector):
182
    """
183
    Two-dimensional R matrix with mathematical operations.
184
    
185
    Supports matrix algebra, indexing by row/column,
186
    and conversion to/from NumPy arrays when available.
187
    """
188
    def __init__(self, array, nrow=None, ncol=None): ...
189
    
190
    @property
191
    def nrow(self) -> int:
192
        """Number of rows."""
193
    
194
    @property  
195
    def ncol(self) -> int:
196
        """Number of columns."""
197
    
198
    @property
199
    def rownames(self) -> StrVector:
200
        """Row names."""
201
    
202
    @property
203
    def colnames(self) -> StrVector:
204
        """Column names."""
205

206
class Array(Vector):
207
    """
208
    Multi-dimensional R array with arbitrary dimensions.
209
    
210
    Supports n-dimensional indexing and operations
211
    similar to NumPy arrays but with R semantics.
212
    """
213
    def __init__(self, array, dim=None): ...
214
    
215
    @property
216
    def dim(self) -> IntVector:
217
        """Array dimensions."""
218
```
219

220
### Specialized Matrix Types
221

222
Type-specific matrix classes for each vector type.
223

224
```python { .api }
225
class IntMatrix(Matrix, IntVector):
226
    """Integer matrix with mathematical operations."""
227

228
class FloatMatrix(Matrix, FloatVector):
229
    """Floating-point matrix with mathematical operations."""
230

231
class BoolMatrix(Matrix, BoolVector):
232
    """Boolean matrix with logical operations."""
233

234
class ComplexMatrix(Matrix, ComplexVector):
235
    """Complex number matrix with mathematical operations."""
236

237
class StrMatrix(Matrix, StrVector):
238
    """String matrix for text data organization."""
239

240
class ByteMatrix(Matrix, ByteVector):
241
    """Byte matrix for raw binary data organization."""
242
```
243

244
### Specialized Array Types
245

246
Type-specific array classes for each vector type.
247

248
```python { .api }
249
class IntArray(Array, IntVector):
250
    """Multi-dimensional integer array."""
251

252
class FloatArray(Array, FloatVector):
253
    """Multi-dimensional floating-point array."""
254

255
class BoolArray(Array, BoolVector):
256
    """Multi-dimensional boolean array."""
257

258
class ComplexArray(Array, ComplexVector):
259
    """Multi-dimensional complex number array."""
260

261
class StrArray(Array, StrVector):
262
    """Multi-dimensional string array."""
263

264
class ByteArray(Array, ByteVector):
265
    """Multi-dimensional byte array for raw data."""
266
```
267

268
### Date and Time Vectors
269

270
R date and time representations with timezone support.
271

272
```python { .api }
273
class DateVector(Vector):
274
    """
275
    R Date vector for calendar dates.
276
    
277
    Represents dates without time information,
278
    compatible with Python datetime.date objects.
279
    """
280
    def __init__(self, iterable): ...
281

282
class POSIXct(Vector):
283
    """
284
    R POSIXct vector for date-time as continuous time.
285
    
286
    Calendar time representation with timezone support,
287
    compatible with Python datetime.datetime objects.
288
    """
289
    def __init__(self, iterable, timezone=None): ...
290

291
class POSIXlt(Vector):
292
    """
293
    R POSIXlt vector for date-time as list structure.
294
    
295
    Broken-down time representation storing components
296
    like year, month, day, hour, minute, second separately.
297
    """
298
    def __init__(self, iterable, timezone=None): ...
299
```
300

301
### Usage Examples
302

303
```python
304
from rpy2.robjects.vectors import (IntVector, FloatVector, StrVector, 
305
                                   BoolVector, ByteVector, ComplexVector,
306
                                   FactorVector, DataFrame, Matrix, Array)
307
import rpy2.robjects as ro
308

309
# Create vectors from Python data
310
int_vec = IntVector([1, 2, 3, 4, 5])
311
float_vec = FloatVector([1.1, 2.2, 3.3, 4.4, 5.5])
312
str_vec = StrVector(['a', 'b', 'c', 'd', 'e'])
313

314
# Vector operations
315
print(len(int_vec))  # 5
316
print(int_vec[0])    # 1
317
print(list(int_vec)) # [1, 2, 3, 4, 5]
318

319
# Named vectors
320
int_vec.names = str_vec
321
print(int_vec.names)  # ['a', 'b', 'c', 'd', 'e']
322

323
# Create data frame
324
df = DataFrame({
325
    'integers': int_vec,
326
    'floats': float_vec,
327
    'strings': str_vec
328
})
329

330
print(df.nrow)     # 5
331
print(df.ncol)     # 3
332
print(df.colnames) # ['integers', 'floats', 'strings']
333

334
# Access data frame columns
335
print(df[0])  # integers column
336
print(df['floats'])  # floats column by name
337

338
# Factor vectors for categorical data
339
from rpy2.robjects.vectors import FactorVector
340
categories = FactorVector(['low', 'medium', 'high', 'low', 'high'])
341
print(categories.levels)  # ['high', 'low', 'medium']
342

343
# Matrix operations
344
from rpy2.robjects.vectors import Matrix
345
import numpy as np
346

347
# Create matrix from Python data
348
matrix_data = Matrix(range(12), nrow=3, ncol=4)
349
print(matrix_data.nrow)  # 3
350
print(matrix_data.ncol)  # 4
351
```