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:

  1. import proplot as plot
  2. plot.rc.name = value
  3. plot.rc['name'] = value
  4. plot.rc.update(name1=value1, name2=value2)
  5. 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:

  1. import proplot as plot
  2. fig, ax = plot.subplots()
  3. ax.format(name1=value1, name2=value2)
  4. 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’]](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=title.loc#rc-proplot) property, the following approaches are valid:

  1. import proplot as plot
  2. # Apply globally
  3. plot.rc.titleloc = value
  4. plot.rc.update(titleloc=value)
  5. # Apply locally
  6. fig, ax = plot.subplots()
  7. 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](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=linewidth#rc-proplot) 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.

alpha

The opacity of the background axes patch.

axes.alpha

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.

  1. #--------------------------------------------------------------------
  2. # Use this file to change the default proplot and matplotlib settings
  3. # The syntax is identical to matplotlibrc syntax. For details see:
  4. # https://proplot.readthedocs.io/en/latest/configuration.html
  5. # https://matplotlib.org/3.1.1/tutorials/introductory/customizing
  6. #--------------------------------------------------------------------
  7. # ProPlot settings
  8. style:                      None
  9. abc:                        False
  10. abc.border:                 True
  11. abc.borderwidth:            1.5
  12. abc.color:                  black
  13. abc.loc:                    l
  14. abc.size:                   med-large
  15. abc.style:                  a
  16. abc.weight:                 bold
  17. alpha:                      1
  18. axes.alpha:                 1.0
  19. formatter.timerotation:     90
  20. formatter.zerotrim:         True
  21. formatter.limits:           -5, 6
  22. formatter.use_locale:       False
  23. formatter.use_mathtext:     False
  24. formatter.min_exponent:     0
  25. formatter.use_offset:       True
  26. formatter.offset_threshold: 4
  27. borders:                    False
  28. borders.color:              black
  29. borders.linewidth:          0.6
  30. borders.zorder:             2
  31. bottomlabel.color:          black
  32. bottomlabel.size:           med-large
  33. bottomlabel.weight:         bold
  34. cartopy.autoextent:         False
  35. coast:                      False
  36. coast.color:                black
  37. coast.linewidth:            0.6
  38. colorbar.extend:            1.3em
  39. colorbar.framealpha:        0.8
  40. colorbar.frameon:           True
  41. colorbar.grid:              False
  42. colorbar.insetextend:       1em
  43. colorbar.insetlength:       8em
  44. colorbar.insetpad:          0.5em
  45. colorbar.insetwidth:        1.2em
  46. colorbar.length:            1
  47. colorbar.loc:               right
  48. colorbar.width:             1.5em
  49. cmap:                       fire
  50. color:                      black
  51. cycle:                      colorblind
  52. facecolor:                  white
  53. font.name:                  sans-serif
  54. grid:                       True
  55. grid.below:                 line
  56. grid.dmslabels:             True
  57. grid.pad:                   5
  58. grid.labels:                False
  59. grid.labelsize:             medium
  60. grid.labelweight:           normal
  61. grid.labelcolor:            black
  62. grid.latinline:             False
  63. grid.loninline:             False
  64. grid.nsteps:                250
  65. grid.ratio:                 0.5
  66. grid.rotatelabels:          False
  67. gridminor:                  False
  68. gridminor.alpha:            0.11
  69. gridminor.color:            black
  70. gridminor.latstep:          10
  71. gridminor.linestyle:        -
  72. gridminor.linewidth:        0.3
  73. gridminor.lonstep:          20
  74. image.edgefix:              True
  75. image.levels:               11
  76. inlinefmt:                  retina
  77. innerborders:               False
  78. innerborders.color:         black
  79. innerborders.linewidth:     0.6
  80. innerborders.zorder:        2
  81. lakes:                      False
  82. lakes.color:                w
  83. lakes.zorder:               1
  84. land:                       False
  85. land.color:                 black
  86. land.zorder:                1
  87. leftlabel.color:            black
  88. leftlabel.size:             med-large
  89. leftlabel.weight:           bold
  90. linewidth:                  0.6
  91. lut:                        256
  92. margin:                     0.05
  93. negcolor:                   blue7
  94. poscolor:                   red7
  95. ocean:                      False
  96. ocean.color:                w
  97. ocean.zorder:               1
  98. reso:                       lo
  99. rightlabel.color:           black
  100. rightlabel.size:            med-large
  101. rightlabel.weight:          bold
  102. rivers:                     False
  103. rivers.color:               black
  104. rivers.linewidth:           0.6
  105. rivers.zorder:              2
  106. subplots.align:             False
  107. subplots.axpad:             1em
  108. subplots.axwidth:           20em
  109. subplots.pad:               0.5em
  110. subplots.panelpad:          0.5em
  111. subplots.panelwidth:        4em
  112. subplots.share:             3
  113. subplots.span:              True
  114. subplots.tight:             True
  115. suptitle.color:             black
  116. suptitle.size:              med-large
  117. suptitle.weight:            bold
  118. text.labelsize:             medium
  119. text.titlesize:             med-large
  120. tick.color:                 black
  121. tick.dir:                   out
  122. tick.labelcolor:            black
  123. tick.labelsize:             medium
  124. tick.labelweight:           normal
  125. tick.len:                   4.0
  126. tick.lenratio:              0.5
  127. tick.minor:                 True
  128. tick.pad:                   2.0
  129. tick.ratio:                 0.8
  130. title.border:               True
  131. title.borderwidth:          1.5
  132. title.color:                black
  133. title.loc:                  c
  134. title.pad:                  5.0
  135. title.size:                 med-large
  136. title.weight:               normal
  137. toplabel.color:             black
  138. toplabel.size:              med-large
  139. toplabel.weight:            bold
  141. # Matplotlib settings
  142. axes.axisbelow:              line
  143. axes.formatter.use_mathtext: False
  144. axes.grid:                   True
  145. axes.grid.which:             major
  146. axes.labelpad:               4.0
  147. axes.labelsize:              medium
  148. axes.labelweight:            normal
  149. axes.linewidth:              0.6
  150. axes.titlepad:               5.0
  151. axes.titlesize:              med-large
  152. axes.titleweight:            normal
  153. axes.xmargin:                0.05
  154. axes.ymargin:                0.05
  155. figure.autolayout:           False
  156. figure.dpi:                  100
  157. figure.facecolor:            '#f2f2f2'
  158. figure.titlesize:            med-large
  159. figure.titleweight:          bold
  160. 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
  161. 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
  162. 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
  163. font.cursive:                TeX Gyre Chorus, Apple Chancery, Felipa, Sand, Script MT, Textile, Zapf Chancery, cursive
  164. font.fantasy:                TeX Gyre Adventor, Avant Garde, Charcoal, Chicago, Comic Sans MS, Futura, Humor Sans, Impact, Optima, Western, xkcd, fantasy
  165. font.size:                   9.0
  166. grid.alpha:                  0.11
  167. grid.color:                  black
  168. grid.linestyle:              -
  169. grid.linewidth:              0.6
  170. hatch.color:                 black
  171. hatch.linewidth:             0.6
  172. image.cmap:                  fire
  173. lines.linestyle:             -
  174. lines.linewidth:             1.5
  175. lines.markersize:            6.0
  176. legend.borderaxespad:        0
  177. legend.borderpad:            0.5
  178. legend.columnspacing:        1.5
  179. legend.fancybox:             False
  180. legend.fontsize:             medium
  181. legend.framealpha:           0.8
  182. legend.handletextpad:        0.5
  183. mathtext.fontset:            custom
  184. mathtext.default:            regular
  185. patch.linewidth:             0.6
  186. savefig.bbox:                None
  187. savefig.directory:           
  188. savefig.dpi:                 1200
  189. savefig.facecolor:           white
  190. savefig.format:              pdf
  191. savefig.transparent:         True
  192. xtick.direction:             out
  193. xtick.labelsize:             medium
  194. xtick.major.pad:             2.0
  195. xtick.major.size:            4.0
  196. xtick.major.width:           0.6
  197. xtick.minor.pad:             2.0
  198. xtick.minor.size:            2.0
  199. xtick.minor.visible:         True
  200. xtick.minor.width:           0.48
  201. ytick.direction:             out
  202. ytick.labelsize:             medium
  203. ytick.major.pad:             2.0
  204. ytick.major.size:            4.0
  205. ytick.major.width:           0.6
  206. ytick.minor.pad:             2.0
  207. ytick.minor.size:            2.0
  208. ytick.minor.width:           0.48
  209. ytick.minor.visible:         True