Behavior Changes
----------------


``pyplot.subplot`` and ``pyplot.subplot_mosaic`` raise *ValueError* on existing figures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Passing a *num* argument to `~.pyplot.subplots` or `~.pyplot.subplot_mosaic` that refers
to an existing figure or is a ``Figure`` instance now raises a `ValueError`.

These utility functions are intended strictly for the creation of new figures and
subplots. Previously, they accidentally allowed the reuse of existing figures because
they internally called `~.pyplot.figure`. This change ensures that these functions
strictly follow their documented purpose of creating new figures.

To reuse an existing figure, clear it first using ``clear=True``:

.. code-block:: python

    fig, axs = plt.subplots(num=1, clear=True)
    # or
    fig, axd = plt.subplot_mosaic([['A', 'B']], num=1, clear=True)

If you have a ``Figure`` instance and want to add subplots to it, use the
object-oriented API:

.. code-block:: python

    fig.subplots(nrows=2, ncols=2)
    # or
    fig.subplot_mosaic([['A', 'B']])

Complex layouts and constrained layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Constrained layout now produces smaller spacing between subplots in some circumstances.
This should only affect complex layouts where rows or columns contain different numbers
of subplots, for example a layout created with ``plt.subplot_mosaic('AC;BC',
layout='constrained')``.

Bivariate colormaps now fully span the intended range of colors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bivariate colormaps generated by ``SegmentedBivarColormap`` (e.g., ``BiOrangeBlue``)
from a set of input colors now fully span that range of colors. There had been a bug
with the numerical interpolation such that the colormap did not actually include the
first or last colors.

Rendering of images now more accurate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There have been several fixes to improve the accuracy of how images are resampled and
placed during rendering. Some inaccuracies were up to a pixel off in the output. The
most apparent improvement is that the alignment of data pixels with tick marks and grid
lines is now reliable. Nearly all image output has changed, but often only at a subtle
level that is not obvious qualitatively.

*alpha* parameter handling on images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prior to Matplotlib 3.10.1, when passing an array to ``imshow(..., alpha=...)``, the
parameter was silently ignored if the image data was an RGB or RGBA image or if
:rc:`image.interpolation_stage` resolved to "rbga".

Matplotlib 3.10.1 changed this to apply the alpha array as the alpha channel,
overwriting any existing transparency information in the image data. Matplotlib 3.11.0
further fixes the handling for RGBA images: the existing alpha channel is now multiplied
by the alpha array, consistent with how scalar alpha values are handled.

Legend labels for ``plot``
~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously if a sequence was passed to the *label* parameter of `~.Axes.plot` when
plotting a single dataset, the sequence was automatically cast to string for the legend
label. Now, if the sequence length is not one an error is raised. To keep the old
behavior, cast the sequence to string before passing.

Mixing positional and keyword arguments for ``legend`` handles and labels...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

... is no longer valid. If passing *handles* and *labels* to ``legend``, they must now
be passed either both positionally or both as keyword arguments.

``Axes.add_collection(..., autolim=True)`` updates view limits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Axes.add_collection(..., autolim=True)`` has so far only updated the data limits, and
calling `.Axes.autoscale_view` was also necessary to update the view limits. View limits
are now updated as well if ``autolim=True``, using a lazy internal update mechanism, so
that the costs only apply once also if you add multiple collections.

``relim()`` now accounts for Collection artists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously, `~.axes.Axes.relim` did not recalculate data limits for `.Collection`
artists (e.g. those created by `~.axes.Axes.scatter`). Calling ``ax.relim()`` followed
by ``ax.autoscale_view()`` now correctly includes scatter plots and other collections in
the axes limits.

hist2d no longer forces axes limits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously, `.Axes.hist2d` would force the axes x and y limits to the extents of the
histogrammed data, ignoring any other artists. `.Axes.hist2d` now behaves similarly to
`.Axes.imshow`: axes limits are updated to fit the data, but autoscaling is not
otherwise disabled.

Axes.violinplot and cbook.violin_stats ignore non-finite values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`~matplotlib.axes.Axes.violinplot` and `matplotlib.cbook.violin_stats` now ignore masked
and non-finite (NaN and inf) values.

Minor log tick labels are set by number of major log ticks, not number of decades spanned
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously, by default, on a log-scaled axis, the minor ticks would be unlabeled if the
axis limits spanned more than one decade. The meaning of the *minor_thresholds*
parameter to `.LogFormatter` has been altered so that the decision of whether to label
the minor ticks is now based on the number of major ticks drawn within the axis limits.

For example, for an axis spanning from 4 to 60 (with thus a single major log tick, at
10), minor ticks are now labeled, even though the axis spans more than one decade.

Setting titles of figures using webagg backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously when using the ``webagg`` backend the title of a figure was set using
``figure.set_label``. Now it is set using ``figure.canvas.manager.set_window_title``
which is more consistent with other backends.

Default name of ``ListedColormap``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default name of `.ListedColormap` has changed from "from_list" to "unnamed".

``font_manager.findfont`` logs if selected font weight does not match requested
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When searching for a font with a weight specified, if the best-matched font differs in
weight, then a warning will be logged.

FT2Font no longer sets a default size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the interest of handling non-scalable fonts and reducing font initialization, the
`.FT2Font` constructor no longer sets a default size. Non-scalable fonts are sometimes
used for bitmap-backed emoji fonts.

If metrics are important (i.e., if you are loading character glyphs, or setting a text
string), then explicitly call `.FT2Font.set_size` beforehand.

``mathtext.VectorParse`` now includes glyph indices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a *path*-outputting `.MathTextParser`, in the return value of
`~.MathTextParser.parse`, (a `.VectorParse`), the *glyphs* field is now a list
containing tuples of:

- font: `.FT2Font`
- fontsize: `float`
- character code: `int`
- glyph index: `int`
- x: `float`
- y: `float`

Specifically, the glyph index was added after the character code.

SVG links open in new tab or window
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`.Artist.set_url` allows to turn the Artist into a link. In SVG output, this has been
implemented without specifying a `target`_ attribute. The default target value "_self"
resulted in replacing the SVG document with the linked page when the link was clicked.

The target is now set to "_blank" so that the link opens in a new tab or window.

.. _target: https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/target

``matplotlib.testing.check_figures_equal`` defaults to PNG only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In most cases, checking that figures are equal with `.check_figures_equal` does not
depend on the file format. Consequently, the *extensions* parameter now defaults to
``['png']`` instead of ``['png', 'pdf', 'svg']``, reducing default test requirements.

Default *style* parameter of ``image_comparison``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The *style* parameter of the `.image_comparison` decorator will become 'mpl20' in
Matplotlib 3.13. Not passing it and relying on the previous default will warn until the
change occurs.

Windows configuration directory location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Windows, the default configuration and cache directories now use
``%LOCALAPPDATA%\matplotlib`` instead of ``%USERPROFILE%\.matplotlib``. This follows
Windows application data storage conventions.

The ``MPLCONFIGDIR`` environment variable can still be used to override this default.
