Configuring proplot¶
Overview¶
A dictionary-like object named rc
, belonging to the
Configurator
class, is created when you import proplot.
This is your one-stop shop for working with
matplotlib settings
stored in rc_matplotlib
(our name for the rcParams
dictionary)
and proplot settings
stored in rc_proplot
.
To change global settings on-the-fly, simply update rc
using either dot notation or as you would any other dictionary:
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 or figure, pass the setting
to proplot.axes.Axes.format
or proplot.figure.Figure.format
:
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¶
Matplotlib settings are natively stored in the rcParams
dictionary. Proplot makes this dictionary available in the top-level namespace as
rc_matplotlib
. All matplotlib settings can also be changed with
rc
. Details on the matplotlib settings can be found on
this page.
Proplot settings¶
Proplot settings are natively stored in the rc_proplot
dictionary.
They should almost always be changed with rc
rather than
rc_proplot
to ensure that meta-settings are
synced. These settings are not found in rcParams
– they either
control proplot-managed features (e.g., a-b-c labels and geographic gridlines)
or they represent existing matplotlib settings with more clear or succinct names.
Here’s a broad overview of the new settings:
The
subplots
category includes settings that control the default subplot layout and padding.The
geo
category contains settings related to geographic plotting, including the geographic backend, gridline label settings, and map bound settings.The
abc
,title
, andlabel
categories control a-b-c labels, axes titles, and axis labels. The latter two replaceaxes.title
andaxes.label
.The
suptitle
,leftlabel
,toplabel
,rightlabel
, andbottomlabel
categories control the figure titles and subplot row and column labels.The
formatter
category supersedes matplotlib’saxes.formatter
and includes settings that control theAutoFormatter
behavior.The
cmap
category supersedes matplotlib’simage
and includes settings relevant to colormaps and theDiscreteNorm
normalizer.The
tick
category supersedes matplotlib’sxtick
andytick
to simultaneously control x and y axis tick and tick label settings.The matplotlib
grid
category includes new settings that control the meridian and parallel gridlines and gridline labels managed byGeoAxes
.The
gridminor
category optionally controls minor gridlines separately from major gridlines.The
land
,ocean
,rivers
,lakes
,borders
, andinnerborders
categories control geographic content managed byGeoAxes
.
Meta-settings¶
Some proplot settings may be more accurately described as “meta-settings”,
as they change several matplotlib and proplot settings at once (note that settings
are only synced when they are changed on the rc
object rather than
the rc_proplot
and rc_matplotlib
dictionaries).
Here’s a broad overview of the “meta-settings”:
Setting
rc['font.small']
(or, equivalently,rc.fontsmall
) changes therc['tick.labelsize']
,rc['grid.labelsize']
,rc['legend.fontsize']
, andrc['axes.labelsize']
.Setting
rc['font.large']
(or, equivalently,rc.fontlarge
) changes therc['abc.size']
,rc['title.size']
,rc['suptitle.size']
,rc['leftlabel.size']
,rc['toplabel.size']
,rc['rightlabel.size']
rc['bottomlabel.size']
.Setting
rc['meta.color']
changes therc['axes.edgecolor']
,rc['axes.labelcolor']
rc['tick.labelcolor']
,rc['hatch.color']
,rc['xtick.color']
, andrc['ytick.color']
.Setting
rc['meta.width']
changes therc['axes.linewidth']
and the major and minor tickline widthsrc['xtick.major.width']
,rc['ytick.major.width']
,rc['xtick.minor.width']
, andrc['ytick.minor.width']
. The minor tickline widths are scaled byrc['tick.widthratio']
(or, equivalently,rc.tickwidthratio
).Setting
rc['tick.len']
(or, equivalently,rc.ticklen
) changes the major and minor tickline lengthsrc['xtick.major.size']
,rc['ytick.major.size']
,rc['xtick.minor.size']
, andrc['ytick.minor.size']
. The minor tickline lengths are scaled byrc['tick.lenratio']
(or, equivalently,rc.ticklenratio
).Setting
rc['grid.color']
,rc['grid.linewidth']
,rc['grid.linestyle']
, orrc['grid.alpha']
also changes the correspondinggridminor
settings. Any distinctgridminor
settings must be applied aftergrid
settings.Setting
rc['grid.linewidth']
changes the major and minor gridline widths. The minor gridline widths are scaled byrc['grid.widthratio']
(or, equivalently,rc.gridwidthratio
).Setting
rc['title.border']
orrc['abc.border']
toTrue
automatically setsrc['title.bbox']
orrc['abc.bbox']
toFalse
, and vice versa.
Table of settings¶
A comprehensive table of the new proplot settings is shown below.
Key |
Description |
---|---|
|
The default matplotlib stylesheet name. If |
|
If |
|
Whether to draw a white border around a-b-c labels when |
|
Width of the white border around a-b-c labels. |
|
Whether to draw semi-transparent bounding boxes around a-b-c labels when |
|
a-b-c label bounding box color. |
|
a-b-c label bounding box style. |
|
a-b-c label bounding box opacity. |
|
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 |
|
a-b-c label color. |
|
a-b-c label position. For options see the location table. |
|
a-b-c label font size. Must be a relative font size or unit string interpreted by |
|
Padding separating the title and a-b-c label when in the same location. Interpreted by |
|
a-b-c label font weight. |
|
Whether to automatically apply labels from |
|
Opacity of the background axes patch. |
|
Whether to exclude out-of-bounds data when determining the default y (x) axis limits and the x (y) axis limits have been locked. |
|
The fractional x and y axis margins when limits are unset. |
|
Toggles country border lines on and off. |
|
Opacity for country border lines. |
|
Line color for country border lines. |
|
Line width for country border lines. |
|
Z-order for country border lines. |
|
Font color for column labels on the bottom of the figure. |
|
Padding between axes content and column labels on the bottom of the figure. Interpreted by |
|
Rotation for column labels at the bottom of the figure. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees. |
|
Font size for column labels on the bottom of the figure. Must be a relative font size or unit string interpreted by |
|
Font weight for column labels on the bottom of the figure. |
|
Toggles coastline lines on and off. |
|
Opacity for coast lines |
|
Line color for coast lines. |
|
Line width for coast lines. |
|
Z-order for coast lines. |
|
Color for the inset colorbar frame edge. |
|
Length of rectangular or triangular “extensions” for panel colorbars. Interpreted by |
|
Whether to use a “fancy” round bounding box for inset colorbar frames. |
|
Opacity for inset colorbar frames. |
|
Color for the inset colorbar frame. |
|
Whether to draw a frame behind inset colorbars. |
|
Whether to draw borders between each level of the colorbar. |
|
Length of rectangular or triangular “extensions” for inset colorbars. Interpreted by |
|
Length of inset colorbars. Interpreted by |
|
Padding between axes edge and inset colorbars. Interpreted by |
|
Width of inset colorbars. Interpreted by |
|
Length of outer colorbars. |
|
Inset colorbar location. For options see the location table. |
|
Width of outer colorbars. Interpreted by |
|
Whether to use rasterization for colorbar solids. |
|
Whether to add a shadow underneath inset colorbar frames. |
|
Name of the color cycle assigned to |
|
Alias for |
|
Whether to automatically apply a diverging colormap and normalizer based on the data. |
|
Default colormap for qualitative datasets. |
|
Default colormap for cyclic datasets. |
|
If |
|
Default colormap for diverging datasets. |
|
If |
|
Default number of |
|
Native |
|
Number of colors in the colormap lookup table. Alias for |
|
If |
|
Default colormap for sequential datasets. Alias for |
|
Whether to fix issues with “white lines” appearing between patches in saved vector graphics and with vector graphic backends. Applies to colorbar levels and bar, area, pcolor, and contour plots. |
|
Alias for |
|
Alias for |
|
Meta setting that changes the label-like sizes |
|
Alias for |
|
Meta setting that changes the title-like sizes |
|
Rotation for x axis datetime tick labels. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees. |
|
Whether to trim trailing decimal zeros on tick labels. |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
The backend used for |
|
If |
|
If |
|
Toggle major gridlines on and off. |
|
Alias for |
|
Whether to have cartopy automatically check for and remove overlapping |
|
Whether to use degrees-minutes-seconds rather than decimals for cartopy |
|
Whether to include the |
|
Whether to add inline labels for cartopy |
|
Whether to add outer labels for |
|
Font color for |
|
Padding between the map boundary and cartopy |
|
Font size for |
|
Font weight for |
|
Number of points used to draw cartopy |
|
Alias for |
|
Whether to rotate cartopy |
|
Major gridline style. Alias for |
|
Major gridline width. Alias for |
|
Ratio of minor gridline width to major gridline width. |
|
Toggle minor gridlines on and off. |
|
Minor gridline opacity. |
|
Minor gridline color. |
|
Minor gridline style. |
|
Minor gridline width. |
|
Minor gridline style. Alias for |
|
Minor gridline width. Alias for |
|
The inline backend figure format. Valid formats include |
|
Toggles internal political border lines (e.g. states and provinces) on and off. |
|
Opacity for internal political border lines |
|
Line color for internal political border lines. |
|
Line width for internal political border lines. |
|
Z-order for internal political border lines. |
|
Alias for |
|
Alias for |
|
Alias for |
|
Alias for |
|
Toggles lake patches on and off. |
|
Opacity for lake patches |
|
Face color for lake patches. |
|
Z-order for lake patches. |
|
Toggles land patches on and off. |
|
Opacity for land patches |
|
Face color for land patches. |
|
Z-order for land patches. |
|
Font color for row labels on the left-hand side. |
|
Padding between axes content and row labels on the left-hand side. Interpreted by |
|
Rotation for row labels on the left-hand side. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees. |
|
Font size for row labels on the left-hand side. Must be a relative font size or unit string interpreted by |
|
Font weight for row labels on the left-hand side. |
|
The fractional x and y axis data margins when limits are unset. Alias for |
|
Color of axis spines, tick marks, tick labels, and labels. |
|
Color of axis spines, tick marks, tick labels, and labels. Alias for |
|
Thickness of axis spines and major tick lines. |
|
Thickness of axis spines and major tick lines. Alias for |
|
Color for negative bars and shaded areas when using |
|
Color for positive bars and shaded areas when using |
|
Toggles ocean patches on and off. |
|
Opacity for ocean patches |
|
Face color for ocean patches. |
|
Z-order for ocean patches. |
|
Resolution for |
|
Font color for row labels on the right-hand side. |
|
Padding between axes content and row labels on the right-hand side. Interpreted by |
|
Rotation for row labels on the right-hand side. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees. |
|
Font size for row labels on the right-hand side. Must be a relative font size or unit string interpreted by |
|
Font weight for row labels on the right-hand side. |
|
Toggles river lines on and off. |
|
Opacity for river lines. |
|
Line color for river lines. |
|
Line width for river lines. |
|
Z-order for river lines. |
|
Whether to align axis labels during draw. See aligning labels. |
|
Whether to make the tight layout algorithm assign the same space for every row and the same space for every column. |
|
Whether to make the tight layout algorithm consider space between only adjacent subplot “groups” rather than every subplot in the row or column. |
|
Padding between adjacent subplots. Interpreted by |
|
Padding around figure edge. Interpreted by |
|
Padding between subplots and panels, and between stacked panels. Interpreted by |
|
Width of side panels. Interpreted by |
|
Default width of the reference subplot. Interpreted by |
|
The axis sharing level, one of |
|
Toggles spanning axis labels. See |
|
Whether to auto-adjust the subplot spaces and figure margins. |
|
Figure title color. |
|
Padding between axes content and the figure super title. Interpreted by |
|
Figure title font size. Must be a relative font size or unit string interpreted by |
|
Figure title font weight. |
|
Major and minor tick color. |
|
Major and minor tick direction. Must be one of |
|
Axis tick label color. |
|
Padding between ticks and tick labels. Interpreted by |
|
Axis tick label font size. Must be a relative font size or unit string interpreted by |
|
Axis tick label font weight. |
|
Length of major ticks in points. |
|
Ratio of minor tickline length to major tickline length. |
|
Major tickline width. |
|
Toggles minor ticks on and off. |
|
Alias for |
|
Major tickline width. Alias for |
|
Ratio of minor tickline width to major tickline width. |
|
Whether to move outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. If the string ‘panels’ then text is only redirected above axes panels. Otherwise should be boolean. |
|
Whether to draw a white border around titles when |
|
Width of the border around titles. |
|
Whether to draw semi-transparent bounding boxes around titles when |
|
Axes title bounding box color. |
|
Axes title bounding box style. |
|
Axes title bounding box opacity. |
|
Padding for the title bounding box. By default this is scaled to make the box flush against the axes edge. Interpreted by |
|
Axes title color. Alias for |
|
Title position. For options see the location table. |
|
Padding between the axes edge and the inner and outer titles and a-b-c labels. Alias for |
|
Axes title font size. Alias for |
|
Axes title font weight. Alias for |
|
Font color for column labels on the top of the figure. |
|
Padding between axes content and column labels on the top of the figure. Interpreted by |
|
Rotation for column labels at the top of the figure. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees. |
|
Font size for column labels on the top of the figure. Must be a relative font size or unit string interpreted by |
|
Font weight for column labels on the top of the figure. |
|
The format string used to format |
The proplotrc file¶
When you import proplot for the first time, a proplotrc
file is generated with
all lines commented out. This file is just like matplotlibrc,
except it controls both matplotlib and proplot settings. The syntax is essentially
the same as matplotlibrc, and the file path is very similar to matplotlibrc. On most
platforms it is found in ~/.proplot/proplotrc
, but a loose hidden file in the
home directory named ~/.proplotrc
is also allowed (use
user_file
to print the path). To update this file
after a version change, simply remove it and restart your python session.
To change the global rc
settings, edit and uncomment the lines
in the proplotrc
file. To change the settings for a specific project, place a file
named either .proplotrc
or proplotrc
in the same directory as your python
session, or in an arbitrary parent directory. To generate a proplotrc
file
containing the settings you have changed during a python session, use
save
(use changed
to preview a dictionary of the changed settings). To explicitly load a proplotrc
file, use load
.
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
abc: False
abc.bbox: False
abc.bboxalpha: 0.5
abc.bboxcolor: white
abc.bboxpad: None
abc.bboxstyle: square
abc.border: True
abc.borderwidth: 1.5
abc.color: black
abc.loc: left
abc.size: med-large
abc.titlepad: 4.0
abc.weight: bold
autoformat: True
axes.alpha: None
axes.inbounds: True
axes.margin: 0.05
borders: False
borders.alpha: None
borders.color: black
borders.linewidth: 0.6
borders.zorder: 2.0
bottomlabel.color: black
bottomlabel.pad: 5.0
bottomlabel.rotation: horizontal
bottomlabel.size: med-large
bottomlabel.weight: bold
cmap: Fire
cmap.autodiverging: True
cmap.cyclic: twilight
cmap.discrete: None
cmap.diverging: BuRd
cmap.inbounds: True
cmap.levels: 11
cmap.listedthresh: 64
cmap.lut: 256
cmap.qualitative: colorblind10
cmap.robust: False
cmap.sequential: Fire
coast: False
coast.alpha: None
coast.color: black
coast.linewidth: 0.6
coast.zorder: 2.0
colorbar.edgecolor: black
colorbar.extend: 1.3
colorbar.facecolor: white
colorbar.fancybox: False
colorbar.framealpha: 0.8
colorbar.frameon: True
colorbar.grid: False
colorbar.insetextend: 0.9
colorbar.insetlength: 8.0
colorbar.insetpad: 0.7
colorbar.insetwidth: 1.2
colorbar.length: 1.0
colorbar.loc: right
colorbar.rasterized: False
colorbar.shadow: False
colorbar.width: 0.2
cycle: colorblind
edgefix: True
font.large: med-large
font.largesize: med-large
font.name: sans-serif
font.small: medium
font.smallsize: medium
formatter.limits: -5, 6
formatter.min_exponent: 0
formatter.offset_threshold: 4
formatter.timerotation: vertical
formatter.use_locale: False
formatter.use_mathtext: False
formatter.use_offset: True
formatter.zerotrim: True
geo.backend: cartopy
geo.extent: globe
geo.round: True
grid: True
grid.below: line
grid.checkoverlap: True
grid.dmslabels: True
grid.geolabels: True
grid.inlinelabels: False
grid.labelcolor: black
grid.labelpad: 3.0
grid.labels: False
grid.labelsize: medium
grid.labelweight: normal
grid.nsteps: 250
grid.pad: 3.0
grid.rotatelabels: False
grid.style: -
grid.width: 0.6
grid.widthratio: 0.5
gridminor: False
gridminor.alpha: 0.1
gridminor.color: black
gridminor.linestyle: -
gridminor.linewidth: 0.3
gridminor.style: -
gridminor.width: 0.3
inlineformat: retina
innerborders: False
innerborders.alpha: None
innerborders.color: black
innerborders.linewidth: 0.6
innerborders.zorder: 2.0
label.color: black
label.pad: 4.0
label.size: medium
label.weight: normal
lakes: False
lakes.alpha: None
lakes.color: white
lakes.zorder: 1.0
land: False
land.alpha: None
land.color: black
land.zorder: 1.0
leftlabel.color: black
leftlabel.pad: 5.0
leftlabel.rotation: vertical
leftlabel.size: med-large
leftlabel.weight: bold
margin: 0.05
meta.color: black
meta.edgecolor: black
meta.linewidth: 0.6
meta.width: 0.6
negcolor: blue7
ocean: False
ocean.alpha: None
ocean.color: white
ocean.zorder: 1.0
poscolor: red7
reso: lo
rightlabel.color: black
rightlabel.pad: 5.0
rightlabel.rotation: vertical
rightlabel.size: med-large
rightlabel.weight: bold
rivers: False
rivers.alpha: None
rivers.color: black
rivers.linewidth: 0.6
rivers.zorder: 2.0
style: None
subplots.align: False
subplots.equalspace: False
subplots.groupspace: True
subplots.innerpad: 1.0
subplots.outerpad: 0.5
subplots.panelpad: 0.5
subplots.panelwidth: 0.5
subplots.refwidth: 2.5
subplots.share: True
subplots.span: True
subplots.tight: True
suptitle.color: black
suptitle.pad: 5.0
suptitle.size: med-large
suptitle.weight: bold
tick.color: black
tick.dir: out
tick.labelcolor: black
tick.labelpad: 2.0
tick.labelsize: medium
tick.labelweight: normal
tick.len: 4.0
tick.lenratio: 0.5
tick.linewidth: 0.6
tick.minor: True
tick.pad: 2.0
tick.width: 0.6
tick.widthratio: 0.8
title.above: True
title.bbox: False
title.bboxalpha: 0.5
title.bboxcolor: white
title.bboxpad: None
title.bboxstyle: square
title.border: True
title.borderwidth: 1.5
title.color: black
title.loc: center
title.pad: 5.0
title.size: med-large
title.weight: normal
toplabel.color: black
toplabel.pad: 5.0
toplabel.rotation: horizontal
toplabel.size: med-large
toplabel.weight: bold
unitformat: L
# Matplotlib settings
axes.axisbelow: line
axes.edgecolor: black
axes.formatter.use_mathtext: False
axes.grid: True
axes.grid.which: major
axes.labelcolor: black
axes.labelpad: 4.0
axes.labelsize: medium
axes.labelweight: normal
axes.linewidth: 0.6
axes.titlecolor: black
axes.titlepad: 5.0
axes.titlesize: med-large
axes.titleweight: normal
axes.xmargin: 0.05
axes.ymargin: 0.05
errorbar.capsize: 3.0
figure.autolayout: False
figure.dpi: 100.0
figure.facecolor: f4f4f4
figure.figsize: 4.0, 4.0
figure.titlesize: med-large
figure.titleweight: bold
font.cursive: TeX Gyre Chorus, Apple Chancery, Felipa, Sand, Script MT, Textile, Zapf Chancery, cursive
font.family: sans-serif
font.fantasy: TeX Gyre Adventor, Avant Garde, Charcoal, Chicago, Comic Sans MS, Futura, Humor Sans, Impact, Optima, Western, xkcd, fantasy
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.sans-serif: TeX Gyre Heros, DejaVu Sans, Bitstream Vera Sans, Computer Modern Sans Serif, Arial, Avenir, Fira Math, Fira Sans, 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.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, Noto Serif, Palatino, Source Serif Pro, Times New Roman, Times, Utopia, serif
font.size: 9.0
grid.alpha: 0.1
grid.color: black
grid.linestyle: -
grid.linewidth: 0.6
hatch.color: black
hatch.linewidth: 0.6
image.cmap: Fire
legend.borderaxespad: 0.0
legend.borderpad: 0.5
legend.columnspacing: 1.5
legend.edgecolor: black
legend.facecolor: white
legend.fancybox: False
legend.fontsize: medium
legend.framealpha: 0.8
legend.handleheight: 1.0
legend.handlelength: 2.0
legend.handletextpad: 0.5
lines.linestyle: -
lines.linewidth: 1.5
lines.markersize: 6.0
mathtext.bf: regular:bold
mathtext.cal: cursive
mathtext.default: it
mathtext.fontset: custom
mathtext.it: regular:italic
mathtext.rm: regular
mathtext.sf: regular
mathtext.tt: monospace
patch.linewidth: 0.6
savefig.bbox: None
savefig.directory:
savefig.dpi: 1000.0
savefig.facecolor: white
savefig.format: pdf
savefig.transparent: False
xtick.color: black
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.color: black
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.visible: True
ytick.minor.width: 0.48