solarwindpy.plotting.tools

Utility functions for common matplotlib tasks.

These helpers provide shortcuts for creating figures, saving output, and building grids of axes with shared colorbars.

Functions

build_ax_array_with_common_colorbar([nrows, ...])

Build an array of axes that share a colour bar.

calculate_nrows_ncols(n)

Determine a sensible (nrows, ncols) pair for n axes.

joint_legend(*axes[, idx_for_legend])

Create a combined legend for multiple axes.

multipanel_figure_shared_cbar(nrows, ncols)

Create a grid of axes that share a single colorbar.

save(fig, spath[, add_info, info_x, info_y, ...])

Save a figure in both PDF and PNG formats.

subplots([nrows, ncols, scale_width, ...])

Create a grid of subplots with a scaled figure size.
subplots(nrows=1, ncols=1, scale_width=1.0, scale_height=1.0, **kwargs)[source]

Create a grid of subplots with a scaled figure size.

Parameters:

  • nrows (int, optional) – Number of subplot rows.

  • ncols (int, optional) – Number of subplot columns.

  • scale_width (float, optional) – Factor applied to the default figure width.

  • scale_height (float, optional) – Factor applied to the default figure height.

  • **kwargs – Additional keyword arguments passed directly to matplotlib.pyplot.subplots().

Returns:

Examples

>>> fig, ax = subplots(2, 2, scale_width=1.5)
save(fig, spath, add_info=True, info_x=0, info_y=0, log=True, pdf=True, png=True, **kwargs)[source]

Save a figure in both PDF and PNG formats.

Parameters:

  • fig (matplotlib.figure.Figure or matplotlib.axes.Axes) – The figure or axis to save.

  • spath (pathlib.Path) – Base path for the output files. The appropriate extension will be added automatically.

  • add_info (bool, optional) – If True, add an attribution and timestamp to the bottom left of the PNG version.

  • info_x (float, optional) – X-position of the attribution text in figure coordinates.

  • info_y (float, optional) – Y-position of the attribution text in figure coordinates.

  • log (bool, optional) – If True, write information about the saved files to alog.

  • pdf (bool, optional) – Save a PDF version of the figure.

  • png (bool, optional) – Save a PNG version of the figure.

  • **kwargs – Additional keyword arguments passed to Figure.savefig().

Return type:

None

Examples

>>> fig, ax = subplots()
>>> save(fig, Path('my_plot'))
joint_legend(*axes, idx_for_legend=-1, **kwargs)[source]

Create a combined legend for multiple axes.

Parameters:

  • *axes (matplotlib.axes.Axes) – Axes objects from which to collect legend handles and labels.

  • idx_for_legend (int, optional) – Index of the axis (after flattening) on which to place the legend. By default the legend is placed on the last axis. idx_for_legend=-1 assumes that the last axis is on the right hand side of the figure.

  • **kwargs – Extra keyword arguments forwarded to Axes.legend().

Returns:

legend

Return type:

matplotlib.legend.Legend

Examples

>>> fig, ax = subplots(1, 2)
>>> ax[0].plot([1, 2], label='a')
[<matplotlib.lines.Line2D object at 0x...>]
>>> ax[1].plot([2, 3], label='b')
[<matplotlib.lines.Line2D object at 0x...>]
>>> joint_legend(ax[0], ax[1])
<matplotlib.legend.Legend object at 0x...>
multipanel_figure_shared_cbar(nrows: int, ncols: int, vertical_cbar: bool = True, sharex: bool = True, sharey: bool = True, **kwargs)[source]

Create a grid of axes that share a single colorbar.

This is a lightweight wrapper around build_ax_array_with_common_colorbar() for backward compatibility.

Parameters:

  • nrows (int) – Shape of the axes grid.

  • ncols (int) – Shape of the axes grid.

  • vertical_cbar (bool, optional) – If True the colorbar is placed to the right of the axes; otherwise it is placed above them.

  • sharex (bool, optional) – If True share the respective axis limits across all panels.

  • sharey (bool, optional) – If True share the respective axis limits across all panels.

  • **kwargs – Additional arguments controlling layout such as figsize or grid ratios.

Returns:

Examples

>>> fig, axs, cax = multipanel_figure_shared_cbar(2, 2)
build_ax_array_with_common_colorbar(nrows=1, ncols=1, cbar_loc='top', fig_kwargs=None, gs_kwargs=None)[source]

Build an array of axes that share a colour bar.

Parameters:

  • nrows (int, optional) – Desired grid shape.

  • ncols (int, optional) – Desired grid shape.

  • cbar_loc ({"top", "bottom", "left", "right"}, optional) – Location of the colorbar relative to the axes grid.

  • fig_kwargs (dict, optional) – Keyword arguments forwarded to matplotlib.pyplot.figure().

  • gs_kwargs (dict, optional) – Additional options for matplotlib.gridspec.GridSpec.

Returns:

Examples

>>> fig, axes, cax = build_ax_array_with_common_colorbar(2, 3, cbar_loc='right')
calculate_nrows_ncols(n)[source]

Determine a sensible (nrows, ncols) pair for n axes.

The heuristic attempts to generate a nearly square layout while also taking typical display aspect ratios into account.

Parameters:

n (int) – Total number of axes required.

Returns:

  • nrows (int)

  • ncols (int)

Examples

>>> calculate_nrows_ncols(5)
(...2..., ...3...)