table
Groups data by two fields and lays the groups out in a 2D grid — one axis per field. The primary operator for heatmaps and other grid-based visualizations.
from gofish import chart, table, rect, Color
chart(data, color=Color.gradient(["#ffffcc", "#fd8d3c", "#bd0026"]), axes=True).flow(
table(by={"x": "hour", "y": "day"}, spacing=4)
).mark(rect(fill="value")).render(w=500, h=300)Signature
table(*, by, **options) -> OperatorParameters
table — Operator form
Arrange cells in a numCols-wide grid (or a {x, y} keyed grid via by).
| Option | Type | Default | Description |
|---|---|---|---|
by | dict | Required. The column key (x) and the row key (y), both required. Each takes what spread's by takes: a field name, a field(...) key (sorted, binned, a chain or product of bins, a part of a cycle), or chunk(size). A binned key's columns or rows are its cells, empty ones included. Each cell of the table holds the rows in both its column and its row. | |
spacing | float | LengthValue | tuple | 0 | Cell gap: a single number for both axes, or [x, y]. Each is pixels, percent(n), n percent of the table's room on its axis, or fr(k), k shares of its scope. |
num_cols | float | Explicit column count (falls back to the number of distinct column keys). |
table — Combinator form
| Option | Type | Default | Description |
|---|---|---|---|
spacing | float | LengthValue | tuple | 0 | Cell gap: a single number for both axes, or [x, y]. Each is pixels, percent(n), n percent of the table's room on its axis, or fr(k), k shares of its scope. |
num_cols | float | Explicit column count (falls back to the number of distinct column keys). |
Returns an Operator for use inside .flow().
Examples
# Heatmap: hour on x, day on y, colored by value
chart(data, color=Color.gradient(["#ffffcc", "#fd8d3c", "#bd0026"])).flow(
table(by={"x": "hour", "y": "day"}, spacing=4)
).mark(rect(fill="value"))
# Asymmetric spacing
chart(data).flow(table(by={"x": "col", "y": "row"}, spacing=(2, 8)))Notes
- Each of
by["x"]andby["y"]takes whatspread'sbytakes: a field name or afield(...)key, sorted or binned. A binned key's columns (or rows) are its cells, in order, empty ones included, and its axis labels them asspread's does:table(by={"x": field("date").bin(Calendar.week), "y": field("date").bin(Calendar.weekday)})is a calendar heatmap, one column per week and one row per day of the week. - A plain field name's columns and rows come in order of first appearance, or in the order of its levels when the chart's
schemadeclares the column ordered. Sort your data first if you need a specific order. - Unlike nested
spreadcalls,tableexposes ordinal axes on both dimensions, so axis labels render on x and y. - Pair
Color.gradient()on the chartcoloroption withfill="fieldName"on the mark for heatmap coloring.
Cell sizing
Tracks size by one rule: a column (or row) is as wide (or tall) as its widest (or tallest) cell — track = max(cell size claims). Cells that carry no size claim ("fill" cells, like a plain rect(fill=...) in a heatmap) contribute nothing, so an all-fill table divides its box into equal tracks exactly as before — heatmaps are unchanged. When cells DO carry a size claim (for example a nested chart with intrinsic content size), each track sizes to its widest cell and the table shrinks to fit its content instead of stretching every cell to an equal share of the box.
