wb_plot

wb_plot(
    width=1200,
    height=800,
    dpi=120,
    nrows=1,
    ncols=1,
    save_path=None,
    title=None,
    subtitle=None,
    note=None,
    legend_title=None,
    palette=None,
    palette_n=None,
    palette_bins=None,
    palette_bin_mode='linear',
    include_insets=False,
    backend='mpl',
    show=True,
)

Create a standardized plotting theme via a decorator for the World Bank with consistent styling, titles, legends, and optional export. Handles both discrete and continuous color logic. Supports Matplotlib (default) and Plotly backends.

The World Bank’s data visualization style guide can be accessed here.

Parameters

Name	Type	Description	Default
width	int	Width of the figure in pixels.	1200
height	int	Height of the figure in pixels.	800
dpi	int	Resolution of the figure in dots per inch (Matplotlib only).	120
nrows	int	Number of subplot rows (Matplotlib only).	1
ncols	int	Number of subplot columns (Matplotlib only).	1
save_path	str or Path	File path to save the rendered figure. If None, the figure is not saved. For Plotly, saves as HTML.	None
title	str	Main title displayed at the top of the figure.	None
subtitle	str	Subtitle displayed below the main title.	None
note	str, tuple, or list	Footnote or caption at the bottom. Can be a string, a single (label, text) tuple, or a list of such tuples (e.g. [("Source:", "World Bank."), ("Note:", "Preliminary.")]).	None
legend_title	str	Title displayed above the legend entries (bold). If provided, appears above the legend keys.	None
palette	str, sequence, or Colormap	Color palette. Supports discrete (cycled), label-mapped, and continuous palettes (Matplotlib Colormap / Plotly colorscale). See “Colours and palettes” in Other tips for names.	None
palette_n	int	Number of colors to sample from the palette.	None
palette_bins	int, sequence, or None	Binning for continuous palettes (Matplotlib only): None = continuous; int = number of bins; sequence = explicit bin edges.	None
palette_bin_mode	{“linear”, “quantile”}	Method for discretizing when palette_bins is set (Matplotlib only).	"linear"
include_insets	bool	Whether to include inset axes in styling (Matplotlib only).	False
backend	{“mpl”, “plotly”}	Rendering backend: "mpl" = Matplotlib (default), "plotly" = Plotly.	"mpl"
show	bool	If True, display the figure; if False, create but do not show (e.g. for programmatic use).	True

Notes

Matplotlib backend

• For discrete (categorical) palettes, the function sets axes.prop_cycle before plotting.
• For label-mapped palettes, it recolors plot elements and their legend entries by label.
• For continuous palettes, it creates a Colormap and, if palette_bins is specified, generates a ListedColormap and BoundaryNorm. These are applied to compatible artists (e.g. imshow, pcolormesh, contourf), and colorbars are refreshed automatically.
• Your plotting function should accept (fig, axs, *args, **kwargs) (or legacy (axs, *args, **kwargs)). Use nrows and ncols for subplots; axs is an array of axes.

Plotly backend

• The decorated function should accept fig as the first parameter (and any other arguments you pass when calling it). Add traces with fig.add_scatter, fig.add_bar, etc.
• Palettes are applied via Plotly’s colorway (discrete) or colorscale (continuous).
• Title, subtitle, and note are rendered in the layout; legends are positioned below the plot automatically.

Returns

• Plotly: The decorated function returns the Plotly figure (so it renders in Quarto/Jupyter).
• Matplotlib: If show=True (default), returns None so Quarto/Jupyter do not print (fig, axs). If show=False, returns (fig, axs) where fig is the figure and axs is the array of subplot axes.