Gribouille

https://m.canouil.dev/gribouille
Admin
Gribouille allows users to create elegant graphics for Typst, composing charts by layering data,...
Tokens:276,023
Snippets:2,444
Trust Score:5.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Define Guides for Aesthetics

Source: https://m.canouil.dev/gribouille/reference/guides/guides.html

Use the guides function to specify guide specifications for aesthetics like color, fill, and size. Set to 'none' to hide a guide or 'auto' for the default.

```typst
guides(
  ..args,
)
```

--------------------------------

### Swatch Strip Plot with Viridis Options

Source: https://m.canouil.dev/gribouille/reference/scales/scale-fill-viridis-d.html

This example shows how to create a swatch strip using `geom-rect` and `scale-fill-viridis-d` to visualize different viridis color options. The `guides(fill: none)` and `theme-void()` are used to simplify the plot appearance.

```typst
#let opts = ("viridis", "magma", "plasma", "inferno", "cividis")
#let d = opts.enumerate().map(((i, k)) => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, k: k,
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", ymax: "ymax", fill: "k"),
  layers: (geom-rect(),),
  scales: (scale-fill-viridis-d(option: "magma"),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 6cm,
  height: 1cm,
)
```

--------------------------------

### Basic Guide Axis Configuration

Source: https://m.canouil.dev/gribouille/reference/guides/guide-axis.html

Configure the basic parameters for axis guides, such as label rotation and staggering. This spec is applied when passed to the `guides` function.

```typst
guide-axis(
  angle: 0,
  n-dodge: 1,
)
```

--------------------------------

### Basic guide-axis-stack structure

Source: https://m.canouil.dev/gribouille/reference/guides/guide-axis-stack.html

This shows the basic structure for creating a stacked axis guide. You provide an array of guide specifications and can adjust the spacing between them.

```typst
guide-axis-stack(
  guides: (),
  spacing: 4pt,
)
```

--------------------------------

### Example: Twelve-bin dotplot

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-dotplot.html

This example demonstrates how to create a twelve-bin dotplot using geom-dotplot with synthetic data.

```APIDOC
## Examples

Twelve-bin dotplot of a synthetic distribution.

```typst
#let d = range(0, 60).map(i => (
  x: calc.sin(i * 0.27) * 3 + i * 0.08,
))
#plot(
  data: d,
  mapping: aes(x: "x"),
  layers: (geom-dotplot(bins: 12),),
  width: 12cm,
  height: 9cm,
)
```
```

--------------------------------

### Example: Per-row offsets with connectors

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-text.html

This example illustrates using `geom-text` with `nudge-x` and `nudge-y` for per-row offsets, and `segment: true` to draw connectors from the labels back to their anchor points, demonstrating routed connectors to avoid overlaps.

```APIDOC
## Example: Per-row offsets with connectors

### Description
Per-row offsets via `nudge-x`/`nudge-y` plus connectors back to each anchor.

### Code
```typst
#let d = (
  (x: 1, y: 2, name: "a", nx: 0.5, ny: 0.4),
  (x: 2, y: 4, name: "b", nx: -0.4, ny: 0.5),
  (x: 3, y: 3, name: "c", nx: 0.4, ny: -0.4),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name", nudge-x: "nx", nudge-y: "ny"),
  layers: (
    geom-point(size: 2pt),
    geom-text(segment: true),
  ),
  scales: (scale-x-continuous(expand: 40%),scale-y-continuous(expand: 40%),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Custom Two-Stop Ramp Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-fill-gradient.html

An example demonstrating how to use `scale-fill-gradient` with custom colors for a continuous fill swatch using `geom-rect`.

```APIDOC
## Example: Custom Two-Stop Ramp

Custom two-stop ramp shown as a continuous swatch via `geom-rect`.

```typst
#let d = range(0, 16).map(i => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, z: i,
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", ymax: "ymax", fill: "z"),
  layers: (geom-rect(),),
  scales: (scale-fill-gradient(
    low: rgb("#fee5d9"),
    high: rgb("#a50f15"),
  ),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 10cm,
  height: 1cm,
)
```
```

--------------------------------

### Example: Default Bin Alignment

Source: https://m.canouil.dev/gribouille/reference/helpers/cut-width.html

Demonstrates how `cut-width` creates bins that align to multiples of the specified width when `center` is not provided.

```APIDOC
## Example: Default Bin Alignment

### Description
Bin widths of 2 align to multiples of two.

### Code
```typst
let bins = cut-width((1, 2, 3, 4, 5, 6, 7, 8), width: 2)
```
```

--------------------------------

### Explicit Bin Labels Example

Source: https://m.canouil.dev/gribouille/reference/helpers/cut-interval.html

Shows how to provide custom labels for each bin using the `labels` parameter.

```APIDOC
## Example: Explicit Labels

```typst
#let bins = cut-interval(
  (1, 2, 3, 4, 5, 6, 7, 8),
  n: 4,
  labels: ("low", "mid-low", "mid-high", "high"),
)
// The output will use the provided labels: ("low", "low", "mid-low", "mid-low", ...)
```

### Returns

An array of bin labels with the same length as the input `values` array, using the explicitly provided labels.
```

--------------------------------

### Continuous Color Scale with Colorbar in Typst

Source: https://m.canouil.dev/gribouille/examples

Demonstrates how a continuous 'fill' aesthetic automatically generates a colorbar guide. This example plots highway mpg against engine displacement, colored by city mpg. Requires Gribouille import and page setup.

```typst
#import "@preview/gribouille:0.4.1": *

#set page(width: auto, height: auto, margin: 0cm)

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy", fill: "cty"),
  layers: (geom-point(size: 4pt, alpha: 0.85),),
  labels: labels(
    title: "Highway Versus Engine Displacement, Coloured by City mpg",
    x: "Displacement (L)",
    y: "Highway mpg",
    fill: "City mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

```

--------------------------------

### Default Bin Labels Example

Source: https://m.canouil.dev/gribouille/reference/helpers/cut-interval.html

Demonstrates how to use cut-interval with default labels, showing the boundary intervals.

```APIDOC
## Example: Default Labels

```typst
#let bins = cut-interval((1, 2, 3, 4, 5, 6, 7, 8), n: 4)
// Expected output might look like: ("(1,2.75]", "(1,2.75]", "(2.75,4.5]", "(2.75,4.5]", ...)
```

### Returns

An array of bin labels with the same length as the input `values` array.
```

--------------------------------

### Default Grey Ramp Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-fill-grey.html

Demonstrates the default grey ramp using geom-rect and scale-fill-grey. This example visualizes data levels with varying grey fills.

```typst
#let levels = ("a", "b", "c", "d", "e", "f")
#let d = levels.enumerate().map(((i, k)) => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, k: k,
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", fill: "k"),
  layers: (geom-rect(),),
  scales: (scale-fill-grey(),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 8cm,
  height: 1cm,
)
```

--------------------------------

### Example 1: Hand-picked colour array

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-manual.html

Applies a hand-picked colour array to three categorical levels.

```APIDOC
## Example: Hand-picked colour array

```typst
#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "sp"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-manual(values: (
    rgb("#1b9e77"), rgb("#d95f02"), rgb("#7570b3"),
  )),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Basic Crossbar Example

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-crossbar.html

This example demonstrates creating a plot with a geom-crossbar layer, mapping x, y, ymin, and ymax from the data.

```APIDOC
## Basic Crossbar

### Description
Box from `lo` to `hi` with the median bar at `y`.

### Code
```typst
#let d = range(1, 5).map(i => (
  x: i,
  y: i,
  lo: i - 0.6,
  hi: i + 0.6,
))
#plot(
  data: d,
  mapping: aes(x: as-factor("x"), y: "y", ymin: "lo", ymax: "hi"),
  layers: (geom-crossbar(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example: Centered Bins

Source: https://m.canouil.dev/gribouille/reference/helpers/cut-width.html

Illustrates using the `center` parameter to force bins to be centered around a specific value, such as zero.

```APIDOC
## Example: Centered Bins

### Description
Force a bin to be centred at zero by passing `center`.

### Code
```typst
let bins = cut-width((-3, -1, 0, 1, 2, 4), width: 2, center: 0)
```
```

--------------------------------

### Example Usage with Cividis Option

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-viridis-d.html

Illustrates using scale-colour-viridis-d with the 'cividis' option, a color-blind safe alternative, for plotting.

```APIDOC
## Example: Cividis Option
```typst
#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "c"),
  (x: 4, y: 5, sp: "d"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "sp"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-viridis-d(option: "cividis"),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Limits Clipping Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-continuous.html

Shows how to use the `limits` parameter to clip the trained domain and render extremes at the palette endpoints.

```APIDOC
## Pin limits to clip the trained domain

### Description
Pin `limits` to clip the trained domain and render extremes at the palette endpoints.

### Code
```typst
#let d = range(0, 12).map(i => (x: i, y: i, z: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "z"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-continuous(limits: (1, 4)),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Stat Bin Usage with geom-col

Source: https://m.canouil.dev/gribouille/reference/stats/stat-bin.html

Example demonstrating how to use stat-bin with geom-col to customize the binning partition for column-based visualizations.

```APIDOC
## geom-col(stat: stat-bin())

### Description
Applies the `stat-bin` statistic to a `geom-col` layer, allowing for customized binning of data before plotting columns.

### Parameters
(Inherits parameters from stat-bin and geom-col)

### Example
```typst
#let d = range(0, 40).map(i => (x: i * 0.25))
#plot(
  data: d,
  mapping: aes(x: "x"),
  layers: (geom-col(stat: stat-bin(bins: 8)),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example: Trajectory with colored fade

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-path.html

Illustrates creating a trajectory of a moving point, parameterized by `t`, with a colored fade effect over time.

```APIDOC
## Example: Trajectory with colored fade

Trajectory of a moving point parameterised by `t`, drawn in time order with a coloured fade.

```typst
#let d = range(0, 24).map(t => (
  x: calc.cos(t * 0.4), y: calc.sin(t * 0.4) * (t / 24 + 0.5), t: t,
))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "t"),
  layers: (geom-path(stroke: 1.2pt),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Five-bin Discretised Fill Ramp Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-fill-steps.html

Demonstrates creating a five-bin discretised fill ramp using `scale-fill-steps` and displaying it as a swatch with `geom-rect`. The data is partitioned into bins, and the fill aesthetic is mapped to these bins.

```typst
#let d = range(0, 16).map(i => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, z: i,
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", ymax: "ymax", fill: "z"),
  layers: (geom-rect(),),
  scales: (scale-fill-steps(n-breaks: 5),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 10cm,
  height: 1cm,
)
```

--------------------------------

### Stacking rotated labels and log ticks on an axis

Source: https://m.canouil.dev/gribouille/reference/guides/guide-axis-stack.html

This example demonstrates how to stack a rotated-label guide above log minor ticks on a log10 x-axis. This allows the axis to display both readable labels and dense tick marks simultaneously.

```typst
#let d = (
  (x: 1, y: 1),
  (x: 10, y: 100),
  (x: 100, y: 10000),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 3pt),),
  scales: (
    scale-x-continuous(transform: "log10"),
    scale-y-continuous(transform: "log10"),
  ),
  guides: guides(
    x: guide-axis-stack(guides: (
      guide-axis(angle: 30),
      guide-axis-logticks(),
    )),
  ),
  width: 10cm,
  height: 6cm,
)
```

--------------------------------

### stat-qq-line() constructor

Source: https://m.canouil.dev/gribouille/reference/stats/stat-qq-line.html

Use the constructor form `stat: stat-qq-line()` for default settings. This is equivalent to specifying `stat: "qq-line"`.

```typst
stat-qq-line()
```

--------------------------------

### Custom Color and Fill Palettes in Typst

Source: https://m.canouil.dev/gribouille/examples

Uses scale-colour-manual and scale-fill-manual to apply a user-defined palette of colors to plot elements. This example plots penguin species by flipper length and body mass. Requires Gribouille import and page setup.

```typst
#import "@preview/gribouille:0.4.1": *

#set page(width: auto, height: auto, margin: 0cm)

#let palette = (rgb("#ff8c00"), rgb("#800080"), rgb("#008B8B"))

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.7),
    geom-smooth(method: "lm", alpha: 0.15),
  ),
  scales: (
    scale-colour-manual(values: palette),
    scale-fill-manual(values: palette),
    scale-y-continuous(labels: format-comma()),
  ),
  labels: labels(
    title: "Penguin Species Drawn with a Custom Palette",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    colour: "Species",
    fill: "Species",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

```

--------------------------------

### Example: Binning Quality Data into Linetypes

Source: https://m.canouil.dev/gribouille/reference/scales/scale-linetype-binned.html

Demonstrates how to use the binned linetype scale to map a continuous 'q' column into three distinct linetype buckets for different groups. Ensure the 'q' column is numeric for binning.

```typst
#let d = (
  (x: 1, y: 1, q: 1, g: "a"), (x: 2, y: 2, q: 1, g: "a"),
  (x: 3, y: 3, q: 1, g: "a"), (x: 4, y: 4, q: 1, g: "a"),
  (x: 1, y: 2, q: 4, g: "b"), (x: 2, y: 3, q: 4, g: "b"),
  (x: 3, y: 4, q: 4, g: "b"), (x: 4, y: 5, q: 4, g: "b"),
  (x: 1, y: 3, q: 7, g: "c"), (x: 2, y: 4, q: 7, g: "c"),
  (x: 3, y: 5, q: 7, g: "c"), (x: 4, y: 6, q: 7, g: "c"),
  (x: 1, y: 4, q: 10, g: "d"), (x: 2, y: 5, q: 10, g: "d"),
  (x: 3, y: 6, q: 10, g: "d"), (x: 4, y: 7, q: 10, g: "d"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", linetype: "q", group: "g"),
  layers: (geom-line(stroke: 1pt),),
  scales: (scale-linetype-binned(n-breaks: 3),),
  width: 10cm,
  height: 6cm,
)
```

--------------------------------

### guide-custom Function Signature

Source: https://m.canouil.dev/gribouille/reference/guides/guide-custom.html

This is the signature for the `guide-custom` function, detailing its parameters and their default values. Use this to understand how to configure custom guide content.

```typst
guide-custom(
  content,
  width: auto,
  height: auto,
  title: none,
  position: "right",
  direction: auto,
  order: none,
  byrow: false,
)
```

--------------------------------

### Example Usage of format-percent in Plotting

Source: https://m.canouil.dev/gribouille/reference/helpers/format-percent.html

This example demonstrates how to use the format-percent function as a label formatter for the y-axis in a plot.

```APIDOC
## Examples

Map proportions in `[0, 1]` to percent labels on the y-axis.

```typst
#plot(
  data: ((g: "a", y: 0.1), (g: "b", y: 0.45), (g: "c", y: 0.9)),
  mapping: aes(x: "g", y: "y"),
  layers: (geom-col(),),
  scales: (scale-y-continuous(labels: format-percent()),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example Usage of after-stat

Source: https://m.canouil.dev/gribouille/reference/core/after-stat.html

This example demonstrates how to bind the `y` aesthetic to the `_count` column published by `stat-count` in a `geom-bar` layer.

```APIDOC
## Example: Binding to a stat column

### Description
Bind `y` to the `_count` column `geom-bar`’s `stat-count` publishes.

### Code
```typst
#let d = (
  (grp: "a"), (grp: "b"), (grp: "a"),
  (grp: "c"), (grp: "a"), (grp: "b"),
)
#plot(
  data: d,
  mapping: aes(x: "grp", y: after-stat("_count")),
  layers: (geom-bar(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### scale-colour-grey with custom start and end

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-grey.html

Narrowing `start` and `end` constrains the ramp to a darker range for tighter contrast.

```APIDOC
## scale-colour-grey(start: number, end: number)

### Description
Discrete grey colour scale with custom start and end luminance values.

### Parameters
`start` (number) - Luminance for the first level, in `[0, 1]`. Defaults to 0.
`end` (number) - Luminance for the last level, in `[0, 1]`. Defaults to 1.
`name` (string) - Legend title. Overrides any name set via `labels` when both are present.
`limits` (array) - Array of level names controlling order and inclusion, or `none`.
`oob` (string) - Out-of-range policy: `"drop"` (default) removes rows whose value falls outside `limits`; `"squish"` clamps continuous values to the nearest endpoint.
`labels` (array) - Array of legend labels aligned with `limits`, or `auto`.

### Returns
Scale object consumed by `plot`.

### Example
```typst
#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "sp"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-grey(start: 0.1, end: 0.5),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Binned Scale Examples

Source: https://m.canouil.dev/gribouille/examples

Demonstrates stepped fill gradients, ColorBrewer palettes, and area sizing scales. Use scale-fill-steps for discrete bins, scale-fill-fermenter for palettes with a specified number of breaks, and scale-size-area for mapping data to point sizes.

```typst
#import "@preview/gribouille:0.4.1": *

#set page(width: auto, height: auto, margin: 0cm)

#let continuous-d = range(0, 24).map(i => (x: i, y: i, z: i * 1.0))
#let area-d = range(1, 11).map(i => (x: i, y: i, w: i * i))

#let common-theme = theme-minimal()

#grid(
  columns: 1,
  row-gutter: 0.5cm,
  plot(
    data: continuous-d,
    mapping: aes(x: "x", y: "y", fill: "z"),
    layers: (geom-point(size: 4pt),),
    scales: (scale-fill-steps(n-breaks: 5),),
    labels: labels(
      title: "Scale-Fill-Steps (5 Bins)",
      x: "X",
      y: "Y",
      fill: "z",
    ),
    theme: common-theme,
    width: 12cm,
    height: 9cm,
  ),
  plot(
    data: continuous-d,
    mapping: aes(x: "x", y: "y", fill: "z"),
    layers: (geom-point(size: 4pt),),
    scales: (scale-fill-fermenter(palette: "Spectral", n-breaks: 7),),
    labels: labels(
      title: "Scale-Fill-Fermenter (Spectral, 7)",
      x: "X",
      y: "Y",
      fill: "z",
    ),
    theme: common-theme,
    width: 12cm,
    height: 9cm,
  ),
  plot(
    data: area-d,
    mapping: aes(x: "x", y: "y", size: "w"),
    layers: (geom-point(fill: rgb("#1f77b4")),),
    scales: (scale-size-area(range: (1pt, 12pt)),),
    labels: labels(
      title: "Scale-Size-Area (sub-linear)",
      x: "X",
      y: "Y",
      size: "w",
    ),
    theme: common-theme,
    width: 12cm,
    height: 9cm,
  ),
)

```

--------------------------------

### Example: Constant Typst Label

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-typst.html

This example shows how to use `geom-typst` with a constant Typst content block as the label for all rows.

```APIDOC
## Example: Constant Typst Label

### Description
Use a constant content block as the label at every row.

### Code
```typst
#let d = (
  (x: 1, y: 1),
  (x: 2, y: 2),
  (x: 3, y: 3),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-typst(label: [#math.alpha]),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Pin a Custom Theme as Project Default

Source: https://m.canouil.dev/gribouille/reference/themes/theme-set.html

Define and set a custom theme as the project default. This example customizes the panel background and grid colors.

```typst
#theme-set(
  theme(
    panel-background: element-rect(fill: rgb("#fff7e6")),
    panel-grid: element-line(colour: rgb("#d9cfbf")),
  )
)
```

--------------------------------

### Get Alt Text from Plot Spec

Source: https://m.canouil.dev/gribouille/reference/helpers/get-alt-text.html

Retrieves the alt text from a plot specification. This is useful for accessibility tooling to get a description of the plot.

```typst
#let p = (data: (), alt: "Scatter of weight vs mpg")
#let alt = get-alt-text(p)
```

--------------------------------

### Per-Row Offsets with Connectors

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-text.html

This example shows how to use per-row offsets for labels with `nudge-x` and `nudge-y`, and draws connectors back to their anchor points using `segment: true`. The `label` aesthetic must be mapped.

```typst
#let d = (
  (x: 1, y: 2, name: "a", nx: 0.5, ny: 0.4),
  (x: 2, y: 4, name: "b", nx: -0.4, ny: 0.5),
  (x: 3, y: 3, name: "c", nx: 0.4, ny: -0.4),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name", nudge-x: "nx", nudge-y: "ny"),
  layers: (
    geom-point(size: 2pt),
    geom-text(segment: true),
  ),
  scales: (scale-x-continuous(expand: 40%),scale-y-continuous(expand: 40%),),
  width: 10cm,
  height: 6cm,
)
```

--------------------------------

### Example: Per-row opacity

Source: https://m.canouil.dev/gribouille/reference/scales/scale-alpha-identity.html

An example demonstrating how to use `scale-alpha-identity` to set per-row opacity for points in a plot, where the opacity is directly mapped from a data column.

```APIDOC
## Example: Per-row opacity

Per-row opacity carried straight through to the point fills.

```typst
#let d = (
  (x: 1, y: 2, w: 0.2),
  (x: 2, y: 3, w: 0.5),
  (x: 3, y: 4, w: 0.8),
  (x: 4, y: 5, w: 1.0),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", alpha: "w"),
  layers: (geom-point(size: 6pt, fill: rgb("#1f77b4")),
  ),
  scales: (scale-alpha-identity(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Default Usage Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-continuous.html

Demonstrates the default usage of `scale-colour-continuous` with the viridis ramp, interpolating across the library's continuous palette.

```APIDOC
## Default viridis ramp

### Description
Default viridis ramp interpolating across the library’s continuous palette.

### Code
```typst
#let d = range(0, 12).map(i => (x: i, y: i, z: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "z"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-continuous(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Colour-Blind Friendly Palette and Reordered Limits

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-discrete.html

This example demonstrates using a colour-blind-friendly palette and reordering the legend items using the `limits` parameter for a discrete colour scale.

```typst
#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  scales: (scale-colour-discrete(
    palette: (rgb("#0072B2"), rgb("#D55E00"), rgb("#009E73")),
    limits: ("Adelie", "Chinstrap", "Gentoo"),
  ),),
  labels: labels(x: "Flipper Length (mm)", y: "Body Mass (g)", colour: "Species"),
  width: 11cm,
  height: 6cm,
)
```

--------------------------------

### Log-10 y axis example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-y-log10.html

This example demonstrates how a log-10 y-axis can transform an exponential curve into a near-linear shape, making it easier to visualize wide ranges of data.

```APIDOC
## Example: Log-10 y axis turns an exponential into a near-linear shape.

```typst
#let d = range(1, 11).map(i => (x: i, y: calc.pow(2, i)))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  scales: (scale-y-log10(name: "y"),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Initialize coord-fixed with default ratio

Source: https://m.canouil.dev/gribouille/reference/coord/coord-fixed.html

Use this to create a fixed coordinate system with a default aspect ratio of 1:1.

```typst
coord-fixed(
  ratio: 1,
)
```

--------------------------------

### Example: Labels with Typst Markup from Data

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-typst.html

This example demonstrates how to use `geom-typst` where each row's `label` column contains Typst markup that is evaluated directly.

```APIDOC
## Example: Labels with Typst Markup from Data

### Description
Each row’s `label` column carries Typst markup that is evaluated in place; no `typst()` wrapper is needed at the call site.

### Code
```typst
#let d = (
  (x: 1, y: 1, t: "$alpha$"),
  (x: 2, y: 2, t: "*bold*"),
  (x: 3, y: 3, t: "#emph[italic]"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "t"),
  layers: (geom-typst(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example: Mapping numeric data to linetypes

Source: https://m.canouil.dev/gribouille/reference/scales/scale-linetype-continuous.html

This example demonstrates how to use `scale-linetype-continuous` to map a numeric column ('q') to different line types in a plot, with grouping by 'g'.

```APIDOC
## Examples

Map a numeric column onto a dash interpolation across four default bins.

```typst
#let d = (
  (x: 1, y: 1, q: 1, g: "a"), (x: 2, y: 2, q: 1, g: "a"),
  (x: 3, y: 3, q: 1, g: "a"), (x: 4, y: 4, q: 1, g: "a"),
  (x: 1, y: 2, q: 4, g: "b"), (x: 2, y: 3, q: 4, g: "b"),
  (x: 3, y: 4, q: 4, g: "b"), (x: 4, y: 5, q: 4, g: "b"),
  (x: 1, y: 3, q: 7, g: "c"), (x: 2, y: 4, q: 7, g: "c"),
  (x: 3, y: 5, q: 7, g: "c"), (x: 4, y: 6, q: 7, g: "c"),
  (x: 1, y: 4, q: 10, g: "d"), (x: 2, y: 5, q: 10, g: "d"),
  (x: 3, y: 6, q: 10, g: "d"), (x: 4, y: 7, q: 10, g: "d"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", linetype: "q", group: "g"),
  layers: (geom-line(stroke: 1pt),),
  scales: (scale-linetype-continuous(),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Using Brewer Palette for Set1 Swatches

Source: https://m.canouil.dev/gribouille/reference/scales/brewer-palette.html

Demonstrates how to retrieve the 'Set1' ColorBrewer palette and use it to create a manual fill scale for rectangular geoms, rendered as swatches.

```typst
#let pal = brewer-palette("Set1")
#let d = pal.enumerate().map(((i, _)) => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, k: str(i),
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", ymax: "ymax", fill: "k"),
  layers: (geom-rect(),),
  scales: (scale-fill-manual(values: pal),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 8cm,
  height: 1cm,
)
```

--------------------------------

### Typst Filled Contour Plot Example

Source: https://m.canouil.dev/gribouille/examples

Creates filled contour bands on a 2D grid using a radial wave function. This example uses `geom-contour-filled` for shaded regions.

```typst
#import "@preview/gribouille:0.4.1": *

#set page(width: auto, height: auto, margin: 0cm)

#let n = 50
#let d = ()
#for i in range(n) {
  for j in range(n) {
    let x = -3 + 6 * i / (n - 1)
    let y = -3 + 6 * j / (n - 1)
    let r = calc.sqrt(x * x + y * y)
    d.push((x: x, y: y, z: calc.sin(r * 2.5) * calc.exp(-r / 3)))
  }
}

#plot(
  data: d,
  mapping: aes(x: "x", y: "y", z: "z"),
  layers: (geom-contour-filled(bins: 10),),
  scales: (scale-fill-viridis-c(option: "magma"),),
  labels: labels(
    title: "Radial Wave: 10 Filled Bands",
    subtitle: "z = sin(2.5 r) · exp(-r / 3) over a 50-by-50 grid",
    fill: "level",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)
```

--------------------------------

### Three-Stop Gradient Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-gradientn.html

Creates a three-stop colour gradient interpolating between green, yellow, and red across the domain. This example demonstrates basic usage with custom RGB colours.

```typst
#let d = range(0, 12).map(i => (x: i, y: i, z: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "z"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-gradientn(colours: (
    rgb("#1a9850"), rgb("#ffffbf"), rgb("#d73027"),
  )),),
  width: 10cm,
  height: 6cm,
)
```

--------------------------------

### Example: Connecting rows in input order

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-path.html

Demonstrates how to use `geom-path` to connect data points in their input order, without sorting by x-axis.

```APIDOC
## Example: Connecting rows in input order

Connect rows in input order (deliberately not sorted by x).

```typst
#let d = (
  (x: 1, y: 1), (x: 3, y: 4), (x: 2, y: 2), (x: 4, y: 5),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-path(stroke: 1pt),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Import Gribouille from Release Assets

Source: https://m.canouil.dev/gribouille/get-started

Install Gribouille by downloading release assets and placing them in Typst's local package directory. Use this import path for local installations.

```typst
#import "@local/gribouille:0.4.1": *
```

--------------------------------

### Diverging Ramp Example

Source: https://m.canouil.dev/gribouille/reference/scales/scale-fill-gradient2.html

Demonstrates a diverging color ramp pivoting at zero, visualized as a swatch using geom-rect. This example maps fill color to a range of values and applies the scale-fill-gradient2 with a midpoint of 0.

```typst
#let d = range(-7, 8).map(i => (
  xmin: i, xmax: i + 1, ymin: 0, ymax: 1, z: i,
))
#plot(
  data: d,
  mapping: aes(xmin: "xmin", xmax: "xmax", ymin: "ymin", ymax: "ymax", fill: "z"),
  layers: (geom-rect(),),
  scales: (scale-fill-gradient2(midpoint: 0),),
  guides: guides(fill: none),
  theme: theme-void(),
  width: 10cm,
  height: 1cm,
)
```

--------------------------------

### Example: Labels nudged above their points

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-text.html

This example demonstrates how to use `geom-text` with `nudge-y` to position labels slightly above their corresponding data points. It also shows the basic structure of creating a plot with data, mappings, and layers.

```APIDOC
## Example: Labels nudged above their points

### Description
Labels nudged above their points via `nudge-y`.

### Code
```typst
#let d = (
  (x: 1, y: 2, name: "a"),
  (x: 2, y: 4, name: "b"),
  (x: 3, y: 3, name: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name"),
  layers: (
    geom-point(size: 2pt),
    geom-text(mapping: aes(nudge-y: 0.2cm)),
  ),
  scales: (scale-y-continuous(expand: 15%),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example Usage with Plasma Option

Source: https://m.canouil.dev/gribouille/reference/scales/scale-colour-viridis-d.html

Demonstrates how to use the scale-colour-viridis-d function with the 'plasma' option to create a plot with points colored based on a categorical variable.

```APIDOC
## Example: Plasma Option
```typst
#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "c"),
  (x: 4, y: 5, sp: "d"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "sp"),
  layers: (geom-point(size: 3pt),),
  scales: (scale-colour-viridis-d(option: "plasma"),),
  width: 10cm,
  height: 6cm,
)
```
```

--------------------------------

### Example: Ten bands on a radial-wave field, shaded by level.

Source: https://m.canouil.dev/gribouille/reference/geoms/geom-contour-filled.html

This example demonstrates how to use geom-contour-filled to visualize a radial-wave field with ten bands, shaded according to their lower bound level using a viridis color scale.

```APIDOC
## Example

Ten bands on a radial-wave field, shaded by level.
```typst
#let n = 50
#let d = ()
#for i in range(n) { for j in range(n) {
  let x = -3 + 6 * i / (n - 1)
  let y = -3 + 6 * j / (n - 1)
  d.push((x: x, y: y, z: calc.sin(x) * calc.cos(y)))
} }
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", z: "z"),
  layers: (geom-contour-filled(bins: 10),),
  scales: (scale-fill-viridis-c(),),
  width: 11cm,
  height: 7cm,
)
```
```

--------------------------------

### defer Usage Example

Source: https://m.canouil.dev/gribouille/reference/core/defer.html

This example demonstrates how to use `defer` to create two deferred scatter panels that share a hoisted color legend. The `panel` function is defined using `defer` and `plot`, and then these panels are composed together.

```APIDOC
## Example
#let panel(map) = defer(plot,
  data: mpg, mapping: map,
  layers: (geom-point(size: 3pt),),
)
#compose(
  panel(aes(x: "displ", y: "hwy", colour: as-factor("cyl"))),
  panel(aes(x: "displ", y: "cty", colour: as-factor("cyl"))),
  columns: 2,
)
```

--------------------------------

### Two-Dimensional Facet Grid Layout

Source: https://m.canouil.dev/gribouille/reference/facets/facet-grid.html

Example demonstrating a two-dimensional grid layout using 'sex' for rows and 'sp' for columns. Requires data with 'sex', 'sp', 'x', and 'y' fields.

```typst
#let d = ()
#for sp in ("a", "b") {
  for sex in ("F", "M") {
    for i in range(0, 5) {
      d.push((sp: sp, sex: sex, x: i, y: i + 1))
    }
  }
}
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  facet: facet-grid(rows: "sex", columns: "sp"),
  width: 12cm,
  height: 7cm,
)
```
Tokens:
Raw