API Changes in 1.4.x ==================== Code changes ------------ * A major refactoring of the axes module was made. The axes module has been split into smaller modules: - the ``_base`` module, which contains a new private ``_AxesBase`` class. This class contains all methods except plotting and labelling methods. - the `~matplotlib.axes` module, which contains the `.axes.Axes` class. This class inherits from ``_AxesBase``, and contains all plotting and labelling methods. - the ``_subplot`` module, with all the classes concerning subplotting. There are a couple of things that do not exists in the `~matplotlib.axes` module's namespace anymore. If you use them, you need to import them from their original location: - ``math`` -> ``import math`` - ``ma`` -> ``from numpy import ma`` - ``cbook`` -> ``from matplotlib import cbook`` - ``docstring`` -> ``from matplotlib import docstring`` - ``is_sequence_of_strings`` -> ``from matplotlib.cbook import is_sequence_of_strings`` - ``is_string_like`` -> ``from matplotlib.cbook import is_string_like`` - ``iterable`` -> ``from matplotlib.cbook import iterable`` - ``itertools`` -> ``import itertools`` - ``martist`` -> ``from matplotlib import artist as martist`` - ``matplotlib`` -> ``import matplotlib`` - ``mcoll`` -> ``from matplotlib import collections as mcoll`` - ``mcolors`` -> ``from matplotlib import colors as mcolors`` - ``mcontour`` -> ``from matplotlib import contour as mcontour`` - ``mpatches`` -> ``from matplotlib import patches as mpatches`` - ``mpath`` -> ``from matplotlib import path as mpath`` - ``mquiver`` -> ``from matplotlib import quiver as mquiver`` - ``mstack`` -> ``from matplotlib import stack as mstack`` - ``mstream`` -> ``from matplotlib import stream as mstream`` - ``mtable`` -> ``from matplotlib import table as mtable`` * As part of the refactoring to enable Qt5 support, the module ``matplotlib.backends.qt4_compat`` was renamed to ``matplotlib.backends.qt_compat``. ``qt4_compat`` is deprecated in 1.4 and will be removed in 1.5. * The :func:`~matplotlib.pyplot.errorbar` method has been changed such that the upper and lower limits (*lolims*, *uplims*, *xlolims*, *xuplims*) now point in the correct direction. * The *fmt* kwarg for :func:`~matplotlib.pyplot.errorbar` now supports the string 'none' to suppress drawing of a line and markers; use of the *None* object for this is deprecated. The default *fmt* value is changed to the empty string (''), so the line and markers are governed by the :func:`~matplotlib.pyplot.plot` defaults. * A bug has been fixed in the path effects rendering of fonts, which now means that the font size is consistent with non-path effect fonts. See https://github.com/matplotlib/matplotlib/issues/2889 for more detail. * The Sphinx extensions ``ipython_directive`` and ``ipython_console_highlighting`` have been moved to the IPython project itself. While they remain in Matplotlib for this release, they have been deprecated. Update your extensions in :file:`conf.py` to point to ``IPython.sphinxext.ipython_directive`` instead of ``matplotlib.sphinxext.ipython_directive``. * In ``matplotlib.finance``, almost all functions have been deprecated and replaced with a pair of functions name ``*_ochl`` and ``*_ohlc``. The former is the 'open-close-high-low' order of quotes used previously in this module, and the latter is the 'open-high-low-close' order that is standard in finance. * For consistency the ``face_alpha`` keyword to :class:`matplotlib.patheffects.SimplePatchShadow` has been deprecated in favour of the ``alpha`` keyword. Similarly, the keyword ``offset_xy`` is now named ``offset`` across all :class:`~matplotlib.patheffects.AbstractPathEffect`\ s. ``matplotlib.patheffects._Base`` has been renamed to :class:`matplotlib.patheffects.AbstractPathEffect`. ``matplotlib.patheffect.ProxyRenderer`` has been renamed to :class:`matplotlib.patheffects.PathEffectRenderer` and is now a full RendererBase subclass. * The artist used to draw the outline of a `.Figure.colorbar` has been changed from a `matplotlib.lines.Line2D` to `matplotlib.patches.Polygon`, thus ``colorbar.ColorbarBase.outline`` is now a `matplotlib.patches.Polygon` object. * The legend handler interface has changed from a callable, to any object which implements the ``legend_artists`` method (a deprecation phase will see this interface be maintained for v1.4). See :ref:`legend_guide` for further details. Further legend changes include: * ``matplotlib.axes.Axes._get_legend_handles`` now returns a generator of handles, rather than a list. * The :func:`~matplotlib.pyplot.legend` function's *loc* positional argument has been deprecated. Use the *loc* keyword argument instead. * The :rc:`savefig.transparent` has been added to control default transparency when saving figures. * Slightly refactored the `.Annotation` family. The text location in `.Annotation` is now entirely handled by the underlying `.Text` object so ``.set_position`` works as expected. The attributes *xytext* and *textcoords* have been deprecated in favor of *xyann* and *anncoords* so that `.Annotation` and `.AnnotationBbox` can share a common sensibly named api for getting/setting the location of the text or box. - *xyann* -> set the location of the annotation - *xy* -> set where the arrow points to - *anncoords* -> set the units of the annotation location - *xycoords* -> set the units of the point location - ``set_position()`` -> `.Annotation` only set location of annotation * `matplotlib.mlab.specgram`, `matplotlib.mlab.psd`, `matplotlib.mlab.csd`, `matplotlib.mlab.cohere`, ``matplotlib.mlab.cohere_pairs``, `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`, `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere` now raise ValueError where they previously raised AssertionError. * For `matplotlib.mlab.psd`, `matplotlib.mlab.csd`, `matplotlib.mlab.cohere`, ``matplotlib.mlab.cohere_pairs``, `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`, `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere`, in cases where a shape (n, 1) array is returned, this is now converted to a (n, ) array. Previously, (n, m) arrays were averaged to an (n, ) array, but (n, 1) arrays were returned unchanged. This change makes the dimensions consistent in both cases. * Added the :rc:`axes.formatter.useoffset` to control the default value of *useOffset* in `.ticker.ScalarFormatter` * Added `.Formatter` sub-class `.StrMethodFormatter` which does the exact same thing as `.FormatStrFormatter`, but for new-style formatting strings. * Deprecated ``matplotlib.testing.image_util`` and the only function within, ``matplotlib.testing.image_util.autocontrast``. These will be removed completely in v1.5.0. * The ``fmt`` argument of :meth:`~matplotlib.axes.Axes.plot_date` has been changed from ``bo`` to just ``o``, so color cycling can happen by default. * Removed the class ``FigureManagerQTAgg`` and deprecated ``NavigationToolbar2QTAgg`` which will be removed in 1.5. * Removed formerly public (non-prefixed) attributes ``rect`` and ``drawRect`` from ``FigureCanvasQTAgg``; they were always an implementation detail of the (preserved) ``drawRectangle()`` function. * The function signatures of ``matplotlib.tight_bbox.adjust_bbox`` and ``matplotlib.tight_bbox.process_figure_for_rasterizing`` have been changed. A new *fixed_dpi* parameter allows for overriding the ``figure.dpi`` setting instead of trying to deduce the intended behaviour from the file format. * Added support for horizontal/vertical axes padding to `mpl_toolkits.axes_grid1.axes_grid.ImageGrid` --- argument *axes_pad* can now be tuple-like if separate axis padding is required. The original behavior is preserved. * Added support for skewed transforms to `matplotlib.transforms.Affine2D`, which can be created using the `~.Affine2D.skew` and `~.Affine2D.skew_deg` methods. * Added clockwise parameter to control sectors direction in `.axes.Axes.pie` * In `matplotlib.lines.Line2D` the *markevery* functionality has been extended. Previously an integer start-index and stride-length could be specified using either a two-element-list or a two-element-tuple. Now this can only be done using a two-element-tuple. If a two-element-list is used then it will be treated as NumPy fancy indexing and only the two markers corresponding to the given indexes will be shown. * Removed *prop* keyword argument from `mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar` call. It was passed through to the base-class ``__init__`` and is only used for setting padding. Now *fontproperties* (which is what is really used to set the font properties of `.AnchoredSizeBar`) is passed through in place of *prop*. If *fontproperties* is not passed in, but *prop* is, then *prop* is used in place of *fontproperties*. If both are passed in, *prop* is silently ignored. * The use of the index 0 in `.pyplot.subplot` and related commands is deprecated. Due to a lack of validation, calling ``plt.subplots(2, 2, 0)`` does not raise an exception, but puts an axes in the _last_ position. This is due to the indexing in subplot being 1-based (to mirror MATLAB) so before indexing into the `.GridSpec` object used to determine where the axes should go, 1 is subtracted off. Passing in 0 results in passing -1 to `.GridSpec` which results in getting the last position back. Even though this behavior is clearly wrong and not intended, we are going through a deprecation cycle in an abundance of caution that any users are exploiting this 'feature'. The use of 0 as an index will raise a warning in 1.4 and an exception in 1.5. * Clipping is now off by default on offset boxes. * Matplotlib now uses a less-aggressive call to ``gc.collect(1)`` when closing figures to avoid major delays with large numbers of user objects in memory. * The default clip value of *all* pie artists now defaults to ``False``. Code removal ------------ * Removed ``mlab.levypdf``. The code raised a NumPy error (and has for a long time) and was not the standard form of the Levy distribution. ``scipy.stats.levy`` should be used instead