===========

API Changes

===========

This chapter is a log of changes to matplotlib that affect the

outward-facing API. If updating matplotlib breaks your scripts, this

list may help describe what changes may be necessary in your code or

help figure out possible sources of the changes you are experiencing.

For new features that were added to matplotlib, please see

:ref:`whats-new`.

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 `axes` module, which contains the 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 `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.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 `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 `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:`plotting-guide-legend` for further details. Further legend changes

include:

* :func:`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 instead.

* The rcParams `savefig.transparent` has been added to control

default transparency when saving figures.

* Slightly refactored the `Annotation` family. The text location in

`Annotation` is now handled 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 `AnnotaionBbox` 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 returend unchanged. This change makes the dimensions

consistent in both cases.

* Added the rcParam `axes.fromatter.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 `tight_bbox.adjust_bbox` and

`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.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 `skew` and `skew_deg` methods.

* Added clockwise parameter to control sectors direction in `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 kwarg 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 `fontpropreties` is not passed in, but `prop` is, then `prop` is used inplace

of `fontpropreties`. If both are passed in, `prop` is silently ignored.

* The use of the index 0 in `plt.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

.. _changes_in_1_3:

Changes in 1.3.x

================

Changes in 1.3.1

----------------

It is rare that we make an API change in a bugfix release, however,

for 1.3.1 since 1.3.0 the following change was made:

- `text.Text.cached` (used to cache font objects) has been made into a

private variable. Among the obvious encapsulation benefit, this

removes this confusing-looking member from the documentation.

- The method :meth:`~matplotlib.axes.Axes.hist` now always returns bin

occupancies as an array of type `float`. Previously, it was sometimes

an array of type `int`, depending on the call.

Code removal

------------

* The following items that were deprecated in version 1.2 or earlier

have now been removed completely.

- The Qt 3.x backends (`qt` and `qtagg`) have been removed in

favor of the Qt 4.x backends (`qt4` and `qt4agg`).

- The FltkAgg and Emf backends have been removed.

- The `matplotlib.nxutils` module has been removed. Use the

functionality on `matplotlib.path.Path.contains_point` and

friends instead.

- Instead of `axes.Axes.get_frame`, use `axes.Axes.patch`.

- The following `kwargs` to the `legend` function have been

renamed:

- `pad` -> `borderpad`

- `labelsep` -> `labelspacing`

- `handlelen` -> `handlelength`

- `handletextsep` -> `handletextpad`

- `axespad` -> `borderaxespad`

Related to this, the following rcParams have been removed:

- `legend.pad`, `legend.labelsep`, `legend.handlelen`,

`legend.handletextsep` and `legend.axespad`

- For the `hist` function, instead of `width`, use `rwidth`

(relative width).

- On `patches.Circle`, the `resolution` kwarg has been removed.

For a circle made up of line segments, use

`patches.CirclePolygon`.

- The printing functions in the Wx backend have been removed due

to the burden of keeping them up-to-date.

- `mlab.liaupunov` has been removed.

- `mlab.save`, `mlab.load`, `pylab.save` and `pylab.load` have

been removed. We recommend using `numpy.savetxt` and

`numpy.loadtxt` instead.

- `widgets.HorizontalSpanSelector` has been removed. Use

`widgets.SpanSelector` instead.

Code deprecation

----------------

* The CocoaAgg backend has been deprecated, with the possibility for

deletion or resurrection in a future release.

* The top-level functions in `matplotlib.path` that are implemented in

C++ were never meant to be public. Instead, users should use the

Pythonic wrappers for them in the `path.Path` and

`collections.Collection` classes. Use the following mapping to update

your code:

- `point_in_path` -> `path.Path.contains_point`

- `get_path_extents` -> `path.Path.get_extents`

- `point_in_path_collection` -> `collection.Collection.contains`

- `path_in_path` -> `path.Path.contains_path`

- `path_intersects_path` -> `path.Path.intersects_path`

- `convert_path_to_polygons` -> `path.Path.to_polygons`

- `cleanup_path` -> `path.Path.cleaned`

- `points_in_path` -> `path.Path.contains_points`

- `clip_path_to_rect` -> `path.Path.clip_to_bbox`

* `matplotlib.colors.normalize` and `matplotlib.colors.no_norm` have

been deprecated in favour of `matplotlib.colors.Normalize` and

`matplotlib.colors.NoNorm` respectively.

* The `ScalarMappable` class' `set_colorbar` is now

deprecated. Instead, the

:attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be

used. In previous matplotlib versions this attribute was an

undocumented tuple of ``(colorbar_instance, colorbar_axes)`` but is

now just ``colorbar_instance``. To get the colorbar axes it is

possible to just use the

:attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar

instance.

* The `~matplotlib.mpl` module is now deprecated. Those who relied on this

module should transition to simply using ``import matplotlib as mpl``.

Code changes

------------

* :class:`~matplotlib.patches.Patch` now fully supports using RGBA values for

its ``facecolor`` and ``edgecolor`` attributes, which enables faces and

edges to have different alpha values. If the

:class:`~matplotlib.patches.Patch` object's ``alpha`` attribute is set to

anything other than ``None``, that value will override any alpha-channel

value in both the face and edge colors. Previously, if

:class:`~matplotlib.patches.Patch` had ``alpha=None``, the alpha component

of ``edgecolor`` would be applied to both the edge and face.

* The optional ``isRGB`` argument to

:meth:`~matplotlib.backend_bases.GraphicsContextBase.set_foreground` (and

the other GraphicsContext classes that descend from it) has been renamed to

``isRGBA``, and should now only be set to ``True`` if the ``fg`` color

argument is known to be an RGBA tuple.

* For :class:`~matplotlib.patches.Patch`, the ``capstyle`` used is now

``butt``, to be consistent with the default for most other objects, and to

avoid problems with non-solid ``linestyle`` appearing solid when using a

large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used

``capstyle='projecting'``.

* `Path` objects can now be marked as `readonly` by passing

`readonly=True` to its constructor. The built-in path singletons,

obtained through `Path.unit*` class methods return readonly paths.

If you have code that modified these, you will need to make a

deepcopy first, using either::

import copy

path = copy.deepcopy(Path.unit_circle())

# or

path = Path.unit_circle().deepcopy()

Deep copying a `Path` always creates an editable (i.e. non-readonly)

`Path`.

* The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping

Path codes to the number of expected vertices at

:attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`.

* To support XKCD style plots, the :func:`matplotlib.path.cleanup_path`

method's signature was updated to require a sketch argument. Users of

:func:`matplotlib.path.cleanup_path` are encouraged to use the new

:meth:`~matplotlib.path.Path.cleaned` Path method.

* Data limits on a plot now start from a state of having "null"

limits, rather than limits in the range (0, 1). This has an effect

on artists that only control limits in one direction, such as

`axvline` and `axhline`, since their limits will not longer also

include the range (0, 1). This fixes some problems where the

computed limits would be dependent on the order in which artists

were added to the axes.

* Fixed a bug in setting the position for the right/top spine with data

position type. Previously, it would draw the right or top spine at

+1 data offset.

* In :class:`~matplotlib.patches.FancyArrow`, the default arrow head

width, ``head_width``, has been made larger to produce a visible

arrow head. The new value of this kwarg is ``head_width = 20 *

width``.

* It is now possible to provide ``number of levels + 1`` colors in the case of

`extend='both'` for contourf (or just ``number of levels`` colors for an

extend value ``min`` or ``max``) such that the resulting colormap's

``set_under`` and ``set_over`` are defined appropriately. Any other number

of colors will continue to behave as before (if more colors are provided

than levels, the colors will be unused). A similar change has been applied

to contour, where ``extend='both'`` would expect ``number of levels + 2``

colors.

* A new keyword *extendrect* in :meth:`~matplotlib.pyplot.colorbar` and

:class:`~matplotlib.colorbar.ColorbarBase` allows one to control the shape

of colorbar extensions.

* The extension of :class:`~matplotlib.widgets.MultiCursor` to both vertical

(default) and/or horizontal cursor implied that ``self.line`` is replaced

by ``self.vline`` for vertical cursors lines and ``self.hline`` is added

for the horizontal cursors lines.

* On POSIX platforms, the :func:`~matplotlib.cbook.report_memory` function

raises :class:`NotImplementedError` instead of :class:`OSError` if the

:command:`ps` command cannot be run.

* The :func:`matplotlib.cbook.check_output` function has been moved to

:func:`matplotlib.compat.subprocess`.

Configuration and rcParams

--------------------------

* On Linux, the user-specific `matplotlibrc` configuration file is now

located in `~/.config/matplotlib/matplotlibrc` to conform to the

`XDG Base Directory Specification

<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.

* The `font.*` rcParams now affect only text objects created after the

rcParam has been set, and will not retroactively affect already

existing text objects. This brings their behavior in line with most

other rcParams.

* Removed call of :meth:`~matplotlib.axes.Axes.grid` in

:meth:`~matplotlib.pyplot.plotfile`. To draw the axes grid, set the

``axes.grid`` rcParam to *True*, or explicitly call

:meth:`~matplotlib.axes.Axes.grid`.

Changes in 1.2.x

================

* The ``classic`` option of the rc parameter ``toolbar`` is deprecated

and will be removed in the next release.

* The :meth:`~matplotlib.cbook.isvector` method has been removed since it

is no longer functional.

* The `rasterization_zorder` property on `~matplotlib.axes.Axes` a

zorder below which artists are rasterized. This has defaulted to

-30000.0, but it now defaults to `None`, meaning no artists will be

rasterized. In order to rasterize artists below a given zorder

value, `set_rasterization_zorder` must be explicitly called.

* In :meth:`~matplotlib.axes.Axes.scatter`, and `~pyplot.scatter`,

when specifying a marker using a tuple, the angle is now specified

in degrees, not radians.

* Using :meth:`~matplotlib.axes.Axes.twinx` or

:meth:`~matplotlib.axes.Axes.twiny` no longer overrides the current locaters

and formatters on the axes.

* In :meth:`~matplotlib.axes.Axes.contourf`, the handling of the *extend*

kwarg has changed. Formerly, the extended ranges were mapped

after to 0, 1 after being normed, so that they always corresponded

to the extreme values of the colormap. Now they are mapped

outside this range so that they correspond to the special

colormap values determined by the

:meth:`~matplotlib.colors.Colormap.set_under` and

:meth:`~matplotlib.colors.Colormap.set_over` methods, which

default to the colormap end points.

* The new rc parameter ``savefig.format`` replaces ``cairo.format`` and

``savefig.extension``, and sets the default file format used by

:meth:`matplotlib.figure.Figure.savefig`.

* In :meth:`~matplotlib.pyplot.pie` and :meth:`~matplotlib.Axes.pie`, one can

now set the radius of the pie; setting the *radius* to 'None' (the default

value), will result in a pie with a radius of 1 as before.

* Use of :func:`~matplotlib.projections.projection_factory` is now deprecated

in favour of axes class identification using

:func:`~matplotlib.projections.process_projection_requirements` followed by

direct axes class invocation (at the time of writing, functions which do this

are: :meth:`~matplotlib.figure.Figure.add_axes`,

:meth:`~matplotlib.figure.Figure.add_subplot` and

:meth:`~matplotlib.figure.Figure.gca`). Therefore::

key = figure._make_key(*args, **kwargs)

ispolar = kwargs.pop('polar', False)

projection = kwargs.pop('projection', None)

if ispolar:

if projection is not None and projection != 'polar':

raise ValueError('polar and projection args are inconsistent')

projection = 'polar'

ax = projection_factory(projection, self, rect, **kwargs)

key = self._make_key(*args, **kwargs)

# is now

projection_class, kwargs, key = \

process_projection_requirements(self, *args, **kwargs)

ax = projection_class(self, rect, **kwargs)

This change means that third party objects can expose themselves as

matplotlib axes by providing a ``_as_mpl_axes`` method. See

:ref:`adding-new-scales` for more detail.

* A new keyword *extendfrac* in :meth:`~matplotlib.pyplot.colorbar` and

:class:`~matplotlib.colorbar.ColorbarBase` allows one to control the size of

the triangular minimum and maximum extensions on colorbars.

* A new keyword *capthick* in :meth:`~matplotlib.pyplot.errorbar` has been

added as an intuitive alias to the *markeredgewidth* and *mew* keyword

arguments, which indirectly controlled the thickness of the caps on

the errorbars. For backwards compatibility, specifying either of the

original keyword arguments will override any value provided by

*capthick*.

* Transform subclassing behaviour is now subtly changed. If your transform

implements a non-affine transformation, then it should override the

``transform_non_affine`` method, rather than the generic ``transform`` method.

Previously transforms would define ``transform`` and then copy the

method into ``transform_non_affine``::

class MyTransform(mtrans.Transform):

def transform(self, xy):

...

transform_non_affine = transform

This approach will no longer function correctly and should be changed to::

class MyTransform(mtrans.Transform):

def transform_non_affine(self, xy):

...

* Artists no longer have ``x_isdata`` or ``y_isdata`` attributes; instead

any artist's transform can be interrogated with

``artist_instance.get_transform().contains_branch(ax.transData)``

* Lines added to an axes now take into account their transform when updating the

data and view limits. This means transforms can now be used as a pre-transform.

For instance::

>>> import matplotlib.pyplot as plt

>>> import matplotlib.transforms as mtrans

>>> ax = plt.axes()

>>> ax.plot(range(10), transform=mtrans.Affine2D().scale(10) + ax.transData)

>>> print(ax.viewLim)

Bbox('array([[ 0., 0.],\n [ 90., 90.]])')

* One can now easily get a transform which goes from one transform's coordinate

system to another, in an optimized way, using the new subtract method on a

transform. For instance, to go from data coordinates to axes coordinates::

>>> import matplotlib.pyplot as plt

>>> ax = plt.axes()

>>> data2ax = ax.transData - ax.transAxes

>>> print(ax.transData.depth, ax.transAxes.depth)

3, 1

>>> print(data2ax.depth)

2

for versions before 1.2 this could only be achieved in a sub-optimal way,

using ``ax.transData + ax.transAxes.inverted()`` (depth is a new concept,

but had it existed it would return 4 for this example).

* ``twinx`` and ``twiny`` now returns an instance of SubplotBase if

parent axes is an instance of SubplotBase.

* All Qt3-based backends are now deprecated due to the lack of py3k bindings.

Qt and QtAgg backends will continue to work in v1.2.x for py2.6

and py2.7. It is anticipated that the Qt3 support will be completely

removed for the next release.

* :class:`~matplotlib.colors.ColorConverter`,

:class:`~matplotlib.colors.Colormap` and

:class:`~matplotlib.colors.Normalize` now subclasses ``object``

* ContourSet instances no longer have a ``transform`` attribute. Instead,

access the transform with the ``get_transform`` method.

Changes in 1.1.x

================

* Added new :class:`matplotlib.sankey.Sankey` for generating Sankey diagrams.

* In :meth:`~matplotlib.pyplot.imshow`, setting *interpolation* to 'nearest'

will now always mean that the nearest-neighbor interpolation is performed.

If you want the no-op interpolation to be performed, choose 'none'.

* There were errors in how the tri-functions were handling input parameters

that had to be fixed. If your tri-plots are not working correctly anymore,

or you were working around apparent mistakes, please see issue #203 in the

github tracker. When in doubt, use kwargs.

* The 'symlog' scale had some bad behavior in previous versions. This has now

been fixed and users should now be able to use it without frustrations.

The fixes did result in some minor changes in appearance for some users who

may have been depending on the bad behavior.

* There is now a common set of markers for all plotting functions. Previously,

some markers existed only for :meth:`~matplotlib.pyplot.scatter` or just for

:meth:`~matplotlib.pyplot.plot`. This is now no longer the case. This merge

did result in a conflict. The string 'd' now means "thin diamond" while

'D' will mean "regular diamond".

Changes beyond 0.99.x

=====================

* The default behavior of :meth:`matplotlib.axes.Axes.set_xlim`,

:meth:`matplotlib.axes.Axes.set_ylim`, and

:meth:`matplotlib.axes.Axes.axis`, and their corresponding

pyplot functions, has been changed: when view limits are

set explicitly with one of these methods, autoscaling is turned

off for the matching axis. A new *auto* kwarg is available to

control this behavior. The limit kwargs have been renamed to

*left* and *right* instead of *xmin* and *xmax*, and *bottom*

and *top* instead of *ymin* and *ymax*. The old names may still

be used, however.

* There are five new Axes methods with corresponding pyplot

functions to facilitate autoscaling, tick location, and tick

label formatting, and the general appearance of ticks and

tick labels:

+ :meth:`matplotlib.axes.Axes.autoscale` turns autoscaling

on or off, and applies it.

+ :meth:`matplotlib.axes.Axes.margins` sets margins used to

autoscale the :attr:`matplotlib.axes.Axes.viewLim` based on

the :attr:`matplotlib.axes.Axes.dataLim`.

+ :meth:`matplotlib.axes.Axes.locator_params` allows one to

adjust axes locator parameters such as *nbins*.

+ :meth:`matplotlib.axes.Axes.ticklabel_format` is a convenience

method for controlling the :class:`matplotlib.ticker.ScalarFormatter`

that is used by default with linear axes.

+ :meth:`matplotlib.axes.Axes.tick_params` controls direction, size,

visibility, and color of ticks and their labels.

* The :meth:`matplotlib.axes.Axes.bar` method accepts a *error_kw*

kwarg; it is a dictionary of kwargs to be passed to the

errorbar function.

* The :meth:`matplotlib.axes.Axes.hist` *color* kwarg now accepts

a sequence of color specs to match a sequence of datasets.

* The :class:`~matplotlib.collections.EllipseCollection` has been

changed in two ways:

+ There is a new *units* option, 'xy', that scales the ellipse with

the data units. This matches the :class:'~matplotlib.patches.Ellipse`

scaling.

+ The *height* and *width* kwargs have been changed to specify

the height and width, again for consistency with

:class:`~matplotlib.patches.Ellipse`, and to better match

their names; previously they specified the half-height and

half-width.

* There is a new rc parameter ``axes.color_cycle``, and the color

cycle is now independent of the rc parameter ``lines.color``.

:func:`matplotlib.Axes.set_default_color_cycle` is deprecated.

* You can now print several figures to one pdf file and modify the

document information dictionary of a pdf file. See the docstrings

of the class :class:`matplotlib.backends.backend_pdf.PdfPages` for

more information.

* Removed configobj_ and `enthought.traits`_ packages, which are only

required by the experimental traited config and are somewhat out of

date. If needed, install them independently.

.. _configobj: http://www.voidspace.org.uk/python/configobj.html

.. _`enthought.traits`: http://code.enthought.com/projects/traits

* The new rc parameter ``savefig.extension`` sets the filename extension

that is used by :meth:`matplotlib.figure.Figure.savefig` if its *fname*

argument lacks an extension.

* In an effort to simplify the backend API, all clipping rectangles

and paths are now passed in using GraphicsContext objects, even

on collections and images. Therefore::

draw_path_collection(self, master_transform, cliprect, clippath,

clippath_trans, paths, all_transforms, offsets,

offsetTrans, facecolors, edgecolors, linewidths,

linestyles, antialiaseds, urls)

# is now

draw_path_collection(self, gc, master_transform, paths, all_transforms,

offsets, offsetTrans, facecolors, edgecolors,

linewidths, linestyles, antialiaseds, urls)

draw_quad_mesh(self, master_transform, cliprect, clippath,

clippath_trans, meshWidth, meshHeight, coordinates,

offsets, offsetTrans, facecolors, antialiased,

showedges)

# is now

draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,

coordinates, offsets, offsetTrans, facecolors,

antialiased, showedges)

draw_image(self, x, y, im, bbox, clippath=None, clippath_trans=None)

# is now

draw_image(self, gc, x, y, im)

* There are four new Axes methods with corresponding pyplot

functions that deal with unstructured triangular grids:

+ :meth:`matplotlib.axes.Axes.tricontour` draws contour lines

on a triangular grid.

+ :meth:`matplotlib.axes.Axes.tricontourf` draws filled contours

on a triangular grid.

+ :meth:`matplotlib.axes.Axes.tripcolor` draws a pseudocolor

plot on a triangular grid.

+ :meth:`matplotlib.axes.Axes.triplot` draws a triangular grid

as lines and/or markers.

Changes in 0.99

======================

* pylab no longer provides a load and save function. These are

available in matplotlib.mlab, or you can use numpy.loadtxt and

numpy.savetxt for text files, or np.save and np.load for binary

numpy arrays.

* User-generated colormaps can now be added to the set recognized

by :func:`matplotlib.cm.get_cmap`. Colormaps can be made the

default and applied to the current image using

:func:`matplotlib.pyplot.set_cmap`.

* changed use_mrecords default to False in mlab.csv2rec since this is

partially broken

* Axes instances no longer have a "frame" attribute. Instead, use the

new "spines" attribute. Spines is a dictionary where the keys are

the names of the spines (e.g., 'left','right' and so on) and the

values are the artists that draw the spines. For normal

(rectilinear) axes, these artists are Line2D instances. For other

axes (such as polar axes), these artists may be Patch instances.

* Polar plots no longer accept a resolution kwarg. Instead, each Path

must specify its own number of interpolation steps. This is

unlikely to be a user-visible change -- if interpolation of data is

required, that should be done before passing it to matplotlib.

Changes for 0.98.x

==================

* psd(), csd(), and cohere() will now automatically wrap negative

frequency components to the beginning of the returned arrays.

This is much more sensible behavior and makes them consistent

with specgram(). The previous behavior was more of an oversight

than a design decision.

* Added new keyword parameters *nonposx*, *nonposy* to

:class:`matplotlib.axes.Axes` methods that set log scale

parameters. The default is still to mask out non-positive

values, but the kwargs accept 'clip', which causes non-positive

values to be replaced with a very small positive value.

* Added new :func:`matplotlib.pyplot.fignum_exists` and

:func:`matplotlib.pyplot.get_fignums`; they merely expose

information that had been hidden in :mod:`matplotlib._pylab_helpers`.

* Deprecated numerix package.

* Added new :func:`matplotlib.image.imsave` and exposed it to the

:mod:`matplotlib.pyplot` interface.

* Remove support for pyExcelerator in exceltools -- use xlwt

instead

* Changed the defaults of acorr and xcorr to use usevlines=True,

maxlags=10 and normed=True since these are the best defaults

* Following keyword parameters for :class:`matplotlib.label.Label` are now

deprecated and new set of parameters are introduced. The new parameters

are given as a fraction of the font-size. Also, *scatteryoffsets*,

*fancybox* and *columnspacing* are added as keyword parameters.

================ ================

Deprecated New

================ ================

pad borderpad

labelsep labelspacing

handlelen handlelength

handlestextsep handletextpad

axespad borderaxespad

================ ================

* Removed the configobj and experimental traits rc support

* Modified :func:`matplotlib.mlab.psd`, :func:`matplotlib.mlab.csd`,

:func:`matplotlib.mlab.cohere`, and :func:`matplotlib.mlab.specgram`

to scale one-sided densities by a factor of 2. Also, optionally

scale the densities by the sampling frequency, which gives true values

of densities that can be integrated by the returned frequency values.

This also gives better MATLAB compatibility. The corresponding

:class:`matplotlib.axes.Axes` methods and :mod:`matplotlib.pyplot`

functions were updated as well.

* Font lookup now uses a nearest-neighbor approach rather than an

exact match. Some fonts may be different in plots, but should be

closer to what was requested.

* :meth:`matplotlib.axes.Axes.set_xlim`,

:meth:`matplotlib.axes.Axes.set_ylim` now return a copy of the

:attr:`viewlim` array to avoid modify-in-place surprises.

* :meth:`matplotlib.afm.AFM.get_fullname` and

:meth:`matplotlib.afm.AFM.get_familyname` no longer raise an

exception if the AFM file does not specify these optional

attributes, but returns a guess based on the required FontName

attribute.

* Changed precision kwarg in :func:`matplotlib.pyplot.spy`; default is

0, and the string value 'present' is used for sparse arrays only to

show filled locations.

* :class:`matplotlib.collections.EllipseCollection` added.

* Added ``angles`` kwarg to :func:`matplotlib.pyplot.quiver` for more

flexible specification of the arrow angles.

* Deprecated (raise NotImplementedError) all the mlab2 functions from

:mod:`matplotlib.mlab` out of concern that some of them were not

clean room implementations.

* Methods :meth:`matplotlib.collections.Collection.get_offsets` and

:meth:`matplotlib.collections.Collection.set_offsets` added to

:class:`~matplotlib.collections.Collection` base class.

* :attr:`matplotlib.figure.Figure.figurePatch` renamed

:attr:`matplotlib.figure.Figure.patch`;

:attr:`matplotlib.axes.Axes.axesPatch` renamed

:attr:`matplotlib.axes.Axes.patch`;

:attr:`matplotlib.axes.Axes.axesFrame` renamed

:attr:`matplotlib.axes.Axes.frame`.

:meth:`matplotlib.axes.Axes.get_frame`, which returns

:attr:`matplotlib.axes.Axes.patch`, is deprecated.

* Changes in the :class:`matplotlib.contour.ContourLabeler` attributes

(:func:`matplotlib.pyplot.clabel` function) so that they all have a

form like ``.labelAttribute``. The three attributes that are most

likely to be used by end users, ``.cl``, ``.cl_xy`` and

``.cl_cvalues`` have been maintained for the moment (in addition to

their renamed versions), but they are deprecated and will eventually

be removed.

* Moved several functions in :mod:`matplotlib.mlab` and

:mod:`matplotlib.cbook` into a separate module

:mod:`matplotlib.numerical_methods` because they were unrelated to

the initial purpose of mlab or cbook and appeared more coherent

elsewhere.

Changes for 0.98.1

==================

* Removed broken :mod:`matplotlib.axes3d` support and replaced it with

a non-implemented error pointing to 0.91.x

Changes for 0.98.0

==================

* :func:`matplotlib.image.imread` now no longer always returns RGBA data---if

the image is luminance or RGB, it will return a MxN or MxNx3 array

if possible. Also uint8 is no longer always forced to float.

* Rewrote the :class:`matplotlib.cm.ScalarMappable` callback

infrastructure to use :class:`matplotlib.cbook.CallbackRegistry`

rather than custom callback handling. Any users of

:meth:`matplotlib.cm.ScalarMappable.add_observer` of the

:class:`~matplotlib.cm.ScalarMappable` should use the

:attr:`matplotlib.cm.ScalarMappable.callbacks`

:class:`~matplotlib.cbook.CallbackRegistry` instead.

* New axes function and Axes method provide control over the plot

color cycle: :func:`matplotlib.axes.set_default_color_cycle` and

:meth:`matplotlib.axes.Axes.set_color_cycle`.

* matplotlib now requires Python 2.4, so :mod:`matplotlib.cbook` will

no longer provide :class:`set`, :func:`enumerate`, :func:`reversed`

or :func:`izip` compatibility functions.

* In Numpy 1.0, bins are specified by the left edges only. The axes

method :meth:`matplotlib.axes.Axes.hist` now uses future Numpy 1.3

semantics for histograms. Providing ``binedges``, the last value gives

the upper-right edge now, which was implicitly set to +infinity in

Numpy 1.0. This also means that the last bin doesn't contain upper

outliers any more by default.

* New axes method and pyplot function,

:func:`~matplotlib.pyplot.hexbin`, is an alternative to

:func:`~matplotlib.pyplot.scatter` for large datasets. It makes

something like a :func:`~matplotlib.pyplot.pcolor` of a 2-D

histogram, but uses hexagonal bins.

* New kwarg, ``symmetric``, in :class:`matplotlib.ticker.MaxNLocator`

allows one require an axis to be centered around zero.

* Toolkits must now be imported from ``mpl_toolkits`` (not ``matplotlib.toolkits``)

Notes about the transforms refactoring

--------------------------------------

A major new feature of the 0.98 series is a more flexible and

extensible transformation infrastructure, written in Python/Numpy

rather than a custom C extension.

The primary goal of this refactoring was to make it easier to

extend matplotlib to support new kinds of projections. This is

mostly an internal improvement, and the possible user-visible

changes it allows are yet to come.

See :mod:`matplotlib.transforms` for a description of the design of

the new transformation framework.

For efficiency, many of these functions return views into Numpy

arrays. This means that if you hold on to a reference to them,

their contents may change. If you want to store a snapshot of

their current values, use the Numpy array method copy().

The view intervals are now stored only in one place -- in the

:class:`matplotlib.axes.Axes` instance, not in the locator instances

as well. This means locators must get their limits from their

:class:`matplotlib.axis.Axis`, which in turn looks up its limits from

the :class:`~matplotlib.axes.Axes`. If a locator is used temporarily

and not assigned to an Axis or Axes, (e.g., in

:mod:`matplotlib.contour`), a dummy axis must be created to store its

bounds. Call :meth:`matplotlib.ticker.Locator.create_dummy_axis` to

do so.

The functionality of :class:`Pbox` has been merged with

:class:`~matplotlib.transforms.Bbox`. Its methods now all return

copies rather than modifying in place.

The following lists many of the simple changes necessary to update

code from the old transformation framework to the new one. In

particular, methods that return a copy are named with a verb in the

past tense, whereas methods that alter an object in place are named

with a verb in the present tense.

:mod:`matplotlib.transforms`

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

============================================================ ============================================================

Old method New method

============================================================ ============================================================

:meth:`Bbox.get_bounds` :attr:`transforms.Bbox.bounds`

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.width` :attr:`transforms.Bbox.width`

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.height` :attr:`transforms.Bbox.height`

------------------------------------------------------------ ------------------------------------------------------------

`Bbox.intervalx().get_bounds()` :attr:`transforms.Bbox.intervalx`

`Bbox.intervalx().set_bounds()` [:attr:`Bbox.intervalx` is now a property.]

------------------------------------------------------------ ------------------------------------------------------------

`Bbox.intervaly().get_bounds()` :attr:`transforms.Bbox.intervaly`

`Bbox.intervaly().set_bounds()` [:attr:`Bbox.intervaly` is now a property.]

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.xmin` :attr:`transforms.Bbox.x0` or

:attr:`transforms.Bbox.xmin` [1]_

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.ymin` :attr:`transforms.Bbox.y0` or

:attr:`transforms.Bbox.ymin` [1]_

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.xmax` :attr:`transforms.Bbox.x1` or

:attr:`transforms.Bbox.xmax` [1]_

------------------------------------------------------------ ------------------------------------------------------------

:meth:`Bbox.ymax` :attr:`transforms.Bbox.y1` or

:attr:`transforms.Bbox.ymax` [1]_

------------------------------------------------------------ ------------------------------------------------------------

`Bbox.overlaps(bboxes)` `Bbox.count_overlaps(bboxes)`

------------------------------------------------------------ ------------------------------------------------------------

`bbox_all(bboxes)` `Bbox.union(bboxes)`

[:meth:`transforms.Bbox.union` is a staticmethod.]

------------------------------------------------------------ ------------------------------------------------------------

`lbwh_to_bbox(l, b, w, h)` `Bbox.from_bounds(x0, y0, w, h)`

[:meth:`transforms.Bbox.from_bounds` is a staticmethod.]

------------------------------------------------------------ ------------------------------------------------------------