0
# High-Level R Interface
1

2
The high-level interface (`rpy2.robjects`) provides the primary entry point for most rpy2 users, offering Pythonic access to R objects, functions, and data structures with automatic type conversion.
3

4
## Capabilities
5

6
### R Session Access
7

8
The global `r` object provides direct access to the embedded R session, allowing execution of R code and access to R objects.
9

10
```python { .api }
11
class R:
12
    def __call__(self, string: str, invisible: bool = None, print_r_warnings: bool = None) -> Any:
13
        """
14
        Execute R code string and return result.
15
        
16
        Parameters:
17
        - string: R code to execute
18
        - invisible: If True, suppress R output
19
        - print_r_warnings: If True, print R warnings
20
        
21
        Returns:
22
        R object converted to Python equivalent
23
        """
24
    
25
    def __getitem__(self, item: str) -> Any:
26
        """
27
        Get R object by name from global environment.
28
        
29
        Parameters:
30
        - item: Name of R object
31
        
32
        Returns:
33
        R object converted to Python wrapper
34
        """
35
    
36
    def __getattribute__(self, attr: str) -> Any:
37
        """
38
        Access R object as Python attribute.
39
        
40
        Parameters:
41
        - attr: R object name
42
        
43
        Returns:
44
        R object as Python attribute
45
        """
46

47
# Global R session singleton
48
r: R
49
```
50

51
### R Code Evaluation
52

53
Direct evaluation of R code with high-level type conversion.
54

55
```python { .api }
56
def reval(string: str, envir = globalenv) -> Any:
57
    """
58
    Evaluate R code string with robjects conversion.
59
    
60
    Parameters:
61
    - string: R code to evaluate
62
    - envir: R environment for evaluation (default: global environment)
63
    
64
    Returns:
65
    Evaluated result with robjects conversion
66
    """
67
```
68

69
### Base R Object Wrappers
70

71
High-level wrappers for core R objects with Python-like interfaces.
72

73
```python { .api }
74
class RObject:
75
    """Base mixin class for R objects with high-level interface."""
76
    
77
class ExternalPointer(RObject):
78
    """Wrapper for R external pointer objects."""
79
    
80
class Formula(RObject):
81
    """
82
    R formula object wrapper with environment management.
83
    
84
    Represents R formulas like 'y ~ x1 + x2' for statistical modeling.
85
    """
86
```
87

88
### Function Interface
89

90
Wrappers for R functions that provide Python-like calling conventions.
91

92
```python { .api }
93
class Function(RObject):
94
    """
95
    R function wrapper with Python callable interface.
96
    
97
    Allows calling R functions from Python with automatic
98
    argument conversion and Python-style parameter passing.
99
    """
100
    def __call__(self, *args, **kwargs) -> Any: ...
101

102
class SignatureTranslatedFunction(Function):
103
    """
104
    Function with Python-like signature translation.
105
    
106
    Provides more Pythonic parameter names and calling conventions
107
    by translating R parameter names to Python conventions.
108
    """
109

110
class DocumentedSTFunction(SignatureTranslatedFunction):
111
    """
112
    Documented signature-translated function with help text.
113
    
114
    Includes R help documentation accessible from Python.
115
    """
116
```
117

118
### Language Object Interface
119

120
Wrappers for R language objects and unevaluated expressions.
121

122
```python { .api }
123
class LangVector(RObject):
124
    """
125
    R language object wrapper for unevaluated R expressions.
126
    
127
    Represents R calls, expressions, and language constructs
128
    that can be evaluated in R contexts.
129
    """
130
    
131
    @classmethod
132
    def from_string(cls, string: str) -> 'LangVector':
133
        """
134
        Create language vector from R code string.
135
        
136
        Parameters:
137
        - string: R code as string
138
        
139
        Returns:
140
        Language vector representing the R expression
141
        """
142
```
143

144
### Usage Examples
145

146
```python
147
import rpy2.robjects as robjects
148
from rpy2.robjects import r
149

150
# Execute R code directly
151
result = r('2 + 2')
152
print(result[0])  # 4.0
153

154
# Get R objects by name
155
r('x <- c(1, 2, 3, 4, 5)')
156
x = r['x']
157
print(list(x))  # [1.0, 2.0, 3.0, 4.0, 5.0]
158

159
# Access R objects as attributes
160
r('y <- mean(c(1, 2, 3, 4, 5))')
161
y = r.y
162
print(y[0])  # 3.0
163

164
# Work with R functions
165
r_sum = r['sum']
166
result = r_sum(robjects.IntVector([1, 2, 3, 4, 5]))
167
print(result[0])  # 15.0
168

169
# Create and use formulas
170
from rpy2.robjects import Formula
171
formula = Formula('y ~ x1 + x2')
172
print(formula)
173

174
# Use high-level evaluation
175
result = robjects.reval('mean(c(1, 2, 3, 4, 5))')
176
print(result[0])  # 3.0
177
```