1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
# Gribouille Geom Reference
Full parameter reference for every geom exported in `lib.typ`. All parameters verified against source code.
Columns: **Geom** | **Primary aes channels** | **Key params** | **Best used when**
---
## Point / scatter family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-point` | x, y, colour, fill, shape, size, alpha | `size` (default auto), `stroke` (outline), `alpha`, `shape` | Scatter plots; discrete x vs continuous y |
| `geom-jitter` | x, y, colour, fill, shape, size, alpha | `size`, `stroke: 0.5pt`, `fill`, `colour`, `alpha`, `shape`; position defaults to `"jitter"` | Overplotted categoricals; combine with `geom-boxplot` |
| `geom-count` | x, y, colour, fill, shape | `size: 3pt`, `stroke: none`, `fill`, `colour`, `alpha`, `shape` | Overplotted integer grids; size encodes count |
| `geom-dotplot` | x, fill | `bins: 30`, `binwidth`, `dotsize: 1.0`, `stackratio: 1.0`, `fill`, `colour`, `stroke`, `alpha` | Dot histogram; alternative to `geom-histogram` |
| `geom-rug` | x, y, colour | `sides: "bl"` (b=bottom, l=left, t=top, r=right), `length: 0.15cm`, `stroke: 0.4pt`, `colour`, `alpha` | Marginal data density; stack with another geom |
## Line / path family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-line` | x, y, colour, linetype, alpha | `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Time series; connected data sorted by x |
| `geom-path` | x, y, colour, linetype | `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Lines connected in data-row order (not sorted by x) |
| `geom-step` | x, y, colour, linetype | `direction: "hv"\|"vh"\|"mid"`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Step functions; ECDF; survival curves |
| `geom-area` | x, y, fill, alpha | `colour`, `fill`, `stroke: none`, `alpha` | Area under a line; stacked areas |
| `geom-ribbon` | x, ymin, ymax, fill | `colour`, `fill`, `stroke: none`, `alpha` | Confidence bands; prediction intervals; pair with `geom-line` |
| `geom-freqpoly` | x, colour, linetype | `bins: 30`, `binwidth`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Overlapping distributions as lines; alternative to `geom-histogram` |
## Bar / column family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-bar` | x, fill, colour, alpha | `width: 0.9`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "stack"` | Count bars; map `x` only, gribouille counts automatically |
| `geom-col` | x, y, fill, colour, alpha | `width: 0.9`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "identity"` | Pre-aggregated bar values; map both `x` and `y` |
| `geom-histogram` | x, fill, colour, alpha | `bins: 30`, `binwidth`, `width: 1.0`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "stack"` | Continuous variable distribution; requires `x` mapping |
## Distribution summary family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-boxplot` | x, y (or y alone), fill, colour | `width: 0.6`, `colour`, `fill`, `stroke: 0.6pt`, `alpha`, `outlier-size: 1.8pt`, `outlier-colour: auto`, `whisker-cap: 0.5` | Distribution summary by group |
| `geom-errorbar` | x, ymin, ymax, colour | `width: 0.4` (cap span; number=data units, length=panel units), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Vertical error bars |
| `geom-errorbarh` | y, xmin, xmax, colour | `height: 0.4` (cap span), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Horizontal error bars |
| `geom-linerange` | x, ymin, ymax, colour | `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Vertical range lines without caps |
| `geom-crossbar` | x, y, ymin, ymax, fill, colour | `width: 0.6`, `colour`, `fill`, `stroke: 0.6pt`, `middle-stroke: 1.2pt`, `alpha` | Box without whiskers or outliers |
| `geom-pointrange` | x, y, ymin, ymax, colour | `size: 2.5pt`, `stroke: 0.8pt`, `colour`, `fill`, `alpha`, `linetype: "solid"` | Point with range line |
| `geom-smooth` | x, y, colour, fill | `method: "lm"` (only option in v1), `se: true` (show ribbon), `alpha: auto` (ribbon alpha), `level: 0.95` (CI level), `stroke: 1pt`, `colour`, `fill`, `linetype` | Fitted trend + optional confidence ribbon |
| `geom-quantile` | x, y, colour, linetype | `quantiles: (0.25, 0.5, 0.75)`, `n-samples: 64`, `stroke: 0.6pt`, `colour`, `alpha`, `linetype`, `linewidth` | Quantile regression lines |
## Annotation family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-text` | x, y, label, colour, alpha | `size: 8pt`, `colour`, `alpha`, `anchor: "center"` (CeTZ anchor), `dx: 0`, `dy: 0` | Data labels at point positions |
| `geom-label` | x, y, label, colour, fill | `size: 8pt`, `colour`, `fill`, `stroke: 0.4pt`, `alpha`, `inset: 2pt`, `radius: 1pt`, `anchor: "center"`, `dx: 0`, `dy: 0` | Text with background box; callout labels |
| `geom-typst` | x, y, label (Typst content) | `size: 10pt`, `colour`, `alpha`, `anchor: "center"`, `dx: 0`, `dy: 0`, `label: none` | Arbitrary Typst content at data coordinates |
| `geom-hline` | yintercept | `yintercept` (scalar or array), `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Horizontal reference line; does NOT inherit plot mapping |
| `geom-vline` | xintercept | `xintercept` (scalar or array), `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Vertical reference line; does NOT inherit plot mapping |
| `geom-abline` | slope, intercept | `slope: 1`, `intercept: 0`, `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Diagonal reference (y = a + bx); does NOT inherit plot mapping |
| `geom-segment` | x, y, xend, yend, colour | `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Line segments between two data points |
| `geom-curve` | x, y, xend, yend, colour | `curvature: 0.5`, `angle: 90deg`, `n: 32`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Curved connectors |
| `geom-rect` | xmin, xmax, ymin, ymax, fill, colour | `colour`, `fill`, `stroke: none`, `alpha` | Shaded rectangular regions; highlight bands |
| `geom-polygon` | x, y, fill, colour, group | `colour`, `fill`, `stroke: none`, `alpha` | Arbitrary filled polygons; map outlines |
| `geom-blank` | — | `mapping: none`, `data: none` | Reserve plot area without drawing; useful for setting axis limits |
## Group / density family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-mark` | colour, fill | `method: "rect"\|"circle"\|"ellipse"\|"hull"`, `expand: 0pt` (padding), `n: 64` (ellipse smoothness), `colour`, `fill`, `stroke: 0.5pt`, `alpha` | Group outlines; convex hull or enclosing shape per group |
| `geom-ellipse` | x, y, colour, fill | `a: 1`, `b: 1` (semi-axes), `angle: 0`, `n: 64` (polygon segments), `colour`, `fill`, `stroke: none`, `alpha` | Manually sized ellipses at group centroids |
## 2D density / grid family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-tile` | x, y, fill, colour | `width: 1`, `height: 1`, `colour`, `fill`, `stroke: none`, `alpha` | Heatmaps; requires pre-computed fill values |
| `geom-bin-2d` | x, y, fill | `bins: 30`, `binwidth`, `colour`, `fill`, `stroke: none`, `alpha` | 2D histogram; bins both x and y |
| `geom-hex` | x, y, fill | `bins: 30`, `binwidth`, `colour`, `fill`, `stroke: none`, `alpha` | Hexagonal binning; alternative to scatter for large N |
| `geom-contour` | x, y, z, colour, linetype | (no user params beyond mapping) | Topographic contour lines on a regular grid |
| `geom-contour-filled` | x, y, z, fill | (no user params beyond mapping) | Filled contour regions |
## Specialised family
| Geom | Primary aes | Key params | Best used when |
|---|---|---|---|
| `geom-spoke` | x, y, angle, radius | Fixed params: `angle: 0deg`, `radius: 1`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Wind rose / directional vector field |
| `geom-qq` | sample | `size`, `stroke: none`, `fill`, `colour`, `alpha`, `shape`, `distribution: "normal"` | Q-Q scatter plot |
| `geom-qq-line` | sample | `stroke: 0.8pt`, `colour`, `alpha`, `linetype`, `distribution: "normal"` | Reference line for `geom-qq` |
| `geom-function` | — | `fun` (callable `x => y`), `n: 101`, `xlim: none` (overrides x-domain), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"`; does NOT inherit aes | Draw y = f(x) curve; no data needed |
---
## Stat helpers (used inside geoms via `stat:` param)
Note: most geoms accept `stat: "identity"` (default) or a stat object. The common pattern is to use the geom's default stat.
| Stat | Created by | Key params | Notes |
|---|---|---|---|
| `stat-bin(...)` | `geom-histogram` default | `bins: 30`, `binwidth: none` | Bin continuous x into counts |
| `stat-count` | `geom-bar` default | — | Count rows per x level |
| `stat-boxplot` | `geom-boxplot` default | — | Five-number summary per group |
| `stat-smooth` | `geom-smooth` default | `method: "lm"`, `se: true`, `level: 0.95` | Fit linear model |
| `stat-sum` | `geom-count` default | — | Count overlapping points |
---
## Position adjustments
Pass these as the `position:` argument in geoms. String shortcuts (`"stack"`, `"dodge"`, `"fill"`, `"jitter"`, `"identity"`) also work.
| Position | Key params | Notes |
|---|---|---|
| `position-stack()` | — | Stacked bars/areas |
| `position-fill()` | — | 100% stacked bars |
| `position-dodge(width: 0.9, padding: 0.1)` | `width`, `padding` | Side-by-side bars |
| `position-jitter(width: 0.4, height: 0.4, seed: 0)` | `width`, `height`, `seed` | Jitter points |
| `position-jitterdodge(...)` | `jitter.width`, `dodge.width` | Jitter within dodge |
| `position-nudge(x: 0, y: 0)` | `x`, `y` | Offset text/labels |
| `position-identity()` | — | No adjustment (default) |
---
## `geom-text` / `geom-label` anchor values
Both `geom-text` and `geom-label` use CeTZ anchors, not ggplot2-style hjust/vjust:
| Anchor | Meaning |
|---|---|
| `"center"` | Centred on point (default) |
| `"north"` | Above point |
| `"south"` | Below point |
| `"east"` | Right of point |
| `"west"` | Left of point |
| `"north-east"` | Upper-right |
| `"south-west"` | Lower-left |
Use `dx` and `dy` (numbers in canvas units where 1 = 1cm, or Typst lengths) for fine offsets.
|
