milia.plot.tokens#

Design tokens: the palette and the semantic colour roles every figure uses.

Figures refer to roles (PRIMARY, DANGER), never to palette positions, so re-binding a role here changes every figure at once. The first three palette entries carry meaning:

  • PALETTE[0] teal: the subject, the correct or reference case.

  • PALETTE[1] cyan: a second series, or a supporting one.

  • PALETTE[2] orange: the thing the reader should notice.

Grey (TEXT_MUTED) is reserved for reference lines and background points.

Module Attributes

DEFICIENCIES

Matrices of Machado, Oliveira and Fernandes (2009) that simulate colour-vision deficiency at full severity, applied to linear RGB.

CMYK

The Generic CMYK profile of macOS, an indicative stand-in for a press profile such as FOGRA39 or SWOP.

SHAPES

a circle, two triangles, a square and a diamond (filled shapes), then a plus and a cross.

MARKERS

The same marker shapes in matplotlib, in the same order.

Functions

assign(names, centres, palette[, highlight, ...])

Colours for groups of an embedding, so that groups that lie next to one another differ most.

colors(count)

The first count palette colours, cycling when more are needed.

contrast(color[, background])

The WCAG contrast ratio of a colour against a background (1 to 21).

deficiency(color, kind)

The colour as seen with a colour-vision deficiency (Machado et al., full severity).

diverging([name, low, high])

Diverging colormap for signed quantities such as correlation.

lightness(color)

The CIE lightness L* of a colour (0 black to 100 white), the quantity a greyscale print preserves.

matrix([name])

Light-to-dark grey colormap for an unsigned matrix on [0, 1], such as agreement or p-values.

printed(color[, profile])

The colour after conversion to CMYK through an ICC profile and back, as a press would reproduce it.

printshift(color[, profile])

How far CMYK conversion moves a colour, as a CIEDE2000 difference; at most 5 keeps it recognisable in print.

separation(first, second[, kind])

The perceived difference of two colours in OKLab, times 100, optionally as seen with a deficiency.

sequential([name, color])

White-to-colour colormap, so heatmaps stay in palette.

tint(color[, amount])

Blend a hex colour towards white.

milia.plot.tokens.tint(color, amount=0.85)#

Blend a hex colour towards white.

Parameters:
  • color (str) – Hex colour, e.g. "#107591".

  • amount (float) – Share of white, from 0 (unchanged) to 1 (white).

Return type:

str

Returns:

The blended hex colour.

Examples

>>> tint("#000000", 0.5)
'#808080'
milia.plot.tokens.DEFICIENCIES: dict[str, ndarray] = {'deuteranopia': array([[ 0.367322,  0.860646, -0.227968],        [ 0.280085,  0.672501,  0.047413],        [-0.01182 ,  0.04294 ,  0.968881]]), 'protanopia': array([[ 0.152286,  1.052583, -0.204868],        [ 0.114503,  0.786281,  0.099216],        [-0.003882, -0.048116,  1.051998]]), 'tritanopia': array([[ 1.255528, -0.076749, -0.178779],        [-0.078411,  0.930809,  0.147602],        [ 0.004733,  0.691367,  0.3039  ]])}#

Matrices of Machado, Oliveira and Fernandes (2009) that simulate colour-vision deficiency at full severity, applied to linear RGB.

milia.plot.tokens.CMYK = PosixPath('/System/Library/ColorSync/Profiles/Generic CMYK Profile.icc')#

The Generic CMYK profile of macOS, an indicative stand-in for a press profile such as FOGRA39 or SWOP.

milia.plot.tokens.contrast(color, background='#FFFFFF')#

The WCAG contrast ratio of a colour against a background (1 to 21).

Marks that carry meaning need 3:1 against the page and text 4.5:1; a colour below 3:1 is for fills, bands and bars.

Parameters:
  • color (str) – Hex colour of the mark or text.

  • background (str) – Hex colour of the page.

Return type:

float

Returns:

The contrast ratio.

Examples

>>> round(contrast("#000000"), 1), round(contrast("#FFFFFF"), 1)
(21.0, 1.0)
milia.plot.tokens.lightness(color)#

The CIE lightness L* of a colour (0 black to 100 white), the quantity a greyscale print preserves.

Parameters:

color (str) – Hex colour.

Return type:

float

Returns:

L*.

Examples

>>> round(lightness("#000000")), round(lightness("#FFFFFF"))
(0, 100)
milia.plot.tokens.deficiency(color, kind)#

The colour as seen with a colour-vision deficiency (Machado et al., full severity).

Parameters:
  • color (str) – Hex colour.

  • kind (str) – "deuteranopia", "protanopia" or "tritanopia".

Return type:

str

Returns:

The simulated hex colour.

Raises:

ValueError – If kind is unknown.

Examples

>>> deficiency("#FFFFFF", "deuteranopia")
'#FFFFFF'
milia.plot.tokens.separation(first, second, kind=None)#

The perceived difference of two colours in OKLab, times 100, optionally as seen with a deficiency.

About 10 is clearly distinguishable; categories of a figure should keep at least 10 under every deficiency.

Parameters:
  • first (str) – Hex colour.

  • second (str) – Hex colour.

  • kind (str | None) – A deficiency from DEFICIENCIES, or None for normal vision.

Return type:

float

Returns:

The distance.

Examples

>>> separation("#000000", "#FFFFFF") > 90
True
>>> separation("#336699", "#336699", "tritanopia")
0.0
milia.plot.tokens.printed(color, profile=PosixPath('/System/Library/ColorSync/Profiles/Generic CMYK Profile.icc'))#

The colour after conversion to CMYK through an ICC profile and back, as a press would reproduce it.

Parameters:
  • color (str) – Hex colour.

  • profile (Path) – ICC profile of the press; the generic profile is only indicative.

Return type:

str

Returns:

The hex colour as printed.

Raises:

FileNotFoundError – If the profile does not exist.

Examples

>>> printed("#FFFFFF")
'#FFFFFF'
milia.plot.tokens.printshift(color, profile=PosixPath('/System/Library/ColorSync/Profiles/Generic CMYK Profile.icc'))#

How far CMYK conversion moves a colour, as a CIEDE2000 difference; at most 5 keeps it recognisable in print.

Parameters:
  • color (str) – Hex colour.

  • profile (Path) – ICC profile of the press.

Return type:

float

Returns:

The CIEDE2000 difference between the colour and its printed version.

Raises:

FileNotFoundError – If the profile does not exist.

Examples

>>> printshift("#FFFFFF") < 1.5
True
milia.plot.tokens.colors(count)#

The first count palette colours, cycling when more are needed.

Parameters:

count (int) – Number of colours.

Return type:

list[str]

Returns:

Hex colours.

Examples

>>> colors(2)
['#107591', '#00c0bf']
milia.plot.tokens.SHAPES: list[int] = [21, 24, 22, 23, 25, 3, 4]#

a circle, two triangles, a square and a diamond (filled shapes), then a plus and a cross.

Type:

Marker shapes of lets-plot, one per group, so that colour is not the only identifier of a group

milia.plot.tokens.MARKERS: list[str] = ['o', '^', 's', 'D', '*', 'P', 'X']#

The same marker shapes in matplotlib, in the same order.

milia.plot.tokens.assign(names, centres, palette, highlight=None, accent=None)#

Colours for groups of an embedding, so that groups that lie next to one another differ most.

The groups take the first colours of the palette (without the accent colour, which is kept for the highlighted group). With eight groups or fewer, the assignment is the permutation of those colours that maximises the colour separation of every pair of groups weighted by the inverse distance of their centres; with more groups the palette is cycled.

Parameters:
  • names (Sequence[str]) – Group names.

  • centres (Sequence[Sequence[float]]) – Centre of each group, shape (groups, 2), in the order of names.

  • palette (Sequence[str]) – Categorical colours, in order.

  • highlight (str | None) – Name of the group drawn in the accent colour, such as a minority that stands apart.

  • accent (str | None) – Colour of the highlighted group, and the colour left out of the palette; the second palette colour when omitted.

Return type:

dict[str, str]

Returns:

Group name to colour.

Examples

>>> colours = assign(["1", "2", "3"], [[0, 0], [1, 0], [5, 5]], PALETTE, highlight="3")
>>> sorted(colours), colours["3"] == PALETTE[1]
(['1', '2', '3'], True)
milia.plot.tokens.matrix(name='milia_matrix')#

Light-to-dark grey colormap for an unsigned matrix on [0, 1], such as agreement or p-values.

Grey carries magnitude without implying a direction.

Parameters:

name (str) – Colormap name.

Returns:

A matplotlib colormap.

Examples

>>> matrix().name
'milia_matrix'
milia.plot.tokens.diverging(name='milia_div', low='#107591', high='#f69a48')#

Diverging colormap for signed quantities such as correlation.

The teal and orange ends separate by hue, so the sign survives greyscale printing and red-green colour deficiency.

Parameters:
  • name (str) – Colormap name.

  • low (str) – Colour of the negative end.

  • high (str) – Colour of the positive end.

Returns:

A matplotlib colormap.

Examples

>>> diverging().name
'milia_div'
milia.plot.tokens.sequential(name='milia_seq', color='#107591')#

White-to-colour colormap, so heatmaps stay in palette.

Parameters:
  • name (str) – Colormap name.

  • color (str) – Colour of the high end.

Returns:

A matplotlib colormap.

Examples

>>> sequential().name
'milia_seq'