treemap

Lays children out into a treemap: a 2D tiling of rectangles (or circles) whose areas are proportional to a weight.

treemap has two forms:

• treemap(...) — an operator for use inside .flow(); it tiles the partitioned data of a chart.
• treemap(children, ...) — the low-level combinator form: it takes an explicit list of pre-data-bound marks and assigns each one its (x, y, w, h).

The two share the same options below.

from gofish import chart, circle, field, treemap

# treemap(by=..., size=...) partitions the flow's rows itself, mirroring
# spread/group: `by` groups (dropping null genres first), `size` sums
# worldwide gross per group to weight each tile's area.
chart(movies_raw).flow(
    treemap(
        by=field("Major Genre").drop_nulls(),
        size="Worldwide Gross",
        spacing=2,
        padding=2,
        round=True,
    )
).mark(
    circle(fill="Major Genre", stroke="gray", stroke_width=1).label(
        "Major Genre", position="center", color="white", font_size=12
    )
).render(w=700, h=420)

Signature

# Operator form (inside .flow())
treemap(**options) -> Operator

# Combinator form (explicit children)
treemap(children, **options) -> Mark

Parameters

treemap — Operator form

d3-hierarchy treemap layout over the flow's rows, fare/weight-proportional.

Option	Type	Default	Description
x	int | float | str		Left edge of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
y	int | float | str		Start edge on y (top where y reads top-down, bottom where it grows upward) of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
w	int | float | str		Width of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
h	int | float | str		Height of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
dims	dict		The box the treemap tiles into, 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}.
by	str | Any		Field to partition rows by (like spread/group); also accepts a field(...) accessor carrying domain ops (sort/reverse/bin/dropNulls). Without by, one leaf is emitted per row.
spacing	float	0	Gap between sibling tiles, in pixels.
padding	float	0	Inset around the outer edge of the treemap, in pixels.
round	bool	True	Round pixel positions and sizes.
tile	dict	{"kind":"squarify"}	The tiling strategy, made by a function call: squarify({ ratio? }), slice(), dice(), binary(), or sliceDice(). Each is one of d3-hierarchy's tiling methods.
sort	str	"desc"	Sort leaves by weight before layout.
size	int | float | str		Per-leaf weight driving tile area (entry-flagged per split entry); a field name aggregates (sums by default) per group.

treemap — Combinator form

Low-level combinator form of treemap (single level). Same fields as the operator form (OPERATORS.treemap) plus key.

Option	Type	Default	Description
x	int | float | str		Left edge of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
y	int | float | str		Start edge on y (top where y reads top-down, bottom where it grows upward) of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
w	int | float | str		Width of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
h	int | float | str		Height of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
dims	dict		The box the treemap tiles into, 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}.
by	str | Any		Field to partition rows by (like spread/group); also accepts a field(...) accessor carrying domain ops (sort/reverse/bin/dropNulls). Without by, one leaf is emitted per row.
spacing	float	0	Gap between sibling tiles, in pixels.
padding	float	0	Inset around the outer edge of the treemap, in pixels.
round	bool	True	Round pixel positions and sizes.
tile	dict	{"kind":"squarify"}	The tiling strategy, made by a function call: squarify({ ratio? }), slice(), dice(), binary(), or sliceDice(). Each is one of d3-hierarchy's tiling methods.
sort	str	"desc"	Sort leaves by weight before layout.
size	int | float | str		Per-leaf weight driving tile area (entry-flagged per split entry); a field name aggregates (sums by default) per group.
key	str		Internal per-node key override.

Strategies

tile holds the tiling strategy. You make a strategy with a function call. Each one is a tiling method from d3-hierarchy. On the wire a strategy is a plain object, such as {"kind": "squarify", "ratio": 1}.

• squarify(ratio=None) makes tiles as close as it can to the aspect ratio ratio, the longer side over the shorter side. ratio must be at least 1, and it does not choose between wide and tall tiles. It is the default. Without ratio, it uses d3's default, the golden ratio. squarify(ratio=1) aims for square tiles, which suits one circle per leaf.
• slice() puts the tiles in one column, stacked along y.
• dice() puts the tiles in one row, side by side along x.
• binary() splits the tiles into two halves of about equal weight, and repeats on each half.
• slice_dice() alternates between slice and dice by depth.

from gofish import squarify, treemap

treemap(by="genre", size="gross", tile=squarify(ratio=1))

Importing slice from gofish hides Python's built-in slice in that module, so you may prefer import gofish as gf and gf.slice().

Notes

• The tile d3 places first sits at the top left. With the default sort="desc", that is the largest tile.
• A treemap accepts a flat list of children; for multi-level treemaps, compose by nesting treemap(...) calls (or add a higher-level wrapper).
• In the combinator form, each child is bound to its row with mark.bind_data(d, key); chain .label(accessor, ...) on the mark to show a field's value on each tile. size in combinator form is an explicit list, one weight per child in child order — it does not read back off each child's bound datum.