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: