Colour and Styling

Why your figures already match

Every plot resolves its colours through one set of design tokens, so a set of figures made at different times in different chapters looks like one set of figures.

Ten hues, each at five lightness levels, plus a small set of greys for axes and chrome.

Roles map onto lightness in a fixed way, which is why a line and its companion fill are the same hue at two different weights rather than two different colours.

A palette role is a claim about your data

This is the part that is not decoration.

Categorical is for unordered series. The draw order is chosen so the first several hues stay distinguishable for colour-blind readers, and the last slot is grey for an "other" or reference category.

Sequential is for magnitude, running from near-white to a saturated hue.

Diverging is for a quantity with a meaningful midpoint — a difference, a correlation, a signed effect. Using it without one asserts something false.

A sequential ramp over unordered categories asserts an order that does not exist. That is a claim about your data, made in colour, and it is as wrong as a mislabelled axis.

The one trap worth reading twice

Passing a hue name — palette = "blue" — switches the role to sequential, even on a plot whose series are unordered.

So a categorical plot given a hue name renders a sequential blue ramp over models that have no order. This is the exact mismatch the section above warns about, it is silent, and it is reachable through a documented argument.

If you want a particular colour family on a categorical plot, pass a full set of colours rather than one hue name.

Four levels of control

Do nothing. Everything already resolves through the token system.

Change it everywhere. A global setting switches the categorical palette between systems. It takes a system name only — a hex colour there is an error, because there is no global custom palette.

Change it for one plot. The per-plot argument accepts a role name, a hue name, a system name, a single colour, a vector of colours, or a ramp function. Precedence is system, then role, then hue, then single colour.

Borrow the tokens for your own plots. The palette accessors give you the hues, the greys, generated categorical and sequential scales, the package theme, and ggplot scale functions.

One cost of the last option: hard-coding a hex value means a later global palette change will not reach your figure. Use the accessors and it will.

The theme

The package theme is a compact classic style at a small base size, close to what journals in this field expect: thin axis lines, no grid, tight legends.

It is applied per plot rather than set globally, deliberately — so a PolyGenius figure looks the same whether or not you have changed your own session defaults.

The plain alternative gives you a minimal canvas while keeping the package's colours.

Heatmap typography is currently outside the package's control. A heatmap will not match a themed ggplot panel at the same base size, which matters when composing them into one figure.

Two plots where colour means something different

The leaderboard has three colour layers: one for the score annotation, one per analysis category for the rank cells, and a fallback. In every ramp the saturated end is the best rank, and an unranked cell never reads as best. This is also the page's best positive example of a sequential role, because ranks genuinely are ordered.

The forest plot's palette argument is not a series palette. It is the two-colour alternating row stripe and needs exactly two colours; passing a system name is an error rather than a restyle.