SavedFigure

class stonerplots.SavedFigure(filename=None, style=None, autoclose=False, formats=None, include_open=False)

Bases: _TrackNewFiguresAndAxes, _PreserveFigureMixin

A context manager for applying plotting styles and saving matplotlib figures.

This class simplifies the process of managing figure styling and saving multiple figures within a single context. It allows for automatic application of matplotlib stylesheets and handles the generation of unique filenames for figures, taking into account user-provided templates and output formats. SavedFigure can be reused across multiple with blocks, and its settings can dynamically be reconfigured by calling the instance with new parameters.

Args:

filename (str, Path, None):

The base filename or target directory for saving figures. - If filename is a directory, the figure’s label is used to generate the filename. - If filename includes placeholders (e.g., {label}, {number}), they will be replaced dynamically.

style (list[str], str, None):

One or more matplotlib stylesheets to apply. If a single string is provided, it is split by commas to form a list of styles. Defaults to [“stoner”].

autoclose (bool):

Determines whether figures should be closed automatically after being saved. Default is False.

formats (str, list[str], None):

The output file formats for saved figures (e.g., “png”, “pdf”). Can be a comma-separated string, a list of strings, or None (default: [“png”]).

include_open (bool):

If True, any figures opened before entering the context are included for saving. Default is False.

Attributes:

filename (Path):

A property representing the base filename or directory for saving figures.

formats (list[str]):

A list of file formats to save the figures (e.g., [“png”, “pdf”]).

style (list[str]):

A list of stylesheets to apply to the figures.

autoclose (bool):

Indicates whether figures are closed after being saved.

include_open (bool):

Determines whether figures already open before entering the context are saved.

Notes:

• SavedFigure can identify and save only the new figures created while inside its context, unless include_open is set to True.

• filename and formats parameters support dynamic placeholders: - {number}: Figure number. - {label}: Figure label. - {alpha}, {Alpha}: Counter in lowercase or uppercase. - {roman}, {Roman}: Roman numeral (lowercase/uppercase).

• Files are automatically numbered if placeholders are missing and multiple figures are created.

Examples:

Saving two figures in the same context:

>>> cm = SavedFigure(filename="plots/figure_{label}.png", style="default", autoclose=True)
>>> with cm:
...     plt.figure("plot1")
...     plt.plot([1, 2, 3], [4, 5, 6])
...     plt.show()
...     plt.figure("plot2")
...     plt.plot([7, 8, 9], [10, 11, 12])
...     plt.show()

After exiting the context, SavedFigure will save: - plots/figure_plot1.png - plots/figure_plot2.png

Dynamically updating SavedFigure settings during reuse:

>>> with cm(formats=["pdf", "png"]):
...     plt.figure("plot3")
...     plt.plot([3, 4, 5], [9, 8, 7])
...     plt.show()

This saves: - plots/figure_plot3.pdf - plots/figure_plot3.png