.. redirect-from:: /users/prev_whats_new/whats_new_3.10.0
For a list of all of the issues and pull requests since the last revision, see the :ref:`github-stats`.
Table of Contents
- What's new in Matplotlib 3.10.0 (December 13, 2024)
- Accessible Colors
- Plotting and Annotation improvements
- Specifying a single color in
contourandcontourf - Vectorized
histstyle parameters InsetIndicatorartistmatplotlib.ticker.EngFormattercan computes offsets now- Fix padding of single colorbar for
ImageGrid ax.tablewill accept a pandas DataFrame- Subfigures are now added in row-major order
boxplotandbxporientation parameterviolinplotandviolinorientation parameterFillBetweenPolyCollectionmatplotlib.colorizer.Colorizeras container fornormandcmap
- Specifying a single color in
- 3D plotting improvements
- Preliminary support for free-threaded CPython 3.13
- Other Improvements
.. toctree:: :maxdepth: 4
A new color cycle named 'petroff10' was added. This cycle was constructed using a combination of algorithmically-enforced accessibility constraints, including color-vision-deficiency modeling, and a machine-learning-based aesthetics model developed from a crowdsourced color-preference survey. It aims to be both generally pleasing aesthetically and colorblind accessible such that it could serve as a default in the aim of universal design. For more details see Petroff, M. A.: "Accessible Color Sequences for Data Visualization" and related SciPy talk. A demonstration is included in the style sheets reference. To load this color cycle in place of the default:
import matplotlib.pyplot as plt
plt.style.use('petroff10')
Three diverging colormaps have been added: "berlin", "managua", and "vanimo". They are dark-mode diverging colormaps, with minimum lightness at the center, and maximum at the extremes. These are taken from F. Crameri's Scientific colour maps version 8.0.1 (DOI: https://doi.org/10.5281/zenodo.1243862).
.. plot::
:include-source: true
:alt: Example figures using "imshow" with dark-mode diverging colormaps on positive and negative data. First panel: "berlin" (blue to red with a black center); second panel: "managua" (orange to cyan with a dark purple center); third panel: "vanimo" (pink to green with a black center).
import numpy as np
import matplotlib.pyplot as plt
vals = np.linspace(-5, 5, 100)
x, y = np.meshgrid(vals, vals)
img = np.sin(x*y)
_, ax = plt.subplots(1, 3)
ax[0].imshow(img, cmap="berlin")
ax[1].imshow(img, cmap="managua")
ax[2].imshow(img, cmap="vanimo")
~.Axes.contour and ~.Axes.contourf previously accepted a single color provided it was expressed as a string. This restriction has now been removed and a single color in any format described in the :ref:`colors_def` tutorial may be passed.
.. plot::
:include-source: true
:alt: Two-panel example contour plots. The left panel has all transparent red contours. The right panel has all dark blue contours.
import matplotlib.pyplot as plt
fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(6, 3))
z = [[0, 1], [1, 2]]
ax1.contour(z, colors=('r', 0.4))
ax2.contour(z, colors=(0.1, 0.2, 0.5))
plt.show()
The parameters hatch, edgecolor, facecolor, linewidth and linestyle of the ~matplotlib.axes.Axes.hist method are now vectorized. This means that you can pass in individual parameters for each histogram when the input x has multiple datasets.
.. plot::
:include-source: true
:alt: Four charts, each displaying stacked histograms of three Poisson distributions. Each chart differentiates the histograms using various parameters: top left uses different linewidths, top right uses different hatches, bottom left uses different edgecolors, and bottom right uses different facecolors. Each histogram on the left side also has a different edgecolor.
import matplotlib.pyplot as plt
import numpy as np
np.random.seed(19680801)
fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(9, 9))
data1 = np.random.poisson(5, 1000)
data2 = np.random.poisson(7, 1000)
data3 = np.random.poisson(10, 1000)
labels = ["Data 1", "Data 2", "Data 3"]
ax1.hist([data1, data2, data3], bins=range(17), histtype="step", stacked=True,
edgecolor=["red", "green", "blue"], linewidth=[1, 2, 3])
ax1.set_title("Different linewidths")
ax1.legend(labels)
ax2.hist([data1, data2, data3], bins=range(17), histtype="barstacked",
hatch=["/", ".", "*"])
ax2.set_title("Different hatch patterns")
ax2.legend(labels)
ax3.hist([data1, data2, data3], bins=range(17), histtype="bar", fill=False,
edgecolor=["red", "green", "blue"], linestyle=["--", "-.", ":"])
ax3.set_title("Different linestyles")
ax3.legend(labels)
ax4.hist([data1, data2, data3], bins=range(17), histtype="barstacked",
facecolor=["red", "green", "blue"])
ax4.set_title("Different facecolors")
ax4.legend(labels)
plt.show()
~.Axes.indicate_inset and ~.Axes.indicate_inset_zoom now return an instance of ~matplotlib.inset.InsetIndicator which contains the rectangle and connector patches. These patches now update automatically so that
ax.indicate_inset_zoom(ax_inset)
ax_inset.set_xlim(new_lim)now gives the same result as
ax_inset.set_xlim(new_lim)
ax.indicate_inset_zoom(ax_inset)matplotlib.ticker.EngFormatter has gained the ability to show an offset text near the
axis. Using logic shared with matplotlib.ticker.ScalarFormatter, it is capable of
deciding whether the data qualifies having an offset and show it with an appropriate SI
quantity prefix, and with the supplied unit.
To enable this new behavior, simply pass useOffset=True when you
instantiate matplotlib.ticker.EngFormatter. See example
:doc:`/gallery/ticks/engformatter_offset`.
.. plot:: gallery/ticks/engformatter_offset.py
ImageGrid with cbar_mode="single" no longer adds the axes_pad between the
axes and the colorbar for cbar_location "left" and "bottom". If desired, add additional spacing
using cbar_pad.
The ~.axes.Axes.table method can now accept a Pandas DataFrame for the cellText argument.
import matplotlib.pyplot as plt
import pandas as pd
data = {
'Letter': ['A', 'B', 'C'],
'Number': [100, 200, 300]
}
df = pd.DataFrame(data)
fig, ax = plt.subplots()
table = ax.table(df, loc='center') # or table = ax.table(cellText=df, loc='center')
ax.axis('off')
plt.show()Figure.subfigures are now added in row-major order for API consistency.
.. plot::
:include-source: true
:alt: Example of creating 3 by 3 subfigures.
import matplotlib.pyplot as plt
fig = plt.figure()
subfigs = fig.subfigures(3, 3)
x = np.linspace(0, 10, 100)
for i, sf in enumerate(fig.subfigs):
ax = sf.subplots()
ax.plot(x, np.sin(x + i), label=f'Subfigure {i+1}')
sf.suptitle(f'Subfigure {i+1}')
ax.set_xticks([])
ax.set_yticks([])
plt.show()
Boxplots have a new parameter orientation: {"vertical", "horizontal"} to change the orientation of the plot. This replaces the deprecated vert: bool parameter.
.. plot::
:include-source: true
:alt: Example of creating 4 horizontal boxplots.
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
np.random.seed(19680801)
all_data = [np.random.normal(0, std, 100) for std in range(6, 10)]
ax.boxplot(all_data, orientation='horizontal')
plt.show()
Violinplots have a new parameter orientation: {"vertical", "horizontal"} to change the orientation of the plot. This will replace the deprecated vert: bool parameter.
.. plot::
:include-source: true
:alt: Example of creating 4 horizontal violinplots.
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
np.random.seed(19680801)
all_data = [np.random.normal(0, std, 100) for std in range(6, 10)]
ax.violinplot(all_data, orientation='horizontal')
plt.show()
The new class :class:`matplotlib.collections.FillBetweenPolyCollection` provides
the set_data method, enabling e.g. resampling
(:file:`galleries/event_handling/resample.html`).
:func:`matplotlib.axes.Axes.fill_between` and
:func:`matplotlib.axes.Axes.fill_betweenx` now return this new class.
import numpy as np
from matplotlib import pyplot as plt
t = np.linspace(0, 1)
fig, ax = plt.subplots()
coll = ax.fill_between(t, -t**2, t**2)
fig.savefig("before.png")
coll.set_data(t, -t**4, t**4)
fig.savefig("after.png")matplotlib.colorizer.Colorizer encapsulates the data-to-color pipeline. It makes reuse of colormapping easier, e.g. across multiple images. Plotting methods that support norm and cmap keyword arguments now also accept a colorizer keyword argument.
In the following example the norm and cmap are changed on multiple plots simultaneously:
.. plot::
:include-source: true
:alt: Example use of a matplotlib.colorizer.Colorizer object
import matplotlib.pyplot as plt
import matplotlib as mpl
import numpy as np
x = np.linspace(-2, 2, 50)[np.newaxis, :]
y = np.linspace(-2, 2, 50)[:, np.newaxis]
im_0 = 1 * np.exp( - (x**2 + y**2 - x * y))
im_1 = 2 * np.exp( - (x**2 + y**2 + x * y))
colorizer = mpl.colorizer.Colorizer()
fig, axes = plt.subplots(1, 2, figsize=(6, 2))
cim_0 = axes[0].imshow(im_0, colorizer=colorizer)
fig.colorbar(cim_0)
cim_1 = axes[1].imshow(im_1, colorizer=colorizer)
fig.colorbar(cim_1)
colorizer.vmin = 0.5
colorizer.vmax = 2
colorizer.cmap = 'RdBu'
All plotting methods that use a data-to-color pipeline now create a colorizer object if one is not provided. This can be reused by subsequent artists such that they will share a single data-to-color pipeline:
.. plot::
:include-source: true
:alt: Example of how artists that share a ``colorizer`` have coupled colormaps
import matplotlib.pyplot as plt
import matplotlib as mpl
import numpy as np
x = np.linspace(-2, 2, 50)[np.newaxis, :]
y = np.linspace(-2, 2, 50)[:, np.newaxis]
im_0 = 1 * np.exp( - (x**2 + y**2 - x * y))
im_1 = 2 * np.exp( - (x**2 + y**2 + x * y))
fig, axes = plt.subplots(1, 2, figsize=(6, 2))
cim_0 = axes[0].imshow(im_0, cmap='RdBu', vmin=0.5, vmax=2)
fig.colorbar(cim_0)
cim_1 = axes[1].imshow(im_1, colorizer=cim_0.colorizer)
fig.colorbar(cim_1)
cim_1.cmap = 'rainbow'
The new method .Axes3D.fill_between allows to fill the surface between two 3D lines with polygons.
.. plot::
:include-source:
:alt: Example of 3D fill_between
N = 50
theta = np.linspace(0, 2*np.pi, N)
x1 = np.cos(theta)
y1 = np.sin(theta)
z1 = 0.1 * np.sin(6 * theta)
x2 = 0.6 * np.cos(theta)
y2 = 0.6 * np.sin(theta)
z2 = 2 # Note that scalar values work in addition to length N arrays
fig = plt.figure()
ax = fig.add_subplot(projection='3d')
ax.fill_between(x1, y1, z1, x2, y2, z2,
alpha=0.5, edgecolor='k')
Rotating three-dimensional plots with the mouse has been made more intuitive. The plot now reacts the same way to mouse movement, independent of the particular orientation at hand; and it is possible to control all 3 rotational degrees of freedom (azimuth, elevation, and roll). By default, it uses a variation on Ken Shoemake's ARCBALL [1]. The particular style of mouse rotation can be set via :rc:`axes3d.mouserotationstyle`. See also :ref:`toolkit_mouse-rotation`.
To revert to the original mouse rotation style,
create a file matplotlibrc with contents:
axes3d.mouserotationstyle: azel
To try out one of the various mouse rotation styles:
import matplotlib as mpl
mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball' # 'azel', 'trackball', 'sphere', or 'arcball'
import numpy as np
import matplotlib.pyplot as plt
from matplotlib import cm
ax = plt.figure().add_subplot(projection='3d')
X = np.arange(-5, 5, 0.25)
Y = np.arange(-5, 5, 0.25)
X, Y = np.meshgrid(X, Y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)
surf = ax.plot_surface(X, Y, Z, cmap=cm.coolwarm,
linewidth=0, antialiased=False)
plt.show()
| [1] | Ken Shoemake, "ARCBALL: A user interface for specifying three-dimensional rotation using a mouse", in Proceedings of Graphics Interface '92, 1992, pp. 151-156, https://doi.org/10.20380/GI1992.18 |
All 3D plotting functions now support the axlim_clip keyword argument, which will clip the data to the axes view limits, hiding all data outside those bounds. This clipping will be dynamically applied in real time while panning and zooming.
Please note that if one vertex of a line segment or 3D patch is clipped, then the entire segment or patch will be hidden. Not being able to show partial lines or patches such that they are "smoothly" cut off at the boundaries of the view box is a limitation of the current renderer.
.. plot::
:include-source: true
:alt: Example of default behavior (blue) and axlim_clip=True (orange)
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
x = np.arange(-5, 5, 0.5)
y = np.arange(-5, 5, 0.5)
X, Y = np.meshgrid(x, y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)
# Note that when a line has one vertex outside the view limits, the entire
# line is hidden. The same is true for 3D patches (not shown).
# In this example, data where x < 0 or z > 0.5 is clipped.
ax.plot_wireframe(X, Y, Z, color='C0')
ax.plot_wireframe(X, Y, Z, color='C1', axlim_clip=True)
ax.set(xlim=(0, 10), ylim=(-5, 5), zlim=(-1, 0.5))
ax.legend(['axlim_clip=False (default)', 'axlim_clip=True'])
Matplotlib 3.10 has preliminary support for the free-threaded build of CPython 3.13. See https://py-free-threading.github.io, PEP 703 and the CPython 3.13 release notes for more detail about free-threaded Python.
Support for free-threaded Python does not mean that Matplotlib is wholly thread safe. We
expect that use of a Figure within a single thread will work, and though input data is
usually copied, modification of data objects used for a plot from another thread may
cause inconsistencies in cases where it is not. Use of any global state (such as the
pyplot module) is highly discouraged and unlikely to work consistently. Also note
that most GUI toolkits expect to run on the main thread, so interactive usage may be
limited or unsupported from other threads.
If you are interested in free-threaded Python, for example because you have a multiprocessing-based workflow that you are interested in running with Python threads, we encourage testing and experimentation. If you run into problems that you suspect are because of Matplotlib, please open an issue, checking first if the bug also occurs in the “regular” non-free-threaded CPython 3.13 build.
:rc:`svg.id` lets you insert an id attribute into the top-level <svg> tag.
e.g. rcParams["svg.id"] = "svg1" results in
<svg
xmlns:xlink="http://www.w3.org/1999/xlink"
width="50pt" height="50pt"
viewBox="0 0 50 50"
xmlns="http://www.w3.org/2000/svg"
version="1.1"
id="svg1"
></svg>This is useful if you would like to link the entire matplotlib SVG file within
another SVG file with the <use> tag.
<svg>
<use
width="50" height="50"
xlink:href="mpl.svg#svg1" id="use1"
x="0" y="0"
/></svg>Where the #svg1 indicator will now refer to the top level <svg> tag, and
will hence result in the inclusion of the entire file.
By default, no id tag is included.
The exception raised when an invalid keyword parameter is passed now includes
that parameter name as the exception's name property. This provides more
control for exception handling:
import matplotlib.pyplot as plt
def wobbly_plot(args, **kwargs):
w = kwargs.pop('wobble_factor', None)
try:
plt.plot(args, **kwargs)
except AttributeError as e:
raise AttributeError(f'wobbly_plot does not take parameter {e.name}') from e
wobbly_plot([0, 1], wibble_factor=5)AttributeError: wobbly_plot does not take parameter wibble_factor
Figures using the Agg renderer are now limited to 2**23 pixels in each direction, instead of 2**16. Additionally, bugs that caused artists to not render past 2**15 pixels horizontally have been fixed.
Note that if you are using a GUI backend, it may have its own smaller limits (which may themselves depend on screen size.)
- The matplotlib.ticker.ScalarFormatter class has gained a new instantiating parameter
usetex. - Creating an Axes is now 20-25% faster due to internal optimizations.
- The API on .Figure.subfigures and .SubFigure are now considered stable.