Configuring proplot

Overview

A special object named rc, belonging to the rc_configurator class, is created on import. This is your one-stop shop for changing global settings belonging to any of the following three categories:

  1. Builtin matplotlib rcParams settings. These have the format x.y or x.y.z.

  2. ProPlot rcParamsLong settings. These also have the format x.y (see below).

  3. ProPlot rcParamsShort settings. These have no dots (see below).

You can change settings with the rc object as follows:

  • plot.rc.name = value

  • plot.rc['name'] = value

  • plot.rc.update(name1=value1, name2=value2)

  • plot.rc.update({'name1':value1, 'name2':value2})

To temporarily change settings on a particular axes, use either of the following:

  • ax.format(name=value)

  • ax.format(rc_kw={'name':value})

In all of these examples, if the setting name name contains any dots, you can simply omit the dots. For example, to change the rc[‘title.loc’] property, use plot.rc.titleloc = value, plot.rc.update(titleloc=value), or ax.format(titleloc=value).

rcParamsShort

These are simple, short names used to change multiple matplotlib and ProPlot settings at once, as shorthands for settings with longer names, or for special options. For example, rc.ticklen changes the tick length for the x and y axes in one go.

Key

Description

abc

Boolean, whether to draw a-b-c labels by default.

align

Whether to align axis labels during draw. See aligning labels.

alpha

The opacity of the background axes patch.

autoreload

If not empty or 0, passed to %autoreload.

autosave

If not empty or 0, passed to %autosave.

borders

Boolean, toggles country border lines on and off.

cmap

The default colormap.

coast

Boolean, toggles coastline lines on and off.

color

The color of axis spines, tick marks, tick labels, and labels.

cycle

The default color cycle name, used e.g. for lines.

facecolor

The color of the background axes patch.

fontname

Name of font used for all text in the figure. The default is Helvetica Neue. See fonttools for details.

geogrid

Boolean, toggles meridian and parallel gridlines on and off.

grid

Boolean, toggles major grid lines on and off.

gridminor

Boolean, toggles minor grid lines on and off.

gridratio

Ratio of minor gridline width to major gridline width.

inlinefmt

The inline backend figure format or list thereof. Valid formats include 'svg', 'pdf', 'retina', 'png', and jpeg.

innerborders

Boolean, toggles internal border lines on and off, e.g. for states and provinces.

lakes

Boolean, toggles lake patches on and off.

land

Boolean, toggles land patches on and off.

large

Font size for titles, “super” titles, and a-b-c subplot labels.

linewidth

Thickness of axes spines and major tick lines.

lut

The number of colors to put in the colormap lookup table.

margin

The margin of space between axes edges and objects plotted inside the axes, if xlim and ylim are unset.

matplotlib

If not empty, passed to %matplotlib. If 'auto' (the default) uses 'inline' for notebooks and 'osx' or 'qt' for other ipython sessions.

ocean

Boolean, toggles ocean patches on and off.

reso

Resolution of geographic features, one of 'lo', 'med', or 'hi'

rgbcycle

If True, and colorblind is the current cycle, this registers the colorblind colors as 'r', 'b', 'g', etc., like in seaborn.

rivers

Boolean, toggles river lines on and off.

share

The axis sharing level, one of 0, 1, 2, or 3. See subplots for details.

small

Font size for legend text, tick labels, axis labels, and text generated with text.

span

Boolean, toggles spanning axis labels. See subplots for details.

tickdir

Major and minor tick direction. Must be one of out, in, or inout.

ticklen

Length of major ticks in points.

ticklenratio

Ratio of minor tickline length to major tickline length.

tickpad

Padding between ticks and tick labels in points.

titlepad

Padding between the axes and the title, alias for rc[‘axes.titlepad’].

tickratio

Ratio of minor tickline width to major tickline width.

tight

Boolean, indicates whether to auto-adjust figure bounds and subplot spacings.

rcParamsLong

These are longer, specific setting names used to customize things not covered by rcParams.

The subplots category controls the default layout for figures and axes. The abc, title, and tick categories control a-b-c label, title, and axis tick label settings. The suptitle, leftlabel, toplabel, rightlabel, and bottomlabel categories control figure title and edge label settings.

There are two new additions to the image category, and the new colorbar category controls inset and outer colorbar properties. The new gridminor category controls minor gridline settings, and the new geogrid category controls meridian and parallel line settings for ProjAxes. Note that when a grid property is changed, it also changed the corresponding gridminor property.

Finally, the geoaxes, land, ocean, rivers, lakes, borders, and innerborders categories control various ProjAxes settings. These are used when the boolean toggles for the corresponding rcParamsShort settings are turned on.

Key(s)

Description

abc.style

a-b-c label style. For options, see format.

abc.loc

a-b-c label position. For options, see format.

abc.border

Boolean, indicates whether to draw a white border around a-b-c labels inside an axes.

abc.linewidth

Width of the white border around a-b-c labels.

abc.color

a-b-c label color.

abc.size

a-b-c label font size.

abc.weight

a-b-c label font weight.

axes.formatter.zerotrim

Boolean, indicates whether trailing decimal zeros are trimmed on tick labels.

axes.formatter.timerotation

Float, indicates the default x axis tick label rotation for datetime tick labels.

borders.color

Line color for country borders.

borders.linewidth

Line width for country borders.

bottomlabel.color

Font color for column labels on the bottom of the figure.

bottomlabel.size

Font size for column labels on the bottom of the figure.

bottomlabel.weight

Font weight for column labels on the bottom of the figure.

colorbar.loc

Inset colorbar location, options are listed in colorbar.

colorbar.grid

Boolean, indicates whether to draw borders between each level of the colorbar.

colorbar.frameon

Boolean, indicates whether to draw a frame behind inset colorbars.

colorbar.framealpha

Opacity for inset colorbar frames.

colorbar.length

Length of outer colorbars.

colorbar.insetlength

Length of inset colorbars. Units are interpreted by units.

colorbar.width

Width of outer colorbars. Units are interpreted by units.

colorbar.insetwidth

Width of inset colorbars. Units are interpreted by units.

colorbar.axespad

Padding between axes edge and inset colorbars. Units are interpreted by units.

colorbar.extend

Length of rectangular or triangular “extensions” for panel colorbars. Units are interpreted by units.

colorbar.insetextend

Length of rectangular or triangular “extensions” for inset colorbars. Units are interpreted by units.

geoaxes.facecolor

Face color for the map outline patch.

geoaxes.edgecolor

Edge color for the map outline patch.

geoaxes.linewidth

Edge width for the map outline patch.

geogrid.labels

Boolean, indicates whether to label the parallels and meridians.

geogrid.labelsize

Font size for latitude and longitude labels. Inherits from small.

geogrid.latmax

Absolute latitude in degrees, poleward of which meridian gridlines are cut off.

geogrid.lonstep

Default interval for meridian gridlines in degrees.

geogrid.latstep

Default interval for parallel gridlines in degrees.

gridminor.linewidth

Minor gridline width.

gridminor.linestyle

Minor gridline style.

gridminor.alpha

Minor gridline transparency.

gridminor.color

Minor gridline color.

image.levels

Default number of levels for pcolormesh and contourf plots.

image.edgefix

Whether to fix the white-lines-between-filled-contours and white-lines-between-pcolor-rectangles issues. This slows down figure rendering a bit.

innerborders.color

Line color for internal border lines.

innerborders.linewidth

Line width for internal border lines.

land.color

Face color for land patches.

lakes.color

Face color for lake patches.

leftlabel.color

Font color for row labels on the left-hand side.

leftlabel.size

Font size for row labels on the left-hand side.

leftlabel.weight

Font weight for row labels on the left-hand side.

ocean.color

Face color for ocean patches.

rightlabel.color

Font color for row labels on the right-hand side.

rightlabel.size

Font size for row labels on the right-hand side.

rightlabel.weight

Font weight for row labels on the right-hand side.

rivers.color

Line color for river lines.

rivers.linewidth

Line width for river lines.

subplots.axwidth

Default width of each axes. Units are interpreted by units.

subplots.panelwidth

Width of side panels. Units are interpreted by units.

subplots.pad

Padding around figure edge. Units are interpreted by units.

subplots.axpad

Padding between adjacent subplots. Units are interpreted by units.

subplots.panelpad

Padding between subplots and panels, and between stacked panels. Units are interpreted by units.

suptitle.color

Figure title color.

suptitle.size

Figure title font size.

suptitle.weight

Figure title font weight.

tick.color

Axis tick label color. Mirrors the axis label rc[‘axes.labelcolor’] setting.

tick.size

Axis tick label font size. Mirrors the axis label rc[‘axes.labelsize’] setting.

tick.weight

Axis tick label font weight. Mirrors the axis label rc[‘axes.labelweight’] setting.

title.loc

Title position. For options, see format.

title.border

Boolean, indicates whether to draw a white border around titles inside an axes.

title.linewidth

Width of the white border around titles.

title.pad

The title offset in arbitrary units. Alias for rc[‘axes.titlepad’].

title.color

Axes title color.

title.size

Axes title font size.

title.weight

Axes title font weight.

toplabel.color

Font color for column labels on the top of the figure.

toplabel.size

Font size for column labels on the top of the figure.

toplabel.weight

Font weight for column labels on the top of the figure.

The .proplotrc file

To modify the global settings, edit your ~/.proplotrc file. To modify settings for a particular project, create a .proplotrc file in the same directory as your ipython notebook, or in an arbitrary parent directory. As an example, a .proplotrc file containing the default settings is shown below. The syntax is mostly the same as the syntax used for matplotlibrc files.

#---------------------------------------------------------------------
# Use this file to change the default proplot and matplotlib settings
# The syntax is mostly the same as for matplotlibrc files
# For descriptions of each setting see:
# https://proplot.readthedocs.io/en/latest/rctools.html
# https://matplotlib.org/3.1.1/tutorials/introductory/customizing.html
#---------------------------------------------------------------------
# ProPlot short name settings
abc:          False
align:        False
alpha:        1
autoreload:   2
autosave:     30
borders:      False
cmap:         fire
coast:        False
color:        k
cycle:        colorblind
facecolor:    w
fontname:     sans-serif
inlinefmt:    retina
geogrid:      True
grid:         True
gridminor:    False
gridratio:    0.5
innerborders: False
lakes:        False
land:         False
large:        10
linewidth:    0.6
lut:          256
margin:       0.0
matplotlib:   auto
ocean:        False
reso:         lo
rgbcycle:     False
rivers:       False
share:        3
small:        9
span:         True
tickdir:      out
ticklen:      4.0
ticklenratio: 0.5
tickminor:    True
tickpad:      2.0
tickratio:    0.8
tight:        True

# ProPlot long name settings
abc.border:                  True
abc.color:                   k
abc.linewidth:               1.5
abc.loc:                     l
abc.size:                    large
abc.style:                   a
abc.weight:                  bold
axes.facealpha:              alpha
axes.formatter.timerotation: 90
axes.formatter.zerotrim:     True
axes.geogrid:                True
axes.gridminor:              True
borders.color:               k
borders.linewidth:           0.6
bottomlabel.color:           k
bottomlabel.size:            large
bottomlabel.weight:          bold
coast.color:                 k
coast.linewidth:             0.6
colorbar.extend:             1.3em
colorbar.framealpha:         0.8
colorbar.frameon:            True
colorbar.grid:               False
colorbar.insetextend:        1em
colorbar.insetlength:        8em
colorbar.insetpad:           0.5em
colorbar.insetwidth:         1.2em
colorbar.length:             1
colorbar.loc:                right
colorbar.width:              1.5em
geoaxes.edgecolor:           color
geoaxes.facealpha:           alpha
geoaxes.facecolor:           facecolor
geoaxes.linewidth:           linewidth
geogrid.alpha:               0.5
geogrid.color:               k
geogrid.labels:              False
geogrid.labelsize:           small
geogrid.latmax:              90
geogrid.latstep:             20
geogrid.linestyle:           :
geogrid.linewidth:           1.0
geogrid.lonstep:             30
gridminor.alpha:             grid.alpha
gridminor.color:             grid.color
gridminor.linestyle:         grid.linestyle
gridminor.linewidth:         grid.linewidth
image.edgefix:               True
image.levels:                11
innerborders.color:          k
innerborders.linewidth:      0.6
lakes.color:                 w
land.color:                  k
leftlabel.color:             k
leftlabel.size:              large
leftlabel.weight:            bold
ocean.color:                 w
rightlabel.color:            k
rightlabel.size:             large
rightlabel.weight:           bold
rivers.color:                k
rivers.linewidth:            0.6
subplots.axpad:              1em
subplots.axwidth:            18em
subplots.pad:                0.5em
subplots.panelpad:           0.5em
subplots.panelwidth:         4em
suptitle.color:              k
suptitle.size:               large
suptitle.weight:             bold
tick.labelcolor:             color
tick.labelsize:              small
tick.labelweight:            normal
title.border:                True
title.color:                 k
title.linewidth:             1.5
title.loc:                   c
title.pad:                   3.0
title.size:                  large
title.weight:                normal
toplabel.color:              k
toplabel.size:               large
toplabel.weight:             bold

# Matplotlib settings
axes.grid:               True
axes.labelpad:           3.0
axes.titlepad:           3.0
axes.titleweight:        normal
axes.xmargin:            0.0
axes.ymargin:            0.0
figure.autolayout:       False
figure.facecolor:        #f2f2f2
figure.max_open_warning: 0
figure.titleweight:      bold
font.serif:              New Century Schoolbook, Century Schoolbook L, Utopia, ITC Bookman, Bookman, Nimbus Roman No9 L, Times New Roman, Times, Palatino, Charter, Computer Modern Roman, DejaVu Serif, Bitstream Vera Serif, serif
font.sans-serif:         Helvetica, Arial, Lucida Grande, Verdana, Geneva, Lucid, Avant Garde, TeX Gyre Heros, DejaVu Sans, Bitstream Vera Sans, Computer Modern Sans Serif, sans-serif
font.monospace:          Andale Mono, Nimbus Mono L, Courier New, Courier, Fixed, Terminal, Computer Modern Typewriter, DejaVu Sans Mono, Bitstream Vera Sans Mono, monospace
grid.alpha:              0.1
grid.color:              k
grid.linestyle:          -
grid.linewidth:          0.6
hatch.color:             k
hatch.linewidth:         0.6
legend.borderaxespad:    0
legend.borderpad:        0.5
legend.columnspacing:    1.0
legend.fancybox:         False
legend.framealpha:       0.8
legend.frameon:          True
legend.handlelength:     1.5
legend.handletextpad:    0.5
legend.labelspacing:     0.5
lines.linewidth:         1.3
lines.markersize:        3.0
mathtext.fontset:        custom
mathtext.default:        regular
savefig.bbox:            standard
savefig.directory:       
savefig.dpi:             300
savefig.facecolor:       white
savefig.format:          pdf
savefig.pad_inches:      0.0
savefig.transparent:     True
text.usetex:             False
xtick.minor.visible:     True
ytick.minor.visible:     True