.. _whats-new-3-1-0: What's new in Matplotlib 3.1 (May 18, 2019) =========================================== 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 New Features ------------ `~.dates.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. .. 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() 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 :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)) `~.scale.FuncScale` for arbitrary axes scales ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. Legend for scatter ~~~~~~~~~~~~~~~~~~ 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`. 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 `~.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. Add ``inaxes`` method to `.FigureCanvasBase` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. 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 `~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`. mplot3d Line3D now allows {set,get}_data_3d ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. ``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 :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() 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 :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). 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 `~.Animation.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 :ghissue:`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 :class:`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 :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. New logging API ~~~~~~~~~~~~~~~ `matplotlib.set_loglevel` / `.pyplot.set_loglevel` can be called to display more (or less) detailed logging output.