Skip to content

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.

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

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

Parameters ​

table — Operator form ​

Arrange cells in a numCols-wide grid (or a {x, y} keyed grid via by).

OptionTypeDefaultDescription
bydictRequired. 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.
spacingfloat | LengthValue | tuple0Cell 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_colsfloatExplicit column count (falls back to the number of distinct column keys).

table — Combinator form ​

OptionTypeDefaultDescription
spacingfloat | LengthValue | tuple0Cell 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_colsfloatExplicit column count (falls back to the number of distinct column keys).

Returns an Operator for use inside .flow().

Examples ​

python
# 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"] and by["y"] takes what spread's by takes: a field name or a field(...) key, sorted or binned. A binned key's columns (or rows) are its cells, in order, empty ones included, and its axis labels them as spread'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 schema declares the column ordered. Sort your data first if you need a specific order.
  • Unlike nested spread calls, table exposes ordinal axes on both dimensions, so axis labels render on x and y.
  • Pair Color.gradient() on the chart color option with fill="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.