Bio.Graphics.ColorSpiral module

Generate RGB colours suitable for distinguishing categorical data.

This module provides a class that implements a spiral ‘path’ through HSV colour space, permitting the selection of a number of points along that path, and returning the output in RGB colour space, suitable for use with ReportLab and other graphics packages.

This approach to colour choice was inspired by Bang Wong’s Points of View article: Color Coding, in Nature Methods _7_ 573 (https://doi.org/10.1038/nmeth0810-573).

The module also provides helper functions that return a list for colours, or a dictionary of colours (if passed an iterable containing the names of categories to be coloured).

class Bio.Graphics.ColorSpiral.ColorSpiral(a=1, b=0.33, v_init=0.85, v_final=0.5, jitter=0.05)

Bases: object

Implement a spiral path through HSV colour space.

This class provides functions for sampling points along a logarithmic spiral path through HSV colour space.

The spiral is described by r = a * exp(b * t) where r is the distance from the axis of the HSV cylinder to the current point in the spiral, and t is the angle through which the spiral has turned to reach the current point. a and b are (positive, real) parameters that control the shape of the spiral.

  • a: the starting direction of the spiral

  • b: the number of revolutions about the axis made by the spiral

We permit the spiral to move along the cylinder (‘in V-space’) between v_init and v_final, to give a gradation in V (essentially, brightness), along the path, where v_init, v_final are in [0,1].

A brightness ‘jitter’ may also be provided as an absolute value in V-space, to aid in distinguishing consecutive colour points on the path.

__init__(self, a=1, b=0.33, v_init=0.85, v_final=0.5, jitter=0.05)

Initialize a logarithmic spiral path through HSV colour space.

Arguments:

  • a - Parameter a for the spiral, controls the initial spiral direction. a > 0

  • b - parameter b for the spiral, controls the rate at which the spiral revolves around the axis. b > 0

  • v_init - initial value of V (brightness) for the spiral. v_init in [0,1]

  • v_final - final value of V (brightness) for the spiral v_final in [0,1]

  • jitter - the degree of V (brightness) jitter to add to each selected colour. The amount of jitter will be selected from a uniform random distribution [-jitter, jitter], and V will be maintained in [0,1].

get_colors(self, k, offset=0.1)

Generate k different RBG colours evenly-space on the spiral.

A generator returning the RGB colour space values for k evenly-spaced points along the defined spiral in HSV space.

Arguments:

  • k - the number of points to return

  • offset - how far along the spiral path to start.

property a

Parameter controlling initial spiral direction (a > 0)

property b

Parameter controlling rate spiral revolves around axis (b > 0)

property v_init

Initial value of V (brightness) for the spiral (range 0 to 1)

property v_final

Final value of V (brightness) for the spiral (range 0 to 1)

property jitter

Degree of V (brightness) jitter to add to each color (range 0 to 1)

Bio.Graphics.ColorSpiral.get_colors(k, **kwargs)

Return k colours selected by the ColorSpiral object, as a generator.

Arguments:

  • k - the number of colours to return

  • kwargs - pass-through arguments to the ColorSpiral object

Bio.Graphics.ColorSpiral.get_color_dict(l, **kwargs)

Return a dictionary of colours using the provided values as keys.

Returns a dictionary, keyed by the members of iterable l, with a colour assigned to each member.

Arguments:

  • l - an iterable representing classes to be coloured

  • kwargs - pass-through arguments to the ColorSpiral object