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:

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

To apply settings to a particular axes, pass the setting to the format command:

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

To temporarily modify settings for particular figure(s), pass the setting to the context command:

import proplot as pplt
with pplt.rc.context(name1=value1, name2=value2):
    fig, ax = pplt.subplots()
with pplt.rc.context({'name1': value1, 'name2': value2}):
    fig, ax = pplt.subplots()

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 pplt
# Apply globally
pplt.rc.titleloc = value
pplt.rc.update(titleloc=value)
# Apply locally
fig, ax = pplt.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.bbox	Boolean, whether to draw semi-transparent bounding boxes around a-b-c labels when rc[‘abc.loc’] is inside the axes.
abc.bboxcolor	a-b-c label bounding box color.
abc.bboxstyle	a-b-c label bounding box style.
abc.bboxalpha	a-b-c label bounding box opacity.
abc.bboxpad	Padding for the a-b-c label bounding box. By default this is scaled to make the box flush against the subplot edge. Interpreted by units.
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.titlepad	Padding used to displace the title and the a-b-c label when they are in the same location.
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.
axes.titleabove	Boolean, indicates whether to move the title and a-b-c labels above any “top” panels above axes.
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’].
basemap	Boolean, toggles whether basemap is the default backend.
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.
bottomlabel.pad	Padding between axes content and column labels on the bottom of the figure. Interpreted by units.
cartopy.autoextent	If False (the default), cartopy projection extents are global by default and no longer automatically adjusted based on plotted content.
cartopy.circular	If True (the default), polar cartopy projections like 'npstere' and 'spstere' are bounded with circles rather than squares.
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. Interpreted 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. Interpreted by units.
colorbar.insetlength	Length of inset colorbars. Interpreted by units.
colorbar.insetpad	Padding between axes edge and inset colorbars. Interpreted by units.
colorbar.insetwidth	Width of inset colorbars. Interpreted 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. Interpreted 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 between map boundary edge and longitude and latitude labels for GeoAxes. Interpreted by units.
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.discrete	If True, DiscreteNorm is used for every colormap plot. If False, it is never used. If None, it is used for all plot types except imshow, matshow, spy, hexbin, and hist2d.
image.edgefix	Whether to fix the white-lines-between-filled-contours and white-lines-between-pcolor-rectangles issues.
image.inbounds	If True and the x and y axis limits have been explicitly set, only in-bounds data is considered when determining default colormap limits.
image.levels	Default number of DiscreteNorm levels for plotting commands that use colormaps.
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.
leftlabel.pad	Padding between axes content and row labels on the left-hand side. Interpreted by units.
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.
rightlabel.pad	Padding between axes content and row labels on the right-hand side. Interpreted by units.
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.innerpad	Padding between adjacent subplots. Interpreted by units.
subplots.outerpad	Padding around figure edge. Interpreted by units.
subplots.panelpad	Padding between subplots and panels, and between stacked panels. Interpreted by units.
subplots.panelwidth	Width of side panels. Interpreted by units.
subplots.refwidth	Default width of the reference subplot. Interpreted 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.
suptitle.pad	Padding between axes content and the figure super title. Interpreted by units.
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. Interpreted by units.
tick.ratio	Ratio of minor tickline width to major tickline width.
title.above	Boolean, indicates whether to move outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes.
title.pad	Padding between the axes edge and the inner and outer titles and a-b-c labels. Alias for rc[‘axes.titlepad’]. Interpreted by units.
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 border around titles.
title.bbox	Boolean, whether to draw semi-transparent bounding boxes around titles when rc[‘title.loc’] is inside the axes.
title.bboxcolor	Axes title bounding box color.
title.bboxstyle	Axes title bounding box style.
title.bboxalpha	Axes title bounding box opacity.
title.bboxpad	Padding for the title bounding box. By default this is scaled to make the box flush against the axes edge. Interpreted by units.
title.color	Axes title color.
title.loc	Title position. For options, see the title location table.
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.
toplabel.pad	Padding between axes content and column labels on the top of the figure. Interpreted by units.

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 file named either .proplotrc or proplotrc in the same directory as your python scripts or jupyter sessions, 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/stable/tutorials/introductory/customizing.html
#--------------------------------------------------------------------
# ProPlot settings
style:                      None
abc:                        False
abc.border:                 True
abc.borderwidth:            1.5
abc.bbox:                   False
abc.bboxcolor:              w
abc.bboxstyle:              square
abc.bboxalpha:              0.5
abc.bboxpad:                None
abc.color:                  black
abc.loc:                    l
abc.size:                   med-large
abc.style:                  a
abc.titlepad:               0.5em
abc.weight:                 bold
autoformat:                 True
alpha:                      1.0
axes.alpha:                 1.0
axes.titleabove:            True
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
basemap:                    False
borders:                    False
borders.color:              black
borders.linewidth:          0.6
borders.zorder:             2
bottomlabel.color:          black
bottomlabel.size:           med-large
bottomlabel.weight:         bold
bottomlabel.pad:            0.3em
cartopy.autoextent:         False
cartopy.circular:           True
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.7em
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.discrete:             None
image.edgefix:              True
image.inbounds:             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
leftlabel.pad:              0.6em
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
rightlabel.pad:             0.6em
rivers:                     False
rivers.color:               black
rivers.linewidth:           0.6
rivers.zorder:              2
subplots.align:             False
subplots.innerpad:          1em
subplots.outerpad:          0.5em
subplots.panelpad:          0.5em
subplots.panelwidth:        4em
subplots.refwidth:          20em
subplots.share:             3
subplots.span:              True
subplots.tight:             True
suptitle.color:             black
suptitle.size:              med-large
suptitle.weight:            bold
suptitle.pad:               0.5em
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.above:                True
title.pad:                  5.0
title.border:               True
title.borderwidth:          1.5
title.bbox:                 False
title.bboxcolor:            w
title.bboxstyle:            square
title.bboxalpha:            0.5
title.bboxpad:              None
title.color:                black
title.loc:                  c
title.size:                 med-large
title.weight:               normal
toplabel.color:             black
toplabel.size:              med-large
toplabel.weight:            bold
toplabel.pad:               0.3em

# 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:                 1000
savefig.facecolor:           white
savefig.format:              pdf
savefig.transparent:         False
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