palettes - Mapping values onto the domain of a scale

Palettes are the link between data values and the values along the dimension of a scale. Before a collection of values can be represented on a scale, they are transformed by a palette. This transformation is knowing as mapping. Values are mapped onto a scale by a palette.

Scales tend to have restrictions on the magnitude of quantities that they can intelligibly represent. For example, the size of a point should be significantly smaller than the plot panel onto which it is plotted or else it would be hard to compare two or more points. Therefore palettes must be created that enforce such restrictions. This is the reason for the *_pal functions that create and return the actual palette functions.

mizani.palettes.hls_palette(n_colors: int = 6, h: float = 0.01, l: float = 0.6, s: float = 0.65) Sequence[TupleFloat3][source]

Get a set of evenly spaced colors in HLS hue space.

h, l, and s should be between 0 and 1

Parameters:
n_colorsint

number of colors in the palette

hfloat

first hue

lfloat

lightness

sfloat

saturation

Returns:
palettelist

List of colors as RGB hex strings.

See also

husl_palette

Make a palette using evenly spaced circular hues in the HUSL system.

Examples

>>> len(hls_palette(2))
2
>>> len(hls_palette(9))
9
mizani.palettes.husl_palette(n_colors: int = 6, h: float = 0.01, s: float = 0.9, l: float = 0.65) Sequence[TupleFloat3][source]

Get a set of evenly spaced colors in HUSL hue space.

h, s, and l should be between 0 and 1

Parameters:
n_colorsint

number of colors in the palette

hfloat

first hue

sfloat

saturation

lfloat

lightness

Returns:
palettelist

List of colors as RGB hex strings.

See also

hls_palette

Make a palette using evenly spaced circular hues in the HSL system.

Examples

>>> len(husl_palette(3))
3
>>> len(husl_palette(11))
11
class mizani.palettes.rescale_pal(range: TupleFloat2 = (0.1, 1))[source]

Rescale the input to the specific output range.

Useful for alpha, size, and continuous position.

Parameters:
rangetuple

Range of the scale

Returns:
outfunction

Palette function that takes a sequence of values in the range [0, 1] and returns values in the specified range.

Examples

>>> palette = rescale_pal()
>>> palette([0, .2, .4, .6, .8, 1])
array([0.1 , 0.28, 0.46, 0.64, 0.82, 1.  ])

The returned palette expects inputs in the [0, 1] range. Any value outside those limits is clipped to range[0] or range[1].

>>> palette([-2, -1, 0.2, .4, .8, 2, 3])
array([0.1 , 0.1 , 0.28, 0.46, 0.82, 1.  , 1.  ])
class mizani.palettes.area_pal(range: TupleFloat2 = (1, 6))[source]

Point area palette (continuous).

Parameters:
rangetuple

Numeric vector of length two, giving range of possible sizes. Should be greater than 0.

Returns:
outfunction

Palette function that takes a sequence of values in the range [0, 1] and returns values in the specified range.

Examples

>>> x = np.arange(0, .6, .1)**2
>>> palette = area_pal()
>>> palette(x)
array([1. , 1.5, 2. , 2.5, 3. , 3.5])

The results are equidistant because the input x is in area space, i.e it is squared.

class mizani.palettes.abs_area(max: float)[source]

Point area palette (continuous), with area proportional to value.

Parameters:
maxfloat

A number representing the maximum size

Returns:
outfunction

Palette function that takes a sequence of values in the range [0, 1] and returns values in the range [0, max].

Examples

>>> x = np.arange(0, .8, .1)**2
>>> palette = abs_area(5)
>>> palette(x)
array([0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5])

Compared to area_pal(), abs_area() will handle values in the range [-1, 0] without returning np.nan. And values whose absolute value is greater than 1 will be clipped to the maximum.

class mizani.palettes.grey_pal(start: float = 0.2, end: float = 0.8)[source]

Utility for creating continuous grey scale palette

Parameters:
startfloat

grey value at low end of palette

endfloat

grey value at high end of palette

Returns:
outfunction

Continuous color palette that takes a single int parameter n and returns n equally spaced colors.

Examples

>>> palette = grey_pal()
>>> palette(5)
['#333333', '#737373', '#989898', '#b4b4b4', '#cccccc']
class mizani.palettes.hue_pal(h: float = 0.01, l: float = 0.6, s: float = 0.65, color_space: Literal['hls', 'husl'] = 'hls')[source]

Utility for making hue palettes for color schemes.

Parameters:
hfloat

first hue. In the [0, 1] range

lfloat

lightness. In the [0, 1] range

sfloat

saturation. In the [0, 1] range

color_space'hls' | 'husl'

Color space to use for the palette

Returns:
outfunction

A discrete color palette that takes a single int parameter n and returns n equally spaced colors. Though the palette is continuous, since it is varies the hue it is good for categorical data. However if n is large enough the colors show continuity.

Examples

>>> hue_pal()(5)
['#db5f57', '#b9db57', '#57db94', '#5784db', '#c957db']
>>> hue_pal(color_space='husl')(5)
['#e0697e', '#9b9054', '#569d79', '#5b98ab', '#b675d7']
class mizani.palettes.brewer_pal(type: ColorScheme | ColorSchemeShort = 'seq', palette: int | str = 1, direction: Literal[1, -1] = 1)[source]

Utility for making a brewer palette

Parameters:
type'sequential' | 'qualitative' | 'diverging'

Type of palette. Sequential, Qualitative or Diverging. The following abbreviations may be used, seq, qual or div.

paletteint | str

Which palette to choose from. If is an integer, it must be in the range [0, m], where m depends on the number sequential, qualitative or diverging palettes. If it is a string, then it is the name of the palette.

directionint

The order of colours in the scale. If -1 the order of colors is reversed. The default is 1.

Returns:
outfunction

A color palette that takes a single int parameter n and returns n colors. The maximum value of n varies depending on the parameters.

Examples

>>> brewer_pal()(5)
['#EFF3FF', '#BDD7E7', '#6BAED6', '#3182BD', '#08519C']
>>> brewer_pal('qual')(5)
['#7FC97F', '#BEAED4', '#FDC086', '#FFFF99', '#386CB0']
>>> brewer_pal('qual', 2)(5)
['#1B9E77', '#D95F02', '#7570B3', '#E7298A', '#66A61E']
>>> brewer_pal('seq', 'PuBuGn')(5)
['#F6EFF7', '#BDC9E1', '#67A9CF', '#1C9099', '#016C59']

The available color names for each palette type can be obtained using the following code:

from mizani.colors.brewer import get_palette_names

print(get_palette_names("sequential"))
print(get_palette_names("qualitative"))
print(get_palette_names("diverging"))
class mizani.palettes.gradient_n_pal(colors: Sequence[str], values: Sequence[float] | None = None)[source]

Create a n color gradient palette

Parameters:
colorslist

list of colors

valueslist, optional

list of points in the range [0, 1] at which to place each color. Must be the same size as colors. Default to evenly space the colors

Returns:
outfunction

Continuous color palette that takes a single parameter either a float or a sequence of floats maps those value(s) onto the palette and returns color(s). The float(s) must be in the range [0, 1].

Examples

>>> palette = gradient_n_pal(['red', 'blue'])
>>> palette([0, .25, .5, .75, 1])
['#ff0000', '#bf0040', '#7f0080', '#4000bf', '#0000ff']
>>> palette([-np.inf, 0, np.nan, 1, np.inf])
[None, '#ff0000', None, '#0000ff', None]
class mizani.palettes.cmap_pal(name: str)[source]

Create a continuous palette using a colormap

Parameters:
namestr

Name of colormap

Returns:
outfunction

Continuous color palette that takes a single parameter either a float or a sequence of floats maps those value(s) onto the palette and returns color(s). The float(s) must be in the range [0, 1].

Examples

>>> palette = cmap_pal('viridis')
>>> palette([.1, .2, .3, .4, .5])
['#482475', '#414487', '#355f8d', '#2a788e', '#21918c']
class mizani.palettes.cmap_d_pal(name: str)[source]

Create a discrete palette from a colormap

Parameters:
namestr

Name of colormap

Returns:
outfunction

A discrete color palette that takes a single int parameter n and returns n colors. The maximum value of n varies depending on the parameters.

Examples

>>> palette = cmap_d_pal('viridis')
>>> palette(5)
['#440154', '#3b528b', '#21918c', '#5ec962', '#fde725']
class mizani.palettes.desaturate_pal(color: str, prop: float, reverse: bool = False)[source]

Create a palette that desaturate a color by some proportion

Parameters:
colorcolor

html color name, hex, rgb-tuple

propfloat

saturation channel of color will be multiplied by this value

reversebool

Whether to reverse the palette.

Returns:
outfunction

Continuous color palette that takes a single parameter either a float or a sequence of floats maps those value(s) onto the palette and returns color(s). The float(s) must be in the range [0, 1].

Examples

>>> palette = desaturate_pal('red', .1)
>>> palette([0, .25, .5, .75, 1])
['#ff0000', '#e21d1d', '#c53a3a', '#a95656', '#8c7373']
class mizani.palettes.manual_pal(values: Sequence[Any])[source]

Create a palette from a list of values

Parameters:
valuessequence

Values that will be returned by the palette function.

Returns:
outfunction

A function palette that takes a single int parameter n and returns n values.

Examples

>>> palette = manual_pal(['a', 'b', 'c', 'd', 'e'])
>>> palette(3)
['a', 'b', 'c']
mizani.palettes.xkcd_palette(colors: Sequence[str]) Sequence[RGBHexColor][source]

Make a palette with color names from the xkcd color survey.

See xkcd for the full list of colors: http://xkcd.com/color/rgb/

Parameters:
colorslist of strings

List of keys in the mizani.colors.xkcd_rgb dictionary.

Returns:
palettelist

List of colors as RGB hex strings.

Examples

>>> palette = xkcd_palette(['red', 'green', 'blue'])
>>> palette
['#E50000', '#15B01A', '#0343DF']
>>> from mizani.colors.named_colors import XKCD
>>> list(sorted(XKCD.keys()))[:4]
['xkcd:acid green', 'xkcd:adobe', 'xkcd:algae', 'xkcd:algae green']
mizani.palettes.crayon_palette(colors: Sequence[str]) Sequence[RGBHexColor][source]

Make a palette with color names from Crayola crayons.

The colors come from http://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors

Parameters:
colorslist of strings

List of keys in the mizani.colors.crayloax_rgb dictionary.

Returns:
palettelist

List of colors as RGB hex strings.

Examples

>>> palette = crayon_palette(['almond', 'silver', 'yellow'])
>>> palette
['#EED9C4', '#C9C0BB', '#FBE870']
>>> from mizani.colors.named_colors import CRAYON
>>> list(sorted(CRAYON.keys()))[:3]
['crayon:almond', 'crayon:antique brass', 'crayon:apricot']
class mizani.palettes.cubehelix_pal(start: int = 0, rotation: float = 0.4, gamma: float = 1.0, hue: float = 0.8, light: float = 0.85, dark: float = 0.15, reverse: bool = False)[source]

Utility for creating discrete palette from the cubehelix system.

This produces a colormap with linearly-decreasing (or increasing) brightness. That means that information will be preserved if printed to black and white or viewed by someone who is colorblind.

Parameters:
startfloat (0 <= start <= 3)

The hue at the start of the helix.

rotfloat

Rotations around the hue wheel over the range of the palette.

gammafloat (0 <= gamma)

Gamma factor to emphasize darker (gamma < 1) or lighter (gamma > 1) colors.

huefloat (0 <= hue <= 1)

Saturation of the colors.

darkfloat (0 <= dark <= 1)

Intensity of the darkest color in the palette.

lightfloat (0 <= light <= 1)

Intensity of the lightest color in the palette.

reversebool

If True, the palette will go from dark to light.

Returns:
outfunction

Continuous color palette that takes a single int parameter n and returns n equally spaced colors.

References

Green, D. A. (2011). "A colour scheme for the display of astronomical intensity images". Bulletin of the Astromical Society of India, Vol. 39, p. 289-295.

Examples

>>> palette = cubehelix_pal()
>>> palette(5)
['#edd1cb', '#d499a7', '#aa678f', '#6e4071', '#2d1e3e']