===========

API Changes

===========

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

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

``ax.plot(..., marker=None)`` gives default marker

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

Prior to 1.5.3 kwargs passed to `~matplotlib.Axes.plot` were handled

in two parts -- default kwargs generated internal to

`~matplotlib.Axes.plot` (such as the cycled styles) and user supplied

kwargs. The internally generated kwargs were passed to the

`matplotlib.lines.Line2D.__init__` and the user kwargs were passed to

``ln.set(**kwargs)`` to update the artist after it was created. Now

both sets of kwargs are merged and passed to

`~matplotlib.lines.Line2D.__init__`. This change was made to allow `None`

to be passed in via the user kwargs to mean 'do the default thing' as

is the convention through out mpl rather than raising an exception.

Unlike most `~matplotlib.lines.Line2D` setter methods

`~matplotlib.lines.Line2D.set_marker` did accept `None` as a valid

input which was mapped to 'no marker'. Thus, by routing this

``marker=None`` through ``__init__`` rather than ``set(...)`` the meaning

of ``ax.plot(..., marker=None)`` changed from 'no markers' to 'default markers

from rcparams'.

This is change is only evident if ``mpl.rcParams['lines.marker']`` has a value

other than ``'None'`` (which is string ``'None'`` which means 'no marker').

Changes in 1.5.2

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

Default Behavior Changes

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

Changed default ``autorange`` behavior in boxplots

``````````````````````````````````````````````````

Prior to v1.5.2, the whiskers of boxplots would extend to the mininum

and maximum values if the quartiles were all equal (i.e., Q1 = median

= Q3). This behavior has been disabled by default to restore consistency

with other plotting packages.

To restore the old behavior, simply set ``autorange=True`` when

calling ``plt.boxplot``.

Changes in 1.5.0

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

Code Changes

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

Split `matplotlib.cbook.ls_mapper` in two

`````````````````````````````````````````

The `matplotlib.cbook.ls_mapper` dictionary is split into two now to

distinguish between qualified linestyle used by backends and

unqualified ones. `ls_mapper` now maps from the short symbols

(e.g. `"--"`) to qualified names (`"solid"`). The new ls_mapper_r is

the reversed mapping.

Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes

``````````````````````````````````````````````````````````````````````````````````````````````

The reason this was done was to prevent adding an Artist that is

already associated with an Axes to be moved/added to a different Axes.

This was never supported as it causes havoc with the transform stack.

The apparent support for this (as it did not raise an exception) was

the source of multiple bug reports and questions on SO.

For almost all use-cases, the assignment of the axes to an artist should be

taken care of by the axes as part of the ``Axes.add_*`` method, hence the

deprecation {get,set}_axes.

Removing the ``set_axes`` method will also remove the 'axes' line from

the ACCEPTS kwarg tables (assuming that the removal date gets here

before that gets overhauled).

Tighted input validation on 'pivot' kwarg to quiver

```````````````````````````````````````````````````

Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'}

(but any capitalization) are valid values for the 'pivot' kwarg in

the `Quiver.__init__` (and hence `Axes.quiver` and

`plt.quiver` which both fully delegate to `Quiver`). Previously any

input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as

'tip' and any string not matching one of those patterns as 'tail'.

The value of `Quiver.pivot` is normalized to be in the set {'tip',

'tail', 'middle'} in `Quiver.__init__`.

Reordered `Axes.get_children`

`````````````````````````````

The artist order returned by `Axes.get_children` did not

match the one used by `Axes.draw`. They now use the same

order, as `Axes.draw` now calls `Axes.get_children`.

Changed behaviour of contour plots

``````````````````````````````````

The default behaviour of :func:`~matplotlib.pyplot.contour` and

:func:`~matplotlib.pyplot.contourf` when using a masked array is now determined

by the new keyword argument `corner_mask`, or if this is not specified then

the new rcParam `contour.corner_mask` instead. The new default behaviour is

equivalent to using `corner_mask=True`; the previous behaviour can be obtained

using `corner_mask=False` or by changing the rcParam. The example

http://matplotlib.org/examples/pylab_examples/contour_corner_mask.html

demonstrates the difference. Use of the old contouring algorithm, which is

obtained with `corner_mask='legacy'`, is now deprecated.

Contour labels may now appear in different places than in earlier versions of

matplotlib.

In addition, the keyword argument `nchunk` now applies to

:func:`~matplotlib.pyplot.contour` as well as

:func:`~matplotlib.pyplot.contourf`, and it subdivides the domain into

subdomains of exactly `nchunk` by `nchunk` quads, whereas previously it was

only roughly `nchunk` by `nchunk` quads.

The C/C++ object that performs contour calculations used to be stored in the

public attribute QuadContourSet.Cntr, but is now stored in a private attribute

and should not be accessed by end users.

Added set_params function to all Locator types

``````````````````````````````````````````````

This was a bug fix targeted at making the api for Locators more consistent.

In the old behavior, only locators of type MaxNLocator have set_params()

defined, causing its use on any other Locator to throw an AttributeError *(

aside: set_params(args) is a function that sets the parameters of a Locator

instance to be as specified within args)*. The fix involves moving set_params()

to the Locator class such that all subtypes will have this function defined.

Since each of the Locator subtype have their own modifiable parameters, a

universal set_params() in Locator isn't ideal. Instead, a default no-operation

function that raises a warning is implemented in Locator. Subtypes extending

Locator will then override with their own implementations. Subtypes that do

not have a need for set_params() will fall back onto their parent's

implementation, which raises a warning as intended.

In the new behavior, all Locator instances will not throw an AttributeError

when set_param() is called. For Locators that do not implement set_params(),

the default implementation in Locator is used.

Disallow ``None`` as x or y value in ax.plot

````````````````````````````````````````````

Do not allow ``None`` as a valid input for the ``x`` or ``y`` args in

`ax.plot`. This may break some user code, but this was never officially

supported (ex documented) and allowing ``None`` objects through can lead

to confusing exceptions downstream.

To create an empty line use ::

ln1, = ax.plot([], [], ...)

ln2, = ax.plot([], ...)

In either case to update the data in the `Line2D` object you must update

both the ``x`` and ``y`` data.

Removed `args` and `kwargs` from `MicrosecondLocator.__call__`

``````````````````````````````````````````````````````````````

The call signature of :meth:`~matplotlib.dates.MicrosecondLocator.__call__`

has changed from `__call__(self, *args, **kwargs)` to `__call__(self)`.

This is consistent with the super class :class:`~matplotlib.ticker.Locator`

and also all the other Locators derived from this super class.

No `ValueError` for the MicrosecondLocator and YearLocator

``````````````````````````````````````````````````````````

The :class:`~matplotlib.dates.MicrosecondLocator` and

:class:`~matplotlib.dates.YearLocator` objects when called will return

an empty list if the axes have no data or the view has no interval.

Previously, they raised a `ValueError`. This is consistent with all

the Date Locators.

'OffsetBox.DrawingArea' respects the 'clip' keyword argument

````````````````````````````````````````````````````````````

The call signature was `OffsetBox.DrawingArea(..., clip=True)` but nothing

was done with the `clip` argument. The object did not do any clipping

regardless of that parameter. Now the object can and does clip the child `Artists` if they are set to be clipped.

You can turn off the clipping on a per-child basis using `child.set_clip_on(False)`.

Add salt to clipPath id

```````````````````````

Add salt to the hash used to determine the id of the ``clipPath``

nodes. This is to avoid conflicts in two svg documents with the same

clip path are included in the same document (see

https://github.com/ipython/ipython/issues/8133 and

https://github.com/matplotlib/matplotlib/issues/4349 ), however this

means that the svg output is no longer deterministic if the same

figure is saved twice. It is not expected that this will affect any

users as the current ids are generated from an md5 hash of properties

of the clip path and any user would have a very difficult time

anticipating the value of the id.

Changed snap threshold for circle markers to inf

````````````````````````````````````````````````

When drawing circle markers above some marker size (previously 6.0)

the path used to generate the marker was snapped to pixel centers. However,

this ends up distorting the marker away from a circle. By setting the

snap threshold to inf snapping is never done on circles.

This change broke several tests, but is an improvement.

Preserve units with Text position

`````````````````````````````````

Previously the 'get_position' method on Text would strip away unit information

even though the units were still present. There was no inherent need to do

this, so it has been changed so that unit data (if present) will be preserved.

Essentially a call to 'get_position' will return the exact value from a call to

'set_position'.

If you wish to get the old behaviour, then you can use the new method called

'get_unitless_position'.

New API for custom Axes view changes

````````````````````````````````````

Interactive pan and zoom were previously implemented using a Cartesian-specific

algorithm that was not necessarily applicable to custom Axes. Three new private

methods, :meth:`~matplotlib.axes._base._AxesBase._get_view`,

:meth:`~matplotlib.axes._base._AxesBase._set_view`, and

:meth:`~matplotlib.axes._base._AxesBase._set_view_from_bbox`, allow for custom

``Axes`` classes to override the pan and zoom algorithms. Implementors of

custom ``Axes`` who override these methods may provide suitable behaviour for

both pan and zoom as well as the view navigation buttons on the interactive

toolbars.

MathTex visual changes

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

The spacing commands in mathtext have been changed to more closely

match vanilla TeX.

Improved spacing in mathtext

````````````````````````````

The extra space that appeared after subscripts and superscripts has

been removed.

No annotation coordinates wrap

``````````````````````````````

In #2351 for 1.4.0 the behavior of ['axes points', 'axes pixel',

'figure points', 'figure pixel'] as coordinates was change to

no longer wrap for negative values. In 1.4.3 this change was

reverted for 'axes points' and 'axes pixel' and in addition caused

'axes fraction' to wrap. For 1.5 the behavior has been reverted to

as it was in 1.4.0-1.4.2, no wrapping for any type of coordinate.

Deprecation

-----------

Deprecated `GraphicsContextBase.set_graylevel`

``````````````````````````````````````````````

The `GraphicsContextBase.set_graylevel` function has been deprecated in 1.5 and

will be removed in 1.6. It has been unused. The

`GraphicsContextBase.set_foreground` could be used instead.

deprecated idle_event

`````````````````````

The `idle_event` was broken or missing in most backends and causes spurious

warnings in some cases, and its use in creating animations is now obsolete due

to the animations module. Therefore code involving it has been removed from all

but the wx backend (where it partially works), and its use is deprecated. The

animations module may be used instead to create animations.

`color_cycle` deprecated

````````````````````````

In light of the new property cycling feature,

the Axes method *set_color_cycle* is now deprecated.

Calling this method will replace the current property cycle with

one that cycles just the given colors.

Similarly, the rc parameter *axes.color_cycle* is also deprecated in

lieu of the new *axes.prop_cycle* parameter. Having both parameters in

the same rc file is not recommended as the result cannot be

predicted. For compatibility, setting *axes.color_cycle* will

replace the cycler in *axes.prop_cycle* with a color cycle.

Accessing *axes.color_cycle* will return just the color portion

of the property cycle, if it exists.

Timeline for removal has not been set.

Bundled jquery

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

The version of jquery bundled with the webagg backend has been upgraded

from 1.7.1 to 1.11.3. If you are using the version of jquery bundled

with webagg you will need to update you html files as such

.. code-block:: diff

- <script src="_static/jquery/js/jquery-1.7.1.min.js"></script>

+ <script src="_static/jquery/js/jquery-1.11.3.min.js"></script>

Code Removed

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

Removed `Image` from main namespace

```````````````````````````````````

`Image` was imported from PIL/pillow to test if PIL is available, but there is no

reason to keep `Image` in the namespace once the availability has been determined.

Removed `lod` from Artist

`````````````````````````

Removed the method *set_lod* and all references to

the attribute *_lod* as the are not used anywhere else in the

code base. It appears to be a feature stub that was never built

out.

Removed threading related classes from cbook

````````````````````````````````````````````

The classes ``Scheduler``, ``Timeout``, and ``Idle`` were in cbook, but

are not used internally. They appear to be a prototype for the idle event

system which was not working and has recently been pulled out.

Removed `Lena` images from sample_data

``````````````````````````````````````

The ``lena.png`` and ``lena.jpg`` images have been removed from

matplotlib's sample_data directory. The images are also no longer

available from `matplotlib.cbook.get_sample_data`. We suggest using

`matplotlib.cbook.get_sample_data('grace_hopper.png')` or

`matplotlib.cbook.get_sample_data('grace_hopper.jpg')` instead.

Legend

``````

Removed handling of `loc` as a positional argument to `Legend`

Legend handlers

```````````````

Remove code to allow legend handlers to be callable. They must now

implement a method ``legend_artist``.

Axis

````

Removed method ``set_scale``. This is now handled via a private method which

should not be used directly by users. It is called via ``Axes.set_{x,y}scale``

which takes care of ensuring the coupled changes are also made to the Axes object.

finance.py

``````````

Removed functions with ambiguous argument order from finance.py

Annotation

``````````

Removed ``textcoords`` and ``xytext`` proprieties from Annotation objects.

spinxext.ipython_*.py

`````````````````````

Both ``ipython_console_highlighting`` and ``ipython_directive`` have been moved to

`IPython`.

Change your import from 'matplotlib.sphinxext.ipython_directive' to

'IPython.sphinxext.ipython_directive' and from 'matplotlib.sphinxext.ipython_directive' to

'IPython.sphinxext.ipython_directive'

LineCollection.color

````````````````````

Deprecated in 2005, use ``set_color``

remove ``'faceted'`` as a valid value for `shading` in ``tri.tripcolor``

````````````````````````````````````````````````````````````````````````

Use `edgecolor` instead. Added validation on ``shading`` to

only be valid values.

Remove ``faceted`` kwarg from scatter

`````````````````````````````````````

Remove support for the ``faceted`` kwarg. This was deprecated in

d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by

``edgecolor``.

Remove ``set_colorbar`` method from ``ScalarMappable``

``````````````````````````````````````````````````````

Remove ``set_colorbar`` method, use `colorbar` attribute directly.

patheffects.svg

```````````````

- remove ``get_proxy_renderer`` method from ``AbstarctPathEffect`` class

- remove ``patch_alpha`` and ``offset_xy`` from ``SimplePatchShadow``

Remove ``testing.image_util.py``

````````````````````````````````

Contained only a no-longer used port of functionality from PIL

Remove ``mlab.FIFOBuffer``

``````````````````````````

Not used internally and not part of core mission of mpl.

Remove ``mlab.prepca``

``````````````````````

Deprecated in 2009.

Remove ``NavigationToolbar2QTAgg``

``````````````````````````````````

Added no functionality over the base ``NavigationToolbar2Qt``

mpl.py

``````

Remove the module `matplotlib.mpl`. Deprecated in 1.3 by

PR #1670 and commit 78ce67d161625833cacff23cfe5d74920248c5b2

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