# Gribouille Scale Reference

Full parameter reference for every scale family exported in `lib.typ`. All parameters verified against source code.

Columns: **Scale** | **Aesthetic** | **Key params** | **When to use**

---

## Position scales — x axis

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-x-continuous(name, limits, breaks, labels, transform: "identity", expand, secondary)` | x | `name`, `limits`, `breaks`, `labels`, `transform` | Override x axis ticks, labels, or limits |
| `scale-x-log10(name, limits, breaks, labels)` | x | `name`, `breaks`, `labels` | Log₁₀ x axis; data must be positive |
| `scale-x-sqrt(name, limits, breaks, labels)` | x | `name`, `breaks`, `labels` | Square-root x axis |
| `scale-x-reverse(name, limits, breaks, labels)` | x | `name` | Reverse x direction |
| `scale-x-binned(name, limits, n-breaks: 10, labels)` | x | `n-breaks`, `labels`, `limits` | Bin continuous x into discrete intervals |
| `scale-x-discrete(name, limits, labels, expand)` | x | `limits` (reorder levels), `labels` | Force discrete x; reorder categories |
| `scale-x-date(name, limits, breaks, labels, date-format, expand)` | x | `date-format` (Typst datetime.display pattern) | Date x axis; values as numeric days since 2000-01-01 or ISO-8601 strings |
| `scale-x-datetime(...)` | x | same as `scale-x-date` | Datetime x axis |
| `scale-x-time(...)` | x | same as `scale-x-date` | Time-of-day x axis |

## Position scales — y axis

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-y-continuous(name, limits, breaks, labels, transform: "identity", expand, secondary)` | y | same as `scale-x-continuous` | Override y axis |
| `scale-y-log10(name, limits, breaks, labels)` | y | `name`, `breaks`, `labels` | Log₁₀ y axis |
| `scale-y-sqrt(...)` | y | — | Square-root y axis |
| `scale-y-reverse(...)` | y | — | Flip y direction |
| `scale-y-binned(name, limits, n-breaks: 10, labels)` | y | `n-breaks`, `labels` | Bin continuous y |
| `scale-y-discrete(name, limits, labels, expand)` | y | `limits`, `labels` | Force discrete y |
| `scale-y-date(...)` | y | `date-format`, `limits`, `breaks` | Date y axis |
| `scale-y-datetime(...)` | y | same | Datetime y axis |
| `scale-y-time(...)` | y | same | Time-of-day y axis |

---

## Colour scales (discrete)

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-colour-discrete(name, palette, limits, labels)` | colour | `palette` (array of colours or `auto`), `limits` | Custom discrete colour palette |
| `scale-colour-manual(values, name, limits, labels)` | colour | `values` (array of colours or dict `level -> colour`) | Explicit named mapping |
| `scale-colour-identity(name)` | colour | — | Colour column holds literal colour values |
| `scale-colour-okabe-ito(name, limits, labels)` | colour | — | Colourblind-safe 8-colour discrete palette |
| `scale-colour-hue(hue, chroma, luminance, name, limits, labels)` | colour | `hue` (range, e.g. `(15deg, 375deg)`), `chroma: 100`, `luminance: 65` | Hue-based palette; tune saturation |
| `scale-colour-grey(start, end, name, limits, labels)` | colour | `start: 0.2`, `end: 0.8` (grey levels 0–1) | Greyscale discrete |
| `scale-colour-brewer(palette, name, limits, labels)` | colour | `palette: "Set1"` (ColorBrewer palette name) | ColorBrewer palettes |

## Colour scales (continuous)

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-colour-continuous(name, palette, limits, breaks, labels)` | colour | `palette` (gradient or colour array) | Continuous colour from palette |
| `scale-colour-gradient(low, high, name, limits, breaks, labels)` | colour | `low: rgb("#132B43")`, `high: rgb("#56B1F7")` | Simple two-colour gradient |
| `scale-colour-gradient2(low, mid, high, midpoint, name, limits, breaks, labels)` | colour | `low`, `mid: white`, `high`, `midpoint: 0` | Diverging gradient centred at `midpoint` |
| `scale-colour-gradientn(colours, name, limits, breaks, labels)` | colour | `colours` (array of 3+ colours) | Multi-stop gradient |
| `scale-colour-distiller(palette, direction, name, limits, breaks, labels)` | colour | `palette: "Spectral"`, `direction: 1\|-1` | Brewer palettes interpolated to continuous |
| `scale-colour-steps(low, high, n-breaks, name, limits, labels)` | colour | `low`, `high`, `n-breaks: 5` | Stepped two-colour gradient |
| `scale-colour-steps2(low, mid, high, midpoint, n-breaks, name, limits, labels)` | colour | `low`, `mid: white`, `high`, `midpoint: 0`, `n-breaks: 5` | Stepped diverging gradient |
| `scale-colour-stepsn(colours, n-breaks, name, limits, labels)` | colour | `colours`, `n-breaks: 5` | Stepped multi-stop gradient |
| `scale-colour-fermenter(palette, n-breaks, direction, name, limits, labels)` | colour | `palette: "Spectral"`, `n-breaks: 5`, `direction: 1` | Brewer palettes cut into discrete bins |

## Colour scales (viridis family)

Supported `option` values: `"viridis"` (default), `"magma"`, `"plasma"`, `"inferno"`, `"cividis"`.

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-colour-viridis-c(option, name, limits, breaks, labels)` | colour | `option: "viridis"` | Perceptually uniform continuous colour |
| `scale-colour-viridis-d(option, name, limits, labels)` | colour | `option: "viridis"` | Perceptually uniform discrete colour |
| `scale-colour-viridis-b(option, n-breaks, name, limits, labels)` | colour | `option: "viridis"`, `n-breaks: 5` | Perceptually uniform binned colour |

## Fill scales

Every colour scale above has an exact fill counterpart. Replace `colour` with `fill`:

```
scale-fill-discrete()         scale-fill-continuous()
scale-fill-manual()           scale-fill-gradient()
scale-fill-identity()         scale-fill-gradient2()
scale-fill-okabe-ito()        scale-fill-gradientn()
scale-fill-hue()              scale-fill-brewer()
scale-fill-grey()             scale-fill-distiller()
scale-fill-viridis-c()        scale-fill-fermenter()
scale-fill-viridis-d()        scale-fill-steps()
scale-fill-viridis-b()        scale-fill-steps2()
                              scale-fill-stepsn()
```

---

## Alpha scales

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-alpha-continuous(name, range, limits, breaks, labels)` | alpha | `range: (0.1, 1)` | Map a continuous variable to transparency |
| `scale-alpha-binned(n-breaks, range, name, limits, labels)` | alpha | `n-breaks: 4`, `range: (0.1, 1)` | Binned (stepped) alpha |
| `scale-alpha-manual(values, name, limits, labels)` | alpha | `values` (array of 0–1 values) | Explicit alpha per level |
| `scale-alpha-identity(name)` | alpha | — | Alpha column holds literal 0–1 values |

---

## Size scales

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-size-continuous(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Map continuous var to point size |
| `scale-radius(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Alias of `scale-size-continuous`; map to radius |
| `scale-size-area(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Map to area (perceptually correct for magnitude) |
| `scale-size-binned(n-breaks, range, name, limits, labels)` | size | `n-breaks: 4`, `range: (1pt, 6pt)` | Binned size scale |
| `scale-size-binned-area(n-breaks, range, name, limits, labels)` | size | `n-breaks: 4`, `range: (1pt, 6pt)` | Binned area scale |
| `scale-size-identity(name)` | size | — | Size column holds literal length values |
| `scale-size-manual(values, name, limits, labels)` | size | `values` (array of lengths) | Explicit size per level |

---

## Linewidth scales

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-linewidth-continuous(name, range, limits, breaks, labels)` | linewidth | `range: (0.4pt, 1.4pt)` | Map continuous var to line width |
| `scale-linewidth-binned(n-breaks, range, name, limits, labels)` | linewidth | `n-breaks: 4`, `range: (0.4pt, 1.4pt)` | Binned linewidth |
| `scale-linewidth-manual(values, name, limits, labels)` | linewidth | `values` (array of lengths) | Explicit linewidth per level |
| `scale-linewidth-identity(name)` | linewidth | — | Linewidth column holds literal length values |

---

## Shape / linetype scales

| Scale | Aesthetic | Key params | When to use |
|---|---|---|---|
| `scale-shape(name, palette, limits, labels)` | shape | `palette` (array of shape keywords or `auto`) | Discrete point shapes |
| `scale-shape-manual(values, name, limits, labels)` | shape | `values` (array of shape keywords) | Explicit shape per level |
| `scale-shape-identity(name)` | shape | — | Shape column holds literal keywords |
| `scale-shape-binned(n-breaks, palette, name, limits, labels)` | shape | `n-breaks: 4`, `palette` | Binned shape scale |
| `scale-linetype(name, palette, limits, labels)` | linetype | `palette` (array of dash keywords or `auto`) | Discrete line types |
| `scale-linetype-manual(values, name, limits, labels)` | linetype | `values` (array of dash keywords) | Explicit linetype per level |
| `scale-linetype-identity(name)` | linetype | — | Linetype column holds literal keywords |
| `scale-linetype-binned(n-breaks, palette, name, limits, labels)` | linetype | `n-breaks: 4`, `palette` | Binned linetype scale (continuous var) |
| `scale-linetype-continuous(name, palette, limits, labels)` | linetype | alias of `scale-linetype-binned(n-breaks: 4)` | Alias |
| `scale-linetype-discrete(name, palette, limits, labels)` | linetype | alias of `scale-linetype()` | Alias |

Shape keywords: `"circle"`, `"square"`, `"triangle"`, `"diamond"`, `"cross"`, `"x"`, `"star"`, `"triangle-down"`

Linetype keywords: `"solid"`, `"dashed"`, `"dotted"`, `"dash-dotted"`, `"densely-dashed"`, `"loosely-dashed"`

---

## Format helpers (use in `labels:` parameter)

| Function | Output example | Notes |
|---|---|---|
| `format-comma()` | 1,234,567 | Thousands separator; best for y-axis with large integers |
| `format-percent()` | 12.3% | Multiply by 100 and append %; input should be 0–1 |
| `format-scientific()` | 1.23×10⁴ | Scientific notation |
| `format-currency()` | $1,234 | Dollar prefix + comma separator |
| `format-number(digits: N)` | 3.14 | Fixed decimal places |
| `format-lower()` | lowercase | Convert labels to lowercase |
| `format-upper()` | UPPERCASE | Convert labels to uppercase |
| `format-title()` | Title Case | Capitalise each word |
| `format-wrap(width: N)` | wrapped text | Word-wrap long labels at N characters |

---

## Common patterns

**Large y-axis numbers:**
```typst
scales: (scale-y-continuous(labels: format-comma()),)
```

**Log-log axes:**
```typst
scales: (scale-x-log10(), scale-y-log10(),)
```

**Custom discrete colour palette:**
```typst
scales: (
  scale-colour-manual(
    values: ("Setosa": rgb("#E69F00"), "Versicolor": rgb("#56B4E9"), "Virginica": rgb("#009E73")),
    limits: ("Setosa", "Versicolor", "Virginica"),
  ),
)
```

**Colourblind-safe palette:**
```typst
scales: (scale-colour-okabe-ito(),)
```

**Viridis continuous fill for heatmap:**
```typst
scales: (scale-fill-viridis-c(option: "viridis"),)
```

**Diverging colour centred at zero:**
```typst
scales: (scale-colour-gradient2(low: blue, mid: white, high: red, midpoint: 0),)
```

**Reorder discrete x axis:**
```typst
scales: (scale-x-discrete(limits: ("small", "medium", "large")),)
```

**Date axis:**
```typst
scales: (scale-x-date(date-format: "[month repr:short] [year]"),)
```

**Size range for bubble chart:**
```typst
scales: (scale-size-area(range: (1pt, 12pt)),)
```