Skip to content

group ​

Partitions the data by a field and draws the partitions in one layer, without positioning them. Pair it with another operator — or a nested mark — to lay the groups out.

python
from gofish import chart, spread, group, stack, rect

chart(seafood, axes=True).flow(
    spread(by="lake", dir="x"),
    group(by="species"),
).mark(rect(h="count", fill="species")).render(w=400, h=300)

Signature ​

python
group(*, by, **options) -> Operator

Parameters ​

group — Operator form ​

Partition rows by by into one layer of the groups (no layout beyond grouping). Its box takes spread's x, y, w and h.

OptionTypeDefaultDescription
bystr | FieldAccessor | ChunkKeyRequired. Field to group rows by; also accepts a field(...) accessor carrying domain ops (sort/reverse/bin), or chunk(size) to group consecutive rows.
xint | float | strLeft edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
yint | float | strStart 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.
wint | float | str | LengthValueWidth 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.
hint | float | str | LengthValueHeight 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.

group — Combinator form ​

OptionTypeDefaultDescription
xint | float | strLeft edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
yint | float | strStart 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.
wint | float | str | LengthValueWidth 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.
hint | float | str | LengthValueHeight 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.

For the simple case — one ribbon or stream band per group, re-partitioning the marks a chart already drew — reach for a bare .layer(ribbon(...)) instead, with no by at all: a ribbon or line fused over a chart's own flow splits at the flow's own grouping by default (see ribbon's Default grouping). group() is for nested splits (composing with a connector's own by, or an explicit by override) and for operator pipelines generally — anywhere you need a named per-partition group without a connector mark driving the partitioning. group's own by reads refs when it runs after a select_all, and a ref is read through its rows, so the bare field name works — by="species":

python
chart(select_all("bars")) \
    .flow(group(by="species")) \
    .mark(ribbon(opacity=0.8))

On a ref, a field resolves to a scalar only when every row in the ref's bag agrees on that field (homogeneity collapse); otherwise it is None. See spread → path-aware by for the full explanation.

Returns an Operator for use inside .flow().

How it works ​

group only partitions — it draws each partition's contents in a shared layer but does not move the partitions apart. Use it when a later operator (or the mark itself) is responsible for layout, or when you need the grouping boundary for scales and color.

Notes ​

  • For most charts, spread or stack — which partition and position — are what you want. Reach for group when you need the partition without the layout.
  • by is required.