# 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.