Color cycles

Proplot defines color cycles or discrete colormaps as color palettes comprising sets of distinct colors. Unlike continuous colormaps, interpolation between these colors may not make sense. Generally, color cycles are used with line plots, bar plots, and other distinct plot elements. Occasionally, they are used as colormaps for qualitative or categorical data. Proplot’s color cycles are registered as DiscreteColormaps, and can be converted into matplotlib property cyclers for use with distinct plot elements using the Cycle constructor function. Cycle can also extract colors from ContinuousColormaps.

Proplot adds several features to help you use color cycles effectively in your figures. This section documents the new registered color cycles, explains how to make and modify color cycles, and shows how to apply them to your plots.

Included color cycles

Use show_cycles to generate a table of the color cycles registered by default, loaded from the cycles user_folder, and/or created with the Cycle constructor function. To retrieve the list of colors associated with a registered or on-the-fly color cycle, simply use get_colors.

import proplot as pplt
fig, axs = pplt.show_cycles(rasterize=True)

Changing the color cycle

Various plotting commands like line and scatter now accept a cycle keyword passed to the Cycle constructor function (see the 1D plotting section). To save your color cycle data and use it every time proplot is imported, simply pass save=True to Cycle. If you want to change the global property cycler, pass a DiscreteColormap or colormap name to rc.cycle or pass the result of Cycle to rc['axes.prop_cycle'] (see the configuration guide).

import proplot as pplt
import numpy as np

# Sample data
state = np.random.RandomState(51423)
data = (state.rand(12, 6) - 0.45).cumsum(axis=0)
kwargs = {'legend': 'b', 'labels': list('abcdef')}

# Figure
lw = 5
pplt.rc.cycle = '538'
fig = pplt.figure(refwidth=1.9, suptitle='Changing the color cycle')

# Modify the default color cycle
ax = fig.subplot(131, title='Global color cycle')
ax.plot(data, lw=lw, **kwargs)

# Pass the cycle to a plotting command
ax = fig.subplot(132, title='Local color cycle')
ax.plot(data, cycle='qual1', lw=lw, **kwargs)

# As above but draw each line individually
# Note that passing cycle=name to successive plot calls does
# not reset the cycle position if the cycle is unchanged
ax = fig.subplot(133, title='Multiple plot calls')
labels = kwargs['labels']
for i in range(data.shape[1]):
    ax.plot(data[:, i], cycle='qual1', legend='b', label=labels[i], lw=lw)

Making color cycles

You can make new color cycles with the Cycle constructor function. One great way to make cycles is by sampling colormaps! Just pass the colormap name to Cycle, and optionally specify the number of samples you want to draw as the last positional argument – e.g. pplt.Cycle('Blues', 5). Using e.g. ax.plot(data, cycle='Blues') will automatically use the same number of samples as the number of columns in the dataset.

Positional arguments passed to Cycle are interpreted by the Colormap constructor function, and the resulting colormap is sampled at discrete values. To exclude near-white colors on the end of a colormap, pass e.g. left=x to Cycle, or supply a plotting command with e.g. cycle_kw={'left': x}. See the colormaps section for details.

In the below example, several cycles are constructed from scratch, and the lines are referenced with colorbars and legends. Note that proplot allows you to generate colorbars from lists of artists.

import proplot as pplt
import numpy as np
fig = pplt.figure(refwidth=2, share=False)
state = np.random.RandomState(51423)
data = (20 * state.rand(10, 21) - 10).cumsum(axis=0)

# Cycle from on-the-fly monochromatic colormap
ax = fig.subplot(121)
lines = ax.plot(data[:, :5], cycle='plum', lw=5)
fig.colorbar(lines, loc='b', col=1, values=np.arange(0, len(lines)))
fig.legend(lines, loc='b', col=1, labels=np.arange(0, len(lines)))
ax.format(title='Cycle from a single color')

# Cycle from registered colormaps
ax = fig.subplot(122)
cycle = pplt.Cycle('blues', 'reds', 'oranges', 15, left=0.1)
lines = ax.plot(data[:, :15], cycle=cycle, lw=5)
fig.colorbar(lines, loc='b', col=2, values=np.arange(0, len(lines)), locator=2)
fig.legend(lines, loc='b', col=2, labels=np.arange(0, len(lines)), ncols=4)
ax.format(title='Cycle from merged colormaps', suptitle='Color cycles from colormaps')

Cycles of other properties

Cycle can also generate cyclers that change properties other than color. Below, a single-color dash style cycler is constructed and applied to the axes locally. To apply it globally, simply use pplt.rc['axes.prop_cycle'] = cycle.

import proplot as pplt
import numpy as np
import pandas as pd

# Cycle that loops through 'dashes' Line2D property
cycle = pplt.Cycle(lw=3, dashes=[(1, 0.5), (1, 1.5), (3, 0.5), (3, 1.5)])

# Sample data
state = np.random.RandomState(51423)
data = (state.rand(20, 4) - 0.5).cumsum(axis=0)
data = pd.DataFrame(data, columns=pd.Index(['a', 'b', 'c', 'd'], name='label'))

# Plot data
fig, ax = pplt.subplots(refwidth=2.5, suptitle='Plot without color cycle')
obj = ax.plot(
    data, cycle=cycle, legend='ll',
    legend_kw={'ncols': 2, 'handlelength': 2.5}

Downloading color cycles

There are plenty of online interactive tools for generating and testing color cycles, including i want hue, coolers, and viz palette.

To add color cycles downloaded from any of these sources, add a cycle data file to the cycles subfolder inside user_folder and call register_cycles (or restart your python session). You can also use from_file or manually pass discrete colormaps or file paths to register_cycles. See from_file for a table of valid data file extensions.