You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<divid="unreleased-message"> You are reading an old version of the documentation (v1.4.1). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<h1>API Changes<aclass="headerlink" href="#api-changes" title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<p>For new features that were added to matplotlib, please see
<aclass="reference internal" href="../users/whats_new.html#whats-new"><em>What’s new in matplotlib</em></a>.</p>
<divclass="section" id="changes-in-1-4-x">
<h2>Changes in 1.4.x<aclass="headerlink" href="#changes-in-1-4-x" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="code-changes">
<h3>Code changes<aclass="headerlink" href="#code-changes" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first">A major refactoring of the axes module was made. The axes module has been
split into smaller modules:</p>
<blockquote>
<div><ulclass="simple">
<li>the <codeclass="xref py py-obj docutils literal"><spanclass="pre">_base</span></code> module, which contains a new private _AxesBase class. This
class contains all methods except plotting and labelling methods.</li>
<li>the <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes</span></code> module, which contains the Axes class. This class inherits
from _AxesBase, and contains all plotting and labelling methods.</li>
<li>the <codeclass="xref py py-obj docutils literal"><spanclass="pre">_subplot</span></code> module, with all the classes concerning subplotting.</li>
</ul>
</div></blockquote>
</li>
</ul>
<p>There are a couple of things that do not exists in the <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes</span></code> module’s
namespace anymore. If you use them, you need to import them from their
<li><pclass="first">As part of the refactoring to enable Qt5 support, the module
<codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.backends.qt4_compat</span></code> was renamed to
<codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.qt_compat</span></code>. <codeclass="xref py py-obj docutils literal"><spanclass="pre">qt4_compat</span></code> is deprecated in 1.4 and
will be removed in 1.5.</p>
</li>
<li><pclass="first">The <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.errorbar" title="matplotlib.pyplot.errorbar"><codeclass="xref py py-func docutils literal"><spanclass="pre">errorbar()</span></code></a> method has been changed such that
the upper and lower limits (<em>lolims</em>, <em>uplims</em>, <em>xlolims</em>, <em>xuplims</em>) now
point in the correct direction.</p>
</li>
<li><pclass="first">The <em>fmt</em> kwarg for <codeclass="xref py py-func docutils literal"><spanclass="pre">plot()</span></code> defaults.</p>
</li>
<li><pclass="first">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
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues/2889">https://github.com/matplotlib/matplotlib/issues/2889</a> for more detail.</p>
</li>
<li><pclass="first">The Sphinx extensions <codeclass="xref py py-obj docutils literal"><spanclass="pre">ipython_directive</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">ipython_console_highlighting</span></code> have been moved to the IPython
project itself. While they remain in matplotlib for this release,
they have been deprecated. Update your extensions in <codeclass="xref py py-obj docutils literal"><spanclass="pre">conf.py</span></code> to
point to <codeclass="xref py py-obj docutils literal"><spanclass="pre">IPython.sphinxext.ipython_directive</span></code> instead of
<li><pclass="first">In <aclass="reference internal" href="finance_api.html#module-matplotlib.finance" title="matplotlib.finance"><codeclass="xref py py-obj docutils literal"><spanclass="pre">finance</span></code></a>, almost all functions have been deprecated
and replaced with a pair of functions name <codeclass="xref py py-obj docutils literal"><spanclass="pre">*_ochl</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">*_ohlc</span></code>.
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.</p>
</li>
<li><pclass="first">For consistency the <codeclass="docutils literal"><spanclass="pre">face_alpha</span></code> keyword to
<aclass="reference internal" href="patheffects_api.html#matplotlib.patheffects.SimplePatchShadow" title="matplotlib.patheffects.SimplePatchShadow"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.patheffects.SimplePatchShadow</span></code></a> has been deprecated in
favour of the <codeclass="docutils literal"><spanclass="pre">alpha</span></code> keyword. Similarly, the keyword <codeclass="docutils literal"><spanclass="pre">offset_xy</span></code> is now
named <codeclass="docutils literal"><spanclass="pre">offset</span></code> across all <codeclass="xref py py-class docutils literal"><spanclass="pre">_Base`</span></code> has
been renamed to <aclass="reference internal" href="patheffects_api.html#matplotlib.patheffects.AbstractPathEffect" title="matplotlib.patheffects.AbstractPathEffect"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.patheffects.AbstractPathEffect</span></code></a>.
<codeclass="docutils literal"><spanclass="pre">matplotlib.patheffect.ProxyRenderer</span></code> has been renamed to
<aclass="reference internal" href="patheffects_api.html#matplotlib.patheffects.PathEffectRenderer" title="matplotlib.patheffects.PathEffectRenderer"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.patheffects.PathEffectRenderer</span></code></a> and is now a full
RendererBase subclass.</p>
</li>
<li><pclass="first">The artist used to draw the outline of a <codeclass="xref py py-obj docutils literal"><spanclass="pre">colorbar</span></code> has been changed
from a <aclass="reference internal" href="lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.lines.Line2D</span></code></a> to <aclass="reference internal" href="patches_api.html#matplotlib.patches.Polygon" title="matplotlib.patches.Polygon"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.patches.Polygon</span></code></a>,
thus <codeclass="xref py py-obj docutils literal"><spanclass="pre">colorbar.ColorbarBase.outline</span></code> is now a
<li><pclass="first">The legend handler interface has changed from a callable, to any object
which implements the <codeclass="docutils literal"><spanclass="pre">legend_artists</span></code> method (a deprecation phase will
see this interface be maintained for v1.4). See
<aclass="reference internal" href="../users/legend_guide.html#plotting-guide-legend"><em>Legend guide</em></a> for further details. Further legend changes
include:</p>
<blockquote>
<div><ulclass="simple">
<li><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.axes.Axes._get_legend_handles()</span></code> now returns a generator
argument has been deprecated. Use the “loc” keyword instead.</li>
</ul>
</div></blockquote>
</li>
<li><pclass="first">The rcParams <codeclass="xref py py-obj docutils literal"><spanclass="pre">savefig.transparent</span></code> has been added to control
default transparency when saving figures.</p>
</li>
<li><pclass="first">Slightly refactored the <codeclass="xref py py-obj docutils literal"><spanclass="pre">Annotation</span></code> family. The text location in
<codeclass="xref py py-obj docutils literal"><spanclass="pre">Annotation</span></code> is now handled entirely handled by the underlying <codeclass="xref py py-obj docutils literal"><spanclass="pre">Text</span></code>
object so <codeclass="xref py py-obj docutils literal"><spanclass="pre">set_position</span></code> works as expected. The attributes <codeclass="xref py py-obj docutils literal"><spanclass="pre">xytext</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">textcoords</span></code> have been deprecated in favor of <codeclass="xref py py-obj docutils literal"><spanclass="pre">xyann</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">anncoords</span></code> so
that <codeclass="xref py py-obj docutils literal"><spanclass="pre">Annotation</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">AnnotaionBbox</span></code> can share a common sensibly named
api for getting/setting the location of the text or box.</p>
<blockquote>
<div><ulclass="simple">
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">xyann</span></code> -> set the location of the annotation</li>
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">xy</span></code> -> set where the arrow points to</li>
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">anncoords</span></code> -> set the units of the annotation location</li>
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">xycoords</span></code> -> set the units of the point location</li>
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">set_position()</span></code> -> <codeclass="xref py py-obj docutils literal"><spanclass="pre">Annotation</span></code> only set location of annotation</li>
<aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.csd" title="matplotlib.pyplot.csd"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.pyplot.csd</span></code></a>, and <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.cohere" title="matplotlib.pyplot.cohere"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.pyplot.cohere</span></code></a>, 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.</p>
</li>
<li><pclass="first">Added the rcParam <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes.fromatter.useoffset</span></code> to control the default value
of <codeclass="xref py py-obj docutils literal"><spanclass="pre">useOffset</span></code> in <codeclass="xref py py-obj docutils literal"><spanclass="pre">ticker.ScalarFormatter</span></code></p>
does the exact same thing as <codeclass="xref py py-obj docutils literal"><spanclass="pre">FormatStrFormatter</span></code>, but for new-style
formatting strings.</p>
</li>
<li><pclass="first">Deprecated <codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.testing.image_util</span></code> and the only function within,
<codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.testing.image_util.autocontrast</span></code>. These will be removed
completely in v1.5.0.</p>
</li>
<li><pclass="first">The <codeclass="docutils literal"><spanclass="pre">fmt</span></code> argument of <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.plot_date" title="matplotlib.axes.Axes.plot_date"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plot_date()</span></code></a> has been
changed from <codeclass="docutils literal"><spanclass="pre">bo</span></code> to just <codeclass="docutils literal"><spanclass="pre">o</span></code>, so color cycling can happen by default.</p>
</li>
<li><pclass="first">Removed the class <codeclass="xref py py-obj docutils literal"><spanclass="pre">FigureManagerQTAgg</span></code> and deprecated <codeclass="xref py py-obj docutils literal"><spanclass="pre">NavigationToolbar2QTAgg</span></code>
which will be removed in 1.5.</p>
</li>
<li><pclass="first">Removed formerly public (non-prefixed) attributes <codeclass="xref py py-obj docutils literal"><spanclass="pre">rect</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">drawRect</span></code> from <codeclass="xref py py-obj docutils literal"><spanclass="pre">FigureCanvasQTAgg</span></code>; they were always an
implementation detail of the (preserved) <codeclass="xref py py-obj docutils literal"><spanclass="pre">drawRectangle()</span></code> function.</p>
</li>
<li><pclass="first">The function signatures of <codeclass="xref py py-obj docutils literal"><spanclass="pre">tight_bbox.adjust_bbox</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">tight_bbox.process_figure_for_rasterizing</span></code> have been changed. A new
<codeclass="xref py py-obj docutils literal"><spanclass="pre">fixed_dpi</span></code> parameter allows for overriding the <codeclass="xref py py-obj docutils literal"><spanclass="pre">figure.dpi</span></code> setting
instead of trying to deduce the intended behaviour from the file format.</p>
</li>
<li><pclass="first">Added support for horizontal/vertical axes padding to
<codeclass="xref py py-obj docutils literal"><spanclass="pre">mpl_toolkits.axes_grid1.ImageGrid</span></code> — argument <codeclass="docutils literal"><spanclass="pre">axes_pad</span></code> can now be
tuple-like if separate axis padding is required.
The original behavior is preserved.</p>
</li>
<li><pclass="first">Added support for skewed transforms to <aclass="reference internal" href="../devel/transformations.html#matplotlib.transforms.Affine2D" title="matplotlib.transforms.Affine2D"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.transforms.Affine2D</span></code></a>,
which can be created using the <codeclass="xref py py-obj docutils literal"><spanclass="pre">skew</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">skew_deg</span></code> methods.</p>
</li>
<li><pclass="first">Added clockwise parameter to control sectors direction in <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes.pie</span></code></p>
</li>
<li><pclass="first">In <aclass="reference internal" href="lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.lines.Line2D</span></code></a> the <codeclass="xref py py-obj docutils literal"><spanclass="pre">markevery</span></code> 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.</p>
</li>
<li><pclass="first">removed prop kwarg from <codeclass="xref py py-obj docutils literal"><spanclass="pre">mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar</span></code>
call. It was passed through to the base-class <codeclass="xref py py-obj docutils literal"><spanclass="pre">__init__</span></code> and is only used for
setting padding. Now <codeclass="xref py py-obj docutils literal"><spanclass="pre">fontproperties</span></code> (which is what is really used to set
the font properties of <codeclass="xref py py-obj docutils literal"><spanclass="pre">AnchoredSizeBar</span></code>) is passed through in place of <codeclass="xref py py-obj docutils literal"><spanclass="pre">prop</span></code>.
If <codeclass="xref py py-obj docutils literal"><spanclass="pre">fontpropreties</span></code> is not passed in, but <codeclass="xref py py-obj docutils literal"><spanclass="pre">prop</span></code> is, then <codeclass="xref py py-obj docutils literal"><spanclass="pre">prop</span></code> is used inplace
of <codeclass="xref py py-obj docutils literal"><spanclass="pre">fontpropreties</span></code>. If both are passed in, <codeclass="xref py py-obj docutils literal"><spanclass="pre">prop</span></code> is silently ignored.</p>
</li>
<li><pclass="first">The use of the index 0 in <codeclass="xref py py-obj docutils literal"><spanclass="pre">plt.subplot</span></code> and related commands is
deprecated. Due to a lack of validation calling <codeclass="xref py py-obj docutils literal"><spanclass="pre">plt.subplots(2,</span><spanclass="pre">2,</span>
<spanclass="pre">0)</span></code> 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 <codeclass="xref py py-obj docutils literal"><spanclass="pre">GridSpec</span></code> object used to
determine where the axes should go, 1 is subtracted off. Passing in
0 results in passing -1 to <codeclass="xref py py-obj docutils literal"><spanclass="pre">GridSpec</span></code> 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.</p>
</li>
<li><pclass="first">Clipping is now off by default on offset boxes.</p>
</li>
<li><pclass="first">matplotlib now uses a less-aggressive call to <codeclass="docutils literal"><spanclass="pre">gc.collect(1)</span></code> when
closing figures to avoid major delays with large numbers of user objects
in memory.</p>
</li>
<li><pclass="first">The default clip value of <em>all</em> pie artists now defaults to <codeclass="docutils literal"><spanclass="pre">False</span></code>.</p>
</li>
</ul>
</div>
<divclass="section" id="code-removal">
<h3>Code removal<aclass="headerlink" href="#code-removal" title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li>Removed <codeclass="docutils literal"><spanclass="pre">mlab.levypdf</span></code>. The code raised a numpy error (and has for
a long time) and was not the standard form of the Levy distribution.
<codeclass="docutils literal"><spanclass="pre">scipy.stats.levy</span></code> should be used instead</li>
</ul>
</div>
</div>
<divclass="section" id="changes-in-1-3-x">
<spanid="changes-in-1-3"></span><h2>Changes in 1.3.x<aclass="headerlink" href="#changes-in-1-3-x" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="changes-in-1-3-1">
<h3>Changes in 1.3.1<aclass="headerlink" href="#changes-in-1-3-1" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<ulclass="simple">
<li><codeclass="xref py py-obj docutils literal"><spanclass="pre">text.Text.cached</span></code> (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.</li>
<li>The method <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.hist" title="matplotlib.axes.Axes.hist"><codeclass="xref py py-meth docutils literal"><spanclass="pre">hist()</span></code></a> now always returns bin
occupancies as an array of type <codeclass="xref py py-obj docutils literal"><spanclass="pre">float</span></code>. Previously, it was sometimes
an array of type <codeclass="xref py py-obj docutils literal"><spanclass="pre">int</span></code>, depending on the call.</li>
</ul>
</div>
<divclass="section" id="id1">
<h3>Code removal<aclass="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first">The following items that were deprecated in version 1.2 or earlier
have now been removed completely.</p>
<blockquote>
<div><ul>
<li><pclass="first">The Qt 3.x backends (<codeclass="xref py py-obj docutils literal"><spanclass="pre">qt</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">qtagg</span></code>) have been removed in
favor of the Qt 4.x backends (<codeclass="xref py py-obj docutils literal"><spanclass="pre">qt4</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">qt4agg</span></code>).</p>
</li>
<li><pclass="first">The FltkAgg and Emf backends have been removed.</p>
</li>
<li><pclass="first">The <codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.nxutils</span></code> module has been removed. Use the
functionality on <aclass="reference internal" href="path_api.html#matplotlib.path.Path.contains_point" title="matplotlib.path.Path.contains_point"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.path.Path.contains_point</span></code></a> and
friends instead.</p>
</li>
<li><pclass="first">Instead of <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes.Axes.get_frame</span></code>, use <codeclass="xref py py-obj docutils literal"><spanclass="pre">axes.Axes.patch</span></code>.</p>
</li>
<li><pclass="first">The following <codeclass="xref py py-obj docutils literal"><spanclass="pre">kwargs</span></code> to the <codeclass="xref py py-obj docutils literal"><spanclass="pre">legend</span></code> function have been
<h3>Code deprecation<aclass="headerlink" href="#code-deprecation" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first">The CocoaAgg backend has been deprecated, with the possibility for
deletion or resurrection in a future release.</p>
</li>
<li><pclass="first">The top-level functions in <aclass="reference internal" href="path_api.html#module-matplotlib.path" title="matplotlib.path"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.path</span></code></a> that are implemented in
C++ were never meant to be public. Instead, users should use the
Pythonic wrappers for them in the <codeclass="xref py py-obj docutils literal"><spanclass="pre">path.Path</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">collections.Collection</span></code> classes. Use the following mapping to update
<li><pclass="first"><aclass="reference internal" href="colors_api.html#matplotlib.colors.normalize" title="matplotlib.colors.normalize"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.colors.normalize</span></code></a> and <aclass="reference internal" href="colors_api.html#matplotlib.colors.no_norm" title="matplotlib.colors.no_norm"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.colors.no_norm</span></code></a> have
been deprecated in favour of <aclass="reference internal" href="colors_api.html#matplotlib.colors.Normalize" title="matplotlib.colors.Normalize"><codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlib.colors.Normalize</span></code></a> and
<li><pclass="first">The <codeclass="xref py py-obj docutils literal"><spanclass="pre">ScalarMappable</span></code> class’ <codeclass="xref py py-obj docutils literal"><spanclass="pre">set_colorbar</span></code> is now
deprecated. Instead, the
<aclass="reference internal" href="cm_api.html#matplotlib.cm.ScalarMappable.colorbar" title="matplotlib.cm.ScalarMappable.colorbar"><codeclass="xref py py-attr docutils literal"><spanclass="pre">matplotlib.cm.ScalarMappable.colorbar</span></code></a> attribute should be
used. In previous matplotlib versions this attribute was an
undocumented tuple of <codeclass="docutils literal"><spanclass="pre">(colorbar_instance,</span><spanclass="pre">colorbar_axes)</span></code> but is
now just <codeclass="docutils literal"><spanclass="pre">colorbar_instance</span></code>. To get the colorbar axes it is
possible to just use the
<aclass="reference internal" href="colorbar_api.html#matplotlib.colorbar.ColorbarBase.ax" title="matplotlib.colorbar.ColorbarBase.ax"><codeclass="xref py py-attr docutils literal"><spanclass="pre">ax</span></code></a> attribute on a colorbar
instance.</p>
</li>
<li><pclass="first">The <codeclass="xref py py-obj docutils literal"><spanclass="pre">mpl</span></code> module is now deprecated. Those who relied on this
module should transition to simply using <codeclass="docutils literal"><spanclass="pre">import</span><spanclass="pre">matplotlib</span><spanclass="pre">as</span><spanclass="pre">mpl</span></code>.</p>
</li>
</ul>
</div>
<divclass="section" id="id2">
<h3>Code changes<aclass="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first"><aclass="reference internal" href="patches_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><codeclass="xref py py-class docutils literal"><spanclass="pre">Patch</span></code></a> now fully supports using RGBA values for
its <codeclass="docutils literal"><spanclass="pre">facecolor</span></code> and <codeclass="docutils literal"><spanclass="pre">edgecolor</span></code> attributes, which enables faces and
edges to have different alpha values. If the
<aclass="reference internal" href="patches_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><codeclass="xref py py-class docutils literal"><spanclass="pre">Patch</span></code></a> object’s <codeclass="docutils literal"><spanclass="pre">alpha</span></code> attribute is set to
anything other than <codeclass="docutils literal"><spanclass="pre">None</span></code>, that value will override any alpha-channel
value in both the face and edge colors. Previously, if
<aclass="reference internal" href="patches_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><codeclass="xref py py-class docutils literal"><spanclass="pre">Patch</span></code></a> had <codeclass="docutils literal"><spanclass="pre">alpha=None</span></code>, the alpha component
of <codeclass="docutils literal"><spanclass="pre">edgecolor</span></code> would be applied to both the edge and face.</p>
</li>
<li><pclass="first">The optional <codeclass="docutils literal"><spanclass="pre">isRGB</span></code> argument to
the other GraphicsContext classes that descend from it) has been renamed to
<codeclass="docutils literal"><spanclass="pre">isRGBA</span></code>, and should now only be set to <codeclass="docutils literal"><spanclass="pre">True</span></code> if the <codeclass="docutils literal"><spanclass="pre">fg</span></code> color
argument is known to be an RGBA tuple.</p>
</li>
<li><pclass="first">For <aclass="reference internal" href="patches_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><codeclass="xref py py-class docutils literal"><spanclass="pre">Patch</span></code></a>, the <codeclass="docutils literal"><spanclass="pre">capstyle</span></code> used is now
<codeclass="docutils literal"><spanclass="pre">butt</span></code>, to be consistent with the default for most other objects, and to
avoid problems with non-solid <codeclass="docutils literal"><spanclass="pre">linestyle</span></code> appearing solid when using a
large <codeclass="docutils literal"><spanclass="pre">linewidth</span></code>. Previously, <aclass="reference internal" href="patches_api.html#matplotlib.patches.Patch" title="matplotlib.patches.Patch"><codeclass="xref py py-class docutils literal"><spanclass="pre">Patch</span></code></a> used
<li><pclass="first"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Path</span></code> objects can now be marked as <codeclass="xref py py-obj docutils literal"><spanclass="pre">readonly</span></code> by passing
<codeclass="xref py py-obj docutils literal"><spanclass="pre">readonly=True</span></code> to its constructor. The built-in path singletons,
obtained through <codeclass="xref py py-obj docutils literal"><spanclass="pre">Path.unit*</span></code> class methods return readonly paths.
If you have code that modified these, you will need to make a
<li><pclass="first">To support XKCD style plots, the <aclass="reference internal" href="path_api.html#matplotlib.path.cleanup_path" title="matplotlib.path.cleanup_path"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.path.cleanup_path()</span></code></a>
method’s signature was updated to require a sketch argument. Users of
<aclass="reference internal" href="path_api.html#matplotlib.path.cleanup_path" title="matplotlib.path.cleanup_path"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.path.cleanup_path()</span></code></a> are encouraged to use the new
<li><pclass="first">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
<codeclass="xref py py-obj docutils literal"><spanclass="pre">axvline</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">axhline</span></code>, 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.</p>
</li>
<li><pclass="first">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.</p>
</li>
<li><pclass="first">In <aclass="reference internal" href="patches_api.html#matplotlib.patches.FancyArrow" title="matplotlib.patches.FancyArrow"><codeclass="xref py py-class docutils literal"><spanclass="pre">FancyArrow</span></code></a>, the default arrow head
width, <codeclass="docutils literal"><spanclass="pre">head_width</span></code>, has been made larger to produce a visible
arrow head. The new value of this kwarg is <codeclass="docutils literal"><spanclass="pre">head_width</span><spanclass="pre">=</span><spanclass="pre">20</span><spanclass="pre">*</span>
<spanclass="pre">width</span></code>.</p>
</li>
<li><pclass="first">It is now possible to provide <codeclass="docutils literal"><spanclass="pre">number</span><spanclass="pre">of</span><spanclass="pre">levels</span><spanclass="pre">+</span><spanclass="pre">1</span></code> colors in the case of
<codeclass="xref py py-obj docutils literal"><spanclass="pre">extend='both'</span></code> for contourf (or just <codeclass="docutils literal"><spanclass="pre">number</span><spanclass="pre">of</span><spanclass="pre">levels</span></code> colors for an
extend value <codeclass="docutils literal"><spanclass="pre">min</span></code> or <codeclass="docutils literal"><spanclass="pre">max</span></code>) such that the resulting colormap’s
<codeclass="docutils literal"><spanclass="pre">set_under</span></code> and <codeclass="docutils literal"><spanclass="pre">set_over</span></code> 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 <codeclass="docutils literal"><spanclass="pre">extend='both'</span></code> would expect <codeclass="docutils literal"><spanclass="pre">number</span><spanclass="pre">of</span><spanclass="pre">levels</span><spanclass="pre">+</span><spanclass="pre">2</span></code>
colors.</p>
</li>
<li><pclass="first">A new keyword <em>extendrect</em> in <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.colorbar" title="matplotlib.pyplot.colorbar"><codeclass="xref py py-meth docutils literal"><spanclass="pre">colorbar()</span></code></a> and
<aclass="reference internal" href="colorbar_api.html#matplotlib.colorbar.ColorbarBase" title="matplotlib.colorbar.ColorbarBase"><codeclass="xref py py-class docutils literal"><spanclass="pre">ColorbarBase</span></code></a> allows one to control the shape
of colorbar extensions.</p>
</li>
<li><pclass="first">The extension of <aclass="reference internal" href="widgets_api.html#matplotlib.widgets.MultiCursor" title="matplotlib.widgets.MultiCursor"><codeclass="xref py py-class docutils literal"><spanclass="pre">MultiCursor</span></code></a> to both vertical
(default) and/or horizontal cursor implied that <codeclass="docutils literal"><spanclass="pre">self.line</span></code> is replaced
by <codeclass="docutils literal"><spanclass="pre">self.vline</span></code> for vertical cursors lines and <codeclass="docutils literal"><spanclass="pre">self.hline</span></code> is added
for the horizontal cursors lines.</p>
</li>
<li><pclass="first">On POSIX platforms, the <aclass="reference internal" href="cbook_api.html#matplotlib.cbook.report_memory" title="matplotlib.cbook.report_memory"><codeclass="xref py py-func docutils literal"><spanclass="pre">report_memory()</span></code></a> function
raises <codeclass="xref py py-class docutils literal"><spanclass="pre">NotImplementedError</span></code> instead of <codeclass="xref py py-class docutils literal"><spanclass="pre">OSError</span></code> if the
<strongclass="command">ps</strong> command cannot be run.</p>
</li>
<li><pclass="first">The <codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.cbook.check_output()</span></code> function has been moved to
<h3>Configuration and rcParams<aclass="headerlink" href="#configuration-and-rcparams" title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li>On Linux, the user-specific <codeclass="xref py py-obj docutils literal"><spanclass="pre">matplotlibrc</span></code> configuration file is now
located in <codeclass="xref py py-obj docutils literal"><spanclass="pre">config/matplotlib/matplotlibrc</span></code> to conform to the
<aclass="reference external" href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</a>.</li>
<li>The <codeclass="xref py py-obj docutils literal"><spanclass="pre">font.*</span></code> 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.</li>
<li>Removed call of <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.grid" title="matplotlib.axes.Axes.grid"><codeclass="xref py py-meth docutils literal"><spanclass="pre">grid()</span></code></a> in
<aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.plotfile" title="matplotlib.pyplot.plotfile"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plotfile()</span></code></a>. To draw the axes grid, set the
<codeclass="docutils literal"><spanclass="pre">axes.grid</span></code> rcParam to <em>True</em>, or explicitly call
<h2>Changes in 1.2.x<aclass="headerlink" href="#changes-in-1-2-x" title="Permalink to this headline">¶</a></h2>
<ul>
<li><pclass="first">The <codeclass="docutils literal"><spanclass="pre">classic</span></code> option of the rc parameter <codeclass="docutils literal"><spanclass="pre">toolbar</span></code> is deprecated
and will be removed in the next release.</p>
</li>
<li><pclass="first">The <codeclass="xref py py-meth docutils literal"><spanclass="pre">isvector()</span></code> method has been removed since it
is no longer functional.</p>
</li>
<li><pclass="first">The <codeclass="xref py py-obj docutils literal"><spanclass="pre">rasterization_zorder</span></code> property on <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-obj docutils literal"><spanclass="pre">Axes</span></code></a> a
zorder below which artists are rasterized. This has defaulted to
-30000.0, but it now defaults to <codeclass="xref py py-obj docutils literal"><spanclass="pre">None</span></code>, meaning no artists will be
rasterized. In order to rasterize artists below a given zorder
value, <codeclass="xref py py-obj docutils literal"><spanclass="pre">set_rasterization_zorder</span></code> must be explicitly called.</p>
when specifying a marker using a tuple, the angle is now specified
in degrees, not radians.</p>
</li>
<li><pclass="first">Using <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.twinx" title="matplotlib.axes.Axes.twinx"><codeclass="xref py py-meth docutils literal"><spanclass="pre">twinx()</span></code></a> or
<aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.twiny" title="matplotlib.axes.Axes.twiny"><codeclass="xref py py-meth docutils literal"><spanclass="pre">twiny()</span></code></a> no longer overrides the current locaters
and formatters on the axes.</p>
</li>
<li><pclass="first">In <aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.contourf" title="matplotlib.axes.Axes.contourf"><codeclass="xref py py-meth docutils literal"><spanclass="pre">contourf()</span></code></a>, the handling of the <em>extend</em>
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
<aclass="reference internal" href="colors_api.html#matplotlib.colors.Colormap.set_under" title="matplotlib.colors.Colormap.set_under"><codeclass="xref py py-meth docutils literal"><spanclass="pre">set_under()</span></code></a> and
<aclass="reference internal" href="colors_api.html#matplotlib.colors.Colormap.set_over" title="matplotlib.colors.Colormap.set_over"><codeclass="xref py py-meth docutils literal"><spanclass="pre">set_over()</span></code></a> methods, which
default to the colormap end points.</p>
</li>
<li><pclass="first">The new rc parameter <codeclass="docutils literal"><spanclass="pre">savefig.format</span></code> replaces <codeclass="docutils literal"><spanclass="pre">cairo.format</span></code> and
<codeclass="docutils literal"><spanclass="pre">savefig.extension</span></code>, and sets the default file format used by
<li><pclass="first">In <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.pie" title="matplotlib.pyplot.pie"><codeclass="xref py py-meth docutils literal"><spanclass="pre">pie()</span></code></a> and <codeclass="xref py py-meth docutils literal"><spanclass="pre">pie()</span></code>, one can
now set the radius of the pie; setting the <em>radius</em> to ‘None’ (the default
value), will result in a pie with a radius of 1 as before.</p>
</li>
<li><pclass="first">Use of <codeclass="xref py py-func docutils literal"><spanclass="pre">projection_factory()</span></code> is now deprecated
in favour of axes class identification using
<aclass="reference internal" href="../devel/add_new_projection.html#matplotlib.projections.process_projection_requirements" title="matplotlib.projections.process_projection_requirements"><codeclass="xref py py-func docutils literal"><spanclass="pre">process_projection_requirements()</span></code></a> followed by
direct axes class invocation (at the time of writing, functions which do this
<spanclass="k">raise</span><spanclass="ne">ValueError</span><spanclass="p">(</span><spanclass="s">'polar and projection args are inconsistent'</span><spanclass="p">)</span>
<p>This change means that third party objects can expose themselves as
matplotlib axes by providing a <codeclass="docutils literal"><spanclass="pre">_as_mpl_axes</span></code> method. See
<aclass="reference internal" href="../devel/add_new_projection.html#adding-new-scales"><em>Adding new scales and projections to matplotlib</em></a> for more detail.</p>
</li>
<li><pclass="first">A new keyword <em>extendfrac</em> in <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.colorbar" title="matplotlib.pyplot.colorbar"><codeclass="xref py py-meth docutils literal"><spanclass="pre">colorbar()</span></code></a> and
<aclass="reference internal" href="colorbar_api.html#matplotlib.colorbar.ColorbarBase" title="matplotlib.colorbar.ColorbarBase"><codeclass="xref py py-class docutils literal"><spanclass="pre">ColorbarBase</span></code></a> allows one to control the size of
the triangular minimum and maximum extensions on colorbars.</p>
</li>
<li><pclass="first">A new keyword <em>capthick</em> in <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.errorbar" title="matplotlib.pyplot.errorbar"><codeclass="xref py py-meth docutils literal"><spanclass="pre">errorbar()</span></code></a> has been
added as an intuitive alias to the <em>markeredgewidth</em> and <em>mew</em> 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
<em>capthick</em>.</p>
</li>
<li><pclass="first">Transform subclassing behaviour is now subtly changed. If your transform
implements a non-affine transformation, then it should override the
<codeclass="docutils literal"><spanclass="pre">transform_non_affine</span></code> method, rather than the generic <codeclass="docutils literal"><spanclass="pre">transform</span></code> method.
Previously transforms would define <codeclass="docutils literal"><spanclass="pre">transform</span></code> and then copy the
method into <codeclass="docutils literal"><spanclass="pre">transform_non_affine</span></code>:</p>
<li><pclass="first">Artists no longer have <codeclass="docutils literal"><spanclass="pre">x_isdata</span></code> or <codeclass="docutils literal"><spanclass="pre">y_isdata</span></code> attributes; instead
any artist’s transform can be interrogated with
<p>for versions before 1.2 this could only be achieved in a sub-optimal way,
using <codeclass="docutils literal"><spanclass="pre">ax.transData</span><spanclass="pre">+</span><spanclass="pre">ax.transAxes.inverted()</span></code> (depth is a new concept,
but had it existed it would return 4 for this example).</p>
</li>
<li><pclass="first"><codeclass="docutils literal"><spanclass="pre">twinx</span></code> and <codeclass="docutils literal"><spanclass="pre">twiny</span></code> now returns an instance of SubplotBase if
parent axes is an instance of SubplotBase.</p>
</li>
<li><pclass="first">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
will now always mean that the nearest-neighbor interpolation is performed.
If you want the no-op interpolation to be performed, choose ‘none’.</li>
<li>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.</li>
<li>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.</li>
<li>There is now a common set of markers for all plotting functions. Previously,
some markers existed only for <aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.scatter" title="matplotlib.pyplot.scatter"><codeclass="xref py py-meth docutils literal"><spanclass="pre">scatter()</span></code></a> or just for
<aclass="reference internal" href="pyplot_api.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plot()</span></code></a>. 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”.</li>
</ul>
</div>
<divclass="section" id="changes-beyond-0-99-x">
<h2>Changes beyond 0.99.x<aclass="headerlink" href="#changes-beyond-0-99-x" title="Permalink to this headline">¶</a></h2>
a sequence of color specs to match a sequence of datasets.</li>
<li>The <aclass="reference internal" href="collections_api.html#matplotlib.collections.EllipseCollection" title="matplotlib.collections.EllipseCollection"><codeclass="xref py py-class docutils literal"><spanclass="pre">EllipseCollection</span></code></a> has been
changed in two ways:<ul>
<li>There is a new <em>units</em> option, ‘xy’, that scales the ellipse with
the data units. This matches the :class:’~matplotlib.patches.Ellipse`
scaling.</li>
<li>The <em>height</em> and <em>width</em> kwargs have been changed to specify
the height and width, again for consistency with
<aclass="reference internal" href="patches_api.html#matplotlib.patches.Ellipse" title="matplotlib.patches.Ellipse"><codeclass="xref py py-class docutils literal"><spanclass="pre">Ellipse</span></code></a>, and to better match
their names; previously they specified the half-height and
half-width.</li>
</ul>
</li>
<li>There is a new rc parameter <codeclass="docutils literal"><spanclass="pre">axes.color_cycle</span></code>, and the color
cycle is now independent of the rc parameter <codeclass="docutils literal"><spanclass="pre">lines.color</span></code>.
<codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.Axes.set_default_color_cycle()</span></code> is deprecated.</li>
<li>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 <aclass="reference internal" href="backend_pdf_api.html#matplotlib.backends.backend_pdf.PdfPages" title="matplotlib.backends.backend_pdf.PdfPages"><codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.backends.backend_pdf.PdfPages</span></code></a> for
more information.</li>
<li>Removed <aclass="reference external" href="http://www.voidspace.org.uk/python/configobj.html">configobj</a> and <aclass="reference external" href="http://code.enthought.com/projects/traits">enthought.traits</a> packages, which are only
required by the experimental traited config and are somewhat out of
date. If needed, install them independently.</li>
</ul>
<ul>
<li><pclass="first">The new rc parameter <codeclass="docutils literal"><spanclass="pre">savefig.extension</span></code> sets the filename extension
that is used by <aclass="reference internal" href="figure_api.html#matplotlib.figure.Figure.savefig" title="matplotlib.figure.Figure.savefig"><codeclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.figure.Figure.savefig()</span></code></a> if its <em>fname</em>
argument lacks an extension.</p>
</li>
<li><pclass="first">In an effort to simplify the backend API, all clipping rectangles
and paths are now passed in using GraphicsContext objects, even
<li><aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.tripcolor" title="matplotlib.axes.Axes.tripcolor"><codeclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.axes.Axes.tripcolor()</span></code></a> draws a pseudocolor
plot on a triangular grid.</li>
<li><aclass="reference internal" href="axes_api.html#matplotlib.axes.Axes.triplot" title="matplotlib.axes.Axes.triplot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">matplotlib.axes.Axes.triplot()</span></code></a> draws a triangular grid
as lines and/or markers.</li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="changes-in-0-99">
<h2>Changes in 0.99<aclass="headerlink" href="#changes-in-0-99" title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<li>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.</li>
<li>User-generated colormaps can now be added to the set recognized
by <aclass="reference internal" href="cm_api.html#matplotlib.cm.get_cmap" title="matplotlib.cm.get_cmap"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.cm.get_cmap()</span></code></a>. Colormaps can be made the
<li><pclass="first">Added new <aclass="reference internal" href="image_api.html#matplotlib.image.imsave" title="matplotlib.image.imsave"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.image.imsave()</span></code></a> and exposed it to the
<li><pclass="first">Remove support for pyExcelerator in exceltools – use xlwt
instead</p>
</li>
<li><pclass="first">Changed the defaults of acorr and xcorr to use usevlines=True,
maxlags=10 and normed=True since these are the best defaults</p>
</li>
<li><pclass="first">Following keyword parameters for <codeclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.label.Label</span></code> are now
deprecated and new set of parameters are introduced. The new parameters