Gribouille

The Gribouille plotting pipeline is composed of several core abstractions that define how data is transformed and rendered:

• spec (Plot Specification): The primary dictionary built by the user and consumed by render-plot to define the entire visualization.
• layer: An entry within spec.layers. Each layer contains a name (the geom), a mapping (aesthetic connections), data, and params (layer-specific settings).
• geom (Geometric Layer): The visual representation of data (e.g., points, lines). Every geom must export a draw(layer, ctx) function.
• aes (Aesthetic Mapping): Created via the aes() constructor to map data columns to visual channels (e.g., aes(x: "col", y: "col", colour: "col")). This results in a flattened mapping dictionary.
• stat (Statistical Transform): A transformation applied to data (e.g., calculating means or counts) via the stat_* namespace.
• pos (Position Adjustment): Adjustments to how geoms are placed, such as stack, dodge, fill, or jitter.
• coord (Coordinate System): Defines the coordinate space, such as cartesian, fixed, radial, or transform.
• ctx (Per-draw Context): A dictionary passed to every geom's draw method. It contains environment information like trained scales, palette, theme, and canvas dimensions (canvas-w/canvas-h).
• scales: A dictionary fed to plot() that binds aesthetics to specific scales. A later entry for an aesthetic will override previous ones.

When working with geometries, statistics, or layout helpers, the following terms are used:

• band: A rectangular shaded region.
• gap: The x-distance between adjacent bin centres.
• pad: Padding (in cm) around laid-out content.
• sub: A nested theme element (e.g., theme-sub-axis).
• qq: Quantile-quantile related functions (geom-qq, stat-qq, stat-qq-line).
• segment: A thin connector line from a label to its anchor (enabled via segment: true on text/label/typst geoms).
• route: The output of route-segment, which can be a straight (p0, p1) line, an L-bend (p0, mid, p1), or none.
• se: Standard error (e.g., mean-se, geom-errorbar).
• sp: Species (used in example datasets like penguins/iris).
• mm: Millimetres (used in example datasets).
• cb: A callback closure.
• fn: A suffix for names holding a closure rather than a value (e.g., key-fn, to-stat-fn). These are read once and called many times.

Gribouille provides several built-in cases that represent different scaling behaviors:

Variants allow you to isolate the cost of specific render settings. For example, the point case supports:

• base: small filled circle (Reference)
• large: larger filled circle
• star: star glyph
• alpha: translucent small circle

If you pass --variants to the CLI, it overrides the case's default variants and applies the listed ones to every selected case.

Gribouille follows a grammar-of-graphics approach where a plot is constructed through a forward-only pipeline:

data → stat → position → scale → coord → facet → theme → render

Key Components:

• data: A dictionary of column arrays or a built-in dataset (e.g., penguins, mpg, economics).
• mapping: aes(...): Maps data columns to aesthetics. Supported channels include x, y, colour, fill, shape, size, alpha, linetype, and label. Note: Use British spelling colour, not color.
• layers: A tuple of geom-* objects. Each geom can override stat, position, mapping, and key (legend glyph). Stat-backed geoms use stat: auto by default.
• scales: Defines how values map to axes and palettes.
• coord, facet, labels, guides, theme: Control coordinate systems, faceting, labeling, legends, and visual styling respectively.
• Late Binding: Use functions like after-stat(...), after-scale(...), from-theme(...), and stage(...) for advanced transformations.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(),),
  theme: theme-minimal()
)

The Guide Layer manages how axes, legends, and colour bars are drawn. Key abstractions include:

• entry: A single drawn row in a guide (e.g., an axis tick or legend row). It is represented as (value, frac, label, tier) or (start, end, label, depth) for ranges.
• entries: An array of entry dictionaries.
• tier: The tick weight ("major", "mid", or "minor") which determines tick length and label visibility.
• depth: The nesting level for range entries (0 is nearest the panel).
• gctx: The guide context (src/guide/gctx.typ) containing position, aesthetic, mode, direction, axis, span, and injected closures like place, tick-length, key-draw, and bar-draw.
• mode: The guide mode ("axis" or "legend") derived from the aesthetic.
• across: The thickness axis of a guide side, growing away from the panel.
• along: The axis the guide runs along (paired with across).
• place: A (frac, across) -> (x, y) closure on a gctx used for mapping guide points.
• role: The theme surface role requested by a part (e.g., "text", "ticks", "line").
• side-pt: A side-ordered point used to allow a single routine to serve all four sides of a plot.
• sweep: The along-guide angle in radians. A part running along the guide is a straight segment if none, otherwise a sampled polyline.
• span: The along-guide length in cm. Parts laying out contents in cm divide by this value.
• metrics: The cm allocated to a legend key cell (includes off, drop, last, line-h, slack, lead, label-lead, label-drop).
• flow: The direction of a key label relative to its key ("right" for vertical legends, "below" for horizontal).
• gizmo: A guide part that paints its own body (e.g., a colour bar in src/guide/gizmo/).
• band (Guide context):
  • On a colour bar: The cm reserved across the guide past the strip.
  • On an axis: The cm between the panel edge and the ticks/gap/labels (built by axis-band).
• lead: The cm reserved before a label for the key glyph or tick flank. label-lead is the specific offset where the label is pinned.
• justify: The alignment of a key grid inside the guide width (distinct from label-align).