toyplot.color module

Functionality for managing colors, palettes, and color maps.

class toyplot.color.BrewerFactory[source]

Bases: object

Creates Toyplot color palettes and maps based on the Color Brewer 2.0 palettes.

category(name)[source]

Return the category for the given palette.

counts(name)[source]

Return a list of available palette sizes.

map(name, count=None, reverse=False, center=None, domain_min=None, domain_max=None)[source]

Return a color map that uses the given Color Brewer 2.0 palette.

Returns

colormap

Return type

toyplot.color.LinearMap or toyplot.color.CategoricalMap, depending on the palette category.

maps(category=None)[source]

Return a (name, colormap) tuple for every Color Brewer 2.0 palette.

The type of the returned colormaps will be chosen based on the category of each palette.

Parameters

category (str, optional) – If specified, only return palettes from the given category.

Returns

palettes

Return type

sequence of (str, toyplot.color.Map) tuples.

names(category=None)[source]

Return a list of available palette names.

palette(name, count=None, reverse=False)[source]

Construct a toyplot.color.Palette instance from a ColorBrewer 2.0 palette.

Note that some of the sequential palettes have been renamed / reversed so that low-luma colors are always mapped to low values and high-luma colors are always mapped to high values.

Parameters
  • name (str) – The name of the ColorBrewer 2.0 palette.

  • count (integer, optional) – The number of values in the palette. If unspecified, the named palette with the largest number of values is returned.

  • reverse (boolean, optional) – If True, the values in palette will be stored in reverse order.

Returns

palette

Return type

toyplot.color.Palette

palettes(category=None)[source]

Return a (name, palette) tuple for every Color Brewer 2.0 palette.

Parameters

category (str, optional) – If specified, only return palettes from the given category.

Returns

palettes

Return type

sequence of (str, toyplot.color.Palette) tuples.

class toyplot.color.CategoricalMap(palette=None)[source]

Bases: Map

Maps 1D categorical values (nonnegative integers) to colors.

Parameters

Notes

Categorical maps are displayed as a collection of color swatches when viewed in a Jupyter notebook.

color(index, domain_min=None, domain_max=None)[source]

Return one color from the map.

Parameters

index (nonnegative integer) – Specifies the index of the color to retrieve. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

colors(values, domain_min=None, domain_max=None)[source]

Convert a sequence of categorical (nonnegative integer) values to colors.

Each value is mapped to a color in the underlying palette. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.

Parameters

values (array-like collection of nonnegative integers) –

Returns

colors

Return type

numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.

css(index, domain_min=None, domain_max=None)[source]

Return the CSS representation of one color from the map.

Parameters

index (nonnegative integer) – Specifies the index of the color to retrieve. Note that the palette repeats infinitely, so any nonnegative integer value will return a color from the palette.

Returns

css

Return type

str containing a CSS color.

class toyplot.color.DivergingFactory[source]

Bases: object

Creates high-quality diverging color maps by name.

map(name, domain_min=None, domain_max=None)[source]

Construct a named toyplot.color.DivergingMap instance.

Parameters

name (str) – The name of the map. Use toyplot.color.DivergingFactory.names() to retrieve a list of available names.

Returns

map

Return type

toyplot.color.DivergingMap

maps()[source]

Return a (name, colormap) tuple for every map in the collection.

Returns

palettes

Return type

sequence of (str, toyplot.color.DivergingMap) tuples.

names()[source]

Return a list of available map names.

class toyplot.color.DivergingMap(low=None, high=None, domain_min=None, domain_max=None)[source]

Bases: Map

Maps 1D values to colors using a perceptually-uniform diverging color map.

Based on “Diverging Color Maps for Scientific Visualization”, Kenneth Moreland, http://www.sandia.gov/~kmorel/documents/ColorMaps

Values within the domain specified at construction time are mapped to the colors in the underlying palette. Values outside the domain are clamped to the minimum / maximum domain values. If unspecified, the domain will be computed on-the-fly every time toyplot.color.DivergingMap.colors() is called.

Parameters
  • low (Toyplot color, optional) – Defines the color used to represent low values.

  • high (Toyplot color, optional) – Defines the color used to represent high values.

  • domain_min (scalar, optional) –

  • domain_max (scalar, optional) –

Notes

Diverging maps generate a color preview when viewed in a Jupyter notebook.

color(value, domain_min=None, domain_max=None)[source]

Convert one value to a color.

Parameters

value (scalar value) –

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

colors(values, domain_min=None, domain_max=None)[source]

Convert an array-like collection of values to colors.

Parameters

values (array-like collection of scalar values) –

Returns

colors

Return type

numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.

css(value, domain_min=None, domain_max=None)[source]

Convert one value to a CSS representation of its color.

Parameters

value (scalar value) –

Returns

css

Return type

str containing a CSS color.

class toyplot.color.LinearFactory[source]

Bases: object

Creates high-quality linear color maps by name.

map(name, domain_min=None, domain_max=None)[source]

Construct a named toyplot.color.LinearMap instance.

Parameters

name (str) – The name of the map. Use toyplot.color.LinearFactory.names() to retrieve a list of available names.

Returns

map

Return type

toyplot.color.LinearMap

maps()[source]

Return a (name, colormap) tuple for every map in the collection.

Returns

palettes

Return type

sequence of (str, toyplot.color.DivergingMap) tuples.

names()[source]

Return a list of available map names.

class toyplot.color.LinearMap(palette=None, stops=None, center=None, domain_min=None, domain_max=None)[source]

Bases: Map

Maps 1D values to colors.

Values within the domain specified at construction time are mapped to the colors in the underlying palette. Values outside the domain are clamped to the minimum / maximum domain values. If unspecified, the domain will be computed on-the-fly each time toyplot.color.LinearMap.colors() is called.

Parameters
  • palette (toyplot.color.Palette) – Specify the set of colors used by the map.

  • stops (sequence of scalars, one per palette color, optional) – Specify a “stop” in the range [0, 1] for each palette color. By default the stops are evenly spaced.

  • center (scalar, optional) – If specified, map [domain_min, center] to the first half of the color palette, and [center, domain_max] to the second half of the palette. This is useful for diverging palettes when there is a domain-specific critical value that should fall in the middle of the color range, such as zero or a mean or median.

  • domain_min (scalar, optional) –

  • domain_max (scalar, optional) –

Notes

Linear maps are displayed as a color preview of their domain when viewed in a Jupyter notebook.

color(value, domain_min=None, domain_max=None)[source]

Convert one value to a color.

Parameters

value (scalar value) –

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

colors(values, domain_min=None, domain_max=None)[source]

Convert an array-like collection of values to colors.

Parameters

values (array-like collection of scalar values) –

Returns

colors

Return type

numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype and the same shape as values.

css(value, domain_min=None, domain_max=None)[source]

Convert one value to a CSS representation of its color.

Parameters

value (scalar value) –

Returns

css

Return type

str containing a CSS color.

class toyplot.color.Map(domain_min, domain_max)[source]

Bases: object

Abstract interface for objects that map scalar values to colors.

class DomainHelper(domain_min, domain_max)[source]

Bases: object

Interface to get / set the domain for a toyplot.color.Map.

property max

Maximum domain value.

property min

Minimum domain value.

property domain

Accessor for the map’s domain.

Returns

domain – Provides access to the minimum and maximum domain values for the map.

Return type

toyplot.color.Map.DomainHelper

class toyplot.color.Palette(colors=None, reverse=False)[source]

Bases: object

Storage for an ordered collection of colors.

Parameters
  • colors (sequence of color values, optional) – Specifies the list of color values to store in the palette. Each color may be a CSS color string, a Toyplot color, a sequence of three RGB values, or a sequence of four RGBA values. If colors is unspecified, the palette will be initialized with a default collection of colors.

  • reverse (boolean, optional) – If True, the values in colors will be stored in reverse order.

Notes

You can iterate over the colors in a Palette using normal Python iteration.

Palettes are displayed as a collection of color swatches when viewed in a Jupyter notebook.

color(index)[source]

Return one color from the palette.

Parameters

index (integer) – Specifies the index of the color to retrieve.

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

css(index)[source]

Return the CSS representation of one color from the palette.

Parameters

index (integer) – Specifies the index of the color to retrieve.

Returns

css

Return type

str containing a CSS color.

toyplot.color.black = '#292724'

Default color used throughout Toyplot figures.

toyplot.color.brewer = <toyplot.color.BrewerFactory object>

Instance of toyplot.color.BrewerFactory

Use this to create Toyplot color palettes and maps based on the Color Brewer 2.0 palettes.

toyplot.color.broadcast(colors, shape, default=None)[source]

Return a 1D or 2D array of colors with the given shape.

Parameters

shape (tuple) – Shape of the desired output array. A 1-tuple will produce a 1D output array containing \(N\) per-series colors. A 2-tuple will produce an \(M \times N\) output matrix of per-datum colors grouped into \(N\) series.

Returns

colors

Return type

One- or two-dimensional numpy.ndarray containing RGBA values with dtype = toyplot.color.dtype.

toyplot.color.css(value)[source]

Construct a Toyplot color from a CSS string.

Parameters

value (str) –

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

toyplot.color.diverging = <toyplot.color.DivergingFactory object>

Instance of toyplot.color.DivergingFactory

Use this to create Toyplot diverging color maps by name.

toyplot.color.dtype = {'formats': ['float64', 'float64', 'float64', 'float64'], 'names': ['r', 'g', 'b', 'a']}

Data type for storing RGBA color information in numpy.ndarray instances.

toyplot.color.lab(l, a, b)[source]

Construct a Toyplot color from CIE Lab values.

toyplot.color.linear = <toyplot.color.LinearFactory object>

Instance of toyplot.color.LinearFactory

Use this to create Toyplot linear color maps by name.

toyplot.color.rgb(r, g, b)[source]

Construct a Toyplot color from RGB values.

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

toyplot.color.rgba(r, g, b, a)[source]

Construct a Toyplot color from RGBA values.

Returns

color

Return type

numpy.ndarray scalar containing RGBA values with dtype = toyplot.color.dtype.

toyplot.color.spread(color, count=5, lightness=0.9, reverse=False)[source]

Create a palette by progressively altering an initial color.

toyplot.color.to_css(color)[source]

Convert a Toyplot color to a CSS string.

Parameters

color (numpy.ndarray) – Array of RGBA values with dtype = toyplot.color.dtype, which is converted to a CSS rgba() color.

Returns

css

Return type

str containing a CSS color value.

toyplot.color.to_lab(color)[source]

Convert a Toyplot color to a CIE Lab color.

toyplot.color.to_xyz(color)[source]

Convert a Toyplot color to a CIE XYZ color using observer = 2 deg and illuminant = D65.

toyplot.color.xyz(x, y, z)[source]

Construct a Toyplot color from CIE XYZ values, using observer = 2 deg and illuminant = D65.