From d2569a35729e1c7fd123f632c6463183abfab647 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Wed, 1 Nov 2023 13:29:06 +0100 Subject: [PATCH] Clarify semantics of plt.matshow(..., fignum=...). The semantics of the fignum parameter are rather confusing (in particular wrt. whether the figure gets resized or not -- it only does if fignum=(None or a non-existing figure number) (which creates a new figure), but not if fignum=0 (which also creates a new figure). It's probably not worth fixing that (if anything we should just point users to Axes.matshow, which is just fine), but we can still improve the documentation. --- lib/matplotlib/pyplot.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 7f4aa12c9ed6..c8822b97f418 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -2412,18 +2412,15 @@ def matshow(A: ArrayLike, fignum: None | int = None, **kwargs) -> AxesImage: The matrix to be displayed. fignum : None or int - If *None*, create a new figure window with automatic numbering. + If *None*, create a new, appropriately sized figure window. - If a nonzero integer, draw into the figure with the given number - (create it if it does not exist). + If 0, use the current Axes (creating one if there is none, without ever + adjusting the figure size). - If 0, use the current axes (or create one if it does not exist). - - .. note:: - - Because of how `.Axes.matshow` tries to set the figure aspect - ratio to be the one of the array, strange things may happen if you - reuse an existing figure. + Otherwise, create a new Axes on the figure with the given number + (creating it at the appropriate size if it does not exist, but not + adjusting the figure size otherwise). Note that this will be drawn on + top of any preexisting Axes on the figure. Returns -------