0
# Geometric Objects
1

2
Geometric objects (geoms) are the visual representations that render your data as points, lines, bars, areas, and other shapes. Plotnine provides over 50 geometric objects covering all common visualization types, from basic scatter plots to complex statistical graphics. Each geom has specific aesthetic requirements and optional parameters for customization.
3

4
## Capabilities
5

6
### Point and Scatter Geoms
7

8
Visualize individual observations as points, with options for jittering, counting overlaps, and density-based coloring.
9

10
```python { .api }
11
def geom_point(mapping=None, data=None, stat='identity', position='identity', 
12
               na_rm=False, inherit_aes=True, show_legend=None, **kwargs):
13
    """
14
    Scatter plot points.
15
    
16
    Required aesthetics: x, y
17
    Optional aesthetics: alpha, color, fill, shape, size, stroke
18
    
19
    Parameters:
20
    - stat: str, statistical transformation ('identity', 'count', etc.)
21
    - position: str or position object, position adjustment
22
    - na_rm: bool, whether to remove missing values
23
    - **kwargs: additional parameters (alpha, color, size, etc.)
24
    """
25

26
def geom_jitter(mapping=None, data=None, width=None, height=None, **kwargs):
27
    """
28
    Jittered points to reduce overplotting.
29
    
30
    Parameters:
31
    - width, height: float, amount of jittering in each direction
32
    """
33

34
def geom_count(mapping=None, data=None, **kwargs):
35
    """
36
    Count overlapping points and map count to size.
37
    
38
    Computed aesthetics: n (count)
39
    """
40

41
def geom_pointdensity(mapping=None, data=None, **kwargs):
42
    """
43
    Points colored by local density.
44
    
45
    Computed aesthetics: density
46
    """
47
```
48

49
### Line and Path Geoms  
50

51
Connect observations with lines, paths, and steps, supporting grouping and various line styles.
52

53
```python { .api }
54
def geom_line(mapping=None, data=None, stat='identity', position='identity',
55
              na_rm=False, **kwargs):
56
    """
57
    Connect observations with lines, ordered by x values.
58
    
59
    Required aesthetics: x, y
60
    Optional aesthetics: alpha, color, linetype, size, group
61
    """
62

63
def geom_path(mapping=None, data=None, **kwargs):
64
    """
65
    Connect observations with lines in data order.
66
    
67
    Required aesthetics: x, y
68
    Optional aesthetics: alpha, color, linetype, size, group
69
    """
70

71
def geom_step(mapping=None, data=None, direction='hv', **kwargs):
72
    """
73
    Connect observations with step function.
74
    
75
    Parameters:
76
    - direction: str, step direction ('hv', 'vh', 'mid')
77
    """
78

79
def geom_segment(mapping=None, data=None, **kwargs):
80
    """
81
    Line segments between points.
82
    
83
    Required aesthetics: x, y, xend, yend
84
    Optional aesthetics: alpha, color, linetype, size
85
    """
86

87
def geom_spoke(mapping=None, data=None, **kwargs):
88
    """
89
    Line segments from center point with angle and radius.
90
    
91
    Required aesthetics: x, y, angle, radius
92
    Optional aesthetics: alpha, color, linetype, size
93
    """
94
```
95

96
### Area and Shape Geoms
97

98
Create filled areas, ribbons, polygons, and rectangles for area-based visualizations.
99

100
```python { .api }
101
def geom_area(mapping=None, data=None, stat='identity', position='stack',
102
              **kwargs):
103
    """
104
    Filled areas under curves.
105
    
106
    Required aesthetics: x, y
107
    Optional aesthetics: alpha, color, fill, linetype, size
108
    """
109

110
def geom_ribbon(mapping=None, data=None, **kwargs):
111
    """
112
    Ribbons between y limits.
113
    
114
    Required aesthetics: x, ymin, ymax
115
    Optional aesthetics: alpha, color, fill, linetype, size
116
    """
117

118
def geom_polygon(mapping=None, data=None, **kwargs):
119
    """
120
    Filled polygons.
121
    
122
    Required aesthetics: x, y
123
    Optional aesthetics: alpha, color, fill, linetype, size, group
124
    """
125

126
def geom_rect(mapping=None, data=None, **kwargs):
127
    """
128
    Rectangles.
129
    
130
    Required aesthetics: xmin, xmax, ymin, ymax
131
    Optional aesthetics: alpha, color, fill, linetype, size
132
    """
133

134
def geom_tile(mapping=None, data=None, **kwargs):
135
    """
136
    Tiles for heatmaps and grid visualizations.
137
    
138
    Required aesthetics: x, y
139
    Optional aesthetics: alpha, color, fill, linetype, size, width, height
140
    """
141

142
def geom_raster(mapping=None, data=None, **kwargs):
143
    """
144
    High-performance tiles for large datasets.
145
    
146
    Required aesthetics: x, y, fill
147
    """
148
```
149

150
### Bar and Column Geoms
151

152
Create bar charts, histograms, and frequency visualizations with various positioning options.
153

154
```python { .api }
155
def geom_bar(mapping=None, data=None, stat='count', position='stack',
156
             width=None, **kwargs):
157
    """
158
    Bar charts with automatic counting.
159
    
160
    Required aesthetics: x
161
    Optional aesthetics: alpha, color, fill, linetype, size, weight
162
    
163
    Computed aesthetics: count, prop
164
    """
165

166
def geom_col(mapping=None, data=None, position='stack', width=None, **kwargs):
167
    """
168
    Column charts using data values as heights.
169
    
170
    Required aesthetics: x, y
171
    Optional aesthetics: alpha, color, fill, linetype, size
172
    """
173

174
def geom_histogram(mapping=None, data=None, bins=30, binwidth=None, **kwargs):
175
    """
176
    Histograms.
177
    
178
    Required aesthetics: x
179
    Optional aesthetics: alpha, color, fill, linetype, size, weight
180
    
181
    Parameters:
182
    - bins: int, number of bins
183
    - binwidth: float, width of bins
184
    """
185

186
def geom_freqpoly(mapping=None, data=None, **kwargs):
187
    """
188
    Frequency polygons.
189
    
190
    Required aesthetics: x
191
    Optional aesthetics: alpha, color, linetype, size, weight
192
    """
193
```
194

195
### Statistical Geoms
196

197
Visualize statistical summaries including box plots, violin plots, density curves, and smoothed trends.
198

199
```python { .api }
200
def geom_boxplot(mapping=None, data=None, outlier_colour=None, 
201
                 outlier_shape=None, outlier_size=None, **kwargs):
202
    """
203
    Box and whisker plots.
204
    
205
    Required aesthetics: x or y (one must be discrete)
206
    Optional aesthetics: alpha, color, fill, linetype, size, weight
207
    
208
    Computed aesthetics: lower, upper, middle, ymin, ymax
209
    """
210

211
def geom_violin(mapping=None, data=None, scale='area', **kwargs):
212
    """
213
    Violin plots.
214
    
215
    Required aesthetics: x or y (one must be discrete)
216
    Optional aesthetics: alpha, color, fill, linetype, size, weight
217
    
218
    Parameters:
219
    - scale: str, scaling method ('area', 'count', 'width')
220
    """
221

222
def geom_density(mapping=None, data=None, **kwargs):
223
    """
224
    Smooth density estimates.
225
    
226
    Required aesthetics: x
227
    Optional aesthetics: alpha, color, fill, linetype, size, weight
228
    
229
    Computed aesthetics: density, count, scaled
230
    """
231

232
def geom_density_2d(mapping=None, data=None, **kwargs):
233
    """
234
    2D density contours.
235
    
236
    Required aesthetics: x, y
237
    Optional aesthetics: alpha, color, linetype, size
238
    
239
    Computed aesthetics: level, piece
240
    """
241

242
def geom_smooth(mapping=None, data=None, method='auto', se=True, **kwargs):
243
    """
244
    Smoothed conditional means.
245
    
246
    Required aesthetics: x, y
247
    Optional aesthetics: alpha, color, fill, linetype, size, weight
248
    
249
    Parameters:
250
    - method: str, smoothing method ('auto', 'lm', 'loess', 'gam')
251
    - se: bool, whether to display confidence interval
252
    """
253
```
254

255
### Reference Line Geoms
256

257
Add reference lines including horizontal, vertical, and diagonal lines for plot annotation.
258

259
```python { .api }
260
def geom_hline(mapping=None, data=None, yintercept=None, **kwargs):
261
    """
262
    Horizontal reference lines.
263
    
264
    Parameters:
265
    - yintercept: float or list, y-intercept value(s)
266
    Optional aesthetics: alpha, color, linetype, size
267
    """
268

269
def geom_vline(mapping=None, data=None, xintercept=None, **kwargs):
270
    """
271
    Vertical reference lines.
272
    
273
    Parameters:
274
    - xintercept: float or list, x-intercept value(s)
275
    Optional aesthetics: alpha, color, linetype, size
276
    """
277

278
def geom_abline(mapping=None, data=None, slope=None, intercept=None, **kwargs):
279
    """
280
    Diagonal reference lines.
281
    
282
    Parameters:
283
    - slope, intercept: float, line parameters
284
    Optional aesthetics: alpha, color, linetype, size
285
    """
286
```
287

288
### Error Bar and Range Geoms
289

290
Display uncertainty and ranges with error bars, confidence intervals, and range indicators.
291

292
```python { .api }
293
def geom_errorbar(mapping=None, data=None, width=None, **kwargs):
294
    """
295
    Vertical error bars.
296
    
297
    Required aesthetics: x, ymin, ymax
298
    Optional aesthetics: alpha, color, linetype, size
299
    
300
    Parameters:
301
    - width: float, width of error bar caps
302
    """
303

304
def geom_errorbarh(mapping=None, data=None, height=None, **kwargs):
305
    """
306
    Horizontal error bars.
307
    
308
    Required aesthetics: y, xmin, xmax
309
    Optional aesthetics: alpha, color, linetype, size
310
    """
311

312
def geom_linerange(mapping=None, data=None, **kwargs):
313
    """
314
    Vertical line ranges.
315
    
316
    Required aesthetics: x, ymin, ymax
317
    Optional aesthetics: alpha, color, linetype, size
318
    """
319

320
def geom_pointrange(mapping=None, data=None, **kwargs):
321
    """
322
    Points with line ranges.
323
    
324
    Required aesthetics: x, y, ymin, ymax
325
    Optional aesthetics: alpha, color, fill, linetype, shape, size
326
    """
327

328
def geom_crossbar(mapping=None, data=None, **kwargs):
329
    """
330
    Hollow bars with middle line.
331
    
332
    Required aesthetics: x, y, ymin, ymax
333
    Optional aesthetics: alpha, color, fill, linetype, size
334
    """
335
```
336

337
### Text and Label Geoms
338

339
Add text annotations and labels to plots with positioning and formatting options.
340

341
```python { .api }
342
def geom_text(mapping=None, data=None, parse=False, nudge_x=0, nudge_y=0,
343
              check_overlap=False, **kwargs):
344
    """
345
    Text annotations.
346
    
347
    Required aesthetics: x, y, label
348
    Optional aesthetics: alpha, angle, color, family, fontface, hjust, 
349
                        lineheight, size, vjust
350
    
351
    Parameters:
352
    - parse: bool, whether to parse text as expressions
353
    - nudge_x, nudge_y: float, position adjustments
354
    - check_overlap: bool, whether to avoid overlapping text
355
    """
356

357
def geom_label(mapping=None, data=None, **kwargs):
358
    """
359
    Text labels with background boxes.
360
    
361
    Required aesthetics: x, y, label
362
    Optional aesthetics: alpha, angle, color, family, fontface, hjust,
363
                        lineheight, size, vjust, fill
364
    """
365
```
366

367
### Specialized Geoms
368

369
Additional geoms for specific visualization needs including quantile plots, maps, and dot plots.
370

371
```python { .api }
372
def geom_qq(mapping=None, data=None, distribution='norm', **kwargs):
373
    """
374
    Quantile-quantile plots.
375
    
376
    Required aesthetics: sample
377
    Optional aesthetics: alpha, color, fill, linetype, shape, size
378
    
379
    Parameters:
380
    - distribution: str or scipy distribution, theoretical distribution
381
    """
382

383
def geom_qq_line(mapping=None, data=None, distribution='norm', **kwargs):
384
    """
385
    Reference lines for Q-Q plots.
386
    
387
    Required aesthetics: sample
388
    Optional aesthetics: alpha, color, linetype, size
389
    """
390

391
def geom_quantile(mapping=None, data=None, quantiles=None, **kwargs):
392
    """
393
    Quantile regression lines.
394
    
395
    Required aesthetics: x, y
396
    Optional aesthetics: alpha, color, linetype, size, weight
397
    
398
    Parameters:
399
    - quantiles: list, quantiles to compute (default: [0.25, 0.5, 0.75])
400
    """
401

402
def geom_rug(mapping=None, data=None, sides='bl', **kwargs):
403
    """
404
    Marginal rug plots.
405
    
406
    Required aesthetics: x or y
407
    Optional aesthetics: alpha, color, linetype, size
408
    
409
    Parameters:
410
    - sides: str, which sides to draw ('t', 'r', 'b', 'l')
411
    """
412

413
def geom_dotplot(mapping=None, data=None, binaxis='x', method='dotdensity',
414
                 binwidth=None, **kwargs):
415
    """
416
    Dot plots.
417
    
418
    Required aesthetics: x
419
    Optional aesthetics: alpha, color, fill
420
    
421
    Parameters:
422
    - binaxis: str, axis to bin along
423
    - method: str, binning method
424
    - binwidth: float, width of bins
425
    """
426

427
def geom_sina(mapping=None, data=None, **kwargs):
428
    """
429
    Sina plots (jittered violin plots).
430
    
431
    Required aesthetics: x, y
432
    Optional aesthetics: alpha, color, size
433
    """
434

435
def geom_bin2d(mapping=None, data=None, bins=30, **kwargs):
436
    """
437
    2D binning (heatmap).
438
    
439
    Required aesthetics: x, y
440
    Optional aesthetics: alpha, color, fill
441
    
442
    Parameters:
443
    - bins: int or tuple, number of bins in each direction
444
    """
445

446
def geom_bin_2d(mapping=None, data=None, bins=30, **kwargs):
447
    """
448
    2D binning (heatmap) - alternative name for geom_bin2d.
449
    
450
    Required aesthetics: x, y
451
    Optional aesthetics: alpha, color, fill
452
    
453
    Parameters:
454
    - bins: int or tuple, number of bins in each direction
455
    """
456

457
def geom_blank(mapping=None, data=None, **kwargs):
458
    """
459
    Empty geom for setting plot limits.
460
    
461
    Required aesthetics: x, y (or other aesthetics to set limits)
462
    """
463

464
def geom_map(mapping=None, data=None, map=None, **kwargs):
465
    """
466
    Polygon maps.
467
    
468
    Required aesthetics: x, y, group
469
    Optional aesthetics: alpha, color, fill, linetype, size
470
    
471
    Parameters:
472
    - map: DataFrame, map data with polygon coordinates
473
    """
474
```
475

476
### Annotation Functions
477

478
Add annotations and decorative elements to plots.
479

480
```python { .api }
481
def annotate(geom, x=None, y=None, xmin=None, xmax=None, ymin=None, ymax=None,
482
             **kwargs):
483
    """
484
    Add annotations to plots.
485
    
486
    Parameters:
487
    - geom: str, type of annotation ('point', 'text', 'rect', etc.)
488
    - x, y: position coordinates
489
    - xmin, xmax, ymin, ymax: range coordinates for rect annotations
490
    - **kwargs: aesthetic parameters for the annotation
491
    """
492

493
def annotation_logticks(base=10, sides='bl', scaled=True, **kwargs):
494
    """
495
    Add logarithmic tick marks.
496
    
497
    Parameters:
498
    - base: float, logarithm base
499
    - sides: str, which sides to add ticks
500
    - scaled: bool, whether ticks should be scaled
501
    """
502

503
def annotation_stripes(direction='horizontal', **kwargs):
504
    """
505
    Add background stripes.
506
    
507
    Parameters:
508
    - direction: str, stripe direction ('horizontal', 'vertical')
509
    """
510

511
def arrow(angle=30, length=0.25, ends='last', type='open'):
512
    """
513
    Create arrow specification for geom_segment and geom_path.
514
    
515
    Parameters:
516
    - angle: float, angle of arrow head
517
    - length: float, length of arrow head
518
    - ends: str, which ends get arrows ('last', 'first', 'both')
519
    - type: str, arrow type ('open', 'closed')
520
    """
521
```
522

523
## Usage Patterns
524

525
### Layering Multiple Geoms
526
```python
527
# Combine points and smoothed line
528
ggplot(data, aes(x='x', y='y')) + \
529
    geom_point(alpha=0.6) + \
530
    geom_smooth(method='lm', color='red')
531

532
# Bar chart with error bars
533
ggplot(summary_data, aes(x='category', y='mean')) + \
534
    geom_col(fill='lightblue') + \
535
    geom_errorbar(aes(ymin='mean - se', ymax='mean + se'), width=0.2)
536
```
537

538
### Aesthetic Mapping vs Fixed Values
539
```python
540
# Map aesthetics to data
541
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group', size='value'))
542

543
# Set fixed aesthetic values
544
ggplot(data, aes(x='x', y='y')) + geom_point(color='blue', size=3, alpha=0.7)
545

546
# Mix mapped and fixed aesthetics  
547
ggplot(data, aes(x='x', y='y')) + geom_point(aes(color='group'), size=3)
548
```
549

550
### Statistical Geoms with Computed Aesthetics
551
```python
552
# Histogram with fill mapped to count
553
ggplot(data, aes(x='value')) + \
554
    geom_histogram(aes(fill=after_stat('count')), bins=20)
555

556
# Density plot with color mapped to density level
557
ggplot(data, aes(x='x', y='y')) + \
558
    geom_density_2d(aes(color=after_stat('level')))
559
```