Skip to content

ribbon ​

Fills a band. It has two forms. The shape form, ribbon(x=..., h=...), draws one band per group from its rows: an area chart. The connector form traces a layout produced by another chart, selected with select_all(): an array of refs whose placed geometry the ribbon reads.

python
from gofish import layer, chart, spread, blank, select_all, ribbon

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

Signature ​

python
# Shape form
ribbon(x=..., h=..., fill=None, stroke=None, stroke_width=None, opacity=None,
     blend_mode=None, curve=None) -> Mark
ribbon(y=..., w=..., ...) -> Mark

# Connector form
ribbon(stroke=None, stroke_width=None, opacity=None, blend_mode=None,
     dir=None, curve=None, along=None, w=None, h=None, em_x=None, em_y=None) -> Mark

Parameters ​

A filled band. Given x (with h) or y (with w), the shape form: the mark owns its rows and draws one band per group, from its baseline to h at each row's x (or to w at each row's y), sorted by it. Without them, the connector form: a band between the facing edges of consecutive marks another flow placed (sankey ribbons, bands between bars).

OptionTypeDefaultDescription
filterFilter | strA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
fillstrFill color of the band, or a field name or accessor for a color scale (constant within the band). Omitted, the band takes the color of the marks it connects.
strokestrStroke color of the band's outline, or a field name or accessor for a color scale (constant within the band).
stroke_widthfloat0Stroke width in pixels.
opacityfloatOpacity, 0 to 1.
blend_modestr"normal"How bands mix where they overlap (CSS mix-blend-mode).
dirstrConnection axis.
curveCurveScreen-space band-edge shape, made by a call in the Curve family: Curve.linear(), Curve.bezier(), Curve.step(), Curve.monotone(), Curve.smooth() or Curve.catmullRom(). Curve.step() steps both edges, as a stepped area does. Curve.monotone() is piecewise monotone: between two neighboring points each edge only rises or only falls, so it never goes past either point, though the band still turns where the data turns (d3 curveMonotoneX, Vega-Lite interpolate "monotone"); Curve.smooth() is a rounder reading over the same parameter, and can go a little past a point; Curve.catmullRom() is a centripetal Catmull-Rom on screen and can overshoot. Omitted, it is Curve.monotone() on a homogeneous continuous connection axis, else a Curve.bezier() band. The shape form reads its curve over x (or y), so it takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth(), and Curve.monotone() when omitted.
from_str
tostr
alongstrNames a flow tier by its by field: that tier becomes the path tier (threading its groups in order) and every OTHER grouping tier splits. Omitted: the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along where the mark doesn't fuse over this chart's own flow (a refs bag, or the pairwise from/to form), is an error.
em_xboolBlank-fusion anchor key: placed directly in .mark() position, ribbon(opts) elaborates to an invisible anchor tier (a blank() carrying just {w, h, emX, emY}) plus this connector — see the mark construct's doc. Ignored by ribbon itself.
em_yboolBlank-fusion anchor key — see emX. Ignored by ribbon itself.
wint | float | strShape form with y: the band's width at each row, an amount from its baseline (negative values extend the other way). Connector form: a blank-fusion anchor key (see emX), ignored by ribbon itself.
hint | float | strShape form with x: the band's height at each row, an amount from its baseline (negative values extend below it), so a stack can place it. Connector form: a blank-fusion anchor key (see emX), ignored by ribbon itself.
xint | float | strShape form: each row's x, a numeric or time column, a field expression, or an accessor. The band runs through the rows sorted by x, read between them as curve says; two rows of one group at one x are an error. Needs h.
yint | float | strShape form: each row's y, for a band that runs up the y axis. Needs w.
insetfloatShape form: pixels the band is drawn in by from each end of its parameter, so the bands in the cells of a partition are drawn apart. Its values are not drawn in: the band stays on the baseline its data gives it, as a bar's data height is never inset. It changes only what is drawn: the band's box is the same. Not allowed on the connector form.

Returns a Mark for use in .mark().

Shape form ​

Given x, the ribbon draws one band per group, from 0 to h at each row's x. Given y, it draws from 0 to w at each row's y. The rows are sorted by x (or y), which must be a numeric or time column. Two rows of one group at the same x are an error: split them with group first. h may be negative, and the band then goes below the baseline. The curve defaults to Curve.monotone() and takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth().

python
(
    chart(unemployment, schema={"date": Unit.time()})
    .flow(group(by="series"))
    .mark(ribbon(x="date", h="count", fill="series", opacity=0.5))
)

A stack of shape-form ribbons is a stacked area. Each band keeps its thickness at every x, and sits on the bands before it. Outside its own rows a band has thickness 0.

python
(
    chart(unemployment, schema={"date": Unit.time()})
    .flow(stack(by="series", dir="y"))
    .mark(ribbon(x="date", h="count", fill="series"))
)

A shape-form ribbon takes inset, a number of pixels. It is drawn in by inset from each end of its x, so the bands in the cells of a partition are drawn apart. Its values are not drawn in: the band stays on the baseline its data gives it. Only what is drawn changes: the band's box is the same.

Function channels ​

In JavaScript, the shape form reads a function value made with fun in place of a column. Python does not support function values yet: fun raises. Give the function's values at sample points as rows instead.

The ribbon pattern ​

Ribbons use the same two-chart recipe as line: one chart positions named blank marks, a second select_alls them and draws the ribbon(). select_all(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="field") — see group.

Stack several ribbons in one layer — with opacity or blend_mode — 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(select_all(...))) 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 select_all recipe and chain .layer() on the builder — this is the canonical simple ribbon-chart spelling:

python
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(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([...]) + select_all 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:

python
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:

python
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/em_x/em_y anchor/connector key split, .name() chaining, and when the rule doesn't fire).

The w/h/em_x/em_y 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(select_all(...))/chart(ref(...))) is an error, since there's nothing left for them to anchor.

Examples ​

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