spread
Partitions the data and lays the groups out along an axis, with a gap between them. The workhorse operator for bar charts and small multiples.
from gofish import chart, spread, rect
chart(seafood).flow(spread(by="lake", dir="x")).mark(rect(h="count")).render(
w=500, h=300, axes=True
)Signature
spread(*, by=None, dir, **options) -> OperatorParameters
spread — Operator form
Arrange children along dir with spacing, aligning them on the cross axis.
| 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 spread along: x, y, or an axis name the enclosing coordinate space declares (polar theta/r, geo lon/lat). | |
spacing | float | LengthValue | Spacing | 8 | How far apart neighbors are, made by a call in the Spacing family: Spacing.box(gap), a gap between facing edges, or Spacing.pitch(distance, { at }), a fixed distance between the same point on each child. A bare amount is Spacing.box(amount): pixels, percent(n), n percent of the spread's room, or fr(k), k shares of its scope, so the gaps are flexible. |
alignment | str | "baseline" | Cross-axis alignment ("start" | "middle" | "end" | "baseline"). |
reverse | bool | False | Reverse the children's order along dir. |
glue | bool | False | Stack semantics: children glued, sizes sum; spacing forced to 0. |
baseline | Baseline | Where the spread puts its own 0, the point its parent lines up, made by a call in the Baseline family: Baseline.start() (its first child's start), Baseline.end() (its last child's end), Baseline.middle() (halfway, gaps included) or Baseline.at(part, point) (a point on one child). Omitted, its 0 is its start. Baseline.wiggle() is for stack only, and an error here. It only places the spread, which draws no data axis along dir. | |
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. |
spread — Combinator form
Low-level combinator form of spread. Same fields as the operator form (OPERATORS.spread) 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 spread along: x, y, or an axis name the enclosing coordinate space declares (polar theta/r, geo lon/lat). | |
spacing | float | LengthValue | Spacing | 8 | How far apart neighbors are, made by a call in the Spacing family: Spacing.box(gap), a gap between facing edges, or Spacing.pitch(distance, { at }), a fixed distance between the same point on each child. A bare amount is Spacing.box(amount): pixels, percent(n), n percent of the spread's room, or fr(k), k shares of its scope, so the gaps are flexible. |
alignment | str | "baseline" | Cross-axis alignment ("start" | "middle" | "end" | "baseline"). |
reverse | bool | False | Reverse the children's order along dir. |
glue | bool | False | Stack semantics: children glued, sizes sum; spacing forced to 0. |
baseline | Baseline | Where the spread puts its own 0, the point its parent lines up, made by a call in the Baseline family: Baseline.start() (its first child's start), Baseline.end() (its last child's end), Baseline.middle() (halfway, gaps included) or Baseline.at(part, point) (a point on one child). Omitted, its 0 is its start. Baseline.wiggle() is for stack only, and an error here. It only places the spread, which draws no data axis along dir. | |
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().
Examples
# One bar per lake
chart(seafood).flow(spread(by="lake", dir="x")).mark(rect(h="count"))
# Wider gaps
chart(seafood).flow(spread(by="lake", dir="x", spacing=64)).mark(rect(h="count"))
# Nest spreads for grouped layouts
chart(seafood).flow(
spread(by="lake", dir="x"),
spread(by="species", dir="x", spacing=2),
).mark(rect(h="count", fill="species"))Naming the axis with dir
dir="x" and dir="y" mean the first and second axis in any coordinate space. dir also takes the names the enclosing coordinate space declares, so under polar you can write dir="theta" or dir="r":
chart(data, coord=Coord.polar()) \
.flow(spread(by="month", dir="theta", spacing=0)) \
.mark(rect(w=0.5, h="value"))dir="theta" lays the months out exactly as dir="x" does. A name the enclosing space does not declare raises an error that lists the names it does. stack takes the same dir.
Path-aware by
by accepts a field name, a dotted path string, a field(...) accessor, or a chunk(size) key:
spread(by="species", dir="x") # field name
spread(by="origin.country", dir="x") # nested path
spread(by=field("species").sort(), dir="x") # field(...) accessor
spread(by=chunk(5), dir="y") # consecutive rows, five to a groupWithout by
With no by, the split is by row identity: each row is its own group, keyed by its position. The mark under it gets that group, a one-row list [row], just as it gets a group of rows under a by field. An item that is itself a list is still one item, so it becomes [item]. The keys are positions, not data, so they draw no axis and no labels.
chunk(size)
chunk(size) groups consecutive rows: row i goes to group i // size. It is a bin of width size over row position, like Python itertools.batched, lodash _.chunk and Rust chunks(n). Like no by, its keys name no field, so they draw no axis and no labels. chunk(1) is the same split as no by.
chart(seafood).flow(
spread(by="lake", dir="x"),
derive(lambda d: [unit for row in d for unit in repeat(row, "count")]),
spread(by=chunk(5), dir="y", reverse=True), # rows of five units
spread(dir="x"),
).mark(rect(w=8, h=8, fill="species"))The same bare field name works after a ref / select_all selection. The stream items are then refs, not raw records, but a ref is read through its .datum rows automatically, so you still write by="species". Do not add a datum. prefix: by="datum.species" looks for a field named datum inside each row, finds nothing, and puts every ref in one group.
How by resolves on a ref (homogeneity collapse)
A ref's .datum is the raw bag of rows that flowed into the node (a list; a fully-split leaf is a 1-row list). A by="field" path on a ref does not just read the field off the first row — it projects with homogeneity collapse:
fieldresolves to a scalar iff every row in the node's bag agrees on that field; otherwise it isNone— the "this field is multi-valued here, grouping by it is ill-posed" signal.
This is exactly SQL's ONLY_FULL_GROUP_BY / functional-dependency rule: you may only group by a column that is constant within each row-bag.
Example. After select_all("bars") where each ref is a lake aggregate of 5 species rows:
group(by="lake") # resolves — all 5 rows share one lake
group(by="species") # None — 5 distinct species; ill-posedTo group by a field that is multi-valued in the current bag, disaggregate first (split the bag so each child is homogeneous in that field). A fully-split cell (1 row) trivially collapses, so by="species" works once each node holds a single record.
So a ribbon chart reads:
chart(select_all("bars")) \
.flow(group(by="species")) \
.mark(ribbon(opacity=0.8))spread or stack
A spread keeps each child in a space of its own and puts spacing between them. A stack adds its children's data amounts, so they share one data axis on dir. A stack is for data: every part needs a data size on dir, and a part sized in pixels or by its content is an error. Pixel boxes, text, images and nested layouts only touch, so lay them out with spread(..., spacing=0). glue=True makes a spread a stack, with the same rule.
Baselines
baseline sets where the spread puts its own 0, the point its parent lines up with its other children. It takes a member of the Baseline family: Baseline.start(), Baseline.end(), Baseline.middle() or Baseline.at(part, point). The start of a spread is the start of its first child, and its end is the end of its last child. The gaps between children are part of the way from one to the other. Without baseline, a spread's 0 is its start. Baseline.wiggle() is for stack only, and on a spread it is an error.
A spread's baseline only places it. The spread keeps its space, a sequence of separate spaces, so it draws no data axis along dir. Here each row's 0 is the middle of its Neutral bar, and the rows keep the gaps between their bars:
chart(survey, color=likert_colors, axes={"x": False, "y": True}).flow(
spread(by="question", dir="y"),
spread(by="response", dir="x", spacing=3, baseline=Baseline.at("Neutral", 0.5)),
).mark(rect(w="count", fill="response"))A parent's alignment="start", "middle" or "end" draws the same picture as giving each child that baseline and keeping the parent's default, alignment="baseline".
Field-expression pipeline
field(name) returns a chainable accessor — a builder where each method appends one op to an ordered pipeline. It works in two disjoint places:
- As
by(a domain slot):.sort(by=None, order=None),.sort(values)(an explicit order list),.reverse(),.bin(partition=None), and.drop_nulls()decide which groups exist and in what order. - As a mark or
sizechannel value (a value slot):.sum(),.mean(),.median(),.count(), and.distinct()fold a group's rows to one number, overriding the channel's own default aggregation (sum for size, mean for position)..map(fn)and.reduce(fn)compute values with your own function (below).
Mixing the two — an aggregate op on by, or a domain op on a value channel — raises.
map and reduce
field(name).map(lambda x, i, xs: y, unit=None)
field(name).reduce(lambda xs: result, unit=None)map gives one new value per row: fn(x, i, xs), where xs is all of the group's values. fn may take fewer arguments, as in lambda x: x * 2. Maps come before a reduce.
reduce runs once per group on the group's values. Its result is lifted by its shape:
| The reduce returns | The expression is |
|---|---|
| a number | one value per group, for any value channel |
| a dict | an object with one method per key, read with s.lo(), each lifted in turn |
| a list | an error; return a dict instead |
| a function | an error: a Python reduce cannot return a function of t yet |
A channel takes only a number, so a dict must be read down to one. Nothing chains after a value: field("v").reduce(f).sum() raises when the chart renders.
unit mirrors the result's shape. It is one unit for every number of the result, or a dict with a unit per key. A number whose unit is not declared cannot be summed or stacked.
Each Python map or reduce is called across the bridge once per chart, with every group's values, and answers one result per group. A function of t is read many times during layout, which is synchronous, so a Python reduce cannot return one.
import statistics
def five_numbers(xs):
q1, median, q3 = statistics.quantiles(xs, n=4, method="inclusive")
return {"lo": min(xs), "q1": q1, "median": median, "q3": q3, "hi": max(xs)}
box = field("body_mass_g").reduce(five_numbers, unit="g")
chart(penguins).flow(spread(by="species", dir="x")).mark(
layer([
rect(w=1, y=box.lo(), y2=box.hi()),
rect(w=16, y=box.q1(), y2=box.q3()),
])
)Each named method is a built-in callback, on the same path:
| Method | Stands for |
|---|---|
.sum() | reduce(lambda xs: sum(xs)), missing values aside |
.mean() | reduce(statistics.mean), missing values aside |
.median() | reduce(statistics.median), missing values aside |
.count() | reduce(len), in the unit "count" |
.distinct() | reduce(lambda xs: len(set(xs))), in the unit "count" |
.normalize() | map(lambda x, i, xs: x / sum(xs)), a share of the whole |
The named methods run in JS and cross the bridge as data, with no call into Python.
map and reduce read one column. A computation over several columns, such as a fit, belongs in derive (why).
Distribution members
A column can hold a distribution, a Dist, instead of numbers: derive(kde("x")) smooths each group's values into a kernel density that the column then holds (kde). A field of such a column reads the distribution through these methods:
| Method | Gives |
|---|---|
.density() | a function of t: the distribution's density |
.domain() | a function of t: t itself, over the interval the density is drawn over |
.cdf() | a function of t: the share of the mass at or below t, a ratio |
.quantile(p) | one value per group: the inverse of the cdf at p |
.median() | one value per group: .quantile(0.5) |
.mean() | one value per group: the distribution's mean |
A kernel density is in the column's count per unit, so the densities of several groups add up and stack. .domain() is in the column's unit, so its axis joins the column's. Every row of a group holds the same distribution; different ones in one group are an error. In a cell of a partition by the same field, each method reads the distribution restricted to the cell. The other methods are an error on such a column.
On a column of numbers, .median() and .mean() are the data's, and .density(), .domain(), .cdf() and .quantile(p) are an error that names derive(kde("x")). They run in JS and cross the bridge as data.
mass = field("Body Mass (g)")
chart(penguins).flow(
stack(by="Species", dir="y"), derive(kde("Body Mass (g)"))
).mark(ribbon(x=mass.domain(), h=mass.density(), fill="Species"))One method is neither: .between(lo, hi, closed=None) returns a field predicate for filter rather than appending an op, because a predicate never takes part in grouping, folding or scaling. For the same reason it raises if the expression already carries ops.
# Keep the rows whose day falls in (100, 120]
.flow(filter(field("day").between(100, 120, closed="right")))closed is polars' is_between argument: "both" (the default), "left", "right" or "none", choosing which ends of the interval are inclusive. The comparison is by value, not by row count. lo and hi are plain numbers.
Sort a stack's groups by another field's total, instead of data order:
# Bars ordered ascending by their own total `value`
chart(data).flow(
spread(by=field("category").sort("value"), dir="x")
).mark(rect(h="value"))Omit the by argument to sort by the group key itself; pass order="desc" for descending.
Sort groups by an explicit order, for a domain-specific sequence no aggregate expresses (severity, calendar order, a fixed ranking):
# Weather categories in a fixed order, not alphabetical or by aggregate
chart(data).flow(
stack(by=field("weather").sort(["sun", "fog", "drizzle", "rain", "snow"]), dir="y")
)Groups whose key isn't in the list are appended after, in natural sort order.
Bin a field into cells — a histogram, with no precomputed bins:
# One bar per half-point cell of `rating`, height = row count per cell
chart(data).flow(
spread(by=field("rating").bin(Bin.step(0.5)), dir="x")
).mark(rect(h=field("rating").count()))
# One bar per month of the year, all Junes in one bar
chart(sales, schema={"date": Unit.time()}).flow(
spread(by=field("date").bin(Calendar.month), dir="x")
).mark(rect(h=field("value").sum()))
# One bar per month of each year, labeled "Jun 2015"
spread(by=field("date").bin([Calendar.year, Calendar.month]), dir="x")
# The months of each year: a month level and a year level on the axis
spread(by=field("date").bin(Calendar.year).bin(Calendar.month), dir="x").bin(...) maps each value to its cell: an interval [start, end) that holds its start and not its end. The partition is one of:
| Partition | Cells |
|---|---|
| a Calendar value | The calendar cells of a time column, in the column's zone. A level that is a part of a larger one gives its parts, a cycle: Calendar.month is the month of the year, so all Junes are one cell. Calendar.year and Calendar.week are parts of nothing and give cells of the time line. |
| a list of Calendar values | A product, [Calendar.year, Calendar.month]: one cell where one cell of each level meets one of the next (the June of 2015), labeled "Jun 2015". |
Bin.step(size) | Cells size wide, starting at multiples of size. |
Bin.thresholds(n) | About n cells, with the step a numeric axis with n ticks uses. The default, with no argument, is Bin.thresholds(10). |
Bin.thresholds([t1, ...]) | Cells cut at the given edges, with the smallest and largest values as the outer edges. |
Bin.step and Bin.thresholds are members of the Bin family. A thresholds partition includes its top edge, so the largest value falls in the last cell. Custom cell labels (.format) are JS-only for now.
A second .bin(...) splits each cell of the first, a chain: .bin(Calendar.year).bin(Calendar.month) gives the months of each year, and each cell keeps the cell it was split from. See Calendar › Bins for which levels a product or a chain combines.
The groups are the cells over the column's values in the chart's data (or the result of the last derive), not over the rows of one group. So every group of a nested split has the same cells in the same order, a cell with no rows is kept as an empty group, and a count picks its step from the chart's values. Ops after .bin reorder the cells. The mean of an empty group has no value, so a mark whose color is that mean is not drawn, and keeps its slot; a sum or a count of no rows is 0, and draws.
Each group's key is its cell. Its id is the cell's start, as text, or, for a part of a cycle, its field values ("6" for June). An axis over cells labels each cell (its edges, "0.5–1", or the calendar label "Jan"), with no ticks. A chained key adds a level per bin before the last, e.g. years under months, each year label at the start of its run of months, just past the divider between neighboring years. A part of a cycle covers the whole cycle: an axis over the months of the year shows all twelve. See chart › Axes for the "levels" and "label" ("align") options.
spread gives each cell an equal slot. To place each cell at its true width on a continuous axis, use partition with the same key.
Drop rows with a missing/null grouping field, before grouping:
# Rows with a null/missing "genre" are excluded entirely, instead of
# forming their own "null" group
chart(data).flow(
treemap(by=field("genre").drop_nulls(), size="worldwideGross")
)Override a channel's default aggregation:
# The bar height is each species' MEAN weight, not the sum
chart(data).flow(
spread(by="species", dir="x")
).mark(rect(h=field("weight").mean())).count() and .distinct() are in the unit "count" (they're counts, not the source field's own units).
Space-filling spines (mosaic / marimekko)
size=field(<name>).normalize() turns a stack's entries into a space-filling spine: each entry's size becomes its SHARE of the window (the operator's own split entries, v_e / Σv_e), so the axis reads as a local 0–100% conditional distribution. It replaces the removed normalize=True layout flag — .normalize() is a data transform on the size channel (a windowed share, computed once up front), not a layout mode, so the same field can drive both a cross-axis marginal size and the normalized fill with no preprocessing.
Nest two stacks on alternating axes for a mosaic: the outer sizes each column by its raw total (size="count" — the marginal), the inner sizes by each entry's share (the conditional):
(
chart(passengers, axes=True)
.flow(
# columns by class — width ∝ each class's count (marginal)
stack(by="pclass", dir="x", size="count"),
# survival share within each column (conditional), filling height
stack(by="survived", dir="y", size=field("count").normalize()),
)
.mark(rect(fill="survived", stroke="white", stroke_width=1))
.render(w=400, h=300)
).normalize() composes to any depth: a third alternating level gives a nested mosaic (class → sex → survived). Because each level's stacking axis is a local self-scaling region and the count is read raw everywhere, the marginal × conditional × … area factorization holds all the way down.
WARNING
Inner conditional axes are local scopes, so they don't yet render 0–1 tick labels — only the outermost marginal axis is labeled.
Notes
diris required —spread()raises aValueErrorwithout it.- Use
stackwhen you want groups touching edge-to-edge with no gap. - Data order determines group order; sort your data first if order matters.
