sciris.sc_colors

Handle colors and colormaps.

Highlights:
  • Adds colormaps including 'turbo', 'parula', and 'orangeblue'

  • hex2rgb()/rgb2hex(): convert between different color conventions

  • vectocolor(): map a list of sequential values onto a list of colors

  • gridcolors(): map a list of qualitative categories onto a list of colors

Functions

alpinecolormap

This function generates a map based on ascending height.

arraycolors

Map an N-dimensional array of values onto the current colormap.

bandedcolormap

Map colors onto bands of hue and saturation, with lightness mapped linearly.

bicolormap

This function generators a two-color map, blue for negative, red for positive changes, with grey in the middle.

colormapdemo

Demonstrate a color map using simulated elevation data, shown in both 2D and 3D.

gridcolors

Create a qualitative "color map" by assigning points according to the maximum pairwise distance in the color cube.

hex2rgb

A little helper function to convert e.g.

hsv2rgb

Shortcut to Matplotlib's hsv_to_rgb method, accepts a color triplet or a list/array of color triplets.

midpointnorm

Alias to Matplotlib's TwoSlopeNorm.

orangebluecolormap

Create an orange-blue colormap; most like RdYlBu but more pleasing.

parulacolormap

Create a map similar to Viridis, but brighter.

rgb2hex

A little helper function to convert e.g.

rgb2hsv

Shortcut to Matplotlib's rgb_to_hsv method, accepts a color triplet or a list/array of color triplets.

shifthue

Shift the hue of the colors being fed in.

turbocolormap

NOTE: as of Matplotlib 3.4.0, this colormap is included by default, and will soon be removed from Sciris.

vectocolor

This function converts a vector (i.e., 1D array) of N values into an Nx3 matrix of color values according to the current colormap.

shifthue(colors=None, hueshift=0.0)[source]

Shift the hue of the colors being fed in.

Example:

colors = sc.shifthue(colors=[(1,0,0),(0,1,0)], hueshift=0.5)
rgb2hex(arr)[source]

A little helper function to convert e.g. [0.53, 0.74, 0.15] to a pleasing shade of green.

Example:

hx = sc.rgb2hex([0.53, 0.74, 0.15]) # Returns '#87bc26'
hex2rgb(string)[source]

A little helper function to convert e.g. ‘87bc26’ to a pleasing shade of green.

Example:

rgb = sc.hex2rgb('#87bc26') # Returns array([0.52941176, 0.7372549 , 0.14901961])
rgb2hsv(colors=None)[source]

Shortcut to Matplotlib’s rgb_to_hsv method, accepts a color triplet or a list/array of color triplets.

Example:

hsv = sc.rgb2hsv([0.53, 0.74, 0.15]) # Returns array([0.2259887, 0.7972973, 0.74     ])
hsv2rgb(colors=None)[source]

Shortcut to Matplotlib’s hsv_to_rgb method, accepts a color triplet or a list/array of color triplets.

Example:

rgb = sc.hsv2rgb([0.23, 0.80, 0.74]) # Returns array([0.51504, 0.74   , 0.148  ])
vectocolor(vector, cmap=None, asarray=True, reverse=False, minval=None, maxval=None, midpoint=None)[source]

This function converts a vector (i.e., 1D array) of N values into an Nx3 matrix of color values according to the current colormap. It automatically scales the vector to provide maximum dynamic range for the color map.

Note: see sc.arraycolors() for multidimensional input.

Parameters
  • vector (array) – Input vector (or list, it’s converted to an array)

  • cmap (str) – is the colormap (default: current)

  • asarray (bool) – whether to return as an array (otherwise, a list of tuples)

  • reverse (bool) – whether to reverse the list of colors

  • minval (float) – the minimum value to use

  • maxval (float) – the maximum value to use

  • midpoint (float) – the midpoint value to use

Returns

Nx4 array of RGB-alpha color values

Return type

colors (array)

Example:

n = 1000
x = randn(n,1);
y = randn(n,1);
c = sc.vectocolor(y);
pl.scatter(x, y, c=c, s=50)

New in version 1.2.0: midpoint argument.

arraycolors(arr, **kwargs)[source]

Map an N-dimensional array of values onto the current colormap. An extension of vectocolor() for multidimensional arrays; see that function for additional arguments.

Parameters
  • arr (array) – a multidimensional array to be converted to an array of colors

  • kwargs (dict) – passed to sc.vectocolor()

Example:

n = 1000
ncols = 5
arr = pl.rand(n,ncols)
for c in range(ncols):
    arr[:,c] += c
x = pl.rand(n)
y = pl.rand(n)
colors = sc.arraycolors(arr)
pl.figure(figsize=(20,16))
for c in range(ncols):
    pl.scatter(x+c, y, s=50, c=colors[:,c])

Version: 2020mar07

gridcolors(ncolors=10, limits=None, nsteps=20, asarray=False, ashex=False, reverse=False, hueshift=0, basis='default', demo=False)[source]

Create a qualitative “color map” by assigning points according to the maximum pairwise distance in the color cube. Basically, the algorithm generates n points that are maximally uniformly spaced in the [R, G, B] color cube.

By default, if there are <=9 colors, use Colorbrewer colors; if there are 10-19 colors, use Kelly’s colors; if there are >=20 colors, use uniformly spaced grid colors.

Parameters
  • ncolors (int) – the number of colors to create

  • limits (float) – how close to the edges of the cube to make colors (to avoid white and black)

  • nsteps (int) – the discretization of the color cube (e.g. 10 = 10 units per side = 1000 points total)

  • ashex (bool) – whether to return colors in hexadecimal representation

  • asarray (bool) – whether to return the colors as an array instead of as a list of tuples

  • reverse (bool) – whether to reverse the list of colors

  • hueshift (float) – whether to shift the hue (hueshift > 0 and <=1) or not (0)

  • demo (bool) – whether or not to plot the color cube itself

  • basis (str) – what basis to use – options are ‘colorbrewer’, ‘kelly’, ‘default’, or ‘none’

Example:

import pylab as pl
import sciris as sc
ncolors = 10
piedata = pl.rand(ncolors)
colors = sc.gridcolors(ncolors)
pl.pie(piedata, colors=colors)
sc.gridcolors(ncolors, demo=True)
pl.show()

Version: 2018oct30

midpointnorm(vcenter=0, vmin=None, vmax=None)[source]

Alias to Matplotlib’s TwoSlopeNorm. Used to place the center of the colormap somewhere other than the center of the data.

Parameters
  • vcenter (float) – the center of the colormap (0 by default)

  • vmin (float) – the minimum of the colormap

  • vmax (float) – the maximum of the colormap

Example:

data = pl.rand(10,10) - 0.2
pl.pcolor(data, cmap='bi', norm=sc.midpointnorm())

New in version 1.2.0.

colormapdemo(cmap=None, n=None, smoothing=None, randseed=None, doshow=True)[source]

Demonstrate a color map using simulated elevation data, shown in both 2D and 3D. The argument can be either a colormap itself or a string describing a colormap.

Examples:

sc.colormapdemo('inferno') # Use a registered Matplotlib colormap
sc.colormapdemo('parula') # Use a registered Sciris colormap
sc.colormapdemo(sc.alpinecolormap(), n=200, smoothing=20, randseed=2942) # Use a colormap object

Version: 2019aug22

alpinecolormap(apply=False)[source]

This function generates a map based on ascending height. Based on data from Kazakhstan.

Test case:

sc.colormapdemo('alpine')

Usage example:

import sciris as sc
import pylab as pl
pl.imshow(pl.randn(20,20), interpolation='none', cmap=sc.alpinecolormap())

Version: 2014aug06

bicolormap(gap=0.1, mingreen=0.2, redbluemix=0.5, epsilon=0.01, demo=False, apply=False)[source]

This function generators a two-color map, blue for negative, red for positive changes, with grey in the middle. The input argument is how much of a color gap there is between the red scale and the blue one.

Parameters
  • gap (float) – sets how big of a gap between red and blue color scales there is (0=no gap; 1=pure red and pure blue)

  • mingreen (float) – how much green to include at the extremes of the red-blue color scale

  • redbluemix (float) – how much red to mix with the blue and vice versa at the extremes of the scale

  • epsilon (float) – what fraction of the colormap to make gray in the middle

  • demo (bool) – whether to plot a demo bicolormap or not

  • apply (bool) – whether to apply this colormap to the current figure

Examples:

sc.bicolormap(gap=0, mingreen=0, redbluemix=1, epsilon=0) # From pure red to pure blue with white in the middle
sc.bicolormap(gap=0, mingreen=0, redbluemix=0, epsilon=0.1) # Red -> yellow -> gray -> turquoise -> blue
sc.bicolormap(gap=0.3, mingreen=0.2, redbluemix=0, epsilon=0.01) # Red and blue with a sharp distinction between

Version: 2013sep13

parulacolormap(apply=False)[source]

Create a map similar to Viridis, but brighter. Set apply=True to use immediately.

Demo and example:

cmap = sc.parulacolormap()
sc.colormapdemo(cmap=cmap)

Version: 2019aug22

turbocolormap(apply=False)[source]

NOTE: as of Matplotlib 3.4.0, this colormap is included by default, and will soon be removed from Sciris.

Copyright 2019 Google LLC.

SPDX-License-Identifier: Apache-2.0

Author: Anton Mikhailov

Borrowed directly from https://gist.github.com/mikhailov-work/ee72ba4191942acecc03fe6da94fc73f, with thanks!

Create a map similar to Jet, but better. Set apply=True to use immediately.

Demo and example:

cmap = sc.turbocolormap()
sc.colormapdemo(cmap=cmap)

Version: 2020mar20

bandedcolormap(minvalue=None, minsaturation=None, hueshift=None, saturationscale=None, npts=None, apply=False)[source]

Map colors onto bands of hue and saturation, with lightness mapped linearly. Unlike most colormaps, this colormap does not aim to be percentually uniform, but rather aims to make it easy to relate colors to as-exact-as-possible numbers (while still maintaining a semblance of overall trend from low to high).

Demo and example:

cmap = sc.bandedcolormap(minvalue=0, minsaturation=0)
sc.colormapdemo(cmap=cmap)

Version: 2019aug22

orangebluecolormap(apply=False)[source]

Create an orange-blue colormap; most like RdYlBu but more pleasing. Created by Prashanth Selvaraj.

Demo and example:

cmap = sc.orangebluecolormap()
sc.colormapdemo(cmap=cmap)

New in version 1.0.0.