0
# Jupyter Integration
1

2
IPython magic commands and rich display integration for seamless R usage in Jupyter notebooks with automatic plot rendering, data visualization, and interactive R computing.
3

4
## Capabilities
5

6
### IPython Extension Loading
7

8
Load rpy2 extension to enable R magic commands in Jupyter notebooks and IPython environments.
9

10
```python { .api }
11
def load_ipython_extension(ipython):
12
    """
13
    Load rpy2 IPython extension.
14
    
15
    Parameters:
16
    - ipython: IPython instance
17
    
18
    Enables %R line magic and %%R cell magic commands
19
    for executing R code within Python notebooks.
20
    
21
    Usage:
22
    %load_ext rpy2.ipython
23
    """
24
```
25

26
### Magic Commands
27

28
Execute R code directly in Jupyter notebook cells with automatic data exchange and visualization.
29

30
```python { .api }
31
# Line magic: %R
32
# Execute single line of R code
33
# Usage: %R r_code_here
34

35
# Cell magic: %%R  
36
# Execute entire cell as R code
37
# Usage:
38
# %%R [options]
39
# r_code_line_1
40
# r_code_line_2
41
# ...
42

43
# Magic command options:
44
# -i INPUT: Input Python variable to R
45
# -o OUTPUT: Output R variable to Python  
46
# -w WIDTH: Plot width in pixels
47
# -h HEIGHT: Plot height in pixels
48
# -r RESOLUTION: Plot resolution in DPI
49
# --units UNITS: Plot size units ('in', 'px', 'cm')
50
```
51

52
### HTML Display Integration
53

54
Rich HTML output and visualization rendering for R graphics and data in Jupyter notebooks.
55

56
```python { .api }
57
# Available in rpy2.ipython.html module
58
class HTMLResult:
59
    """
60
    HTML representation of R objects for Jupyter display.
61
    
62
    Automatically renders R objects as HTML in notebook
63
    cells for rich interactive display.
64
    """
65
    def _repr_html_(self) -> str: ...
66

67
def display_html(r_object):
68
    """
69
    Display R object as HTML in Jupyter notebook.
70
    
71
    Parameters:
72
    - r_object: R object to display
73
    
74
    Automatically formats R data frames, summaries,
75
    and other objects for rich notebook display.
76
    """
77
```
78

79
### ggplot2 Integration
80

81
Specialized integration for ggplot2 graphics with automatic rendering and interactive display.
82

83
```python { .api }
84
# Available in rpy2.ipython.ggplot module
85
class GGPlot:
86
    """
87
    ggplot2 plot wrapper with Jupyter display integration.
88
    
89
    Automatically renders ggplot2 plots in notebook cells
90
    with proper sizing, resolution, and format handling.
91
    """
92
    def _repr_png_(self) -> bytes: ...
93
    def _repr_svg_(self) -> str: ...
94
    def show(self, width=None, height=None, dpi=None): ...
95

96
def activate_ggplot():
97
    """
98
    Activate automatic ggplot2 rendering in Jupyter.
99
    
100
    Enables automatic display of ggplot2 objects
101
    when they are the last expression in a cell.
102
    """
103

104
def deactivate_ggplot():
105
    """
106
    Deactivate automatic ggplot2 rendering.
107
    
108
    Returns to default R graphics behavior
109
    without automatic Jupyter integration.
110
    """
111
```
112

113
### Data Exchange
114

115
Seamless data transfer between Python and R variables in notebook environments.
116

117
```python { .api }
118
# Data flows automatically between Python and R
119
# Python → R: Use -i option or direct assignment
120
# R → Python: Use -o option or direct access
121

122
# Automatic conversions:
123
# pandas DataFrame ↔ R data.frame
124
# NumPy array ↔ R vector/matrix  
125
# Python list ↔ R vector
126
# Python dict ↔ R named list
127
```
128

129
### Magic Command Configuration
130

131
Configure magic command behavior and default settings.
132

133
```python { .api }
134
# IPython magic configuration options
135
class RMagicsConfig:
136
    """Configuration for R magic commands."""
137
    cache_display_data: bool = True    # Cache plot data
138
    device: str = 'png'               # Default graphics device
139
    units: str = 'in'                 # Size units
140
    res: int = 72                     # Default resolution
141
    width: float = 7.0                # Default width  
142
    height: float = 7.0               # Default height
143
    pointsize: int = 12               # Default point size
144
```
145

146
### Usage Examples
147

148
```python
149
# Load the extension (run this once per notebook)
150
%load_ext rpy2.ipython
151

152
# Basic R execution
153
%R print("Hello from R!")
154

155
# Execute R code and capture output
156
%R x <- c(1, 2, 3, 4, 5)
157
%R mean_x <- mean(x)  
158
%R print(mean_x)
159

160
# Transfer data from Python to R
161
import pandas as pd
162
import numpy as np
163

164
python_data = pd.DataFrame({
165
    'A': [1, 2, 3, 4, 5],
166
    'B': [1.1, 2.2, 3.3, 4.4, 5.5]
167
})
168

169
%R -i python_data
170
%R print(head(python_data))
171
%R summary(python_data)
172

173
# Transfer data from R to Python
174
%R r_result <- lm(B ~ A, data=python_data)
175
%R -o r_result
176
print(f"R result in Python: {type(r_result)}")
177

178
# Cell magic for multi-line R code
179
%%R
180
# This entire cell is executed as R code
181
library(ggplot2)
182

183
# Create a plot
184
p <- ggplot(python_data, aes(x=A, y=B)) +
185
  geom_point() +
186
  geom_smooth(method="lm") +
187
  labs(title="Linear Regression Plot",
188
       x="Variable A", 
189
       y="Variable B")
190

191
print(p)
192

193
# Control plot size and resolution
194
%%R -w 800 -h 600 -r 150
195
library(ggplot2)
196
ggplot(mtcars, aes(x=wt, y=mpg)) +
197
  geom_point() +
198
  geom_smooth() +
199
  labs(title="Car Weight vs MPG")
200

201
# Bidirectional data flow
202
%%R -i python_data -o r_summary
203
# Input python_data from Python, output r_summary to Python
204
r_summary <- summary(lm(B ~ A, data=python_data))
205
print(r_summary)
206

207
# Now r_summary is available in Python
208
print(f"R summary type: {type(r_summary)}")
209

210
# Working with multiple variables
211
x_data = np.array([1, 2, 3, 4, 5])
212
y_data = np.array([2, 4, 6, 8, 10])
213

214
%%R -i x_data,y_data -o correlation,p_value
215
# Multiple inputs and outputs
216
correlation <- cor(x_data, y_data)  
217
test_result <- cor.test(x_data, y_data)
218
p_value <- test_result$p.value
219

220
print(paste("Correlation:", correlation))
221
print(paste("P-value:", p_value))
222

223
print(f"Correlation: {correlation[0]}")
224
print(f"P-value: {p_value[0]}")
225
```
226

227
### Advanced Integration Patterns
228

229
```python
230
# Custom plot styling and output
231
%%R -w 1000 -h 800 --units px -r 300
232
library(ggplot2)
233
library(dplyr)
234

235
# Advanced ggplot with custom styling
236
mtcars %>%
237
  ggplot(aes(x=wt, y=mpg, color=factor(cyl))) +
238
  geom_point(size=3, alpha=0.7) +
239
  geom_smooth(method="lm", se=FALSE) +
240
  facet_wrap(~gear) +
241
  labs(title="MPG vs Weight by Cylinders and Gears",
242
       x="Weight (1000 lbs)",
243
       y="Miles Per Gallon",
244
       color="Cylinders") +
245
  theme_minimal() +
246
  theme(plot.title = element_text(hjust = 0.5, size=16))
247

248
# Statistical analysis with output capture
249
import scipy.stats as stats
250

251
sample_data = np.random.normal(100, 15, 100)
252

253
%%R -i sample_data -o r_stats
254
# Comprehensive statistical analysis
255
r_stats <- list(
256
  mean = mean(sample_data),
257
  median = median(sample_data),
258
  sd = sd(sample_data),
259
  shapiro_test = shapiro.test(sample_data),
260
  normality_p = shapiro.test(sample_data)$p.value
261
)
262

263
print("Statistical Summary:")
264
print(r_stats)
265

266
# Access detailed results in Python
267
print(f"Mean: {r_stats[0][0]:.2f}")
268
print(f"Median: {r_stats[1][0]:.2f}")  
269
print(f"Standard Deviation: {r_stats[2][0]:.2f}")
270
print(f"Normality test p-value: {r_stats[4][0]:.4f}")
271

272
# Interactive plotting with multiple datasets
273
datasets = {
274
    'iris': pd.read_csv('https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv'),
275
    'tips': pd.read_csv('https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv')
276
}
277

278
for name, data in datasets.items():
279
    print(f"\n=== Analysis of {name} dataset ===")
280
    
281
    %R -i data
282
    %%R
283
    print(paste("Dataset shape:", nrow(data), "x", ncol(data)))
284
    print("Summary:")
285
    print(summary(data))
286
    
287
    if name == 'iris':
288
        %%R -w 600 -h 400
289
        library(ggplot2)
290
        ggplot(data, aes(x=sepal_length, y=sepal_width, color=species)) +
291
          geom_point() +
292
          labs(title="Iris: Sepal Length vs Width")
293
    
294
    elif name == 'tips':
295
        %%R -w 600 -h 400  
296
        library(ggplot2)
297
        ggplot(data, aes(x=total_bill, y=tip, color=time)) +
298
          geom_point() +
299
          geom_smooth(method="lm") +
300
          labs(title="Tips: Total Bill vs Tip Amount")
301
```
302

303
### Configuration and Troubleshooting
304

305
```python
306
# Check if extension is loaded
307
%lsmagic  # Should show %R and %%R in line/cell magics
308

309
# Reload extension if needed
310
%reload_ext rpy2.ipython
311

312
# Configure default plot settings
313
%config InlineBackend.figure_format = 'retina'  # High-res plots
314
%config InlineBackend.rc = {'figure.figsize': (10, 6)}
315

316
# Debug R magic issues
317
%R print(R.version.string)  # Check R version
318
%R print(.libPaths())       # Check R library paths
319
%R print(sessionInfo())     # Complete R session info
320

321
# Handle R warnings and errors
322
%%R
323
options(warn=1)  # Print warnings immediately
324
print("R is working correctly")
325

326
# Memory management for large datasets
327
%%R
328
# Clean up R environment
329
rm(list=ls())
330
gc()  # Garbage collection
331
```