stack
Adds its children's data amounts along dir. Each part starts where the one before it ends, and the parts share one data axis. The basis for stacked bar charts and pie charts.
from gofish import chart, spread, stack, rect
chart(seafood, axes=True).flow(
spread(by="lake", dir="x"),
stack(by="species", dir="y"),
).mark(rect(h="count", fill="species")).render(w=500, h=300)Parts are data amounts
Every part needs a data size along dir: a rect(h="count"), a ribbon with a data h, or another stack. A part sized in pixels or by its content (a rect(h=20), a text, an image, a spread) has no amount to add, so it is an error that names the part. Parts like these only touch. Lay them out with spread(dir=..., spacing=0).
Signature
stack(children=None, *, by=None, dir, **options) -> Operator | MarkLike spread, stack is polymorphic: called with no positional argument it returns an operator for use inside .flow(); called with a positional list of marks it returns a combinator-form mark that stacks those explicit children (the low-level form behind the stackX/stackY operators).
Parameters
stack — Operator form
Add the children's data amounts along dir: each part starts where the one before it ends, in one data space. Every part needs a data size along dir; parts sized in pixels or by their content are laid out with spread({ spacing: 0 }) instead.
| Option | Type | Default | Description |
|---|---|---|---|
by | str | FieldAccessor | ChunkKey | Field to partition rows by; also accepts a field(...) accessor carrying domain ops (sort/reverse/bin), or chunk(size) to group consecutive rows. Without by, each row is its own group. | |
dir | str | Axis to stack along: x, y, or an axis name the enclosing coordinate space declares (polar theta/r, geo lon/lat). | |
alignment | str | "baseline" | Cross-axis alignment ("start" | "middle" | "end" | "baseline"). |
reverse | bool | False | Reverse the children's order along dir. |
baseline | Baseline | {"kind":"start"} | Where the stack puts its own 0, the point its parent lines up: Baseline.start() (the first part's tail), Baseline.end() (the last part's head), Baseline.middle() (halfway between), Baseline.wiggle() (a streamgraph's baseline) or Baseline.at(part, point) (a point on one part). With Trait.diverging() on the by column's unit the default is that column's midpoint, and an explicit baseline is an error. |
axes | bool | dict | ||
x | int | float | str | Left edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it. | |
y | int | float | str | Start edge on y (top where y reads top-down, bottom where it grows upward) of this operator's box, in the parent's space (pixels). Omitted, the parent places it. | |
w | int | float | str | LengthValue | Width of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides. | |
h | int | float | str | LengthValue | Height of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides. | |
size | int | float | str | Per-entry stack-axis extent (field/datum-sized children); a field(...).normalize() accessor makes it a space-filling spine. |
stack — Combinator form
Low-level combinator form of stack. Same fields as the operator form (OPERATORS.stack) plus key and the full box-dims group.
| Option | Type | Default | Description |
|---|---|---|---|
x | int | float | str | Left edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it. | |
w | int | float | str | LengthValue | Width of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides. | |
y | int | float | str | Start edge on y (top where y reads top-down, bottom where it grows upward) of this operator's box, in the parent's space (pixels). Omitted, the parent places it. | |
h | int | float | str | LengthValue | Height of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides. | |
by | str | FieldAccessor | ChunkKey | Field to partition rows by; also accepts a field(...) accessor carrying domain ops (sort/reverse/bin), or chunk(size) to group consecutive rows. Without by, each row is its own group. | |
dir | str | Axis to stack along: x, y, or an axis name the enclosing coordinate space declares (polar theta/r, geo lon/lat). | |
alignment | str | "baseline" | Cross-axis alignment ("start" | "middle" | "end" | "baseline"). |
reverse | bool | False | Reverse the children's order along dir. |
baseline | Baseline | {"kind":"start"} | Where the stack puts its own 0, the point its parent lines up: Baseline.start() (the first part's tail), Baseline.end() (the last part's head), Baseline.middle() (halfway between), Baseline.wiggle() (a streamgraph's baseline) or Baseline.at(part, point) (a point on one part). With Trait.diverging() on the by column's unit the default is that column's midpoint, and an explicit baseline is an error. |
axes | bool | dict | ||
size | int | float | str | Per-entry stack-axis extent (field/datum-sized children); a field(...).normalize() accessor makes it a space-filling spine. | |
key | str | Internal per-node key override. |
Box dimensions
| Option | Type | Default | Description |
|---|---|---|---|
cx | int | float | str | Center x. | |
x2 | int | float | str | Right edge position. | |
em_x | bool | Embed x in the parent's x space. | |
cy | int | float | str | Center y. | |
y2 | int | float | str | Other y edge position. | |
em_y | bool | Embed y in the parent's y space. | |
dims | dict | Box dimensions by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}. |
Returns an Operator for use inside .flow().
dir takes "x", "y", or an axis name the enclosing coordinate space declares, such as "theta" under polar; see spread → naming the axis.
Signed parts
stack places its parts end to end, in order. Each part starts where the one before it ends, and the first part starts at 0. A negative part goes back, so the stack ends at the sum of its parts, and parts that cancel overlap. Parts (+100, −30, +20, −50, +10) rise to 100, step back and forth, and end at 50.
To pile positive parts up from 0 and negative parts down from 0 (a diverging stacked bar), group by sign first, so each stack holds one sign:
# `direction` is "Inflow" for positive amounts and "Outflow" for negative.
chart(cash_flows).flow(
spread(by="quarter", dir="x"),
group(by="direction"),
stack(by="flow", dir="y"),
).mark(rect(h="amount", fill="flow"))Baselines
baseline sets where the stack puts its own 0, the point its parent lines up with its other children. It takes a member of the Baseline family: Baseline.start() (the default), Baseline.end(), Baseline.middle(), Baseline.wiggle() or Baseline.at(part, point).
stack(by="response", dir="x", baseline=Baseline.at("Neutral", 0.5))Centered stacks
When the chart's schema gives the by column a midpoint (Unit(domain=Domain.discrete(levels), traits=[Trait.diverging()])), the stack's 0 is the midpoint of that order instead of the start of its first part: a Baseline.at at that midpoint. The parts must be nonnegative, and the stack takes no baseline option. This draws Likert charts and population pyramids:
chart(
survey, schema={"response": Unit(domain=Domain.discrete(LEVELS), traits=[Trait.diverging()])}
).flow(
spread(by="question", dir="y"),
stack(by="response", dir="x"),
).mark(rect(w="count", fill="response"))Stacked areas
A stack of shape-form ribbons is a stacked area. A band's thickness changes along x, so the stack moves each band by an amount that changes along x too: the thickness of the bands before it, moved by the baseline. Each band keeps its thickness at every x. Outside its own rows a band has thickness 0, so series may be sampled at different x.
chart(unemployment, schema={"date": Unit.time()}).flow(
stack(by="series", dir="y"),
).mark(ribbon(x="date", h="count", fill="series"))With Baseline.wiggle() the stack is a streamgraph. With Baseline.middle() it is centered at every x.
chart(unemployment, schema={"date": Unit.time()}).flow(
stack(by="series", dir="y", baseline=Baseline.wiggle()),
).mark(ribbon(x="date", h="count", fill="series"))Every part of such a stack must be a band. A rect or a text in a stack of bands is an error.
Examples
# Stacked bars: lakes across x, species stacked up y
chart(seafood).flow(
spread(by="lake", dir="x"),
stack(by="species", dir="y"),
).mark(rect(h="count", fill="species"))
# Grouped bars: the bars only touch along x, so they are a spread with no spacing
chart(seafood).flow(
spread(by="lake", dir="x"),
spread(by="species", dir="x", spacing=0),
).mark(rect(h="count", fill="species"))