Configuring ProPlot

Overview

A special object named rc, belonging to the RcConfigurator class, is created on import. This is your one-stop shop for working with builtin matplotlib global settings and the global settings added by proplot. Global settings can be changed on-the-fly using the rc object as follows:

import proplot as plot
plot.rc.name = value
plot.rc['name'] = value
plot.rc.update(name1=value1, name2=value2)
plot.rc.update({'name1': value1, 'name2': value2})

To apply settings to a particular axes, pass the setting to the format command using either of the following approaches:

import proplot as plot
fig, ax = plot.subplots()
ax.format(name1=value1, name2=value2)
ax.format(rc_kw={'name1': value1, 'name2': value2})

In all of these examples, if the setting name contains dots, you can simply omit the dots. For example, to change the rc[‘title.loc’] property, the following approaches are valid:

import proplot as plot
# Apply globally
plot.rc.titleloc = value
plot.rc.update(titleloc=value)
# Apply locally
fig, ax = plot.subplots()
ax.format(titleloc=value)

Matplotlib settings

Details on the matplotlib settings can be found on this page.

ProPlot settings

ProPlot adds several settings to customize things not covered by matplotlib’s builtin settings. Some of these settings may be more accurately described as “meta-settings”, as they change several matplotlib settings at once (for example, rc.linewidth changes axes edge widths, gridline widths, and tick widths). Other settings are for specific features controlled by ProPlot, like a-b-c labels.

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. There is also a new gridminor category for minor gridline settings (note that gridminor inherits grid properties when they are changed). Finally, the land, ocean, rivers, lakes, borders, and innerborders categories control various GeoAxes settings.

Key

Description

style

The default matplotlib stylesheet name. If None, a custom proplot style is used. If 'default', the default matplotlib style is used.

abc

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

abc.border

Boolean, indicates whether to draw a white border around a-b-c labels when rc[‘abc.loc’] is inside the axes.

abc.borderwidth

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

abc.color

a-b-c label color.

abc.loc

a-b-c label position. For options, see the title location table.

abc.size

a-b-c label font size.

abc.style

a-b-c label style. Must be string containing the character a or A, for example 'a.' or '(A)'.

abc.weight

a-b-c label font weight.

autoformat

Whether to automatically apply labels from pandas.Series, pandas.DataFrame, and xarray.DataArray objects passed to plotting functions.

alpha

The opacity of the background axes patch.

axes.alpha

The opacity of the background axes patch.

formatter.timerotation

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

formatter.zerotrim

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

formatter.limits

Alias for rc[‘axes.formatter.limits’].

formatter.use_locale

Alias for rc[‘axes.formatter.use_locale’].

formatter.use_mathtext

Alias for rc[‘axes.formatter.use_mathtext’].

formatter.min_exponent

Alias for rc[‘axes.formatter.min_exponent’].

formatter.use_offset

Alias for rc[‘axes.formatter.useOffset’].

formatter.offset_threshold

Alias for rc[‘axes.formatter.offset_threshold’].

borders

Boolean, toggles country border lines on and off.

borders.color

Line color for country borders.

borders.linewidth

Line width for country borders.

borders.zorder

Z-order for country border lines.

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.

cartopy.autoextent

If False (the default), the projection extent is no longer automatically adjusted based on plotted content. See the user guide for details.

coast

Boolean, toggles coastline lines on and off.

coast.color

Line color for coast lines.

coast.linewidth

Line width for coast lines.

colorbar.extend

Length of rectangular or triangular “extensions” for panel colorbars. Interpted by units.

colorbar.framealpha

Opacity for inset colorbar frames.

colorbar.frameon

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

colorbar.grid

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

colorbar.insetextend

Length of rectangular or triangular “extensions” for inset colorbars. Interpted by units.

colorbar.insetlength

Length of inset colorbars. Interpted by units.

colorbar.insetpad

Padding between axes edge and inset colorbars.

colorbar.insetwidth

Width of inset colorbars. Interpted by units.

colorbar.length

Length of outer colorbars.

colorbar.loc

Inset colorbar location. For options, see the location table.

colorbar.width

Width of outer colorbars. Interpted by units.

cmap

The default sequential colormap.

color

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

cycle

The name of the color cycle used for plot elements like lines.

facecolor

The color of the background axes patch.

font.name

Alias for rc[‘font.family’]. The default is 'sans-serif'.

grid

Boolean, toggles major grid lines on and off.

grid.below

Alias for rc[‘axes.axisbelow’]. If False, draw gridlines on top of everything. If True, underneath everything. If 'line', underneath patches only.

grid.dmslabels

Boolean, indicates whether to use degrees-minutes-seconds rather than decimals for gridline labels on CartopyAxes.

grid.pad

Padding in points between map boundary edge and longitude and latitude labels for GeoAxes.

grid.labels

Boolean, indicates whether to label the longitude and latitude gridlines in GeoAxes.

grid.labelsize

Font size for longitude and latitude gridline labels in GeoAxes.

grid.labelweight

Font weight for longitude and latitude gridline labels in GeoAxes.

grid.labelcolor

Font color for longitude and latitude gridline labels in GeoAxes.

grid.latinline

Whether to use inline labels for CartopyAxes latitude gridlines.

grid.loninline

Whether to use inline labels for CartopyAxes longitude gridlines.

grid.nsteps

Number of interpolation steps used to draw cartopy gridlines.

grid.ratio

Ratio of minor gridline width to major gridline width.

grid.rotatelabels

Boolean, indicates whether to rotate longitude and latitude CartopyAxes gridline labels.

gridminor

Boolean, toggles minor grid lines on and off.

gridminor.alpha

Minor gridline transparency.

gridminor.color

Minor gridline color.

gridminor.latstep

Latitude gridline interval for GeoAxes with global extent.

gridminor.linestyle

Minor gridline style.

gridminor.linewidth

Minor gridline width.

gridminor.lonstep

Interval for GeoAxes longitude gridlines in degrees.

image.edgefix

Whether to fix the white-lines-between-filled-contours and white-lines-between-pcolor-rectangles issues.

image.levels

Default number of levels for pcolormesh and contourf plots.

inlinefmt

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

innerborders

Boolean, toggles internal political border lines (e.g. states and provinces) on and off.

innerborders.color

Line color for internal political borders.

innerborders.linewidth

Line width for internal political borders.

innerborders.zorder

Z-order for internal border lines.

lakes

Boolean, toggles lake patches on and off.

lakes.color

Face color for lake patches.

lakes.zorder

Z-order for lake patches.

land

Boolean, toggles land patches on and off.

land.color

Face color for land patches.

land.zorder

Z-order for land 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.

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.

negcolor

The color for negative bars and shaded areas when using negpos=True. See also rc.poscolor.

poscolor

The color for positive bars and shaded areas when using negpos=True. See also rc.negcolor.

ocean

Boolean, toggles ocean patches on and off.

ocean.color

Face color for ocean patches.

ocean.zorder

Z-order for ocean patches.

reso

Resolution for GeoAxes geographic features. Must be one of 'lo', 'med', 'hi', 'x-hi', or 'xx-hi'.

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

Boolean, toggles river lines on and off.

rivers.color

Line color for river lines.

rivers.linewidth

Line width for river lines.

rivers.zorder

Z-order for river lines.

subplots.align

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

subplots.axpad

Padding between adjacent subplots. Interpted by units.

subplots.axwidth

Default width of each axes. Interpted by units.

subplots.pad

Padding around figure edge. Interpted by units.

subplots.panelpad

Padding between subplots and panels, and between stacked panels. Interpted by units.

subplots.panelwidth

Width of side panels. Interpted by units.

subplots.share

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

subplots.span

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

subplots.tight

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

suptitle.color

Figure title color.

suptitle.size

Figure title font size.

suptitle.weight

Figure title font weight.

text.labelsize

Meta setting that changes the label-like sizes tick.labelsize, axes.labelsize, legend.fontsize, and grid.labelsize. Default is 'medium', i.e. the value of rc[‘font.size’] (see this list of valid font sizes).

text.titlesize

Meta setting that changes the title-like sizes abc.size, title.size, suptitle.size, and row and column label sizes like leftlabel.size. Default is 'med-large', i.e. 1.1 times rc[‘font.size’] (see this list of valid font sizes).

tick.color

Major and minor tick color.

tick.dir

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

tick.labelcolor

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

tick.labelsize

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

tick.labelweight

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

tick.len

Length of major ticks in points.

tick.lenratio

Ratio of minor tickline length to major tickline length.

tick.minor

Boolean, toggles minor ticks on and off.

tick.pad

Padding between ticks and tick labels in points.

tick.ratio

Ratio of minor tickline width to major tickline width.

title.border

Boolean, indicates whether to draw a white border around titles when rc[‘title.loc’] is inside the axes.

title.borderwidth

Width of the white border around titles.

title.color

Axes title color.

title.loc

Title position. For options, see the title location table.

title.pad

Padding between axes and outer titles or a-b-c labels in arbitrary units. Alias for rc[‘axes.titlepad’].

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

When you install ProPlot for the first time, a .proplotrc file is generated and placed in your home directory. This is just like the matplotlibrc file, but for changing both ProPlot and matplotlib settings. The syntax is basically the same as the matplotlibrc syntax.

To change the default global settings, simply edit and uncomment the entries listed in this file. You can also change the settings for individual projects by placing a .proplotrc file in the same directory as your python scripts or jupyter notebooks, or in an arbitrary parent directory. As an example, a .proplotrc file containing the default settings is shown below.

#--------------------------------------------------------------------
# Use this file to change the default proplot and matplotlib settings
# The syntax is identical to matplotlibrc syntax. For details see:
# https://proplot.readthedocs.io/en/latest/configuration.html
# https://matplotlib.org/3.1.1/tutorials/introductory/customizing
#--------------------------------------------------------------------
# ProPlot settings
style:                      None
abc:                        False
abc.border:                 True
abc.borderwidth:            1.5
abc.color:                  black
abc.loc:                    l
abc.size:                   med-large
abc.style:                  a
abc.weight:                 bold
autoformat:                 True
alpha:                      1.0
axes.alpha:                 1.0
formatter.timerotation:     90
formatter.zerotrim:         True
formatter.limits:           -5, 6
formatter.use_locale:       False
formatter.use_mathtext:     False
formatter.min_exponent:     0
formatter.use_offset:       True
formatter.offset_threshold: 4
borders:                    False
borders.color:              black
borders.linewidth:          0.6
borders.zorder:             2
bottomlabel.color:          black
bottomlabel.size:           med-large
bottomlabel.weight:         bold
cartopy.autoextent:         False
coast:                      False
coast.color:                black
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
cmap:                       fire
color:                      black
cycle:                      colorblind
facecolor:                  white
font.name:                  sans-serif
grid:                       True
grid.below:                 line
grid.dmslabels:             True
grid.pad:                   5
grid.labels:                False
grid.labelsize:             medium
grid.labelweight:           normal
grid.labelcolor:            black
grid.latinline:             False
grid.loninline:             False
grid.nsteps:                250
grid.ratio:                 0.5
grid.rotatelabels:          False
gridminor:                  False
gridminor.alpha:            0.11
gridminor.color:            black
gridminor.latstep:          10
gridminor.linestyle:        -
gridminor.linewidth:        0.3
gridminor.lonstep:          20
image.edgefix:              True
image.levels:               11
inlinefmt:                  retina
innerborders:               False
innerborders.color:         black
innerborders.linewidth:     0.6
innerborders.zorder:        2
lakes:                      False
lakes.color:                w
lakes.zorder:               1
land:                       False
land.color:                 black
land.zorder:                1
leftlabel.color:            black
leftlabel.size:             med-large
leftlabel.weight:           bold
linewidth:                  0.6
lut:                        256
margin:                     0.05
negcolor:                   blue7
poscolor:                   red7
ocean:                      False
ocean.color:                w
ocean.zorder:               1
reso:                       lo
rightlabel.color:           black
rightlabel.size:            med-large
rightlabel.weight:          bold
rivers:                     False
rivers.color:               black
rivers.linewidth:           0.6
rivers.zorder:              2
subplots.align:             False
subplots.axpad:             1em
subplots.axwidth:           20em
subplots.pad:               0.5em
subplots.panelpad:          0.5em
subplots.panelwidth:        4em
subplots.share:             3
subplots.span:              True
subplots.tight:             True
suptitle.color:             black
suptitle.size:              med-large
suptitle.weight:            bold
text.labelsize:             medium
text.titlesize:             med-large
tick.color:                 black
tick.dir:                   out
tick.labelcolor:            black
tick.labelsize:             medium
tick.labelweight:           normal
tick.len:                   4.0
tick.lenratio:              0.5
tick.minor:                 True
tick.pad:                   2.0
tick.ratio:                 0.8
title.border:               True
title.borderwidth:          1.5
title.color:                black
title.loc:                  c
title.pad:                  5.0
title.size:                 med-large
title.weight:               normal
toplabel.color:             black
toplabel.size:              med-large
toplabel.weight:            bold

# Matplotlib settings
axes.axisbelow:              line
axes.formatter.use_mathtext: False
axes.grid:                   True
axes.grid.which:             major
axes.labelpad:               4.0
axes.labelsize:              medium
axes.labelweight:            normal
axes.linewidth:              0.6
axes.titlepad:               5.0
axes.titlesize:              med-large
axes.titleweight:            normal
axes.xmargin:                0.05
axes.ymargin:                0.05
figure.autolayout:           False
figure.dpi:                  100
figure.facecolor:            '#f2f2f2'
figure.titlesize:            med-large
figure.titleweight:          bold
font.serif:                  TeX Gyre Schola, TeX Gyre Bonum, TeX Gyre Termes, TeX Gyre Pagella, DejaVu Serif, Bitstream Vera Serif, Computer Modern Roman, Bookman, Century Schoolbook L, Charter, ITC Bookman, New Century Schoolbook, Nimbus Roman No9 L, Palatino, Times New Roman, Times, Utopia, serif
font.sans-serif:             TeX Gyre Heros, DejaVu Sans, Bitstream Vera Sans, Computer Modern Sans Serif, Arial, Avenir, Fira Math, Frutiger, Geneva, Gill Sans, Helvetica, Lucid, Lucida Grande, Myriad Pro, Noto Sans, Roboto, Source Sans Pro, Tahoma, Trebuchet MS, Ubuntu, Univers, Verdana, sans-serif
font.monospace:              TeX Gyre Cursor, DejaVu Sans Mono, Bitstream Vera Sans Mono, Computer Modern Typewriter, Andale Mono, Courier New, Courier, Fixed, Nimbus Mono L, Terminal, monospace
font.cursive:                TeX Gyre Chorus, Apple Chancery, Felipa, Sand, Script MT, Textile, Zapf Chancery, cursive
font.fantasy:                TeX Gyre Adventor, Avant Garde, Charcoal, Chicago, Comic Sans MS, Futura, Humor Sans, Impact, Optima, Western, xkcd, fantasy
font.size:                   9.0
grid.alpha:                  0.11
grid.color:                  black
grid.linestyle:              -
grid.linewidth:              0.6
hatch.color:                 black
hatch.linewidth:             0.6
image.cmap:                  fire
lines.linestyle:             -
lines.linewidth:             1.5
lines.markersize:            6.0
legend.borderaxespad:        0
legend.borderpad:            0.5
legend.columnspacing:        1.5
legend.fancybox:             False
legend.fontsize:             medium
legend.framealpha:           0.8
legend.handletextpad:        0.5
mathtext.fontset:            custom
mathtext.default:            regular
patch.linewidth:             0.6
savefig.bbox:                None
savefig.directory:           
savefig.dpi:                 1200
savefig.facecolor:           white
savefig.format:              pdf
savefig.transparent:         True
xtick.direction:             out
xtick.labelsize:             medium
xtick.major.pad:             2.0
xtick.major.size:            4.0
xtick.major.width:           0.6
xtick.minor.pad:             2.0
xtick.minor.size:            2.0
xtick.minor.visible:         True
xtick.minor.width:           0.48
ytick.direction:             out
ytick.labelsize:             medium
ytick.major.pad:             2.0
ytick.major.size:            4.0
ytick.major.width:           0.6
ytick.minor.pad:             2.0
ytick.minor.size:            2.0
ytick.minor.width:           0.48
ytick.minor.visible:         True