Configuring UltraPlot#

Overview#

A dictionary-like object named rc, belonging to the Configurator class, is created when you import UltraPlot. This is your one-stop shop for working with matplotlib settings stored in rc_matplotlib (our name for the rcParams dictionary) and ultraplot settings stored in rc_ultraplot.

To change global settings on-the-fly, simply update rc using either dot notation or as you would any other dictionary:

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

To apply settings to a particular axes or figure, pass the setting to format() or format():

import ultraplot as uplt
fig, ax = uplt.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 ultraplot as uplt
with uplt.rc.context(name1=value1, name2=value2):
    fig, ax = uplt.subplots()
with uplt.rc.context({'name1': value1, 'name2': value2}):
    fig, ax = uplt.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 ultraplot as uplt
# Apply globally
uplt.rc.titleloc = value
uplt.rc.update(titleloc=value)
# Apply locally
fig, ax = uplt.subplots()
ax.format(titleloc=value)

Matplotlib settings#

Matplotlib settings are natively stored in the rcParams dictionary. UltraPlot 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.

UltraPlot settings#

UltraPlot settings are natively stored in the rc_ultraplot dictionary. They should almost always be changed with rc rather than rc_ultraplot to ensure that meta-settings are synced. These settings are not found in rcParams – they either control UltraPlot-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, and label categories control a-b-c labels, axes titles, and axis labels. The latter two replace axes.title and axes.label.

  • The suptitle, leftlabel, toplabel, rightlabel, and bottomlabel categories control the figure titles and subplot row and column labels.

  • The formatter category supersedes matplotlib’s axes.formatter and includes settings that control the AutoFormatter behavior.

  • The cmap category supersedes matplotlib’s image and includes settings relevant to colormaps and the DiscreteNorm normalizer.

  • The tick category supersedes matplotlib’s xtick and ytick 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 by GeoAxes.

  • The gridminor category optionally controls minor gridlines separately from major gridlines.

  • The land, ocean, rivers, lakes, borders, and innerborders categories control geographic content managed by GeoAxes.

Meta-settings#

Some UltraPlot settings may be more accurately described as “meta-settings”, as they change several matplotlib and UltraPlot settings at once (note that settings are only synced when they are changed on the rc object rather than the rc_UltraPlot and rc_matplotlib dictionaries). Here’s a broad overview of the “meta-settings”:

Relative font size table#

When a setting accepts a relative font size string, these values are available. The 'med', 'med-small', and 'med-large' aliases are added by UltraPlot.

Size

Scale

'xx-small'

0.579

'x-small'

0.694

'small', 'smaller'

0.833

'med-small'

0.9

'med', 'medium'

1.0

'med-large'

1.1

'large', 'larger'

1.2

'x-large'

1.440

'xx-large'

1.728

Table of settings#

A comprehensive table of the new UltraPlot settings is shown below.

Key

Description

curved_quiver.arrowsize

Default size scaling for arrows in curved quiver plots.

curved_quiver.arrowstyle

Default arrow style for curved quiver plots.

curved_quiver.scale

Default scale factor for curved quiver plots.

curved_quiver.grains

Default number of grains (segments) for curved quiver arrows.

curved_quiver.density

Default density of arrows for curved quiver plots.

curved_quiver.arrows_at_end

Whether to draw arrows at the end of curved quiver lines by default.

external.shrink

Default shrink factor for external axes containers.

sankey.nodepad

Vertical padding between nodes in layered sankey diagrams.

sankey.nodewidth

Node width for layered sankey diagrams (axes-relative units).

sankey.margin

Margin around layered sankey diagrams (axes-relative units).

sankey.flow.alpha

Flow transparency for layered sankey diagrams.

sankey.flow.curvature

Flow curvature for layered sankey diagrams.

sankey.node.facecolor

Default node facecolor for layered sankey diagrams.

ribbon.xmargin

Horizontal margin around ribbon diagrams (axes-relative units).

ribbon.ymargin

Vertical margin around ribbon diagrams (axes-relative units).

ribbon.rowheightratio

Height scale factor controlling ribbon row occupancy.

ribbon.nodewidth

Node width for ribbon diagrams (axes-relative units).

ribbon.flow.curvature

Flow curvature for ribbon diagrams.

ribbon.flow.alpha

Flow transparency for ribbon diagrams.

ribbon.topic_labels

Whether to draw topic labels on the right side of ribbon diagrams.

ribbon.topic_label_offset

Offset for right-side ribbon topic labels.

ribbon.topic_label_size

Font size for ribbon topic labels.

ribbon.topic_label_box

Whether to draw backing boxes behind ribbon topic labels.

style

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

abc

If False then a-b-c labels are disabled. If True the default label style a is used. If string this indicates the style and must contain the character a or A, for example 'a.' or '(A)'.

abc.border

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.

text.borderstyle

Join style for text border strokes. Must be one of 'miter', 'round', or 'bevel'.

text.align

Whether text and annotations avoid overlapping each other and the data by default. Set to True to opt every label into the solver used by auto_align_text.

text.align.pad

Padding in points kept around auto-aligned text.

text.align.maxiter

Maximum number of relaxation iterations used to auto-align text.

text.align.arrows

Whether auto-aligned text draws a connector back to the point it labels.

text.curved.upright

Whether curved text is flipped to remain upright by default.

text.curved.ellipsis

Whether to show ellipses when curved text exceeds path length.

text.curved.avoid_overlap

Whether curved text hides overlapping glyphs by default.

text.curved.overlap_tol

Overlap threshold used when hiding curved-text glyphs.

text.curved.curvature_pad

Extra curved-text glyph spacing per radian of local curvature.

text.curved.min_advance

Minimum extra curved-text glyph spacing in pixels.

abc.bbox

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. Numeric units are points.

abc.color

a-b-c label color.

abc.loc

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

abc.size

a-b-c label font size. Must be a relative font size or unit string interpreted by units. Numeric units are points.

abc.titlepad

Padding separating the title and a-b-c label when in the same location. Interpreted by units. Numeric units are points.

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. See also rc.unitformat.

axes.alpha

Opacity of the background axes patch.

axes.inbounds

Whether to exclude out-of-bounds data when determining the default y (x) axis limits and the x (y) axis limits have been locked.

axes.margin

The fractional x and y axis margins when limits are unset.

bar.bar_labels

Add value of the bars to the bar labels

borders

Toggles country border lines on and off.

borders.alpha

Opacity for country border lines.

borders.color

Line color for country border lines.

borders.linewidth

Line width for country border lines.

borders.zorder

Z-order for country border lines.

borders.rasterized

Toggles rasterization on or off for border feature in GeoAxes.

bottomlabel.color

Font color 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. Numeric units are points.

bottomlabel.sharedpad

Padding between column labels and a shared x label on the bottom of the figure. Interpreted by units. Numeric units are points.

bottomlabel.rotation

Rotation for column labels at the bottom of the figure. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees.

bottomlabel.size

Font size for column labels on the bottom of the figure. Must be a relative font size or unit string interpreted by units. Numeric units are points.

bottomlabel.weight

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

cftime.time_unit

Time unit for non-Gregorian calendars.

cftime.resolution

Default time resolution for non-Gregorian calendars.

cftime.time_resolution_format

Dict used for formatting non-Gregorian calendars.

cftime.max_display_ticks

Number of ticks to display for cftime units.

coast

Toggles coastline lines on and off.

coast.alpha

Opacity for coast lines

coast.color

Line color for coast lines.

coast.linewidth

Line width for coast lines.

coast.zorder

Z-order for coast lines.

coast.rasterized

Toggles the rasterization of the coastlines feature for GeoAxes.

colorbar.center_levels

Center the ticks in the center of each segment.

colorbar.edgecolor

Color for the inset colorbar frame edge.

colorbar.extend

Length of rectangular or triangular “extensions” for panel colorbars. Interpreted by units. Numeric units are em-widths.

colorbar.outline

Whether to draw a frame around the colorbar.

colorbar.labelrotation

Rotation of colorbar labels.

colorbar.fancybox

Whether to use a “fancy” round bounding box for inset colorbar frames.

colorbar.framealpha

Opacity for inset colorbar frames.

colorbar.facecolor

Color for the inset colorbar frame.

colorbar.frameon

Whether to draw a frame behind inset colorbars.

colorbar.grid

Whether to draw borders between each level of the colorbar.

colorbar.insetextend

Length of rectangular or triangular “extensions” for inset colorbars. Interpreted by units. Numeric units are em-widths.

colorbar.insetlength

Length of inset colorbars. Interpreted by units. Numeric units are em-widths.

colorbar.insetpad

Padding between axes edge and inset colorbars. Interpreted by units. Numeric units are em-widths.

colorbar.insetwidth

Width of inset colorbars. Interpreted by units. Numeric units are em-widths.

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. Numeric units are inches.

colorbar.rasterized

Whether to use rasterization for colorbar solids.

colorbar.shadow

Whether to add a shadow underneath inset colorbar frames.

legend.cat.line

Default line/marker mode for Axes.catlegend.

legend.cat.marker

Default marker for Axes.catlegend entries.

legend.cat.linestyle

Default line style for Axes.catlegend entries.

legend.cat.linewidth

Default line width for Axes.catlegend entries.

legend.cat.markersize

Default marker size for Axes.catlegend entries.

legend.cat.alpha

Default alpha for Axes.catlegend entries.

legend.cat.markeredgecolor

Default marker edge color for Axes.catlegend entries.

legend.cat.markeredgewidth

Default marker edge width for Axes.catlegend entries.

legend.size.color

Default marker color for Axes.sizelegend entries.

legend.size.marker

Default marker for Axes.sizelegend entries.

legend.size.area

Whether Axes.sizelegend interprets levels as marker area by default.

legend.size.scale

Default marker size scale factor for Axes.sizelegend entries.

legend.size.minsize

Default minimum marker size for Axes.sizelegend entries.

legend.size.format

Default label format string for Axes.sizelegend entries.

legend.size.alpha

Default alpha for Axes.sizelegend entries.

legend.size.markeredgecolor

Default marker edge color for Axes.sizelegend entries.

legend.size.markeredgewidth

Default marker edge width for Axes.sizelegend entries.

legend.num.n

Default number of sampled levels for Axes.numlegend.

legend.num.cmap

Default colormap for Axes.numlegend entries.

legend.num.edgecolor

Default edge color for Axes.numlegend patch entries.

legend.num.linewidth

Default edge width for Axes.numlegend patch entries.

legend.num.alpha

Default alpha for Axes.numlegend entries.

legend.num.format

Default label format string for Axes.numlegend entries.

legend.geo.facecolor

Default face color for Axes.geolegend entries.

legend.geo.edgecolor

Default edge color for Axes.geolegend entries.

legend.geo.linewidth

Default edge width for Axes.geolegend entries.

legend.geo.alpha

Default alpha for Axes.geolegend entries.

legend.geo.fill

Default fill mode for Axes.geolegend entries.

legend.geo.country_reso

Default Natural Earth resolution used for country shorthand geometry entries in Axes.geolegend.

legend.geo.country_territories

Whether country shorthand entries in Axes.geolegend include far-away territories instead of pruning to the local footprint.

legend.geo.country_proj

Optional projection name for country shorthand entries in Axes.geolegend. Can be overridden per call with a cartopy CRS or callable.

legend.geo.handlesize

Scale factor applied to both legend handle length and height for Axes.geolegend when explicit handle dimensions are not provided.

cycle

Name of the color cycle assigned to rc['axes.prop_cycle'].

cmap

Alias for rc['cmap.sequential'] and rc['image.cmap'].

cmap.autodiverging

Whether to automatically apply a diverging colormap and normalizer based on the data.

cmap.qualitative

Default colormap for qualitative datasets.

cmap.cyclic

Default colormap for cyclic datasets.

cmap.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.

cmap.diverging

Default colormap for diverging datasets.

cmap.inbounds

If True and the x and y axis limits are fixed, only in-bounds data is considered when determining the default colormap vmin and vmax.

cmap.levels

Default number of DiscreteNorm levels for plotting commands that use colormaps.

cmap.listedthresh

Native ListedColormaps with more colors than this are converted to ContinuousColormap rather than DiscreteColormap. This helps translate continuous colormaps from external projects.

cmap.lut

Number of colors in the colormap lookup table. Alias for rc['image.lut'].

cmap.robust

If True, the default colormap vmin and vmax are chosen using the 2nd to 98th percentiles rather than the minimum and maximum.

cmap.sequential

Default colormap for sequential datasets. Alias for rc['image.cmap'].

edgefix

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.

font.name

Alias for rc['font.family'].

font.small

Alias for rc['font.smallsize'].

font.smallsize

Meta setting that changes the label-like sizes axes.labelsize, legend.fontsize, tick.labelsize, and grid.labelsize. Default is 'medium' (equivalent to rc['font.size']). Must be a relative font size or unit string interpreted by units. Numeric units are points.

font.large

Alias for rc['font.largesize'].

font.largesize

Meta setting that changes the title-like sizes abc.size, title.size, suptitle.size, leftlabel.size, rightlabel.size, etc. Default is 'med-large' (i.e. 1.1 times rc['font.size']). Must be a relative font size or unit string interpreted by units. Numeric units are points.

formatter.timerotation

Rotation for x axis datetime tick labels. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees.

formatter.zerotrim

Whether to trim trailing decimal zeros on tick labels.

formatter.log

Whether to use log formatting (e.g., $10^{4}$) for logarithmically scaled axis tick labels.

formatter.limits

Alias for rc['axes.formatter.limits'].

formatter.min_exponent

Alias for rc['axes.formatter.min_exponent'].

formatter.offset_threshold

Alias for rc['axes.formatter.offset_threshold'].

formatter.use_locale

Alias for rc['axes.formatter.use_locale'].

formatter.use_mathtext

Alias for rc['axes.formatter.use_mathtext'].

formatter.use_offset

Alias for rc['axes.formatter.useOffset'].

geo.backend

The backend used for GeoAxes. Must be either ‘cartopy’ or ‘basemap’.

geo.extent

If 'globe', the extent of cartopy GeoAxes is always global. If 'auto', the extent is automatically adjusted based on plotted content. Default is 'globe'.

geo.round

If True (the default), polar GeoAxes like 'npstere' and 'spstere' are bounded with circles rather than squares.

geo.choropleth.country_reso

Default Natural Earth resolution used by GeoAxes.choropleth when country identifiers are resolved to polygons.

geo.choropleth.country_territories

Whether GeoAxes.choropleth keeps distant territories when resolving country identifiers into Natural Earth geometries.

geo.choropleth.zorder

Default z-order for GeoAxes.choropleth. When None, the choropleth is drawn just above the land feature.

graph.draw_nodes

If True draws the nodes for all the nodes, otherwise only the nodes that are in the iterable.

graph.draw_edges

If True draws the edges for all the edges, otherwise only the edges that are in the iterable.

graph.draw_labels

If True draws the labels for all the nodes, otherwise only the nodes that are in the iterable.

graph.draw_grid

If True draws the grid for all the edges, otherwise only the edges that are in the iterable.

graph.aspect

The aspect ratio of the graph.

graph.facecolor

The facecolor of the graph.

graph.draw_spines

If True draws the spines for all the edges, otherwise only the edges that are in the iterable.

graph.rescale

If True rescales the graph to fit the data.

grid

Toggle major gridlines on and off.

grid.below

Alias for rc['axes.axisbelow']. If True, draw gridlines below everything. If True, draw them above everything. If 'line', draw them above patches but below lines and markers.

grid.checkoverlap

Whether to have cartopy automatically check for and remove overlapping GeoAxes gridline labels.

grid.dmslabels

Whether to use degrees-minutes-seconds rather than decimals for cartopy GeoAxes gridlines.

grid.geolabels

Whether to include the 'geo' spine in cartopy >= 0.20 when otherwise toggling left, right, bottom, or top GeoAxes gridline labels.

grid.inlinelabels

Whether to add inline labels for cartopy GeoAxes gridlines.

grid.labels

Whether to add outer labels for GeoAxes gridlines.

grid.labelcolor

Font color for GeoAxes gridline labels.

grid.labelpad

Padding between the map boundary and cartopy GeoAxes gridline labels. Interpreted by units. Numeric units are points.

grid.labelsize

Font size for GeoAxes gridline labels. Must be a relative font size or unit string interpreted by units. Numeric units are points.

grid.labelweight

Font weight for GeoAxes gridline labels.

grid.nsteps

Number of points used to draw cartopy GeoAxes gridlines.

grid.pad

Alias for rc['grid.labelpad'].

grid.rotatelabels

Whether to rotate cartopy GeoAxes gridline labels.

grid.style

Major gridline style. Alias for rc['grid.linestyle'].

grid.width

Major gridline width. Alias for rc['grid.linewidth'].

grid.widthratio

Ratio of minor gridline width to major gridline width.

gridminor

Toggle minor gridlines on and off.

gridminor.alpha

Minor gridline opacity.

gridminor.color

Minor gridline color.

gridminor.linestyle

Minor gridline style.

gridminor.linewidth

Minor gridline width.

gridminor.style

Minor gridline style. Alias for rc['gridminor.linestyle'].

gridminor.width

Minor gridline width. Alias for rc['gridminor.linewidth'].

inlineformat

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

innerborders

Toggles internal political border lines (e.g. states and provinces) on and off.

innerborders.alpha

Opacity for internal political border lines

innerborders.color

Line color for internal political border lines.

innerborders.linewidth

Line width for internal political border lines.

innerborders.zorder

Z-order for internal political border lines.

label.color

Alias for rc['axes.labelcolor'].

label.pad

Alias for rc['axes.labelpad']. Interpreted by units. Numeric units are points.

label.size

Alias for rc['axes.labelsize']. Must be a relative font size or unit string interpreted by units. Numeric units are points.

label.weight

Alias for rc['axes.labelweight'].

lakes

Toggles lake patches on and off.

lakes.alpha

Opacity for lake patches

lakes.color

Face color for lake patches.

lakes.zorder

Z-order for lake patches.

lakes.rasterized

Toggles rasterization on or off for lake feature

land

Toggles land patches on and off.

land.alpha

Opacity for land patches

land.color

Face color for land patches.

land.zorder

Z-order for land patches.

land.rasterized

Toggles the rasterization of the land feature.

leftlabel.color

Font color 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. Numeric units are points.

leftlabel.sharedpad

Padding between row labels and a shared y label on the left-hand side. Interpreted by units. Numeric units are points.

leftlabel.rotation

Rotation for row labels on the left-hand side. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees.

leftlabel.size

Font size for row labels on the left-hand side. Must be a relative font size or unit string interpreted by units. Numeric units are points.

lollipop.markersize

Size of lollipops in the lollipop plot.

lollipop.stemcolor

Color of lollipop lines.

lollipop.stemwidth

Width of the stem

lollipop.stemlinestyle

Line style of lollipop lines.

leftlabel.weight

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

margin

The fractional x and y axis data margins when limits are unset. Alias for rc['axes.margin'].

meta.edgecolor

Color of axis spines, tick marks, tick labels, and labels.

meta.color

Color of axis spines, tick marks, tick labels, and labels. Alias for rc['meta.edgecolor'].

meta.linewidth

Thickness of axis spines and major tick lines.

meta.width

Thickness of axis spines and major tick lines. Alias for rc['meta.linewidth'].

negcolor

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

poscolor

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

ocean

Toggles ocean patches on and off.

ocean.alpha

Opacity for ocean patches

ocean.color

Face color for ocean patches.

ocean.zorder

Z-order for ocean patches.

ocean.rasterized

Turns rasterization on or off for the oceans feature for GeoAxes.

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.pad

Padding between axes content and row labels on the right-hand side. Interpreted by units. Numeric units are points.

rightlabel.sharedpad

Padding between row labels and a shared y label on the right-hand side. Interpreted by units. Numeric units are points.

rightlabel.rotation

Rotation for row labels on the right-hand side. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees.

rightlabel.size

Font size for row labels on the right-hand side. Must be a relative font size or unit string interpreted by units. Numeric units are points.

rightlabel.weight

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

rivers

Toggles river lines on and off.

rivers.alpha

Opacity for river lines.

rivers.color

Line color for river lines.

rivers.linewidth

Line width for river lines.

rivers.zorder

Z-order for river lines.

rivers.rasterized

Toggles rasterization on or off for rivers feature for GeoAxes.

chord.start

Start angle for chord diagrams.

chord.end

End angle for chord diagrams.

chord.space

Inter-sector spacing for chord diagrams.

chord.endspace

Whether to add an ending space gap for chord diagrams.

chord.r_lim

Radial limits for chord diagrams.

chord.ticks_interval

Tick interval for chord diagrams.

chord.order

Ordering of sectors for chord diagrams.

radar.r_lim

Radial limits for radar charts.

radar.vmin

Minimum value for radar charts.

radar.vmax

Maximum value for radar charts.

radar.fill

Whether to fill radar chart polygons.

radar.marker_size

Marker size for radar charts.

radar.bg_color

Background color for radar charts.

radar.circular

Whether to use circular radar charts.

radar.show_grid_label

Whether to show grid labels on radar charts.

radar.grid_interval_ratio

Grid interval ratio for radar charts.

phylogeny.start

Start angle for phylogeny plots.

phylogeny.end

End angle for phylogeny plots.

phylogeny.r_lim

Radial limits for phylogeny plots.

phylogeny.format

Input format for phylogeny plots.

phylogeny.outer

Whether to place phylogeny leaves on the outer edge.

phylogeny.align_leaf_label

Whether to align phylogeny leaf labels.

phylogeny.ignore_branch_length

Whether to ignore branch lengths in phylogeny plots.

phylogeny.leaf_label_size

Leaf label font size for phylogeny plots.

phylogeny.leaf_label_rmargin

Radial margin for phylogeny leaf labels.

phylogeny.reverse

Whether to reverse phylogeny orientation.

phylogeny.ladderize

Whether to ladderize phylogeny branches.

sankey.align

Horizontal alignment of nodes.

sankey.connect

Connection path for Sankey diagram.

sankey.flow_labels

Whether to draw flow labels.

sankey.flow_label_pos

Position of flow labels along the flow.

sankey.flow_sort

Whether to sort flows.

sankey.node_labels

Whether to draw node labels.

sankey.node_label_offset

Offset for node labels.

sankey.node_label_outside

Position of node labels relative to the node.

sankey.other_label

Label for ‘other’ category in Sankey diagram.

sankey.pathlabel

Label for the patch.

sankey.pathlengths

Path lengths for Sankey diagram.

sankey.rotation

Rotation of the Sankey diagram.

sankey.trunklength

Trunk length for Sankey diagram.

subplots.align

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

subplots.equalspace

Whether to make the tight layout algorithm assign the same space for every row and the same space for every column.

subplots.groupspace

Whether to make the tight layout algorithm consider space between only adjacent subplot “groups” rather than every subplot in the row or column.

subplots.innerpad

Padding between adjacent subplots. Interpreted by units. Numeric units are em-widths.

subplots.outerpad

Padding around figure edge. Interpreted by units. Numeric units are em-widths.

subplots.panelpad

Padding between subplots and panels, and between stacked panels. Interpreted by units. Numeric units are em-widths.

subplots.panelwidth

Width of side panels. Interpreted by units. Numeric units are inches.

subplots.refwidth

Default width of the reference subplot. Interpreted by units. Numeric units are inches.

subplots.share

The axis sharing level, one of 0, 1, 2, or 3, or the more intuitive aliases False, 'labels', 'limits', True, or 'auto'. See Figure for details.

subplots.span

Toggles spanning axis labels. See subplots for details.

subplots.tight

Whether to auto-adjust the subplot spaces and figure margins.

subplots.pixelsnap

Whether to snap subplot bounds to the renderer pixel grid during draw.

suptitle.color

Figure title color.

suptitle.pad

Padding between axes content and the figure super title. Interpreted by units. Numeric units are points.

suptitle.size

Figure title font size. Must be a relative font size or unit string interpreted by units. Numeric units are points.

suptitle.weight

Figure title font weight.

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.

tick.labelpad

Padding between ticks and tick labels. Interpreted by units. Numeric units are points.

tick.labelsize

Axis tick label font size. Must be a relative font size or unit string interpreted by units. Numeric units are points.

tick.labelweight

Axis tick label font weight.

tick.len

Length of major ticks in points.

tick.lenratio

Ratio of minor tickline length to major tickline length.

tick.linewidth

Major tickline width.

tick.minor

Toggles minor ticks on and off.

tick.pad

Alias for rc['tick.labelpad'].

tick.width

Major tickline width. Alias for rc['tick.linewidth'].

tick.widthratio

Ratio of minor tickline width to major tickline width.

title.above

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.

title.border

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

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. Numeric units are points.

title.color

Axes title color. Alias for rc['axes.titlecolor'].

title.loc

Title position. For options see the location table.

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. Numeric units are points.

title.size

Axes title font size. Alias for rc['axes.titlesize']. Must be a relative font size or unit string interpreted by units. Numeric units are points.

title.weight

Axes title font weight. Alias for rc['axes.titleweight'].

toplabel.color

Font color 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. Numeric units are points.

toplabel.sharedpad

Padding between column labels and a shared x label on the top of the figure. Interpreted by units. Numeric units are points.

toplabel.rotation

Rotation for column labels at the top of the figure. Must be ‘vertical’, ‘horizontal’, or a float indicating degrees.

toplabel.size

Font size for column labels on the top of the figure. Must be a relative font size or unit string interpreted by units. Numeric units are points.

toplabel.weight

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

unitformat

The format string used to format pint.Quantity default unit labels using format(units, unitformat). See also rc.autoformat.

ultraplot.check_for_latest_version

Whether to check for the latest version of UltraPlot on PyPI when importing

ultraplot.eager_import

Whether to import the full public API during setup instead of lazily.

The ultraplotrc file#

When you import UltraPlot for the first time, a ultraplotrc file is generated with all lines commented out. This file is just like matplotlibrc, except it controls both matplotlib and UltraPlot 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 ~/.UltraPlot/ultraplotrc, but a loose hidden file in the home directory named ~/.ultraplotrc 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 ultraplotrc file. To change the settings for a specific project, place a file named either .ultraplotrc or ultraplotrc in the same directory as your python session, or in an arbitrary parent directory. To generate a ultraplotrc 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 ultraplotrc file, use load().

As an example, a ultraplotrc file containing the default settings is shown below.

#--------------------------------------------------------------------
# Use this file to change the default ultraplot and matplotlib settings.
# The syntax is identical to matplotlibrc syntax. For details see:
# https://ultraplot.readthedocs.io/en/latest/configuration.html
# https://matplotlib.org/stable/tutorials/introductory/customizing.html
#--------------------------------------------------------------------
# ultraplot 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
bar.bar_labels:                     False
borders:                            False
borders.alpha:                      None
borders.color:                      black
borders.linewidth:                  0.6
borders.rasterized:                 False
borders.zorder:                     2.0
bottomlabel.color:                  black
bottomlabel.pad:                    5.0
bottomlabel.rotation:               horizontal
bottomlabel.sharedpad:              10.0
bottomlabel.size:                   med-large
bottomlabel.weight:                 bold
cftime.max_display_ticks:           7
cftime.resolution:                  DAILY
cftime.time_resolution_format:      {SECONDLY: %S, MINUTELY: %M, HOURLY: %H, DAILY: %d, MONTHLY: %m, YEARLY: %Y}
cftime.time_unit:                   days since 2000-01-01
chord.end:                          360.0
chord.endspace:                     True
chord.order:                        None
chord.r_lim:                        97.0, 100.0
chord.space:                        0.0
chord.start:                        0.0
chord.ticks_interval:               None
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.rasterized:                   False
coast.zorder:                       2.0
colorbar.center_levels:             False
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.labelrotation:             auto
colorbar.length:                    1.0
colorbar.loc:                       right
colorbar.outline:                   True
colorbar.rasterized:                False
colorbar.shadow:                    False
colorbar.width:                     0.2
curved_quiver.arrows_at_end:        True
curved_quiver.arrowsize:            1.0
curved_quiver.arrowstyle:           -|>
curved_quiver.density:              10
curved_quiver.grains:               15
curved_quiver.scale:                1.0
cycle:                              colorblind
edgefix:                            True
external.shrink:                    0.9
font.large:                         med-large
font.largesize:                     med-large
font.name:                          sans-serif
font.small:                         medium
font.smallsize:                     medium
formatter.limits:                   -5, 6
formatter.log:                      False
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.choropleth.country_reso:        110m
geo.choropleth.country_territories: False
geo.choropleth.zorder:              None
geo.extent:                         globe
geo.round:                          True
graph.aspect:                       equal
graph.draw_edges:                   True
graph.draw_grid:                    False
graph.draw_labels:                  False
graph.draw_nodes:                   True
graph.draw_spines:                  False
graph.facecolor:                    none
graph.rescale:                      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.rasterized:                   False
lakes.zorder:                       1.0
land:                               False
land.alpha:                         None
land.color:                         black
land.rasterized:                    False
land.zorder:                        1.0
leftlabel.color:                    black
leftlabel.pad:                      5.0
leftlabel.rotation:                 vertical
leftlabel.sharedpad:                10.0
leftlabel.size:                     med-large
leftlabel.weight:                   bold
legend.cat.alpha:                   None
legend.cat.line:                    False
legend.cat.linestyle:               -
legend.cat.linewidth:               2.0
legend.cat.marker:                  o
legend.cat.markeredgecolor:         None
legend.cat.markeredgewidth:         None
legend.cat.markersize:              6.0
legend.geo.alpha:                   None
legend.geo.country_proj:            None
legend.geo.country_reso:            110m
legend.geo.country_territories:     False
legend.geo.edgecolor:               0.25
legend.geo.facecolor:               None
legend.geo.fill:                    None
legend.geo.handlesize:              1.0
legend.geo.linewidth:               1.0
legend.num.alpha:                   None
legend.num.cmap:                    viridis
legend.num.edgecolor:               None
legend.num.format:                  None
legend.num.linewidth:               0.0
legend.num.n:                       5
legend.size.alpha:                  None
legend.size.area:                   True
legend.size.color:                  0.35
legend.size.format:                 None
legend.size.marker:                 o
legend.size.markeredgecolor:        None
legend.size.markeredgewidth:        None
legend.size.minsize:                3.0
legend.size.scale:                  1.0
lollipop.markersize:                36.0
lollipop.stemcolor:                 black
lollipop.stemlinestyle:             -
lollipop.stemwidth:                 0.6
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.rasterized:                   False
ocean.zorder:                       1.0
phylogeny.align_leaf_label:         True
phylogeny.end:                      360.0
phylogeny.format:                   newick
phylogeny.ignore_branch_length:     False
phylogeny.ladderize:                False
phylogeny.leaf_label_rmargin:       2.0
phylogeny.leaf_label_size:          None
phylogeny.outer:                    True
phylogeny.r_lim:                    50.0, 100.0
phylogeny.reverse:                  False
phylogeny.start:                    0.0
poscolor:                           red7
radar.bg_color:                     eeeeee80
radar.circular:                     False
radar.fill:                         True
radar.grid_interval_ratio:          0.2
radar.marker_size:                  0
radar.r_lim:                        0.0, 100.0
radar.show_grid_label:              True
radar.vmax:                         100.0
radar.vmin:                         0.0
reso:                               lo
ribbon.flow.alpha:                  0.58
ribbon.flow.curvature:              0.45
ribbon.nodewidth:                   0.018
ribbon.rowheightratio:              2.2
ribbon.topic_label_box:             True
ribbon.topic_label_offset:          0.028
ribbon.topic_label_size:            7.4
ribbon.topic_labels:                True
ribbon.xmargin:                     0.12
ribbon.ymargin:                     0.08
rightlabel.color:                   black
rightlabel.pad:                     5.0
rightlabel.rotation:                vertical
rightlabel.sharedpad:               10.0
rightlabel.size:                    med-large
rightlabel.weight:                  bold
rivers:                             False
rivers.alpha:                       None
rivers.color:                       black
rivers.linewidth:                   0.6
rivers.rasterized:                  False
rivers.zorder:                      2.0
sankey.align:                       center
sankey.connect:                     0, 0
sankey.flow.alpha:                  0.75
sankey.flow.curvature:              0.5
sankey.flow_label_pos:              0.5
sankey.flow_labels:                 False
sankey.flow_sort:                   True
sankey.margin:                      0.05
sankey.node.facecolor:              0.75
sankey.node_label_offset:           0.01
sankey.node_label_outside:          auto
sankey.node_labels:                 True
sankey.nodepad:                     0.02
sankey.nodewidth:                   0.03
sankey.other_label:                 Other
sankey.pathlabel:                   
sankey.pathlengths:                 0.25
sankey.rotation:                    0.0
sankey.trunklength:                 1.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.pixelsnap:                 False
subplots.refwidth:                  2.5
subplots.share:                     auto
subplots.span:                      True
subplots.tight:                     True
suptitle.color:                     black
suptitle.pad:                       5.0
suptitle.size:                      med-large
suptitle.weight:                    bold
text.align:                         False
text.align.arrows:                  False
text.align.maxiter:                 60
text.align.pad:                     2.0
text.borderstyle:                   bevel
text.curved.avoid_overlap:          True
text.curved.curvature_pad:          2.0
text.curved.ellipsis:               False
text.curved.min_advance:            1.0
text.curved.overlap_tol:            0.1
text.curved.upright:                True
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.sharedpad:                 10.0
toplabel.size:                      med-large
toplabel.weight:                    bold
ultraplot.check_for_latest_version: False
ultraplot.eager_import:             False
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
image.interpolation:         none
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.fallback:           stixsans
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.labelcolor:            black
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.labelcolor:            black
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