.. redirect-from:: /users/prev_whats_new/whats_new_3.1.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.1 (May 18, 2019)
- New Features
- Figure, FigureCanvas, and Backends
- Axes and Artists
- Axis and Ticks
- Animation and Interactivity
- Support for forward/backward mouse buttons
- progress_callback argument to ~.Animation.save()
- Add
cache_frame_datakeyword-only argument into .animation.FuncAnimation - Endless Looping GIFs with PillowWriter
- Adjusted .matplotlib.widgets.Slider to have vertical orientation
- Improved formatting of image values under cursor when a colorbar is present
- MouseEvent button attribute is now an IntEnum
- Configuration, Install, and Development
.. toctree:: :maxdepth: 4
The automatic date formatter used by default can be quite verbose. A new formatter can be accessed that tries to make the tick labels appropriately concise.
.. plot::
import datetime
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
import numpy as np
# make a timeseries...
base = datetime.datetime(2005, 2, 1)
dates = np.array([base + datetime.timedelta(hours= 2 * i)
for i in range(732)])
N = len(dates)
np.random.seed(19680801)
y = np.cumsum(np.random.randn(N))
lims = [(np.datetime64('2005-02'), np.datetime64('2005-04')),
(np.datetime64('2005-02-03'), np.datetime64('2005-02-15')),
(np.datetime64('2005-02-03 11:00'), np.datetime64('2005-02-04 13:20'))]
fig, axs = plt.subplots(3, 1, constrained_layout=True)
for nn, ax in enumerate(axs):
# activate the formatter here.
locator = mdates.AutoDateLocator()
formatter = mdates.ConciseDateFormatter(locator)
ax.xaxis.set_major_locator(locator)
ax.xaxis.set_major_formatter(formatter)
ax.plot(dates, y)
ax.set_xlim(lims[nn])
axs[0].set_title('Concise Date Formatter')
plt.show()
A new method provides the ability to add a second axis to an existing axes via .Axes.secondary_xaxis and .Axes.secondary_yaxis. See :doc:`/gallery/subplots_axes_and_figures/secondary_axis` for examples.
.. plot::
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(5, 3))
ax.plot(range(360))
ax.secondary_xaxis('top', functions=(np.deg2rad, np.rad2deg))
A new ~.scale.FuncScale class was added (and ~.scale.FuncTransform) to allow the user to have arbitrary scale transformations without having to write a new subclass of ~.scale.ScaleBase. This can be accessed by:
ax.set_yscale('function', functions=(forward, inverse))
where forward and inverse are callables that return the scale
transform and its inverse. See the last example in
:doc:`/gallery/scales/scales`.
A new method for creating legends for scatter plots has been introduced. Previously, in order to obtain a legend for a :meth:`~.axes.Axes.scatter` plot, one could either plot several scatters, each with an individual label, or create proxy artists to show in the legend manually. Now, :class:`~.collections.PathCollection` provides a method :meth:`~.collections.PathCollection.legend_elements` to obtain the handles and labels for a scatter plot in an automated way. This makes creating a legend for a scatter plot as easy as
.. plot::
scatter = plt.scatter([1,2,3], [4,5,6], c=[7,2,3])
plt.legend(*scatter.legend_elements())
An example can be found in :ref:`automatedlegendcreation`.
Previous versions of matplotlib required a Framework build of python to work. The app type was updated to no longer require this, so the MacOSX backend should work with non-framework python.
This also adds support for the MacOSX backend for PyPy3.
Accessing Figure.frameon (including via get_frameon and set_frameon
now directly forwards to the visibility of the underlying Rectangle artist
(Figure.patch.get_frameon, Figure.patch.set_frameon).
Matplotlib uses Pillow to handle saving to the JPEG and TIFF formats. The ~.Figure.savefig() function gained a pil_kwargs keyword argument, which can be used to forward arguments to Pillow's PIL.Image.Image.save.
The pil_kwargs argument can also be used when saving to PNG. In that case, Matplotlib also uses Pillow's PIL.Image.Image.save instead of going through its own builtin PNG support.
The .FigureCanvasBase class has now an ~.FigureCanvasBase.inaxes method to check whether a point is in an axes and returns the topmost axes, else None.
This leads to faster import/runtime performance in some cases. The backend will fall back to cairocffi in case pycairo isn't available.
Previously, spines of .axes_grid1 and .axisartist Axes would be drawn twice, leading to a "bold" appearance. This is no longer the case.
.ArtistInspector.get_aliases previously returned the set of aliases as
{fullname: {alias1: None, alias2: None, ...}}. The dict-to-None mapping
was used to simulate a set in earlier versions of Python. It has now been
replaced by a set, i.e. {fullname: {alias1, alias2, ...}}.
This value is also stored in ArtistInspector.aliasd, which has likewise
changed.
Alternatively to strings like "data" or "axes fraction",
.ConnectionPatch now accepts any ~matplotlib.transforms.Transform as input
for the coordsA and coordsB arguments. This allows to draw lines between
points defined in different user defined coordinate systems. Also see
:ref:`using_connectionpatch`.
Lines created with the 3d projection in mplot3d can now access the data using ~.mplot3d.art3d.Line3D.get_data_3d() which returns a tuple of array_likes containing the (x, y, z) data. The equivalent ~.mplot3d.art3d.Line3D.set_data_3d can be used to modify the data of an existing Line3D.
The .Axes3D.voxels method now takes a shade parameter that defaults to True. This shades faces based on their orientation, behaving just like the matching parameters to :meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf` and :meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.bar3d`. The plot below shows how this affects the output.
.. plot::
import matplotlib.pyplot as plt
import numpy as np
# prepare some coordinates
x, y, z = np.indices((8, 8, 8))
# draw cuboids in the top left and bottom right corners, and a link between them
cube1 = (x < 3) & (y < 3) & (z < 3)
cube2 = (x >= 5) & (y >= 5) & (z >= 5)
link = abs(x - y) + abs(y - z) + abs(z - x) <= 2
# combine the objects into a single boolean array
voxels = cube1 | cube2 | link
# set the colors of each object
colors = np.empty(voxels.shape, dtype=object)
colors[link] = 'red'
colors[cube1] = 'blue'
colors[cube2] = 'green'
# and plot everything
fig = plt.figure(figsize=plt.figaspect(0.5))
ax, ax_shaded = fig.subplots(1, 2, subplot_kw=dict(projection='3d'))
ax.voxels(voxels, facecolors=colors, edgecolor='k', shade=False)
ax.set_title("Unshaded")
ax_shaded.voxels(voxels, facecolors=colors, edgecolor='k', shade=True)
ax_shaded.set_title("Shaded (default)")
plt.show()
The .Axis.get_inverted and .Axis.set_inverted methods query and set whether the axis uses "inverted" orientation (i.e. increasing to the left for the x-axis and to the bottom for the y-axis).
They perform tasks similar to .Axes.xaxis_inverted, .Axes.yaxis_inverted, .Axes.invert_xaxis, and .Axes.invert_yaxis, with the specific difference that .Axis.set_inverted makes it easier to set the inversion of an axis regardless of whether it had previously been inverted before.
Default minor tick spacing was changed from 0.625 to 0.5 for major ticks spaced 2.5 units apart.
A public API has been added to .EngFormatter to control how the numbers in the ticklabels will be rendered. By default, useMathText evaluates to :rc:`axes.formatter.use_mathtext` and usetex evaluates to :rc:`text.usetex`.
If either is True then the numbers will be encapsulated by $
signs. When using TeX this implies that the numbers will be shown
in TeX's math font. When using mathtext, the $ signs around
numbers will ensure Unicode rendering (as implied by mathtext). This
will make sure that the minus signs in the ticks are rendered as the
Unicode minus (U+2212) when using mathtext (without relying on the
~.Formatter.fix_minus method).
Figure managers now support a button_press event for mouse
buttons, similar to the key_press events. This allows binding
actions to mouse buttons (see .MouseButton) The first application of
this mechanism is support of forward/backward mouse buttons in figures
created with the Qt5 backend.
The method .Animation.save gained an optional progress_callback argument to notify the saving progress.
.matplotlib.animation.FuncAnimation has been caching frame data by default; however, this caching is not ideal in certain cases e.g. When .FuncAnimation needs to be only drawn(not saved) interactively and memory required by frame data is quite large. By adding cache_frame_data keyword-only argument, users can now disable this caching; thereby, this new argument provides a fix for issue :ghissue:`8528`.
We acknowledge that most people want to watch a GIF more than once. Saving an animation as a GIF with PillowWriter now produces an endless looping GIF.
The :class:`matplotlib.widgets.Slider` widget now takes an optional
argument orientation which indicates the direction
('horizontal' or 'vertical') that the slider should take.
When a colorbar is present, its formatter is now used to format the image
values under the mouse cursor in the status bar. For example, for an image
displaying the values 10,000 and 10,001, the statusbar will now (using default
settings) display the values as 10000 and 10001), whereas both values
were previously displayed as 1e+04.
The button attribute of ~.MouseEvent instances can take the values
None, 1 (left button), 2 (middle button), 3 (right button), "up" (scroll), and
"down" (scroll). For better legibility, the 1, 2, and 3 values are now
represented using the enum.IntEnum class matplotlib.backend_bases.MouseButton,
with the values .MouseButton.LEFT (== 1), .MouseButton.MIDDLE (== 2),
and .MouseButton.RIGHT (== 3).
This includes device files; in particular, on Unix systems, one can set
MATPLOTLIBRC to /dev/null to ignore the user's matplotlibrc file and
fall back to Matplotlib's defaults.
As a reminder, if MATPLOTLIBRC points to a directory, Matplotlib will try
to load the matplotlibrc file from $MATPLOTLIBRC/matplotlibrc.
Previously, the rc file keys :rc:`pgf.preamble` and :rc:`text.latex.preamble` were parsed using commas as separators. This would break valid LaTeX code, such as:
\usepackage[protrusion=true, expansion=false]{microtype}
The parsing has been modified to pass the complete line to the LaTeX system, keeping all commas. Passing a list of strings from within a Python script still works as it used to.
matplotlib.set_loglevel / .pyplot.set_loglevel can be called to display more (or less) detailed logging output.