Cartesian axis settings

This section documents features used for modifying Cartesian x and y axis settings, including axis scales, tick locations, and tick label formatting. It also documents a handy “dual axes” feature.

Tick locations

Tick locators are used to automatically select sensible tick locations based on the axis data limits. In ProPlot, you can change the tick locator using the format keyword arguments xlocator, ylocator, xminorlocator, and yminorlocator (or their aliases, xticks, yticks, xminorticks, and yminorticks). This is powered by the Locator constructor function.

These keyword arguments can be used to apply built-in matplotlib Locators by their “registered” names (e.g. xlocator=’log’), to draw ticks every N data values with MultipleLocator (e.g. xlocator=2), or to tick the specific locations in a list using FixedLocator (just like set_xticks and set_yticks). See format and Locator for details.

To generate lists of tick locations, we recommend using ProPlot’s arange function – it’s basically an endpoint-inclusive version of numpy.arange, which is usually what you’ll want in this context.

[1]:

import proplot as plotimport numpy as npstate = np.random.RandomState(51423)plot.rc.update(    facecolor=plot.scale_luminance('powderblue', 1.15),    linewidth=1, fontsize=10,    color='dark blue', suptitlecolor='dark blue',    titleloc='upper center', titlecolor='dark blue', titleborder=False,)fig, axs = plot.subplots(nrows=8, axwidth=5, aspect=(8, 1), share=0)axs.format(suptitle='Tick locators demo')# Step size for tick locationsaxs[0].format(    xlim=(0, 200), xminorlocator=10, xlocator=30,    title='MultipleLocator')# Specific list of locationsaxs[1].format(    xlim=(0, 10), xminorlocator=0.1,    xlocator=[0, 0.3, 0.8, 1.6, 4.4, 8, 8.8, 10],    title='FixedLocator',)# Ticks at numpy.linspace(xmin, xmax, N)axs[2].format(    xlim=(0, 10), xlocator=('linear', 21),    title='LinearLocator',)# Logarithmic locator, used automatically for log scale plotsaxs[3].format(    xlim=(1, 100), xlocator='log', xminorlocator='logminor',    title='LogLocator',)# Maximum number of ticks, but at "nice" locationsaxs[4].format(    xlim=(1, 7), xlocator=('maxn', 11),    title='MaxNLocator',)# Index locator, only draws ticks where data is plottedaxs[5].plot(np.arange(10) - 5, state.rand(10), alpha=0)axs[5].format(    xlim=(0, 6), ylim=(0, 1), xlocator='index',    xformatter=[r'$\alpha$', r'$\beta$', r'$\gamma$', r'$\delta$', r'$\epsilon$'],    title='IndexLocator',)plot.rc.reset()# Hide all ticksaxs[6].format(    xlim=(-10, 10), xlocator='null',    title='NullLocator',)# Tick locations that cleanly divide 60 minute/60 second intervalsaxs[7].format(    xlim=(0, 2), xlocator='dms', xformatter='dms',    title='Degree-Minute-Second Locator (requires cartopy)',)

Tick labels

Tick formatters are used to convert floating point numbers to nicely-formatted tick labels. In ProPlot, you can change the tick formatter using the format keyword arguments xformatter and yformatter (or their aliases, xticklabels and yticklabels). This is powered by the Formatter constructor function.

These keyword arguments can be used to apply built-in matplotlib Formatters by their “registered” names (e.g. xformatter=’log’), to apply a %-style format directive with FormatStrFormatter (e.g. xformatter=’%.0f’), or to apply custom tick labels with FixedFormatter (just like set_xticklabels and set_yticklabels). They can also be used to apply one of ProPlot’s new tick formatters – for example, xformatter=’deglat’ to label ticks as the geographic latitude, xformatter=’pi’ to label ticks as fractions of (\pi), or xformatter=’sci’ to label ticks with scientific notation. See format and Formatter for details.

ProPlot also changes the default tick formatter to AutoFormatter. This class trims trailing zeros by default, can be used to omit tick labels outside of some data range, and can add arbitrary prefixes and suffixes to each label. See AutoFormatter for details. To disable the trailing zero-trimming feature, set rc[‘formatter.zerotrim’] to False.

[2]:

import proplot as plotimport numpy as npplot.rc.update(    linewidth=1.2, fontsize=10, facecolor='gray0', figurefacecolor='gray2',    color='gray8', gridcolor='gray8', titlecolor='gray8', suptitlecolor='gray8',    titleloc='upper center', titleborder=False,)fig, axs = plot.subplots(nrows=9, axwidth=5, aspect=(8, 1), share=0)# Scientific notationaxs[0].format(xlim=(0, 1e20), xformatter='sci', title='SciFormatter')# N significant figures for ticks at specific valuesaxs[1].format(    xlim=(0, 20), xlocator=(0.0034, 3.233, 9.2, 15.2344, 7.2343, 19.58),    xformatter=('sigfig', 2), title='SigFigFormatter',  # 2 significant digits)# Fraction formattersaxs[2].format(    xlim=(0, 3 * np.pi), xlocator=np.pi / 4, xformatter='pi', title='FracFormatter',)axs[3].format(    xlim=(0, 2 * np.e), xlocator=np.e / 2, xticklabels='e', title='FracFormatter',)# Geographic formattersaxs[4].format(    xlim=(-90, 90), xlocator=30, xformatter='deglat', title='Latitude Formatter')axs[5].format(    xlim=(0, 360), xlocator=60, xformatter='deglon', title='Longitude Formatter')# User input labelsaxs[6].format(    xlim=(-1.01, 1), xlocator=0.5,    xticklabels=['a', 'b', 'c', 'd', 'e'], title='FixedFormatter',)# Custom style labelsaxs[7].format(    xlim=(0, 0.001), xlocator=0.0001, xformatter='%.E', title='FormatStrFormatter',)axs[8].format(    xlim=(0, 100), xtickminor=False, xlocator=20,    xformatter='{x:.1f}', title='StrMethodFormatter',)axs.format(ylocator='null', suptitle='Tick formatters demo')plot.rc.reset()

[3]:

import proplot as plotplot.rc.linewidth = 2plot.rc.fontsize = 11locator = [0, 0.25, 0.5, 0.75, 1]fig, axs = plot.subplots(ncols=2, nrows=2, axwidth=1.5, share=0)# Formatter comparisonaxs[0].format(    xformatter='scalar', yformatter='scalar', title='Matplotlib formatter')axs[1].format(yticklabelloc='both', title='ProPlot formatter')axs[:2].format(xlocator=locator, ylocator=locator)# Limiting the tick rangeaxs[2].format(    title='Omitting tick labels', ticklen=5, xlim=(0, 5), ylim=(0, 5),    xtickrange=(0, 2), ytickrange=(0, 2), xlocator=1, ylocator=1)# Setting the wrap rangeaxs[3].format(    title='Wrapping the tick range', ticklen=5, xlim=(0, 7), ylim=(0, 6),    xwraprange=(0, 5), ywraprange=(0, 3), xlocator=1, ylocator=1)axs.format(    ytickloc='both', yticklabelloc='both',    titlepad='0.5em', suptitle='Default formatters demo')plot.rc.reset()

Datetime ticks

ProPlot can also be used to customize the tick locations and tick label format of “datetime” axes. To draw ticks on some particular time unit, just use a unit string (e.g. xlocator=’month’). To draw ticks every N time units, just use a (unit, N) tuple (e.g. xlocator=(‘day’, 5)). For % style formatting of datetime tick labels, just use a string containing ‘%’ (e.g. xformatter=’%Y-%m-%d’). See format, Locator, and Formatter for details.

[4]:

import proplot as plotimport numpy as npplot.rc.update(    linewidth=1.2, fontsize=10, ticklenratio=0.7,    figurefacecolor='w', facecolor='pastel blue',    titleloc='upper center', titleborder=False,)fig, axs = plot.subplots(nrows=5, axwidth=6, aspect=(8, 1), share=0)axs[:4].format(xrotation=0)  # no rotation for these examples# Default date locator# This is enabled if you plot datetime data or set datetime limitsaxs[0].format(    xlim=(np.datetime64('2000-01-01'), np.datetime64('2001-01-02')),    title='Auto date locator and formatter')# Concise date formatter introduced in matplotlib 3.1axs[1].format(    xlim=(np.datetime64('2000-01-01'), np.datetime64('2001-01-01')),    xformatter='concise', title='Concise date formatter',)# Minor ticks every year, major every 10 yearsaxs[2].format(    xlim=(np.datetime64('2000-01-01'), np.datetime64('2050-01-01')),    xlocator=('year', 10), xformatter='\'%y', title='Ticks every N units',)# Minor ticks every 10 minutes, major every 2 minutesaxs[3].format(    xlim=(np.datetime64('2000-01-01T00:00:00'), np.datetime64('2000-01-01T12:00:00')),    xlocator=('hour', range(0, 24, 2)), xminorlocator=('minute', range(0, 60, 10)),    xformatter='T%H:%M:%S', title='Ticks at specific intervals',)# Month and year labels, with default tick label rotationaxs[4].format(    xlim=(np.datetime64('2000-01-01'), np.datetime64('2008-01-01')),    xlocator='year', xminorlocator='month',  # minor ticks every month    xformatter='%b %Y', title='Ticks with default rotation',)axs.format(    ylocator='null', suptitle='Datetime locators and formatters demo')plot.rc.reset()

Changing the axis scale

“Axis scales” like ‘linear’ and ‘log’ control the x and y axis coordinate system. To change the axis scale, simply pass e.g. xscale=’log’ or yscale=’log’ to format. This is powered by the Scale constructor function.

ProPlot also makes several changes to the axis scale API:

• By default, the AutoFormatter formatter is used for all axis scales instead of e.g. LogFormatter for LogScale scales. This can be changed e.g. by passing xformatter=’log’ or yformatter=’log’ to format.
• To make its behavior consistent with Locator and Formatter, the Scale constructor function returns instances of ScaleBase, and set_xscale and set_yscale now accept these class instances in addition to string names like ‘log’.
• While matplotlib axis scales must be instantiated with an Axis instance (for backward compatibility reasons), ProPlot axis scales can be instantiated without the axis instance (e.g. plot.LogScale() instead of plot.LogScale(ax.xaxis)).
• The default subs for the ‘symlog’ axis scale is now np.arange(1, 10), and the default linthresh is now 1. Also the ‘log’ and ‘symlog’ axis scales now accept the keywords base, linthresh, linscale, and subs rather than keywords with trailing x or y.

[5]:

import proplot as plotimport numpy as npN = 200lw = 3plot.rc.update({    'linewidth': 1, 'ticklabelweight': 'bold', 'axeslabelweight': 'bold'})fig, axs = plot.subplots(ncols=2, nrows=2, axwidth=1.8, share=0)axs.format(suptitle='Axis scales demo', ytickminor=True)# Linear and log scalesaxs[0].format(yscale='linear', ylabel='linear scale')axs[1].format(ylim=(1e-3, 1e3), yscale='log', ylabel='log scale')axs[:2].plot(np.linspace(0, 1, N), np.linspace(0, 1000, N), lw=lw)# Symlog scaleax = axs[2]ax.format(yscale='symlog', ylabel='symlog scale')ax.plot(np.linspace(0, 1, N), np.linspace(-1000, 1000, N), lw=lw)# Logit scaleax = axs[3]ax.format(yscale='logit', ylabel='logit scale')ax.plot(np.linspace(0, 1, N), np.linspace(0.01, 0.99, N), lw=lw)plot.rc.reset()

Special axis scales

ProPlot introduces several new axis scales. The ‘cutoff’ scale (see CutoffScale) is useful when the statistical distribution of your data is very unusual. The ‘sine’ scale (see SineLatitudeScale) scales the axis with a sine function, resulting in an area weighted spherical latitude coordinate, and the ‘mercator’ scale (see MercatorLatitudeScale) scales the axis with the Mercator projection latitude coordinate. The ‘inverse’ scale (see InverseScale) can be useful when working with spectral data, especially with “dual” unit axes.

[6]:

import proplot as plotimport numpy as npfig, axs = plot.subplots(width=6, nrows=4, aspect=(5, 1), sharex=False)ax = axs[0]# Sample datax = np.linspace(0, 4 * np.pi, 100)dy = np.linspace(-1, 1, 5)y1 = np.sin(x)y2 = np.cos(x)state = np.random.RandomState(51423)data = state.rand(len(dy) - 1, len(x) - 1)# Loop through various cutoff scale optionstitles = ('Zoom out of left', 'Zoom into left', 'Discrete jump', 'Fast jump')args = (    (np.pi, 3),  # speed up    (3 * np.pi, 1 / 3),  # slow down    (np.pi, np.inf, 3 * np.pi),  # discrete jump    (np.pi, 5, 3 * np.pi)  # fast jump)locators = (    np.pi / 3,    np.pi / 3,    np.pi * np.append(np.linspace(0, 1, 4), np.linspace(3, 4, 4)),    np.pi * np.append(np.linspace(0, 1, 4), np.linspace(3, 4, 4)),)for ax, iargs, title, locator in zip(axs, args, titles, locators):    ax.pcolormesh(x, dy, data, cmap='grays', cmap_kw={'right': 0.8})    for y, color in zip((y1, y2), ('coral', 'sky blue')):        ax.plot(x, y, lw=4, color=color)    ax.format(        xscale=('cutoff', *iargs), title=title,        xlim=(0, 4 * np.pi), ylabel='wave amplitude',        xformatter='pi', xlocator=locator,        xtickminor=False, xgrid=True, ygrid=False, suptitle='Cutoff axis scales demo'    )

[7]:

import proplot as plotimport numpy as npplot.rc.reset()fig, axs = plot.subplots(nrows=2, ncols=3, axwidth=1.7, share=0, order='F')axs.format(    collabels=('Power scales', 'Exponential scales', 'Cartographic scales'),    suptitle='Additional axis scales demo')x = np.linspace(0, 1, 50)y = 10 * xstate = np.random.RandomState(51423)data = state.rand(len(y) - 1, len(x) - 1)# Power scalescolors = ('coral', 'sky blue')for ax, power, color in zip(axs[:2], (2, 1 / 4), colors):    ax.pcolormesh(x, y, data, cmap='grays', cmap_kw={'right': 0.8})    ax.plot(x, y, lw=4, color=color)    ax.format(        ylim=(0.1, 10), yscale=('power', power),        title=f'$x^{{{power}}}$'    )# Exp scalesfor ax, a, c, color in zip(axs[2:4], (np.e, 2), (0.5, 2), colors):    ax.pcolormesh(x, y, data, cmap='grays', cmap_kw={'right': 0.8})    ax.plot(x, y, lw=4, color=color)    ax.format(        ylim=(0.1, 10), yscale=('exp', a, c),        title=f"${(a, 'e')[a == np.e]}^{{{(c, '')[c == 1]}x}}$"    )# Geographic scalesn = 20x = np.linspace(-180, 180, n)y1 = np.linspace(-85, 85, n)y2 = np.linspace(-85, 85, n)data = state.rand(len(x) - 1, len(y2) - 1)for ax, scale, color in zip(axs[4:], ('sine', 'mercator'), ('coral', 'sky blue')):    ax.plot(x, y1, '-', color=color, lw=4)    ax.pcolormesh(x, y2, data, cmap='grays', cmap_kw={'right': 0.8})    ax.format(        title=scale.title() + ' y-axis', yscale=scale, ytickloc='left',        yformatter='deg', grid=False, ylocator=20,        xscale='linear', xlim=None, ylim=(-85, 85)    )

Dual unit axes

The dualx and dualy methods can be used to draw duplicate x and y axes meant to represent alternate units in the same coordinate range as the “parent” axis. This feature is powered by the FuncScale class.

dualx and dualy accept either (1) a single linear forward function, (2) a pair of arbitrary forward and inverse functions, or (3) a scale name or scale class instance. In the latter case, the scale’s transforms are used for the forward and inverse functions, and the scale’s default locators and formatters are used for the default FuncScale locators and formatters.

In the below examples, we generate dual axes with each of these three methods. Note that the “parent” axis scale is now arbitrary – in the first example shown below, we create a dualx axis for an axis scaled by the symlog scale.

[8]:

import proplot as plotplot.rc.update({'grid.alpha': 0.4, 'linewidth': 1, 'grid.linewidth': 1})c1 = plot.scale_luminance('cerulean', 0.5)c2 = plot.scale_luminance('red', 0.5)fig, axs = plot.subplots(    [[1, 1, 2, 2], [0, 3, 3, 0]],    share=0, aspect=2.2, axwidth=3)axs.format(    suptitle='Duplicate axes with custom transformations',    xcolor=c1, gridcolor=c1,    ylocator=[], yformatter=[])# Meters and kilometersax = axs[0]ax.format(xlim=(0, 5000), xlabel='meters')ax.dualx(    lambda x: x * 1e-3,    label='kilometers', grid=True, color=c2, gridcolor=c2)# Kelvin and Celsiusax = axs[1]ax.format(xlim=(200, 300), xlabel='temperature (K)')ax.dualx(    lambda x: x - 273.15,    label='temperature (\N{DEGREE SIGN}C)', grid=True, color=c2, gridcolor=c2)# With symlog parentax = axs[2]ax.format(xlim=(-100, 100), xscale='symlog', xlabel='MegaJoules')ax.dualx(    lambda x: x * 1e6,    label='Joules', formatter='log', grid=True, color=c2, gridcolor=c2)plot.rc.reset()

[9]:

import proplot as plotplot.rc.update({'grid.alpha': 0.4, 'linewidth': 1, 'grid.linewidth': 1})c1 = plot.scale_luminance('cerulean', 0.5)c2 = plot.scale_luminance('red', 0.5)fig, axs = plot.subplots(ncols=2, share=0, aspect=0.4, axwidth=1.8)axs.format(suptitle='Duplicate axes with special transformations')# Pressure as the linear scale, height on opposite axis (scale height 7km)ax = axs[0]ax.format(    xformatter='null', ylabel='pressure (hPa)',    ylim=(1000, 10), xlocator=[], ycolor=c1, gridcolor=c1)ax.dualy(    'height', label='height (km)', ticks=2.5, color=c2, gridcolor=c2, grid=True)# Height as the linear scale, pressure on opposite axis (scale height 7km)ax = axs[1]  # spanax.format(    xformatter='null', ylabel='height (km)', ylim=(0, 20), xlocator='null',    grid=True, gridcolor=c2, ycolor=c2)ax.dualy(    'pressure', label='pressure (hPa)', locator=100, color=c1, gridcolor=c1, grid=True,)plot.rc.reset()

[10]:

import proplot as plotimport numpy as npplot.rc.margin = 0c1 = plot.scale_luminance('cerulean', 0.5)c2 = plot.scale_luminance('red', 0.5)fig, ax = plot.subplots(aspect=(3, 1), width=6)# Sample datacutoff = 1 / 5x = np.linspace(0.01, 0.5, 1000)  # in wavenumber daysresponse = (np.tanh(-((x - cutoff) / 0.03)) + 1) / 2  # response funcax.axvline(cutoff, lw=2, ls='-', color=c2)ax.fill_between([cutoff - 0.03, cutoff + 0.03], 0, 1, color=c2, alpha=0.3)ax.plot(x, response, color=c1, lw=2)# Add inverse scale to topax.format(    xlabel='wavenumber (days$^{-1}$)', ylabel='response', grid=False,    title='Imaginary response function',    suptitle='Duplicate axes with wavenumber and period',)ax = ax.dualx(    'inverse', locator='log', locator_kw={'subs': (1, 2, 5)}, label='period (days)')plot.rc.reset()