Pie charts

TL;DR

Ask your agent

Use Plotwork to draw a pie chart of where the visits to our docs came from last month. Search 18,420, Direct 11,960, Social 6,310, Email 4,180, Referral 2,140, Paid 1,490. Put an icon on each slice and call the total "Visits in March".

Use Plotwork to draw a donut of our cloud spend in dollars by service: compute 48,200, storage 21,400, network 12,900, databases 9,800, monitoring 3,100, queues 1,400, email 900, and DNS 300. Keep five slices and merge the smallest into Other.

Example

Six shares of one total. The slices are in order of size, clockwise from the top, and each one takes the next tone. Every slice is big enough to be named beside the ring.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment.

A slice has no id. Its name is its identity, compared in any case, so a name used twice is E130. The number is zero or more, written as digits with an optional fraction. A sign, a comma, a percent sign, and an exponent are errors, and the hint says what to write: 42, not 42% or 1,200.

Options

Units

A unit is written after each number, set apart by a space when it starts with a letter or a digit: 42%, 42 ms, 42 visits. A currency sign ($, €, £, ¥) goes before it: $42. The total in the hole takes the same unit.

Percentages

Every slice has a share, and the shares are written as whole percentages that add up to exactly 100. Each share is rounded down and the points left over go to the biggest fractions, the earlier slice first on a tie, so a chart never prints 99 or 101. A share too small to round to 1 is written <1%. The size of a slice in the ring always comes from its exact share.

A label writes the value and the share, 5,208 visits (42%). With values=off it writes the share alone. When the unit is % and the values add up to 100, the value already is the share, so a label writes it once: 62.5%.

Folding the small slices

fold=5 draws at most five slices: the largest four stay and the rest are merged into one grey slice named Other, which is always last. The text description names what was merged, so folding loses nothing for a reader who needs it. A slice you named Other joins the merge and lends it its tone, so there is never a second one.

PictureSourceOutline

Where the names go

With labels=outside, the default, each slice of 3% or more is named in a pill beside the ring, joined to its slice by a thin line. The pills stand in a column on each side and are spread so that none touches another. Slices under 3% are named in a legend under the ring, with a dot in their tone, so nothing is left unnamed.

With labels=legend, every slice is named in the legend and the picture has no lines. It suits a narrow column, and a chart of shares that are all small.

PictureSourceOutline

Colors

The slices take blue, orange, aqua, violet, amber, green, red, and neutral in turn. These are the validated hues of the Plotwork data palette, arranged so that neighbours differ the most, with grey last because grey reads as the rest. A tone= on a slice keeps that tone and the others take the next ones that nobody has claimed, so two slices never share a hue until all eight are in use. A chart with an Other slice keeps grey for it, and the colors of the others repeat only after seven. Nobody writes a color value: the theme owns every color, in light and in dark, and every segment keeps at least 3:1 against the background.

Limits and warnings

Honest charts

A pie chart is the right picture for a few shares of one whole and a poor one for almost anything else. Plotwork warns instead of drawing a chart that misleads. A warning never stops the drawing.

Limits

Errors

Every mistake comes back as a result with a code, a line, a column, and a hint. All the codes are the shared ones.

From Mermaid

Mermaid pie converts to a pie chart. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1pie showData title Browser share2    "Chrome" : 65.43    "Safari" : 18.74    "Edge" : 5.25    "Firefox" : 2.86    "Chrome" : 97    "Other" : 7.9

The converter reports the repeated slice (M209) and keeps the order Mermaid was written in. A chart that also carries an %%{init}%% directive or front matter config: for textPosition converts the same way, and the converter reports the settings it dropped (M200):

1pie "Browser share" sort=written2
3slice "Chrome" 65.44slice "Safari" 18.75slice "Edge" 5.26slice "Firefox" 2.87slice "Other" 7.9

See also