doc/users/prev_whats_new/whats_new_3.7.0.rst
For a list of all of the issues and pull requests since the last revision, see
the :ref:github-stats.
.. contents:: Table of Contents :depth: 4
.. toctree:: :maxdepth: 4
hatch parameter for pie~matplotlib.axes.Axes.pie now accepts a hatch keyword that takes as input
a hatch or list of hatches:
.. plot:: :include-source: true :alt: Two pie charts, identified as ax1 and ax2, both have a small blue slice, a medium orange slice, and a large green slice. ax1 has a dot hatching on the small slice, a small open circle hatching on the medium slice, and a large open circle hatching on the large slice. ax2 has the same large open circle with a dot hatch on every slice.
fig, (ax1, ax2) = plt.subplots(ncols=2)
x = [10, 30, 60]
ax1.pie(x, hatch=['.', 'o', 'O'])
ax2.pie(x, hatch='.O')
ax1.set_title("hatch=['.', 'o', 'O']")
ax2.set_title("hatch='.O'")
Caps and error lines are now drawn with respect to polar coordinates, when plotting errorbars on polar plots.
.. figure:: /gallery/pie_and_polar_charts/images/sphx_glr_polar_error_caps_001.png :target: ../../gallery/pie_and_polar_charts/polar_error_caps.html
~matplotlib.axes.Axes.bar_labelThe fmt argument of ~matplotlib.axes.Axes.bar_label now accepts
{}-style format strings:
.. plot:: :include-source: true
import matplotlib.pyplot as plt
fruit_names = ['Coffee', 'Salted Caramel', 'Pistachio']
fruit_counts = [4000, 2000, 7000]
fig, ax = plt.subplots()
bar_container = ax.bar(fruit_names, fruit_counts)
ax.set(ylabel='pints sold', title='Gelato sales by flavor', ylim=(0, 8000))
ax.bar_label(bar_container, fmt='{:,.0f}')
It also accepts callables:
.. plot:: :include-source: true
animal_names = ['Lion', 'Gazelle', 'Cheetah']
mph_speed = [50, 60, 75]
fig, ax = plt.subplots()
bar_container = ax.bar(animal_names, mph_speed)
ax.set(ylabel='speed in MPH', title='Running speeds', ylim=(0, 80))
ax.bar_label(
bar_container, fmt=lambda x: '{:.1f} km/h'.format(x * 1.61)
)
ellipse boxstyle option for annotationsThe 'ellipse' option for boxstyle can now be used to create annotations
with an elliptical outline. It can be used as a closed curve shape for
longer texts instead of the 'circle' boxstyle which can get quite big.
.. plot:: :include-source: true
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(5, 5))
t = ax.text(0.5, 0.5, "elliptical box",
ha="center", size=15,
bbox=dict(boxstyle="ellipse,pad=0.3"))
imshow can now be expressed with unitsThe extent parameter of ~.axes.Axes.imshow and ~.AxesImage.set_extent
can now be expressed with units.
.. plot:: :include-source: true
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots(layout='constrained')
date_first = np.datetime64('2020-01-01', 'D')
date_last = np.datetime64('2020-01-11', 'D')
arr = [[i+j for i in range(10)] for j in range(10)]
ax.imshow(arr, origin='lower', extent=[0, 10, date_first, date_last])
plt.show()
The order of legend entries can now be reversed by passing reverse=True to
~.Axes.legend.
pcolormesh accepts RGB(A) colorsThe ~.Axes.pcolormesh method can now handle explicit colors
specified with RGB(A) values. To specify colors, the array must be 3D
with a shape of (M, N, [3, 4]).
.. plot:: :include-source: true
import matplotlib.pyplot as plt
import numpy as np
colors = np.linspace(0, 1, 90).reshape((5, 6, 3))
plt.pcolormesh(colors)
plt.show()
The new ~matplotlib.axis.Axis.get_tick_params method can be used to
retrieve the appearance settings that will be applied to any
additional ticks, tick labels, and gridlines added to the plot:
.. code-block:: pycon
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> ax.yaxis.set_tick_params(labelsize=30, labelcolor='red',
... direction='out', which='major')
>>> ax.yaxis.get_tick_params(which='major')
{'direction': 'out',
'left': True,
'right': False,
'labelleft': True,
'labelright': False,
'gridOn': False,
'labelsize': 30,
'labelcolor': 'red'}
>>> ax.yaxis.get_tick_params(which='minor')
{'left': True,
'right': False,
'labelleft': True,
'labelright': False,
'gridOn': False}
Third-party packages can now distribute style files that are globally available
as follows. Assume that a package is importable as import mypackage, with
a mypackage/__init__.py module. Then a mypackage/presentation.mplstyle
style sheet can be used as plt.style.use("mypackage.presentation").
The implementation does not actually import mypackage, making this process
safe against possible import-time side effects. Subpackages (e.g.
dotted.package.name) are also supported.
The pan and zoom buttons in the toolbar of 3D plots are now enabled. Unselect both to rotate the plot. When the zoom button is pressed, zoom in by using the left mouse button to draw a bounding box, and out by using the right mouse button to draw the box. When zooming a 3D plot, the current view aspect ratios are kept fixed.
While setting equal aspect ratios for 3D plots, users can choose to modify either the data limits or the bounding box in parity with 2D Axes.
.. plot:: :include-source: true
import matplotlib.pyplot as plt
import numpy as np
from itertools import combinations, product
aspects = ('auto', 'equal', 'equalxy', 'equalyz', 'equalxz')
fig, axs = plt.subplots(1, len(aspects), subplot_kw={'projection': '3d'},
figsize=(12, 6))
# Draw rectangular cuboid with side lengths [4, 3, 5]
r = [0, 1]
scale = np.array([4, 3, 5])
pts = combinations(np.array(list(product(r, r, r))), 2)
for start, end in pts:
if np.sum(np.abs(start - end)) == r[1] - r[0]:
for ax in axs:
ax.plot3D(*zip(start*scale, end*scale), color='C0')
# Set the aspect ratios
for i, ax in enumerate(axs):
ax.set_aspect(aspects[i], adjustable='datalim')
# Alternatively: ax.set_aspect(aspects[i], adjustable='box')
# which will change the box aspect ratio instead of axis data limits.
ax.set_title(f"set_aspect('{aspects[i]}')")
plt.show()
Poly3DCollection supports shadingIt is now possible to shade a .Poly3DCollection. This is useful if the
polygons are obtained from e.g. a 3D model.
.. plot:: :include-source: true
import numpy as np
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d.art3d import Poly3DCollection
# Define 3D shape
block = np.array([
[[1, 1, 0],
[1, 0, 0],
[0, 1, 0]],
[[1, 1, 0],
[1, 1, 1],
[1, 0, 0]],
[[1, 1, 0],
[1, 1, 1],
[0, 1, 0]],
[[1, 0, 0],
[1, 1, 1],
[0, 1, 0]]
])
ax = plt.subplot(projection='3d')
pc = Poly3DCollection(block, facecolors='b', shade=True)
ax.add_collection(pc)
plt.show()
The rcParams :rc:axes3d.xaxis.panecolor, :rc:axes3d.yaxis.panecolor,
:rc:axes3d.zaxis.panecolor can be used to change the color of the background
panes in 3D plots. Note that it is often beneficial to give them slightly
different shades to obtain a "3D effect" and to make them slightly transparent
(alpha < 1).
.. plot:: :include-source: true
import matplotlib.pyplot as plt
with plt.rc_context({'axes3d.xaxis.panecolor': (0.9, 0.0, 0.0, 0.5),
'axes3d.yaxis.panecolor': (0.7, 0.0, 0.0, 0.5),
'axes3d.zaxis.panecolor': (0.8, 0.0, 0.0, 0.5)}):
fig = plt.figure()
fig.add_subplot(projection='3d')
colorbar now has a location keyword argumentThe colorbar method now supports a location keyword argument to more
easily position the color bar. This is useful when providing your own inset
axes using the cax keyword argument and behaves similar to the case where
axes are not provided (where the location keyword is passed through).
orientation and ticklocation are no longer required as they are
determined by location. ticklocation can still be provided if the
automatic setting is not preferred. (orientation can also be provided but
must be compatible with the location.)
An example is:
.. plot:: :include-source: true
import matplotlib.pyplot as plt
import numpy as np
rng = np.random.default_rng(19680801)
imdata = rng.random((10, 10))
fig, ax = plt.subplots(layout='constrained')
im = ax.imshow(imdata)
fig.colorbar(im, cax=ax.inset_axes([0, 1.05, 1, 0.05]),
location='top')
Constrained layout will make space for Figure legends if they are specified
by a loc keyword argument that starts with the string "outside". The
codes are unique from axes codes, in that "outside upper right" will
make room at the top of the figure for the legend, whereas
"outside right upper" will make room on the right-hand side of the figure.
See :ref:legend_guide for details.
subplot_mosaicIt is now possible to pass keyword arguments through to Axes creation in each
specific call to add_subplot in .Figure.subplot_mosaic and
.pyplot.subplot_mosaic :
.. plot:: :include-source: true
fig, axd = plt.subplot_mosaic( "AB;CD", per_subplot_kw={ "A": {"projection": "polar"}, ("C", "D"): {"xscale": "log"}, "B": {"projection": "3d"}, }, )
This is particularly useful for creating mosaics with mixed projections, but any keyword arguments can be passed through.
subplot_mosaic no longer provisionalThe API on .Figure.subplot_mosaic and .pyplot.subplot_mosaic are now
considered stable and will change under Matplotlib's normal deprecation
process.
Additional custom styling of button widgets may be achieved via the
label_props and radio_props arguments to .RadioButtons; and the
label_props, frame_props, and check_props arguments to .CheckButtons.
.. plot:: :include-source: true
from matplotlib.widgets import CheckButtons, RadioButtons
fig, ax = plt.subplots(nrows=2, ncols=2, figsize=(5, 2), width_ratios=[1, 2]) default_rb = RadioButtons(ax[0, 0], ['Apples', 'Oranges']) styled_rb = RadioButtons(ax[0, 1], ['Apples', 'Oranges'], label_props={'color': ['red', 'orange'], 'fontsize': [16, 20]}, radio_props={'edgecolor': ['red', 'orange'], 'facecolor': ['mistyrose', 'peachpuff']})
default_cb = CheckButtons(ax[1, 0], ['Apples', 'Oranges'], actives=[True, True]) styled_cb = CheckButtons(ax[1, 1], ['Apples', 'Oranges'], actives=[True, True], label_props={'color': ['red', 'orange'], 'fontsize': [16, 20]}, frame_props={'edgecolor': ['red', 'orange'], 'facecolor': ['mistyrose', 'peachpuff']}, check_props={'color': ['darkred', 'darkorange']})
ax[0, 0].set_title('Default') ax[0, 1].set_title('Stylized')
The .Button, .CheckButtons, and .RadioButtons widgets now support
blitting for faster rendering, on backends that support it, by passing
useblit=True to the constructor. Blitting is enabled by default on
supported backends.
The :doc:Sphinx plot directive </api/sphinxext_plot_directive_api>
(.. plot::) now supports a :show-source-link: option to show or hide
the link to the source code for each plot. The default is set using the
plot_html_show_source_link variable in :file:conf.py (which
defaults to True).
The new :rc:figure.hooks provides a mechanism to register
arbitrary customizations on pyplot figures; it is a list of
"dotted.module.name:dotted.callable.name" strings specifying functions
that are called on each figure created by .pyplot.figure; these
functions can e.g. attach callbacks or modify the toolbar. See
:doc:/gallery/user_interfaces/mplcvd for an example of toolbar customization.
Animations <animations> tutorial.bar chart <../../gallery/index.html#lines_bars_and_markers>_ examples.contributing guide<contributing>.annotations tutorial.