What's new in Matplotlib 3.1

For a list of all of the issues and pull requests since the last revision, see the GitHub Stats.

Table of Contents

New Features

ConciseDateFormatter

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.

Secondary x/y Axis support

A new method provides the ability to add a second axis to an existing axes via Axes.secondary_xaxis and Axes.secondary_yaxis. See Secondary Axis for examples.

(Source code, png, pdf)

../../_images/whats_new_3-1-0-2.png

FuncScale for arbitrary axes scales

A new FuncScale class was added (and FuncTransform) to allow the user to have arbitrary scale transformations without having to write a new subclass of 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 Scales.

Legend for scatter

A new method for creating legends for scatter plots has been introduced. Previously, in order to obtain a legend for a scatter() plot, one could either plot several scatters, each with an individual label, or create proxy artists to show in the legend manually. Now, PathCollection provides a method 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

(Source code, png, pdf)

../../_images/whats_new_3-1-0-3.png

An example can be found in Automated legend creation.

Matplotlib no longer requires framework app build on MacOSX backend

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.

Figure, FigureCanvas, and Backends

Figure.frameon is now a direct proxy for the Figure patch visibility state

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).

pil_kwargs argument added to savefig

Matplotlib uses Pillow to handle saving to the JPEG and TIFF formats. The savefig() function gained a pil_kwargs keyword argument, which can be used to forward arguments to Pillow's pillow.Image.save().

The pil_kwargs argument can also be used when saving to PNG. In that case, Matplotlib also uses Pillow's pillow.Image.save() instead of going through its own builtin PNG support.

Add inaxes method to FigureCanvasBase

The FigureCanvasBase class has now an inaxes method to check whether a point is in an axes and returns the topmost axes, else None.

cairo backend defaults to pycairo instead of cairocffi

This leads to faster import/runtime performance in some cases. The backend will fall back to cairocffi in case pycairo isn't available.

Axes and Artists

axes_grid1 and axisartist Axes no longer draw spines twice

Previously, spines of axes_grid1 and axisartist Axes would be drawn twice, leading to a "bold" appearance. This is no longer the case.

Return type of ArtistInspector.get_aliases changed

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.

ConnectionPatch accepts arbitrary transforms

Alternatively to strings like "data" or "axes fraction", ConnectionPatch now accepts any 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 the Connect Simple01 example.

mplot3d Line3D now allows {set,get}_data_3d

Lines created with the 3d projection in mplot3d can now access the data using get_data_3d() which returns a tuple of array_likes containing the (x, y, z) data. The equivalent set_data_3d can be used to modify the data of an existing Line3D.

Axes3D.voxels now shades the resulting voxels

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 plot_trisurf() and bar3d(). The plot below shows how this affects the output.

(Source code, png, pdf)

../../_images/whats_new_3-1-0-4.png

Axis and Ticks

Added Axis.get_inverted and Axis.set_inverted

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.

Adjust default minor tick spacing

Default minor tick spacing was changed from 0.625 to 0.5 for major ticks spaced 2.5 units apart.

EngFormatter now accepts usetex, useMathText as keyword only arguments

A public API has been added to EngFormatter to control how the numbers in the ticklabels will be rendered. By default, useMathText evaluates to rcParams["axes.formatter.use_mathtext'"] and usetex evaluates to rcParams["'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 fix_minus method).

Animation and Interactivity

Support for forward/backward mouse buttons

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.

progress_callback argument to save()

The method Animation.save gained an optional progress_callback argument to notify the saving progress.

Add cache_frame_data keyword-only argument into animation.FuncAnimation

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 #8528.

Endless Looping GIFs with PillowWriter

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.

Adjusted matplotlib.widgets.Slider to have vertical orientation

The matplotlib.widgets.Slider widget now takes an optional argument orientation which indicates the direction ('horizontal' or 'vertical') that the slider should take.

Improved formatting of image values under cursor when a colorbar is present

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.

MouseEvent button attribute is now an IntEnum

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).

Configuration, Install, and Development

The MATPLOTLIBRC environment variable can now point to any "file" path

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.

Allow LaTeX code pgf.preamble and text.latex.preamble in MATPLOTLIBRC file

Previously, the rc file keys rcParams["pgf.preamble"] (default: '') and rcParams["text.latex.preamble"] (default: '') 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.

New logging API

matplotlib.set_loglevel / pyplot.set_loglevel can be called to display more (or less) detailed logging output.