ribbon

Fills the region between a baseline and a set of data points as a filled band. Like line, a ribbon traces a layout produced by another chart, selected with selectAll() — an array of refs whose placed geometry the ribbon reads.

from gofish import layer, chart, spread, blank, selectAll, ribbon

layer([
    chart(lake_totals)
        .flow(spread(by="lake", dir="x", spacing=64))
        .mark(blank(h="count").name("points")),
    chart(selectAll("points")).mark(ribbon(opacity=0.8)),
]).render(w=500, h=300, axes=True)

Signature

ribbon(stroke=None, strokeWidth=None, opacity=None, mixBlendMode=None,
     dir=None, curve=None, along=None, w=None, h=None, emX=None, emY=None) -> Mark

Parameters

Parameter	Type	Description
stroke	str	Outline color
strokeWidth	int	Outline width in pixels
opacity	float	Opacity, 0–1
mixBlendMode	str	CSS blend mode for overlapping areas
dir	str	Direction the ribbon fills toward
curve	str | dict	Screen-space path shape; default "auto"
along	str	Names a flow tier by its by field (see Default grouping): that tier becomes the band's path, and every other grouping tier splits into separate bands. Usually omitted — the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along on a ribbon that doesn't fuse into a chart's own flow (a refs bag, or the pairwise from/to form), throws.
w, h	int | float | str | FieldAccessor | datum(...)	Ignored by ribbon itself. Blank-fusion anchor keys: read only when ribbon(...) is placed directly in .mark() position, where they become the invisible anchor tier's blank(w=..., h=..., emX=..., emY=...) opts — same channel-value shapes as a leaf mark's "size" channel, including a field(...) pipeline like field("count").sum(). See .layer()'s blank-fusion section.
emX, emY	bool	Ignored by ribbon itself. Blank-fusion anchor keys — see w/h above.

Returns a Mark for use in .mark().

The ribbon pattern

Ribbons use the same two-chart recipe as line: one chart positions named blank marks, a second selectAlls them and draws the ribbon(). selectAll(name) reads a named layer from an earlier chart as an array of refs, and layer([chartA, chartB]) composes multiple charts into one figure. To re-partition the selection first (e.g. one ribbon per series), run it through group(by="datum.field") — see group.

Stack several ribbons in one layer — with opacity or mixBlendMode — for layered and stacked area charts.

Default grouping

A ribbon fused into a flow — in .mark() position or as .layer() sugar over the previous tier's marks — splits at the flow's own grouping by default: one tier lays the band's path, and every other grouping in the flow splits it into separate bands. You don't restate the split — the flow one line up already declared it, and ribbon has no option that spells the split directly.

When you need a different path tier than the one inference would pick, name it with along: along="species" finds the flow tier whose by is "species", makes it the path, and splits by every other grouping tier instead. Naming a field no tier groups by is an error. This doesn't apply to a ribbon drawn over an explicit refs bag (chart(selectAll(...))) or the pairwise from/to form — along is only meaningful when the ribbon fuses into a chart's own flow, and throws if used on either of those. A refs bag spells its split structurally instead, with an upstream flow(group(by="species")).

Sugar: .layer(ribbon(...))

When the ribbon traces a chart's own marks, skip the two-chart selectAll recipe and chain .layer() on the builder — this is the canonical simple ribbon-chart spelling:

from gofish import chart, spread, stack, field, rect, ribbon

chart(seafood, axes=True).flow(
    spread(by="lake", dir="x", spacing=64),
    stack(by=field("species").sort("count"), dir="y"),
).mark(rect(h="count", fill="species")).layer(
    ribbon(opacity=0.8)
).render(w=400, h=400)

No by needed: the stack(by="species") tier already told the flow how to group, so the ribbon splits into one band per species by default.

See .layer() for the full semantics, including the zBelow-by-default paint order and the desugaring to the explicit layer([...]) + selectAll form (which is still what you want to trace another chart's marks).

Sugar: .mark(ribbon(...)) (blank-fusion)

When there's no earlier tier at all — just raw data that needs both fresh anchors and a connector — place ribbon(...) directly in .mark() position and skip .layer() too:

chart(lake_totals).flow(
    spread(by="lake", dir="x", spacing=64)
).mark(ribbon(h="count", opacity=0.8))

# ...is sugar for the explicit two-tier form:
chart(lake_totals).flow(
    spread(by="lake", dir="x", spacing=64)
).mark(blank(h="count")).layer(ribbon(opacity=0.8))

A grouped flow fuses the same way, with no by needed:

chart(seafood, axes=True).flow(
    spread(by="lake", dir="x", spacing=64, alignment="middle"),
    stack(by="species", dir="y"),
).mark(ribbon(h="count", fill="species", opacity=0.8))

fill here is a shared field name, homogeneous within each species group (the default split, above) — it resolves through the color scale per group, the same as it would if fill were declared on an explicit anchor blank().

See .layer()'s blank-fusion section for the full desugaring rule (the w/h/emX/emY anchor/connector key split, .name() chaining, and when the rule doesn't fire).

The w/h/emX/emY anchor channels are only meaningful when ribbon gets to synthesize its own anchors this way; passing them to a ribbon that instead connects already-drawn marks (an empty-scope chart() tier inside .layer(), or chart(selectAll(...))/chart(ref(...))) is an error, since there's nothing left for them to anchor.

Examples

# Semi-transparent ribbon
chart(selectAll("points")).mark(ribbon(opacity=0.8))