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
Matrices of Machado, Oliveira and Fernandes (2009) that simulate colour-vision deficiency at full severity, applied to linear RGB. |
|
The Generic CMYK profile of macOS, an indicative stand-in for a press profile such as FOGRA39 or SWOP. |
|
a circle, two triangles, a square and a diamond (filled shapes), then a plus and a cross. |
|
The same marker shapes in matplotlib, in the same order. |
Functions
|
Colours for groups of an embedding, so that groups that lie next to one another differ most. |
|
The first |
|
The WCAG contrast ratio of a colour against a background (1 to 21). |
|
The colour as seen with a colour-vision deficiency (Machado et al., full severity). |
|
Diverging colormap for signed quantities such as correlation. |
|
The CIE lightness L* of a colour (0 black to 100 white), the quantity a greyscale print preserves. |
|
Light-to-dark grey colormap for an unsigned matrix on |
|
The colour after conversion to CMYK through an ICC profile and back, as a press would reproduce it. |
|
How far CMYK conversion moves a colour, as a CIEDE2000 difference; at most 5 keeps it recognisable in print. |
|
The perceived difference of two colours in OKLab, times 100, optionally as seen with a deficiency. |
|
White-to-colour colormap, so heatmaps stay in palette. |
|
Blend a hex colour towards white. |
- milia.plot.tokens.tint(color, amount=0.85)#
Blend a hex colour towards white.
- Parameters:
- Return type:
- 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:
- Return type:
- 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.
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:
- Return type:
- Returns:
The simulated hex colour.
- Raises:
ValueError – If
kindis 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 fromDEFICIENCIES, orNonefor normal vision.
- Return type:
- 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:
- Return type:
- 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:
- Return type:
- 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
countpalette colours, cycling when more are needed.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:
centres (
Sequence[Sequence[float]]) – Centre of each group, shape(groups, 2), in the order ofnames.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:
- 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:
- Returns:
A matplotlib colormap.
Examples
>>> diverging().name 'milia_div'