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.
- 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
ortoyplot.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.
- 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
- 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
palette (an instance of
toyplot.color.Palette
) –map. (Defines the set of colors used by the) –
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. Usetoyplot.color.DivergingFactory.names()
to retrieve a list of available names.- Returns
map
- Return type
- maps()[source]¶
Return a (name, colormap) tuple for every map in the collection.
- Returns
palettes
- Return type
sequence of (
str
,toyplot.color.DivergingMap
) tuples.
- 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.
- 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. Usetoyplot.color.LinearFactory.names()
to retrieve a list of available names.- Returns
map
- Return type
- maps()[source]¶
Return a (name, colormap) tuple for every map in the collection.
- Returns
palettes
- Return type
sequence of (
str
,toyplot.color.DivergingMap
) tuples.
- 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.
- 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
- 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
.
- 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.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.