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.