API Reference
distinctipy core
- distinctipy.distinctipy.color_distance(c1, c2)
Metric to define the visual distinction between two (r,g,b) colours. Inspired by: https://www.compuphase.com/cmetric.htm
- Parameters:
c1 – (r,g,b) colour tuples. r,g and b are values between 0 and 1.
c2 – (r,g,b) colour tuples. r,g and b are values between 0 and 1.
- Returns:
distance: float representing visual distinction between c1 and c2. Larger values = more distinct.
- distinctipy.distinctipy.color_swatch(colors, edgecolors=None, show_text=False, text_threshold=0.6, ax=None, title=None, one_row=None, fontsize=None)
Display the colours defined in a list of colors.
- Parameters:
colors – List of (r,g,b) colour tuples to display. (r,g,b) should be floats between 0 and 1.
edgecolors – If None displayed colours have no outline. Otherwise a list of (r,g,b) colours to use as outlines for each colour.
show_text – If True writes the background colour’s hex on top of it in black or white, as appropriate.
text_threshold – float between 0 and 1. With threshold close to 1 white text will be chosen more often.
ax – Matplotlib axis to plot to. If ax is None plt.show() is run in function call.
title – Add a title to the colour swatch.
one_row – If True display colours on one row, if False as a grid. If one_row=None a grid is used when there are more than 8 colours.
fontsize – Fontsize of text on colour swatch. If None fontsize will attempt to be set to an appropriate size based on the number of colours.
- Returns:
- distinctipy.distinctipy.distinct_color(exclude_colors, pastel_factor=0.0, n_attempts=1000, colorblind_type=None, rng=None)
Generate a colour as distinct as possible from the colours defined in exclude_colors Inspired by: https://gist.github.com/adewes/5884820
- Parameters:
exclude_colors – a list of (r,g,b) tuples. r,g,b are values between 0 and 1.
pastel_factor – float between 0 and 1. If pastel_factor>0 paler colours will be generated.
n_attempts – number of random colours to generate to find most distinct colour
colorblind_type –
Type of colourblindness to simulate, can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males, 0.4% females)
’Tritanopia’: Blue-yellow colourblindness (<1% males and females)
’Tritanomaly’ Blue-yellow colourblindness (0.01% males and females)
’Achromatopsia’: Total colourblindness
’Achromatomaly’: Total colourblindness
rng – A random integer seed or random.Random state. If unspecified the global random is used.
- Returns:
(r,g,b) color tuple of the generated colour with the largest minimum color_distance to the colours in exclude_colors.
- distinctipy.distinctipy.get_colormap(list_of_colors, name='distinctipy')
Converts a list of colors into a matplotlib colormap.
- Parameters:
list_of_colors – a list of (r,g,b) color tuples. (r,g,b) values should be floats between 0 and 1.
name – name of the generated colormap
- Returns:
cmap: a matplotlib colormap.
- distinctipy.distinctipy.get_colors(n_colors, exclude_colors=None, return_excluded=False, pastel_factor=0.0, n_attempts=1000, colorblind_type=None, rng=None)
Generate a list of n visually distinct colours.
- Parameters:
n_colors – How many colours to generate
exclude_colors – A list of (r,g,b) colours that new colours should be distinct from. If exclude_colours=None then exclude_colours will be set to avoid white and black (exclude_colours=[(0,0,0), (1,1,1)]). (r,g,b) values should be floats between 0 and 1.
return_excluded – If return_excluded=True then exclude_colors will be included in the returned color list. Otherwise only the newly generated colors are returned (default).
pastel_factor – float between 0 and 1. If pastel_factor>0 paler colours will be generated.
n_attempts – number of random colours to generated to find most distinct colour.
colorblind_type –
Generate colours that are distinct with given type of colourblindness. Can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males,
0.4% females) * ‘Tritanopia’: Blue-yellow colourblindness (<1% males and females) * ‘Tritanomaly’ Blue-yellow colourblindness (0.01% males and females) * ‘Achromatopsia’: Total colourblindness * ‘Achromatomaly’: Total colourblindness
rng – A random integer seed or random.Random state. If unspecified the global random is used.
- Returns:
colors - A list of (r,g,b) colors that are visually distinct to each other and to the colours in exclude_colors. (r,g,b) values are floats between 0 and 1.
- distinctipy.distinctipy.get_hex(color)
Returns hex of given color
- Parameters:
color – (r,g,b) color tuple. r,g,b are floats between 0 and 1.
- Returns:
hex str of color
- distinctipy.distinctipy.get_random_color(pastel_factor=0.0, rng=None)
Generate a random rgb colour.
- Parameters:
pastel_factor – float between 0 and 1. If pastel_factor>0 paler colours will be generated.
rng – A random integer seed or random.Random state. If unspecified the global random is used.
- Returns:
color: a (r,g,b) tuple. r, g and b are values between 0 and 1.
- distinctipy.distinctipy.get_rgb256(color)
Converts 0.0-1.0 rgb colour into 0-255 integer rgb colour.
- Parameters:
color – (r,g,b) tuple with r,g,b floats between 0.0 and 1.0
- Returns:
(r,g,b) ints between 0 and 255
- distinctipy.distinctipy.get_text_color(background_color, threshold=0.6)
Choose whether black or white text will work better on top of background_color. Inspired by: https://stackoverflow.com/a/3943023
- Parameters:
background_color – The colour the text will be displayed on
threshold – float between 0 and 1. With threshold close to 1 white text will be chosen more often.
- Returns:
(0,0,0) if black text should be used or (1,1,1) if white text should be used.
- distinctipy.distinctipy.invert_colors(colors)
Generates inverted colours for each colour in the given colour list, using a simple inversion of each colour to the opposite corner on the r,g,b cube.
- Returns:
inverted_colors - A list of inverted (r,g,b) (r,g,b) values are floats between 0 and 1.
Colourblindness
Adapted from “The Color Blind Simulation function” by Matthew Wickline and the Human - Computer Interaction Resource Network (http://hcirn.com/), 2000 - 2001.
- distinctipy.colorblind.colorblind_filter(color, colorblind_type='Deuteranomaly')
Transforms an (r,g,b) colour into a simulation of how a person with colourblindnes would see that colour.
- Parameters:
color – rgb colour tuple to convert
colorblind_type –
Type of colourblindness to simulate, can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males, 0.4% females)
’Tritanopia’: Blue-yellow colourblindness (<1% males and females)
’Tritanomaly’ Blue-yellow colourblindness (0.01% males and females)
’Achromatopsia’: Total colourblindness
’Achromatomaly’: Total colourblindness
- Returns:
- distinctipy.colorblind.simulate_clusters(dataset='s2', colorblind_type='Deuteranomaly', colorblind_distinct=False, show=True)
Simulates the appearance of an example clustering dataset with and without colourblindness.
- Parameters:
dataset –
The dataset to display, the options are:
s1, s2, s3, s4: 15 clusters with increasing overlaps from s1 to s4
a1: 20 clusters
a2: 35 clusters
a3: 50 clusters
b1: 100 clusters
colorblind_type –
Type of colourblindness to simulate, can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males, 0.4% females)
’Tritanopia’: Blue-yellow colourblindness (<1% males and females)
’Tritanomaly’ Blue-yellow colourblindness (0.01% males and females)
’Achromatopsia’: Total colourblindness
’Achromatomaly’: Total colourblindness
colorblind_distinct – If True generate colours to be as distinct as possible for colorblind_type. Else generate colours that are as distinct as possible for normal vision.
show – if True, calls
plt.show()
.
- Returns:
- distinctipy.colorblind.simulate_colors(colors, colorblind_type='Deuteranomaly', one_row=None, show=True)
Simulate the appearance of colors with and without colourblindness.
- Parameters:
colors – A list of (r,g,b) colour tuples, with r, g andb floats between 0 and 1.
colorblind_type –
Type of colourblindness to simulate, can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males, 0.4% females)
’Tritanopia’: Blue-yellow colourblindness (<1% males and females)
’Tritanomaly’ Blue-yellow colourblindness (0.01% males and females)
’Achromatopsia’: Total colourblindness
’Achromatomaly’: Total colourblindness
one_row – If True display colours on one row, if False as a grid. If one_row=None a grid is used when there are more than 8 colours.
show – if True, calls
plt.show()
.
- Returns:
- distinctipy.colorblind.simulate_image(img_path, colorblind_type)
- Parameters:
img_path –
colorblind_type –
Type of colourblindness to simulate, can be:
’Normal’: Normal vision
’Protanopia’: Red-green colorblindness (1% males)
’Protanomaly’: Red-green colorblindness (1% males, 0.01% females)
’Deuteranopia’: Red-green colorblindness (1% males)
’Deuteranomaly’: Red-green colorblindness (most common type: 6% males, 0.4% females)
’Tritanopia’: Blue-yellow colourblindness (<1% males and females)
’Tritanomaly’ Blue-yellow colourblindness (0.01% males and females)
’Achromatopsia’: Total colourblindness
’Achromatomaly’: Total colourblindness
- Returns:
Coloursets
Provides access to a large list of 200 colors for “normal” and “deuteranomaly” vision.
- distinctipy.colorsets.get_colormap(name='normal')
Get a matplotlib colormap of built-in colours generated with distinctipy.
- Parameters:
name – The name of a colour set present in distinctipy.colorsets.list_colorsets()
- Returns:
A matplotlib ListedColorMap for the colors in distinctipy.colorsets.colors[name].
- distinctipy.colorsets.get_colors(name='normal')
Return a list of built-in colours generated with distinctipy.
- Parameters:
name – The name of a colour set present in distinctipy.colorsets.list_colorsets()
- Returns:
A list of (r,g,b) colour tuples, where r, g and b are floats between 0 and 1.
- distinctipy.colorsets.list_colorsets()
Get a list of the names of built-in distinctipy colours.
- Returns:
A tuple of keys present in the dictionary distinctipy.colorsets.colors
- distinctipy.colorsets.set_palette(name='normal')
Set the default colour palette used by matplotlib to distinctipy colours.
- Parameters:
name – The name of a colour set present in distinctipy.colorsets.list_colorsets()
Example datasets
- distinctipy.examples.compare_clusters(dataset='a3', compare_with='tab20', show=True)
Displays comparisons of distinctipy colormaps with built-in matplotlib colormaps using example clustering datasets from P. Fränti and S. Sieranoja (http://cs.joensuu.fi/sipu/datasets/).
- Parameters:
dataset (str) –
The dataset to display, the options are:
s1, s2, s3, s4: 15 clusters with increasing overlaps from s1 to s4
a1: 20 clusters
a2: 35 clusters
a3: 50 clusters
b1: 100 clusters
compare_with (str) – The name of a matplotlib cmap to compare distinctipy with.
- Returns:
- distinctipy.examples.compare_colors(N=36, compare_with='tab20', show=True)
Compare colour swatches for distinctipy and a given matplotlib colormap for N colours.
- Parameters:
N – Number of colours to generate
compare_with – str representing name of a built-in matplotlib colormap
- Returns: