Treemaps

TL;DR

Ask your agent

Use Plotwork to draw a treemap of our monthly cloud bill by service. Group the services into Compute, Data, Network, and Operations, give the amounts in dollars, and show the change since last month, with a rise in cost in red.

Use Plotwork to draw a treemap of how big each folder of this repository is in kilobytes, with the packages and the apps as groups and the largest folders first.

Example

PictureSourceOutline

The four top-level groups take a tone each, in turn, and what is inside keeps it. The Security group sits inside Operations, so its frame is one step stronger than the frame round it. The green and red chips are changes since last month: the header says better=down, so a fall in cost is green and a rise is red. The line under the picture says the unit, the total, and how much there is of it.

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. Indentation is for the reader and means nothing to the parser: nesting comes from the braces, so a line written at the wrong depth cannot silently move an item.

A group is sized by what it holds, so it has no value of its own, and a group with nothing in it is refused. An item has no id, because a treemap has no cross references.

1treemap "Disk use" unit="GB"2
3group "Home" icon=lucide:folder {4  item "Photos" 420 icon=lucide:folder5  item "Documents" 856}7
8item "Backups" 310

Header options

Item and group options

Writing a change

A change is the difference since the last period, in the unit of the values or in percent. Its chip shows an arrow and the size of the change, so the arrow carries the sign. A rise can be a bare number. A fall, and any percent, is written in double quotes, because the language reads a bare - as part of an arrow and does not read a bare % at all.

A bare delta=-5 is refused with two errors, one for the - the lexer cannot read and one that says to quote it, so a fall is never drawn as a rise. The chip is green when its direction is the one better= names and red when it is not. When any item has a change, the line under the picture carries a key to the two chips.

Sorting and order

By default the largest tile comes first and ties keep the order written, which packs the picture best and puts the biggest part where it is read first. sort=written keeps the order of the source instead, here the order the product lines were launched in. Revenue is good news when it rises, so better=up (the default) draws a rise green.

PictureSourceOutline

A value of 100,000 or more is drawn compactly on a tile ($1.4M, $420K), and in full in the text description.

Colour and nesting

The top-level groups and items take blue, orange, aqua, violet, amber, and neutral in turn, and everything inside a group keeps its tone. tone= on a group or an item changes it for that branch. Green and red are left out of the rotation because they are what a change chip means, so a branch is never mistaken for news; choose them with tone= when they should mean something. A group inside a group is drawn one step stronger, to four levels, so a hierarchy of region, account, team, and service reads as four shades. Nobody writes a color value: the theme owns every color in light and dark.

Groups nest as the data does, with items at any level:

PictureSourceOutline

What a tile shows

A tile shows the richest of these that it has room for, whole. A label is wrapped at word breaks, to at most three lines, and is never cut: a tile too narrow for its longest word shows no label, and the full text is in the text description.

A group's tab gives up its icon first, then its total, then cuts its name with an ellipsis and warning W203, as a flow group does. A frame too small for a readable name has no tab. A tile less than 4px wide or high is not drawn at all, and lint says which.

Limits and warnings

The picture is 880px wide, the width a Markdown column keeps text readable at, and the treemap in it grows taller with the number of items and groups, from 320px to 1100px. The layout is plain arithmetic, so a treemap of 300 items is laid out in a few milliseconds.

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

From Mermaid

Mermaid treemap-beta (and treemap, which Mermaid is renaming it to) converts to a treemap. A node with a value is an item and a node without one is a group, and a node is a child of the nearest node above it that is indented less, as Mermaid reads it. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1---2title: Product budget3---4treemap-beta5"Engineering"6    "Platform": 4500007    "Application": 380000:::important8    "Tooling": 09"Marketing"10    "Campaigns": 21000011    "Events": 90000:::error12"Support": 16000013
14classDef important fill:#f96

The converter reports the class and its definition it dropped (M200), the zero it dropped (M216), and the tone it took from the class error (M207):

1treemap "Product budget"2
3group "Engineering" {4  item "Platform" 4500005  item "Application" 3800006}7
8group "Marketing" {9  item "Campaigns" 21000010  item "Events" 90000 tone=red11}12
13item "Support" 160000

See also