diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
index fa6acba5a2de..3e6a06a14d66 100644
--- a/doc/api/api_changes.rst
+++ b/doc/api/api_changes.rst
@@ -1,27 +1,150 @@
-===========
-API Changes
-===========
+=============
+ 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.
+updating matplotlib breaks your scripts, this list may help you figure
+out what caused the breakage and how to fix it by updating your code.
For new features that were added to matplotlib, please see
:ref:`whats-new`.
-Changes in 2.0.0
-================
+API Changes in 2.0.0
+====================
-Color of Axes
--------------
+Deprecation and removal
+-----------------------
+Color of Axes
+~~~~~~~~~~~~~
The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
deprecated in favor of ``facecolor``.
+GTK and GDK backends deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The GDK and GTK backends have been deprecated. These obsolete backends
+allow figures to be rendered via the GDK API to files and GTK2 figures.
+They are untested and known to be broken, and their use has been
+discouraged for some time. Instead, use the `GTKAgg` and `GTKCairo`
+backends for rendering to GTK2 windows.
+
+WX backend deprecated
+~~~~~~~~~~~~~~~~~~~~~
+The WX backend has been deprecated. It is untested, and its
+use has been discouraged for some time. Instead, use the `WXAgg`
+backend for rendering figures to WX windows.
+
+CocoaAgg backend removed
+~~~~~~~~~~~~~~~~~~~~~~~~
+The deprecated and not fully functional CocoaAgg backend has been removed.
+
+
+`Artist.update` has return value
+--------------------------------
+
+The methods `matplotlib.artist.Artist.set`,
+`matplotlib.Artist.update`, and the function `matplotlib.artist.setp`
+now use a common codepath to look up how to update the given artist
+properties (either using the setter methods or an attribute/property).
+
+The behavior of `matplotlib.Artist.update` is slightly changed to
+return a list of the values returned from the setter methods to avoid
+changing the API of `matplotlib.Artist.set` and
+`matplotlib.artist.setp`.
+
+The keys passed into `matplotlib.Artist.update` are now converted to
+lower case before being processed, to match the behavior of
+`matplotlib.Artist.set` and `matplotlib.artist.setp`. This should not
+break any user code because there are no set methods with capitals in
+their names, but this puts a constraint on naming properties in the future.
+
+
+`Legend` initializers gain edgecolor and facecolor kwargs
+---------------------------------------------------------
+
+The :class:`~matplotlib.legend.Legend` background patch (or 'frame')
+can have its ``edgecolor`` and ``facecolor`` determined by the
+corresponding keyword arguments to the :class:`matplotlib.legend.Legend`
+initializer, or to any of the methods or functions that call that
+initializer. If left to their default values of `None`, their values
+will be taken from ``matplotlib.rcParams``. The previously-existing
+``framealpha`` kwarg still controls the alpha transparency of the
+patch.
+
+
+Qualitative colormaps
+---------------------
+
+Colorbrewer's qualitative/discrete colormaps ("Accent", "Dark2", "Paired",
+"Pastel1", "Pastel2", "Set1", "Set2", "Set3") are now implemented as
+``ListedColormap`` instead of ``LinearSegmentedColormap``.
+
+To use these for images where categories are specified as integers, for
+instance, use::
+
+ plt.imshow(x, cmap='Dark2', norm=colors.NoNorm())
+
+
+Change in the ``draw_image`` backend API
+----------------------------------------
+
+The ``draw_image`` method implemented by backends has changed its interface.
+
+This change is only relevant if the backend declares that it is able
+to transform images by returning ``True`` from ``option_scale_image``.
+See the ``draw_image`` docstring for more information.
+
+
+
+`matplotlib.ticker.LinearLocator` algorithm update
+--------------------------------------------------
+
+The ``matplotlib.ticker.LinearLocator`` is used to define the range and
+location of axis ticks when the user wants an exact number of ticks.
+``LinearLocator`` thus differs from the default locator ``MaxNLocator``,
+for which the user specifies a maximum number of intervals rather than
+a precise number of ticks.
+
+The view range algorithm in ``matplotlib.ticker.LinearLocator`` has been
+changed so that more convenient tick locations are chosen. The new algorithm
+returns a plot view range that is a multiple of the user-requested number of
+ticks. This ensures tick marks will be located at whole integers more
+consistently. For example, when both y-axes of a``twinx`` plot use
+``matplotlib.ticker.LinearLocator`` with the same number of ticks,
+their y-tick locations and grid lines will coincide.
+
+
+New defaults for 3D quiver function in mpl_toolkits.mplot3d.axes3d.py
+---------------------------------------------------------------------
+
+Matplotlib has both a 2D and a 3D ``quiver`` function. These changes
+affect only the 3D function and make the default behavior of the 3D
+function match the 2D version. There are two changes:
+
+1) The 3D quiver function previously normalized the arrows to be the
+ same length, which makes it unusable for situations where the
+ arrows should be different lengths and does not match the behavior
+ of the 2D function. This normalization behavior is now controlled
+ with the ``normalize`` keyword, which defaults to False.
+
+2) The ``pivot`` keyword now defaults to ``tail`` instead of
+ ``tip``. This was done in order to match the default behavior of
+ the 2D quiver function.
+
+To obtain the previous behavior with the 3D quiver function, one can
+call the function with ::
+
+ ax.quiver(x, y, z, u, v, w, normalize=True, pivot='tip')
+
+where "ax" is an ``Axes3d`` object created with something like ::
+
+ import mpl_toolkits.mplot3d.axes3d
+ ax = plt.sublot(111, projection='3d')
+
+
Changes in 1.5.2
================
@@ -30,7 +153,7 @@ 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
@@ -47,34 +170,34 @@ Changes in 1.5.0
Code Changes
------------
-Split `matplotlib.cbook.ls_mapper` in two
-`````````````````````````````````````````
+Reversed `matplotlib.cbook.ls_mapper`, added `ls_mapper_r`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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.
+Formerly, `matplotlib.cbook.ls_mapper` was a dictionary with
+the long-form line-style names (`"solid"`) as keys and the short
+forms (`"-"`) as values. This long-to-short mapping is now done
+by `ls_mapper_r`, and the short-to-long mapping is done by the
+`ls_mapper`.
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 done to prevent an Artist that is
+already associated with an Axes from being 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.
+deprecation of {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 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
@@ -87,14 +210,14 @@ 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
@@ -120,29 +243,29 @@ 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 *(
+defined, causing its use on any other Locator to raise 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
+Since each of the Locator subtypes 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(),
+In the new behavior, Locator instances will not raise an AttributeError
+when set_params() 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
@@ -159,16 +282,16 @@ 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.
+This is consistent with the superclass :class:`~matplotlib.ticker.Locator`
+and also all the other Locators derived from this superclass.
No `ValueError` for the MicrosecondLocator and YearLocator
-``````````````````````````````````````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :class:`~matplotlib.dates.MicrosecondLocator` and
:class:`~matplotlib.dates.YearLocator` objects when called will return
@@ -177,19 +300,21 @@ 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.
+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)`.
+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
+nodes. This is to avoid conflicts when 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
@@ -200,7 +325,7 @@ 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,
@@ -210,7 +335,7 @@ 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
@@ -222,7 +347,7 @@ 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
@@ -242,13 +367,13 @@ 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
@@ -261,14 +386,14 @@ 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
@@ -277,7 +402,7 @@ 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.
@@ -300,7 +425,7 @@ 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
+with webagg you will need to update your html files as such
.. code-block:: diff
@@ -312,13 +437,14 @@ 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.
+`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
@@ -326,13 +452,13 @@ 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
@@ -342,60 +468,62 @@ available from `matplotlib.cbook.get_sample_data`. We suggest using
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.
+which takes care of ensuring the related 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`.
+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' 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
@@ -403,41 +531,41 @@ d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by
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
@@ -1168,7 +1296,7 @@ Changes beyond 0.99.x
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
@@ -1393,7 +1521,7 @@ 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
@@ -1458,7 +1586,7 @@ Old method New method
:attr:`~matplotlib.transforms.Bbox.xmin`.
:mod:`matplotlib.axes`
-``````````````````````
+~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1486,7 +1614,7 @@ The :class:`Polar` class has moved to :mod:`matplotlib.projections.polar`.
`Axes.toggle_log_lineary()` has been removed.
:mod:`matplotlib.artist`
-````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1500,7 +1628,7 @@ Old method New method
the path immediately before clipping.
:mod:`matplotlib.collections`
-`````````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1513,7 +1641,7 @@ Old method New method
provided.
:mod:`matplotlib.colors`
-````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1524,7 +1652,7 @@ Old method New method
============================================================ ============================================================
:mod:`matplotlib.contour`
-`````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1534,7 +1662,7 @@ Old method New method
============================================================ ============================================================
:mod:`matplotlib.figure`
-````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1543,7 +1671,7 @@ Old method New method
============================================================ ============================================================
:mod:`matplotlib.patches`
-`````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1553,7 +1681,7 @@ Old method New method
============================================================ ============================================================
:mod:`matplotlib.backend_bases`
-```````````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
============================================================ ============================================================
Old method New method
@@ -1566,7 +1694,7 @@ Old method New method
============================================================ ============================================================
:class:`~matplotlib.backend_bases.RendererBase`
-```````````````````````````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
New methods:
@@ -2344,7 +2472,7 @@ MATLAB interface
----------------
dpi
-```
+~~~
Several of the backends used a PIXELS_PER_INCH hack that I added to
try and make images render consistently across backends. This just
@@ -2355,7 +2483,7 @@ screen to get true sizes.
pcolor and scatter
-``````````````````
+~~~~~~~~~~~~~~~~~~
There are two changes to the MATLAB interface API, both involving the
patch drawing commands. For efficiency, pcolor and scatter have been
@@ -2396,7 +2524,7 @@ Using sizes in data coords caused several problems. So you will need
to adjust your size arguments accordingly or use scatter_classic.
mathtext spacing
-````````````````
+~~~~~~~~~~~~~~~~
For reasons not clear to me (and which I'll eventually fix) spacing no
longer works in font groups. However, I added three new spacing
@@ -2412,13 +2540,13 @@ Object interface - Application programmers
------------------------------------------
Autoscaling
-```````````
+~~~~~~~~~~~
The x and y axis instances no longer have autoscale view. These are
handled by axes.autoscale_view
Axes creation
-`````````````
+~~~~~~~~~~~~~
You should not instantiate your own Axes any more using the OO API.
Rather, create a Figure as before and in place of::
@@ -2438,13 +2566,13 @@ Axes creation
add_subplot(num, axisbg=defaultcolor, frameon=True)
Artist methods
-``````````````
+~~~~~~~~~~~~~~
If you define your own Artists, you need to rename the _draw method
to draw
Bounding boxes
-``````````````
+~~~~~~~~~~~~~~
matplotlib.transforms.Bound2D is replaced by
matplotlib.transforms.Bbox. If you want to construct a bbox from
@@ -2468,7 +2596,7 @@ Bounding boxes
Object constructors
-```````````````````
+~~~~~~~~~~~~~~~~~~~
You no longer pass the bbox, dpi, or transforms to the various
Artist constructors. The old way or creating lines and rectangles
@@ -2498,7 +2626,7 @@ Object constructors
set your own already, in which case it will eave it unchanged)
Transformations
-```````````````
+~~~~~~~~~~~~~~~
The entire transformation architecture has been rewritten.
Previously the x and y transformations where stored in the xaxis and
diff --git a/doc/api/api_changes/2015-03-14-SSH.rst b/doc/api/api_changes/2015-03-14-SSH.rst
deleted file mode 100644
index 902d0e766f24..000000000000
--- a/doc/api/api_changes/2015-03-14-SSH.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-``matplotlib.ticker.LinearLocator`` algorithm update
-```````````````````````````
-
-The ``matplotlib.ticker.LinearLocator`` is used to define the range and location
-of tickmarks of a plot when the user wants a exact number of ticks.
-``LinearLocator`` thus differs from the default locator ``MaxNLocator``, which
-does not necessarily return the exact user requested number of ticks.
-
-The view range algorithm in ``matplotlib.ticker.LinearLocator`` has been
-changed so that more convenient tick location are chosen. The new algorithm
-returns a plot view range that is a multiple of the user requested number of
-ticks. This ensures tick marks to be located at whole integers more
-constistently. For example, when both y-axis of a``twinx`` plot use
-``matplotlib.ticker.LinearLocator`` with the same number of ticks, the grids of
-both axis will be properly aligned at convenient tick locations.
-
diff --git a/doc/api/api_changes/2015-11-12-DDH.rst b/doc/api/api_changes/2015-11-12-DDH.rst
deleted file mode 100644
index ba899dc6e7f0..000000000000
--- a/doc/api/api_changes/2015-11-12-DDH.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-New defaults for 3D quiver function in mpl_toolkits.mplot3d.axes3d.py
-```````````````````````````
-Matplotlib has both a 2D and a 3D ``quiver`` function. These changes affect only the 3D function and make the default behavior of the 3D function match 2D version. There are two changes:
-
-1) The 3D quiver function previously normalized the arrows to be the same length, which makes it unusable for situations where the arrows should be different lengths and does not match the behavior of the 2D function. This normalization behavior is now controlled with the ``normalize`` keyword, which defaults to False.
-
-2) The ``pivot`` keyword now defaults to ``tail`` instead of ``tip``. This was done in order to match the default behavior of the 2D quiver function.
-
-To obtain the previous behavior with the 3D quiver function, one can call the function with ::
-
- ax.quiver(x, y, z, u, v, w, normalize=True, pivot='tip')
-
-where "ax" is a axes3d object created with something like ::
-
- import mpl_toolkits.mplot3d.axes3d
- ax = plt.sublot(111, projection='3d')
\ No newline at end of file
diff --git a/doc/api/api_changes/2015-12-01-TAC.rst b/doc/api/api_changes/2015-12-01-TAC.rst
deleted file mode 100644
index 62ad44cec06e..000000000000
--- a/doc/api/api_changes/2015-12-01-TAC.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-`Artist.update` has return value
-````````````````````````````````
-
-The methods `matplotlib.artist.Artist.set`,
-`matplotlib.Artist.update`, and the function `matplotlib.artist.setp`
-now use a common codepath to look up how to update the given artist
-properties (either using the setter methods or an attribute/property).
-
-The behavior of `matplotlib.Artist.update` is slightly changed to
-return a list of the returned values from the setter methods to avoid
-changing the API of `matplotlib.Artist.set` and
-`matplotlib.artist.setp`.
-
-The keys passed into `matplotlib.Artist.update` are now converted to
-lower case before being processed to match the behavior of
-`matplotlib.Artist.set` and `matplotlib.artist.setp`. This should not
-break any user code because there are no set methods with capitals in
-the names, however going forward this puts a constraint on naming
-properties.
diff --git a/doc/api/api_changes/2015-12-30_draw_image.rst b/doc/api/api_changes/2015-12-30_draw_image.rst
deleted file mode 100644
index fb135bab28bc..000000000000
--- a/doc/api/api_changes/2015-12-30_draw_image.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Change in the ``draw_image`` backend API
-----------------------------------------
-
-The ``draw_image`` method implemented by backends has changed its interface.
-
-This change is only relevant if the backend declares that it is able
-to transform images by returning ``True`` from ``option_scale_image``.
-See the ``draw_image`` docstring for more information.
diff --git a/doc/api/api_changes/2016-06-deprecate_backends.rst b/doc/api/api_changes/2016-06-deprecate_backends.rst
deleted file mode 100644
index 7645f1fad615..000000000000
--- a/doc/api/api_changes/2016-06-deprecate_backends.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-GTK and GDK backends deprecated
-```````````````````````````````
-The untested and broken GDK and GTK backends have been deprecated.
-These backends allows figures to be rendered via the GDK api to
-files and GTK2 figures. They are untested, known to be broken and
-use have been discouraged for some time. The `GTKAgg` and `GTKCairo` backends
-provide better and more tested ways of rendering figures to GTK2 windows.
-
-WX backend deprecated
-`````````````````````
-The untested WX backend has been deprecated.
-This backend allows figures to be rendered via the WX api to
-files and Wx figures. It is untested, and
-use have been discouraged for some time. The `WXAgg` backend
-provides a better and more tested way of rendering figures to WX windows.
-
-CocoaAgg backend removed
-````````````````````````
-
-The deprecated and not fully functional CocoaAgg backend has been removed
diff --git a/doc/api/api_changes/2016-07-20-EF.rst b/doc/api/api_changes/2016-07-20-EF.rst
deleted file mode 100644
index 218458711a46..000000000000
--- a/doc/api/api_changes/2016-07-20-EF.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-`Legend` initializers gain edgecolor and facecolor kwargs
-``````````````````````````````````````````````````````````
-
-The :class:`~matplotlib.legend.Legend` background patch (or 'frame')
-can have its `edgecolor` and `facecolor` determined by the
-corresponding keyword arguments to its initializer, or to any of the
-methods or functions that call that initializer. If left to
-their default values of `None`, their values will be taken from
-`rcParams`. The previously-existing `framealpha` kwarg still
-controls the alpha transparency of the patch.
diff --git a/doc/api/api_changes/qualitative colormaps.rst b/doc/api/api_changes/qualitative colormaps.rst
deleted file mode 100644
index 4cafdbce8bcf..000000000000
--- a/doc/api/api_changes/qualitative colormaps.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-Qualitative colormaps
----------------------
-
-Colorbrewer's qualitative/discrete colormaps ("Accent", "Dark2", "Paired",
-"Pastel1", "Pastel2", "Set1", "Set2", "Set3") are now implemented as
-``ListedColormap`` instead of ``LinearSegmentedColormap``.
-
-To use these for images where categories are specified as integers, for
-instance, use::
-
- plt.imshow(x, cmap='Dark2', norm=colors.NoNorm())
diff --git a/doc/contents.rst b/doc/contents.rst
index 62612705ab2e..945742eb4e96 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -14,13 +14,12 @@ Overview
.. toctree::
:maxdepth: 2
- style_changes.rst
users/index.rst
+ api/index.rst
faq/index.rst
+ mpl_toolkits/index.rst
resources/index.rst
devel/index.rst
- mpl_toolkits/index.rst
- api/index.rst
examples/index.rst
glossary/index.rst
diff --git a/doc/style_changes.rst b/doc/style_changes.rst
deleted file mode 100644
index c77b49b6c97a..000000000000
--- a/doc/style_changes.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-Default Style Changes
-=====================
-
-Colormap
---------
-
-``matplotlib`` is changing the default colormap and styles in the
-upcoming 2.0 release!
-
-The new default color map will be 'viridis' (aka `option
-D `_). For an introduction to color
-theory and how 'viridis' was generated watch Nathaniel Smith and
-Stéfan van der Walt's talk from SciPy2015
-
-.. raw:: html
-
-
-
-All four color maps will be included in matplotlib 1.5.
-
-
-Everything Else
----------------
-
-We have collected proposals to change any and all visual defaults
-(including adding new rcParams as needed).
-
-Michael Droettboom and Thomas Caswell will decide on the new default
-styles to appear in the upcoming 2.0 release.
-
-A 'classic' style sheet will be provided so reverting to the 1.x
-default values will be a single line of python
-(`mpl.style.use('classic')`).
diff --git a/doc/users/annotations_guide.rst b/doc/users/annotations.rst
similarity index 63%
rename from doc/users/annotations_guide.rst
rename to doc/users/annotations.rst
index 23f8d14652e0..29be8cac5654 100644
--- a/doc/users/annotations_guide.rst
+++ b/doc/users/annotations.rst
@@ -1,18 +1,107 @@
-.. _plotting-guide-annotation:
+============
+ Annotation
+============
+
+.. contents:: Table of Contents
+ :depth: 3
+
+.. _annotations-tutorial:
+
+Basic annotation
+================
+
+The uses of the basic :func:`~matplotlib.pyplot.text` will place text
+at an arbitrary position on the Axes. A common use case of text is to
+annotate some feature of the plot, and the
+:func:`~matplotlib.Axes.annotate` method provides helper functionality
+to make annotations easy. In an annotation, there are two points to
+consider: the location being annotated represented by the argument
+``xy`` and the location of the text ``xytext``. Both of these
+arguments are ``(x,y)`` tuples.
+
+.. plot:: pyplots/annotation_basic.py
+ :include-source:
+
+
+In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
+(text location) are in data coordinates. There are a variety of other
+coordinate systems one can choose -- you can specify the coordinate
+system of ``xy`` and ``xytext`` with one of the following strings for
+``xycoords`` and ``textcoords`` (default is 'data')
+
+==================== ====================================================
+argument coordinate system
+==================== ====================================================
+ 'figure points' points from the lower left corner of the figure
+ 'figure pixels' pixels from the lower left corner of the figure
+ 'figure fraction' 0,0 is lower left of figure and 1,1 is upper right
+ 'axes points' points from lower left corner of axes
+ 'axes pixels' pixels from lower left corner of axes
+ 'axes fraction' 0,0 is lower left of axes and 1,1 is upper right
+ 'data' use the axes data coordinate system
+==================== ====================================================
+
+For example to place the text coordinates in fractional axes
+coordinates, one could do::
+
+ ax.annotate('local max', xy=(3, 1), xycoords='data',
+ xytext=(0.8, 0.95), textcoords='axes fraction',
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ horizontalalignment='right', verticalalignment='top',
+ )
+
+For physical coordinate systems (points or pixels) the origin is the
+(bottom, left) of the figure or axes. If the value is negative,
+however, the origin is from the (right, top) of the figure or axes,
+analogous to negative indexing of sequences.
+
+Optionally, you can enable drawing of an arrow from the text to the annotated
+point by giving a dictionary of arrow properties in the optional keyword
+argument ``arrowprops``.
-****************
-Annotating Axes
-****************
-Do not proceed unless you already have read :ref:`annotations-tutorial`,
-:func:`~matplotlib.pyplot.text` and
-:func:`~matplotlib.pyplot.annotate`!
+==================== =====================================================
+``arrowprops`` key description
+==================== =====================================================
+width the width of the arrow in points
+frac the fraction of the arrow length occupied by the head
+headwidth the width of the base of the arrow head in points
+shrink move the tip and base some percent away from
+ the annotated point and text
+\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
+ e.g., ``facecolor``
+==================== =====================================================
+In the example below, the ``xy`` point is in native coordinates
+(``xycoords`` defaults to 'data'). For a polar axes, this is in
+(theta, radius) space. The text in this example is placed in the
+fractional figure coordinate system. :class:`matplotlib.text.Text`
+keyword args like ``horizontalalignment``, ``verticalalignment`` and
+``fontsize`` are passed from `~matplotlib.Axes.annotate` to the
+``Text`` instance.
+
+.. plot:: pyplots/annotation_polar.py
+ :include-source:
+
+For more on all the wild and wonderful things you can do with
+annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
+and :ref:`pylab_examples-annotation_demo`.
+
+
+Do not proceed unless you have already read :ref:`annotations-tutorial`,
+:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!
+
+
+.. _plotting-guide-annotation:
+
+Advanced Annotation
+===================
+
Annotating with Text with Box
-=============================
+-----------------------------
Let's start with a simple example.
@@ -35,7 +124,7 @@ The patch object associated with the text can be accessed by::
The return value is an instance of FancyBboxPatch and the patch
properties like facecolor, edgewidth, etc. can be accessed and
-modified as usual. To change the shape of the box, use *set_boxstyle*
+modified as usual. To change the shape of the box, use the *set_boxstyle*
method. ::
bb.set_boxstyle("rarrow", pad=0.6)
@@ -60,7 +149,7 @@ keyword arguments. Currently, following box styles are implemented.
.. plot:: mpl_examples/pylab_examples/fancybox_demo2.py
-Note that the attributes arguments can be specified within the style
+Note that the attribute arguments can be specified within the style
name with separating comma (this form can be used as "boxstyle" value
of bbox argument when initializing the text instance) ::
@@ -70,7 +159,7 @@ of bbox argument when initializing the text instance) ::
Annotating with Arrow
-=====================
+---------------------
The :func:`~matplotlib.pyplot.annotate` function in the pyplot module
(or annotate method of the Axes class) is used to draw an arrow
@@ -87,7 +176,7 @@ annotated point is specified in the *data* coordinate and the annotating
text in *offset points*.
See :func:`~matplotlib.pyplot.annotate` for available coordinate systems.
-An arrow connecting two point (xy & xytext) can be optionally drawn by
+An arrow connecting two points (xy & xytext) can be optionally drawn by
specifying the ``arrowprops`` argument. To draw only an arrow, use
empty string as the first argument. ::
@@ -108,7 +197,7 @@ The arrow drawing takes a few steps.
2. If patch object is given (*patchA* & *patchB*), the path is clipped to
avoid the patch.
-3. The path is further shrunk by given amount of pixels (*shirnkA*
+3. The path is further shrunk by given amount of pixels (*shrinkA*
& *shrinkB*)
4. The path is transmuted to arrow patch, which is controlled by the
@@ -119,7 +208,7 @@ The arrow drawing takes a few steps.
The creation of the connecting path between two points is controlled by
-``connectionstyle`` key and following styles are available.
+``connectionstyle`` key and the following styles are available.
========== =============================================
Name Attrs
@@ -133,7 +222,7 @@ The creation of the connecting path between two points is controlled by
Note that "3" in ``angle3`` and ``arc3`` is meant to indicate that the
resulting path is a quadratic spline segment (three control
-points). As will be discussed below, some arrow style option only can
+points). As will be discussed below, some arrow style options can only
be used when the connecting path is a quadratic spline.
The behavior of each connection style is (limitedly) demonstrated in the
@@ -165,9 +254,9 @@ an arrow patch, according to the given ``arrowstyle``.
.. plot:: mpl_examples/pylab_examples/fancyarrow_demo.py
-Some arrowstyles only work with connection style that generates a
+Some arrowstyles only work with connection styles that generate a
quadratic-spline segment. They are ``fancy``, ``simple``, and ``wedge``.
-For these arrow styles, you must use "angle3" or "arc3" connection
+For these arrow styles, you must use the "angle3" or "arc3" connection
style.
If the annotation string is given, the patchA is set to the bbox patch
@@ -189,10 +278,10 @@ lower-left corner and (1,1) means top-right.
Placing Artist at the anchored location of the Axes
-===================================================
+---------------------------------------------------
-There are class of artist that can be placed at the anchored location
-of the Axes. A common example is the legend. This type of artists can
+There are classes of artists that can be placed at an anchored location
+in the Axes. A common example is the legend. This type of artist can
be created by using the OffsetBox class. A few predefined classes are
available in ``mpl_toolkits.axes_grid.anchored_artists``. ::
@@ -215,10 +304,10 @@ artists) is known in pixel size during the time of creation. For
example, If you want to draw a circle with fixed size of 20 pixel x 20
pixel (radius = 10 pixel), you can utilize
``AnchoredDrawingArea``. The instance is created with a size of the
-drawing area (in pixel). And user can add arbitrary artist to the
+drawing area (in pixels), and arbitrary artists can added to the
drawing area. Note that the extents of the artists that are added to
-the drawing area has nothing to do with the placement of the drawing
-area itself. The initial size only matters. ::
+the drawing area are not related to the placement of the drawing
+area itself. Only the initial size matters. ::
from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea
@@ -229,15 +318,15 @@ area itself. The initial size only matters. ::
p2 = Circle((30, 10), 5, fc="r")
ada.drawing_area.add_artist(p2)
-The artists that are added to the drawing area should not have
-transform set (they will be overridden) and the dimension of those
+The artists that are added to the drawing area should not have a
+transform set (it will be overridden) and the dimensions of those
artists are interpreted as a pixel coordinate, i.e., the radius of the
-circles in above example are 10 pixel and 5 pixel, respectively.
+circles in above example are 10 pixels and 5 pixels, respectively.
.. plot:: users/plotting/examples/anchored_box02.py
-Sometimes, you want to your artists scale with data coordinate (or
-other coordinate than canvas pixel). You can use
+Sometimes, you want your artists to scale with the data coordinate (or
+coordinates other than canvas pixels). You can use
``AnchoredAuxTransformBox`` class. This is similar to
``AnchoredDrawingArea`` except that the extent of the artist is
determined during the drawing time respecting the specified transform. ::
@@ -245,11 +334,11 @@ determined during the drawing time respecting the specified transform. ::
from mpl_toolkits.axes_grid.anchored_artists import AnchoredAuxTransformBox
box = AnchoredAuxTransformBox(ax.transData, loc=2)
- el = Ellipse((0,0), width=0.1, height=0.4, angle=30) # in data coordinates!
+ el = Ellipse((0,0), width=0.1, height=0.4, angle=30) # in data coordinates!
box.drawing_area.add_artist(el)
The ellipse in the above example will have width and height
-corresponds to 0.1 and 0.4 in data coordinate and will be
+corresponding to 0.1 and 0.4 in data coordinateing and will be
automatically scaled when the view limits of the axes change.
.. plot:: users/plotting/examples/anchored_box03.py
@@ -263,10 +352,10 @@ legend (as a matter of fact, this is how the legend is created).
Note that unlike the legend, the ``bbox_transform`` is set
to IdentityTransform by default.
-Using Complex Coordinate with Annotation
-========================================
+Using Complex Coordinates with Annotations
+------------------------------------------
-The Annotation in matplotlib support several types of coordinate as
+The Annotation in matplotlib supports several types of coordinates as
described in :ref:`annotations-tutorial`. For an advanced user who wants
more control, it supports a few other options.
@@ -302,16 +391,16 @@ more control, it supports a few other options.
Note that it is your responsibility that the extent of the
coordinate artist (*an1* in above example) is determined before *an2*
- gets drawn. In most cases, it means that an2 needs to be drawn
+ gets drawn. In most cases, it means that *an2* needs to be drawn
later than *an1*.
3. A callable object that returns an instance of either
:class:`~matplotlib.transforms.BboxBase` or
:class:`~matplotlib.transforms.Transform`. If a transform is
- returned, it is same as 1 and if bbox is returned, it is same
- as 2. The callable object should take a single argument of
- renderer instance. For example, following two commands give
+ returned, it is the same as 1 and if a bbox is returned, it is the same
+ as 2. The callable object should take a single argument of the
+ renderer instance. For example, the following two commands give
identical results ::
an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1,
@@ -320,22 +409,21 @@ more control, it supports a few other options.
xytext=(30,0), textcoords="offset points")
- 4. A tuple of two coordinate specification. The first item is for
- x-coordinate and the second is for y-coordinate. For example, ::
+ 4. A tuple of two coordinate specifications. The first item is for the
+ x-coordinate and the second is for the y-coordinate. For example, ::
annotate("Test", xy=(0.5, 1), xycoords=("data", "axes fraction"))
- 0.5 is in data coordinate, and 1 is in normalized axes coordinate.
+ 0.5 is in data coordinates, and 1 is in normalized axes coordinates.
You may use an artist or transform as with a tuple. For example,
.. plot:: users/plotting/examples/annotate_simple_coord02.py
:include-source:
- 5. Sometimes, you want your annotation with some "offset points", but
- not from the annotated point but from other
- point. :class:`~matplotlib.text.OffsetFrom` is a helper class for such
- case.
+ 5. Sometimes, you want your annotation with some "offset points", not from the
+ annotated point but from some other point.
+ :class:`~matplotlib.text.OffsetFrom` is a helper class for such cases.
.. plot:: users/plotting/examples/annotate_simple_coord03.py
:include-source:
@@ -343,12 +431,11 @@ more control, it supports a few other options.
You may take a look at this example :ref:`pylab_examples-annotation_demo3`.
Using ConnectorPatch
-====================
+--------------------
-The ConnectorPatch is like an annotation without a text. While the
-annotate function is recommended in most of situation, the
-ConnectorPatch is useful when you want to connect points in different
-axes. ::
+The ConnectorPatch is like an annotation without text. While the annotate
+function is recommended in most situations, the ConnectorPatch is useful when
+you want to connect points in different axes. ::
from matplotlib.patches import ConnectionPatch
xy = (0.2, 0.2)
@@ -356,27 +443,25 @@ axes. ::
axesA=ax1, axesB=ax2)
ax2.add_artist(con)
-The above code connects point xy in data coordinate of ``ax1`` to
-point xy int data coordinate of ``ax2``. Here is a simple example.
+The above code connects point xy in the data coordinates of ``ax1`` to
+point xy in the data coordinates of ``ax2``. Here is a simple example.
.. plot:: users/plotting/examples/connect_simple01.py
-While the ConnectorPatch instance can be added to any axes, but you
-may want it to be added to the axes in the latter (?) of the axes
-drawing order to prevent overlap (?) by other axes.
-
-
+While the ConnectorPatch instance can be added to any axes, you may want to add
+it to the axes that is latest in drawing order to prevent overlap by other
+axes.
Advanced Topics
-***************
+~~~~~~~~~~~~~~~
Zoom effect between Axes
-========================
+------------------------
mpl_toolkits.axes_grid.inset_locator defines some patch classes useful
-for interconnect two axes. Understanding the code requires some
+for interconnecting two axes. Understanding the code requires some
knowledge of how mpl's transform works. But, utilizing it will be
straight forward.
@@ -385,10 +470,10 @@ straight forward.
Define Custom BoxStyle
-======================
+----------------------
You can use a custom box style. The value for the ``boxstyle`` can be a
-callable object in following forms.::
+callable object in the following forms.::
def __call__(self, x0, y0, width, height, mutation_size,
aspect_ratio=1.):
@@ -401,7 +486,7 @@ callable object in following forms.::
- *aspect_ratio* : aspect-ratio for the mutation.
"""
path = ...
- return path
+ return path
Here is a complete example.
@@ -414,6 +499,6 @@ matplotlib.patches.BoxStyle._Base as demonstrated below.
:include-source:
-Similarly, you can define custom ConnectionStyle and custom ArrowStyle.
+Similarly, you can define a custom ConnectionStyle and a custom ArrowStyle.
See the source code of ``lib/matplotlib/patches.py`` and check
how each style class is defined.
diff --git a/doc/users/annotations_intro.rst b/doc/users/annotations_intro.rst
deleted file mode 100644
index 0b83e1523b3e..000000000000
--- a/doc/users/annotations_intro.rst
+++ /dev/null
@@ -1,87 +0,0 @@
-.. _annotations-tutorial:
-
-Annotating text
-===============
-
-For a more detailed introduction to annotations, see
-:ref:`plotting-guide-annotation`.
-
-The uses of the basic :func:`~matplotlib.pyplot.text` command above
-place text at an arbitrary position on the Axes. A common use case of
-text is to annotate some feature of the plot, and the
-:func:`~matplotlib.Axes.annotate` method provides helper functionality
-to make annotations easy. In an annotation, there are two points to
-consider: the location being annotated represented by the argument
-``xy`` and the location of the text ``xytext``. Both of these
-arguments are ``(x,y)`` tuples.
-
-.. plot:: pyplots/annotation_basic.py
- :include-source:
-
-
-In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
-(text location) are in data coordinates. There are a variety of other
-coordinate systems one can choose -- you can specify the coordinate
-system of ``xy`` and ``xytext`` with one of the following strings for
-``xycoords`` and ``textcoords`` (default is 'data')
-
-==================== ====================================================
-argument coordinate system
-==================== ====================================================
- 'figure points' points from the lower left corner of the figure
- 'figure pixels' pixels from the lower left corner of the figure
- 'figure fraction' 0,0 is lower left of figure and 1,1 is upper right
- 'axes points' points from lower left corner of axes
- 'axes pixels' pixels from lower left corner of axes
- 'axes fraction' 0,0 is lower left of axes and 1,1 is upper right
- 'data' use the axes data coordinate system
-==================== ====================================================
-
-For example to place the text coordinates in fractional axes
-coordinates, one could do::
-
- ax.annotate('local max', xy=(3, 1), xycoords='data',
- xytext=(0.8, 0.95), textcoords='axes fraction',
- arrowprops=dict(facecolor='black', shrink=0.05),
- horizontalalignment='right', verticalalignment='top',
- )
-
-For physical coordinate systems (points or pixels) the origin is the
-(bottom, left) of the figure or axes. If the value is negative,
-however, the origin is from the (right, top) of the figure or axes,
-analogous to negative indexing of sequences.
-
-Optionally, you can specify arrow properties which draws an arrow
-from the text to the annotated point by giving a dictionary of arrow
-properties in the optional keyword argument ``arrowprops``.
-
-
-==================== =====================================================
-``arrowprops`` key description
-==================== =====================================================
-width the width of the arrow in points
-frac the fraction of the arrow length occupied by the head
-headwidth the width of the base of the arrow head in points
-shrink move the tip and base some percent away from
- the annotated point and text
-
-\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
- e.g., ``facecolor``
-==================== =====================================================
-
-
-In the example below, the ``xy`` point is in native coordinates
-(``xycoords`` defaults to 'data'). For a polar axes, this is in
-(theta, radius) space. The text in this example is placed in the
-fractional figure coordinate system. :class:`matplotlib.text.Text`
-keyword args like ``horizontalalignment``, ``verticalalignment`` and
-``fontsize are passed from the `~matplotlib.Axes.annotate` to the
-``Text`` instance
-
-.. plot:: pyplots/annotation_polar.py
- :include-source:
-
-For more on all the wild and wonderful things you can do with
-annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
-and :ref:`pylab_examples-annotation_demo`.
-
diff --git a/doc/users/beginner.rst b/doc/users/beginner.rst
deleted file mode 100644
index 698f04a4d041..000000000000
--- a/doc/users/beginner.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. _beginners-guide-index:
-
-################
-Beginner's Guide
-################
-
-.. htmlonly::
-
- :Release: |version|
- :Date: |today|
-
-.. toctree::
- :maxdepth: 2
-
- pyplot_tutorial.rst
- style_sheets.rst
- navigation_toolbar.rst
- index_text.rst
- image_tutorial.rst
- legend_guide.rst
- annotations_guide.rst
- screenshots.rst
- colors.rst
- colormaps.rst
- colormapnorms.rst
diff --git a/doc/users/color_index.rst b/doc/users/color_index.rst
new file mode 100644
index 000000000000..84238a040f0a
--- /dev/null
+++ b/doc/users/color_index.rst
@@ -0,0 +1,16 @@
+.. _color-index:
+
+========
+ Colors
+========
+
+.. htmlonly::
+
+ :Release: |version|
+ :Date: |today|
+
+.. toctree::
+
+ colors.rst
+ colormaps.rst
+ colormapnorms.rst
diff --git a/doc/users/colors.rst b/doc/users/colors.rst
index 4ae509601351..efc1aade6836 100644
--- a/doc/users/colors.rst
+++ b/doc/users/colors.rst
@@ -7,26 +7,75 @@ Specifying Colors
In almost all places in matplotlib where a color can be specified by the user
it can be provided as:
-* ``(r, g, b)`` tuples
-* ``(r, g, b, a)`` tuples
-* hex string, ex ``#0F0F0F``, or ``#0F0F0F0F`` (with alpha channel)
-* float value between [0, 1] for gray level
-* One of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``
-* valid CSS4/X11 color names
-* valid name from the `xkcd color survey
- `__ These
- names are prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``) to
- prevent name clashes with the CSS4/X11 names.
+* a ``(r, g, b)`` tuple
+* a ``(r, g, b, a)`` tuple
+* a hex RGB or RGBA string (ex ``'#0F0F0F'`` or ``'#0F0F0F0F'``)
+* a float value in ``[0, 1]`` inclusive for gray level
+* one of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``
+* a X11/CSS4 color name
+* a name from the `xkcd color survey `__
+ prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``)
+* one of ``{'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9'}``
All string specifications of color are case-insensitive.
-Internally, mpl is moving to storing all colors as RGBA float quadruples.
-There are 95 (out of 148 colors in the css color list) conflicts between the
-CSS4/X11 names and the xkcd names. Given that the former are the standard
-color names of the web, matplotlib should follow them. Thus, xkcd color names
-are prefixed with ``'xkcd:'``, for example ``'blue'`` maps to ``'#0000FF'``
-where as ``'xkcd:blue'`` maps to ``'#0343DF'``.
+``'CN'`` color selection
+------------------------
+
+Color can be specified by a string matching the regex ``C[0-9]``.
+This can be passed any place that a color is currently accepted and
+can be used as a 'single character color' in format-string to
+`matplotlib.Axes.plot`.
+
+The single digit is the index into the default property cycle
+(``matplotlib.rcParams['axes.prop_cycle']``). If the property cycle does not
+include ``'color`` then black is returned. The color is evaluated when the
+artist is created. For example
+
+.. plot::
+ :include-source: True
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib as mpl
+ th = np.linspace(0, 2*np.pi, 128)
+
+ def demo(sty):
+ mpl.style.use(sty)
+ fig, ax = plt.subplots(figsize=(3, 3))
+
+ ax.set_title('style: {!r}'.format(sty), color='C0')
+
+ ax.plot(th, np.cos(th), 'C1', label='C1')
+ ax.plot(th, np.sin(th), 'C2', label='C2')
+ ax.legend()
+
+ demo('default')
+ demo('seaborn')
+
+will use the first color for the title and then plot using the second
+and third colors of the styles ``mpl.rcParams['axes.prop_cycle']``.
+
+
+xkcd v X11/CSS4
+---------------
+
+The xkcd colors are derived from a user survey conducted by the
+webcomic xkcd. `Details of the survey are available on the xkcd blog
+`__.
+
+There are 95 (out of 148 colors in the css color list) name collisions
+between the X11/CSS4 names and the xkcd names, all but 3 of which have
+different hex values. For example ``'blue'`` maps to ``'#0000FF'``
+where as ``'xkcd:blue'`` maps to ``'#0343DF'``. Due to these name
+collisions all of the xkcd colors have ``'xkcd:'`` prefixed. As noted in
+the blog post, while it might be interesting to re-define the X11/CSS4 names
+based on such a survey we do not do so unilaterally.
+
+The name collisions are shown in the table below, the color names
+where the hex values agree are shown in bold.
+
.. plot::
@@ -41,20 +90,22 @@ where as ``'xkcd:blue'`` maps to ``'#0343DF'``.
ax = fig.add_axes([0, 0, 1, 1])
for j, n in enumerate(sorted(overlap, reverse=True)):
+ weight = None
cn = mcd.CSS4_COLORS[n]
xkcd = mcd.XKCD_COLORS["xkcd:" + n].upper()
- if cn != xkcd:
- print(n, cn, xkcd)
+ if cn == xkcd:
+ weight = 'bold'
r1 = mpatch.Rectangle((0, j), 1, 1, color=cn)
r2 = mpatch.Rectangle((1, j), 1, 1, color=xkcd)
- txt = ax.text(2, j+.5, ' ' + n, va='center', fontsize=10)
+ txt = ax.text(2, j+.5, ' ' + n, va='center', fontsize=10,
+ weight=weight)
ax.add_patch(r1)
ax.add_patch(r2)
ax.axhline(j, color='k')
- ax.text(.5, j + .1, 'X11', ha='center')
- ax.text(1.5, j + .1, 'XKCD', ha='center')
+ ax.text(.5, j + 1.5, 'X11', ha='center', va='center')
+ ax.text(1.5, j + 1.5, 'xkcd', ha='center', va='center')
ax.set_xlim(0, 3)
- ax.set_ylim(0, j + 1)
+ ax.set_ylim(0, j + 2)
ax.axis('off')
diff --git a/doc/users/configuration.rst b/doc/users/configuration.rst
deleted file mode 100644
index 324068f5bf55..000000000000
--- a/doc/users/configuration.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. _configuration-guide-index:
-
-###################
-Configuration Guide
-###################
-
-.. htmlonly::
-
- :Release: |version|
- :Date: |today|
-
-.. toctree::
- :maxdepth: 2
-
- installing.rst
- customizing.rst
- shell.rst
-
-
-
diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst
index 7fcdc7ba7594..a712b2e4a285 100644
--- a/doc/users/customizing.rst
+++ b/doc/users/customizing.rst
@@ -1,23 +1,98 @@
.. _customizing-matplotlib:
-**********************
-Customizing matplotlib
-**********************
+========================
+ Customizing matplotlib
+========================
Using style sheets
==================
-Style sheets provide a means for more specific and/or temporary configuration
-modifications, but in a repeatable and well-ordered manner. A style sheet is a
-file with the same syntax as the :file:`matplotlibrc` file, and when applied, it
-will override the :file:`matplotlibrc`.
+The ``style`` package adds support for easy-to-switch plotting "styles" with
+the same parameters as a matplotlibrc_ file.
-For more information and examples, see :ref:`style-sheets`.
+There are a number of pre-defined styles provided by matplotlib. For
+example, there's a pre-defined style called "ggplot", which emulates the
+aesthetics of ggplot_ (a popular plotting package for R_). To use this style,
+just add::
+
+ >>> import matplotlib.pyplot as plt
+ >>> plt.style.use('ggplot')
+
+To list all available styles, use::
+
+ >>> print(plt.style.available)
+
+
+Defining your own style
+-----------------------
+
+You can create custom styles and use them by calling ``style.use`` with the
+path or URL to the style sheet. Additionally, if you add your
+``.mplstyle`` file to ``mpl_configdir/stylelib``, you can reuse
+your custom style sheet with a call to ``style.use()``. By default
+``mpl_configdir`` should be ``~/.config/matplotlib``, but you can check where
+yours is with ``matplotlib.get_configdir()``; you may need to create this
+directory. Note that a custom style sheet in ``mpl_configdir/stylelib`` will
+override a style sheet defined by matplotlib if the styles have the same name.
+
+For example, you might want to create
+``mpl_configdir/stylelib/presentation.mplstyle`` with the following::
+
+ axes.titlesize : 24
+ axes.labelsize : 20
+ lines.linewidth : 3
+ lines.markersize : 10
+ xtick.labelsize : 16
+ ytick.labelsize : 16
+
+Then, when you want to adapt a plot designed for a paper to one that looks
+good in a presentation, you can just add::
+
+ >>> import matplotlib.pyplot as plt
+ >>> plt.style.use('presentation')
+
+
+Composing styles
+----------------
+
+Style sheets are designed to be composed together. So you can have a style
+sheet that customizes colors and a separate style sheet that alters element
+sizes for presentations. These styles can easily be combined by passing
+a list of styles::
+
+ >>> import matplotlib.pyplot as plt
+ >>> plt.style.use(['dark_background', 'presentation'])
+
+Note that styles further to the right will overwrite values that are already
+defined by styles on the left.
+
+
+Temporary styling
+-----------------
+
+If you only want to use a style for a specific block of code but don't want
+to change the global styling, the style package provides a context manager
+for limiting your changes to a specific scope. To isolate your styling
+changes, you can write something like the following::
+
+ >>> import numpy as np
+ >>> import matplotlib.pyplot as plt
+ >>>
+ >>> with plt.style.context(('dark_background')):
+ >>> plt.plot(np.sin(np.linspace(0, 2 * np.pi)), 'r-o')
+ >>>
+ >>> # Some plotting code with the default style
+ >>>
+ >>> plt.show()
+
+
+matplotlib rcParams
+===================
.. _customizing-with-dynamic-rc-settings:
Dynamic rc settings
-===================
+-------------------
You can also dynamically change the default rc settings in a python script or
interactively from the python shell. All of the rc settings are stored in a
@@ -44,7 +119,7 @@ There is some degree of validation when setting the values of rcParams, see
.. _customizing-with-matplotlibrc-files:
The :file:`matplotlibrc` file
-=============================
+-----------------------------
matplotlib uses :file:`matplotlibrc` configuration files to customize all kinds
of properties, which we call `rc settings` or `rc parameters`. You can control
@@ -88,10 +163,15 @@ See below for a sample :ref:`matplotlibrc file`.
.. _matplotlibrc-sample:
A sample matplotlibrc file
---------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
.. htmlonly::
`(download) <../_static/matplotlibrc>`__
.. literalinclude:: ../_static/matplotlibrc
+
+
+.. _matplotlibrc: http://matplotlib.org/users/customizing.html
+.. _ggplot: http://ggplot2.org/
+.. _R: https://www.r-project.org/
diff --git a/doc/users/developer.rst b/doc/users/developer.rst
deleted file mode 100644
index 02b2ab793b57..000000000000
--- a/doc/users/developer.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _advanced-guide-index:
-
-###############
-Advanced Guide
-###############
-
-.. htmlonly::
-
- :Release: |version|
- :Date: |today|
-
-.. toctree::
- :maxdepth: 2
-
- artists.rst
- gridspec.rst
- tight_layout_guide.rst
- event_handling.rst
- transforms_tutorial.rst
- path_tutorial.rst
- patheffects_guide.rst
- recipes.rst
-
diff --git a/doc/users/dflt_style_changes.rst b/doc/users/dflt_style_changes.rst
new file mode 100644
index 000000000000..6aead7a5e130
--- /dev/null
+++ b/doc/users/dflt_style_changes.rst
@@ -0,0 +1,530 @@
+==============================
+ Changes to the default style
+==============================
+
+The most important changes in matplotlib 2.0 are the changes to the
+default style.
+
+While it is impossible to select the best default for all cases, these
+are designed to work well in the most common cases.
+
+A 'classic' style sheet is provided so reverting to the 1.x default
+values is a single line of python
+
+.. code::
+
+ mpl.style.use('classic')
+
+See :ref:`customizing-with-matplotlibrc-files` for details about how to
+persistently and selectively revert many of these changes.
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+
+
+colors, color cycles, and color maps
+====================================
+
+Colors in default property cycle
+--------------------------------
+
+The colors in the default proprety cycle have been changed from
+``['b', 'g', 'r', 'c', 'm', 'y', 'k']`` to the `Vega category10 palette
+`__
+
+.. plot::
+
+
+ th = np.linspace(0, 2*np.pi, 512)
+
+ fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
+
+
+ def color_demo(ax, colors, title):
+ ax.set_title(title)
+ for j, c in enumerate(colors):
+ v_offset = -(j / len(colors))
+ ax.plot(th, .1*np.sin(th) + v_offset, color=c)
+ ax.annotate("'C{}'".format(j), (0, v_offset),
+ xytext=(-1.5, 0),
+ ha='right',
+ va='center',
+ color=c,
+ textcoords='offset points',
+ family='monospace')
+
+ ax.annotate("{!r}".format(c), (2*np.pi, v_offset),
+ xytext=(1.5, 0),
+ ha='left',
+ va='center',
+ color=c,
+ textcoords='offset points',
+ family='monospace')
+ ax.axis('off')
+
+ old_colors = ['b', 'g', 'r', 'c', 'm', 'y', 'k']
+
+ new_colors = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728',
+ '#9467bd', '#8c564b', '#e377c2', '#7f7f7f',
+ '#bcbd22', '#17becf']
+
+ color_demo(ax1, old_colors, 'classic')
+ color_demo(ax2, new_colors, 'v2.0')
+
+ fig.subplots_adjust(**{'bottom': 0.0, 'left': 0.059, 'right': 0.869, 'top': 0.895})
+
+In addition to changing the colors, an additional method to specify
+colors was added. Previously, the default colors were the single
+character short-hand notations for red, green, blue, cyan, magenta,
+yellow, and black. This made them easy to type and usable in the
+abbreviated style string in ``plot``, however the new default colors
+are only specified via hex values. To access these colors outside of
+the property cycling the notation for colors ``'CN'`` was added to
+denote the first 10 colors in ``mpl.rcParams['axes.prop_cycle']`` See
+:ref:`colors` for more details.
+
+To restore the old color cycle use
+
+.. code::
+
+ from cycler import cycler
+ mpl.rcParams['axes.prop_cycle'] = cycler(color='bgrcmyk')
+
+or setting
+
+.. code::
+
+ axes.prop_cycle : cycler('color', 'bgrcmyk')
+
+in your :file:`matplotlibrc` file.
+
+
+Colormap
+--------
+
+The new default color map used by `matplotlib.cm.ScalarMappable` instances is
+ `'viridis'` (aka `option D `__).
+
+.. plot::
+
+ import numpy as np
+ N = M = 200
+ X, Y = np.ogrid[0:20:N*1j, 0:20:M*1j]
+ data = np.sin(np.pi * X*2 / 20) * np.cos(np.pi * Y*2 / 20)
+
+ fig, (ax2, ax1) = plt.subplots(1, 2, figsize=(7, 3))
+ im = ax1.imshow(data, extent=[0, 200, 0, 200])
+ ax1.set_title("v2.0: 'viridis'")
+ fig.colorbar(im, ax=ax1, shrink=.9)
+
+ im2 = ax2.imshow(data, extent=[0, 200, 0, 200], cmap='jet')
+ fig.colorbar(im2, ax=ax2, shrink=.9)
+ ax2.set_title("classic: 'jet'")
+
+ fig.tight_layout()
+
+For an introduction to color theory and how 'viridis' was generated
+watch Nathaniel Smith and Stéfan van der Walt's talk from SciPy2015.
+See `here for many more details `__
+about the other alternatives and the tools used to create the color
+map. For details on all of color maps available in matplotlib see
+:ref:`colormaps`.
+
+.. raw:: html
+
+
+
+
+The previous default can be restored using
+
+.. code::
+
+ mpl.rcParams['image.cmap'] = 'jet'
+
+or setting
+
+.. code::
+
+ image.cmap : 'jet'
+
+in your :file:`matplotlibrc` file; however this is strongly discouraged.
+
+Interactive figures
+-------------------
+
+The default interactive figure background color has changed from grey
+to white, which matches the default background color used when saving.
+
+The previous defaults can be restored by ::
+
+ mpl.rcParams['figure.facecolor'] = '0.75'
+
+or setting ::
+
+
+ figure.facecolor : '0.75'
+
+in your :file:`matplotlibrc` file.
+
+
+Grid lines
+----------
+
+The default style of grid lines was changed from, black dashed lines to thicker
+solid light grey lines.
+
+.. plot::
+
+ fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
+
+ ax1.grid(color='k', linewidth=.5, linestyle=':')
+ ax1.set_title('classic')
+
+ ax2.grid()
+ ax2.set_title('v2.0')
+
+The previous default can be restored by using::
+
+ mpl.rcParams['grid.color'] = 'k'
+ mpl.rcParams['grid.linestyle'] = ':'
+ mpl.rcParams['grid.linewidth'] = 0.5
+
+or setting::
+
+ grid.color : k # grid color
+ grid.linestyle : : # dotted
+ grid.linewidth : 0.5 # in points
+
+in your :file:`matplotlibrc` file.
+
+
+Figure size, font size, and screen dpi
+======================================
+
+The default dpi used for on-screen display was changed from 80dpi to
+100dpi, the same as the default dpi for saving files. Due to this
+change, the on-screen display is now more what-you-see-is-what-you-get
+for saved files. To keep figure the same size in terms of pixels, in
+order to maintain approximately the same size on the screen, the
+default figure size was reduced from 8in by 6in to 6.4in by 4.8in. As
+a consequence of this the default font sizes used for the title, tick
+labels, and axes labels were reduced to maintain their size relative
+to the overall size of the figure. By default the dpi of the saved
+image is now the dpi of the `~matplotlib.figure.Figure` instance being
+saved.
+
+This will have consequences if you are trying to match text in a
+figure directly with external text.
+
+
+The previous defaults can be restored by ::
+
+ mpl.rcParams['figure.figsize'] = [8.0, 6.0]
+ mpl.rcParams['figure.dpi'] = 80
+ mpl.rcParams['savefig.dpi'] = 100
+
+ mpl.rcParams['font.size'] = 12
+ mpl.rcParams['legend.fontsize'] = 'large'
+ mpl.rcParams['figure.titlesize'] = 'medium'
+
+or set::
+
+ figure.figsize : [8.0, 6.0]
+ figure.dpi : 80
+ savefig.dpi : 100
+
+ font.size : 12.0
+ legend.fontsize : 'large'
+ figure.titlesize : 'medium'
+
+In your :file:`matplotlibrc` file.
+
+
+Plotting functions
+==================
+
+``scatter``
+-----------
+
+The following changes were made to the default behavior of `~matplotlib.axes.Axes.scatter`
+
+ - The default size of the elements in a scatter plot is now based on
+ the rcParam ``lines.markersize`` so it is consistent with ``plot(X,
+ Y, 'o')``. The old value was 20, and the new value is 36 (6^2).
+ - scatter markers no longer have a black edge.
+ - if the color of the markers is not specified it will follow the property cycle
+ pulling from the 'patches' cycle on the ``Axes``.
+
+.. plot::
+
+ np.random.seed(2)
+
+ fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
+
+ x = np.arange(15)
+ y = np.random.rand(15)
+ y2 = np.random.rand(15)
+ ax1.scatter(x, y, s=20, edgecolors='k', c='b', label='a')
+ ax1.scatter(x, y2, s=20, edgecolors='k', c='b', label='b')
+ ax1.legend()
+ ax1.set_title('classic')
+
+ ax2.scatter(x, y, label='a')
+ ax2.scatter(x, y2, label='b')
+ ax2.legend()
+ ax2.set_title('v2.0')
+
+
+The classic default behavior of `~matplotlib.axes.Axes.scatter` can
+only be recovered through ``mpl.style.use('classic')``. The marker size
+can be recovered via ::
+
+ mpl.rcParam['lines.markersize'] = np.sqrt(20)
+
+however, this will also affect the default marker size of
+`~matplotlib.axes.Axes.plot`. To recover the classic behavior on
+a per-call basis pass the following kwargs::
+
+ classic_kwargs = {'s': 20, 'edgecolors': 'k', 'c': 'b'}
+
+``plot``
+--------
+
+The following changes were made to the default behavior of
+`~matplotlib.axes.Axes.plot`
+
+ - the default linewidth change from 1 to 1.5
+ - the dash patterns associated with ``'--'``, ``':'``, and ``'-.'`` have
+ changed
+ - the dash patterns now scale with line width
+
+
+.. plot::
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib as mpl
+ from cycler import cycler
+
+ fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(6, 3))
+
+ N = 15
+
+ x = np.arange(N)
+ y = np.ones_like(x)
+
+ sty_cycle = (cycler('ls', ['--' ,':', '-.']) *
+ cycler('lw', [None, 1, 2, 5]))
+
+ classic = {
+ 'lines.linewidth': 1.0,
+ 'lines.dashed_pattern' : [6, 6],
+ 'lines.dashdot_pattern' : [3, 5, 1, 5],
+ 'lines.dotted_pattern' : [1, 3],
+ 'lines.scale_dashes': False}
+
+ v2 = {}
+ # {'lines.linewidth': 1.5,
+ # 'lines.dashed_pattern' : [2.8, 1.2],
+ # 'lines.dashdot_pattern' : [4.8, 1.2, 0.8, 1.2],
+ # 'lines.dotted_pattern' : [1.1, 1.1],
+ # 'lines.scale_dashes': True}
+
+ def demo(ax, rcparams, title):
+ ax.axis('off')
+ ax.set_title(title)
+ with mpl.rc_context(rc=rcparams):
+ for j, sty in enumerate(sty_cycle):
+ ax.plot(x, y + j, **sty)
+
+ demo(ax1, classic, 'classic')
+ demo(ax2, {}, 'v2.0')
+
+
+The previous defaults can be restored by setting::
+
+ mpl.rcParams['lines.linewidth'] = 1.0
+ mpl.rcParams['lines.dashed_pattern'] = [6, 6]
+ mpl.rcParams['lines.dashdot_pattern'] = [3, 5, 1, 5]
+ mpl.rcParams['lines.dotted_pattern'] = [1, 3]
+ mpl.rcParams['lines.scale_dashes'] = False
+
+or by setting::
+
+ lines.linewidth : 1.0
+ lines.dashed_pattern : 6, 6
+ lines.dashdot_pattern : 3, 5, 1, 5
+ lines.dotted_pattern : 1, 3
+ lines.scale_dashes: False
+
+in your :file:`matplotlibrc` file.
+
+Patch edges and color
+---------------------
+
+Artists drawn with a patch (``~matplotlib.axes.Axes.bar``,
+``~matplotlib.axes.Axes.pie``, etc) no longer have a black edge by
+default. The default face color is now ``'C0'`` instead of ``'b'``.
+
+.. plot::
+
+ import matplotlib.pyplot as plt
+ import numpy as np
+ from matplotlib import rc_context
+ import matplotlib.patches as mpatches
+
+ fig, all_ax = plt.subplots(3, 2, figsize=(4, 6), tight_layout=True)
+
+ def demo(ax_top, ax_mid, ax_bottom, rcparams, label):
+ labels = 'Frogs', 'Hogs', 'Dogs', 'Logs'
+ fracs = [15, 30, 45, 10]
+
+ explode = (0, 0.05, 0, 0)
+
+ ax_top.set_title(label)
+
+ with rc_context(rc=rcparams):
+ ax_top.pie(fracs, labels=labels)
+ ax_top.set_aspect('equal')
+ ax_mid.bar(range(len(fracs)), fracs, tick_label=labels, align='center')
+ plt.setp(ax_mid.get_xticklabels(), rotation=-45)
+ grid = np.mgrid[0.2:0.8:3j, 0.2:0.8:3j].reshape(2, -1).T
+
+ ax_bottom.set_xlim(0, .75)
+ ax_bottom.set_ylim(0, .75)
+ ax_bottom.add_artist(mpatches.Rectangle(grid[1] - [0.025, 0.05], 0.05, 0.1))
+ ax_bottom.add_artist(mpatches.RegularPolygon(grid[3], 5, 0.1))
+ ax_bottom.add_artist(mpatches.Ellipse(grid[4], 0.2, 0.1))
+ ax_bottom.add_artist(mpatches.Circle(grid[0], 0.1))
+ ax_bottom.axis('off')
+
+ demo(*all_ax[:, 0], rcparams={'patch.force_edgecolor': True,
+ 'patch.facecolor': 'b'}, label='classic')
+ demo(*all_ax[:, 1], rcparams={}, label='v2.0')
+
+The previous defaults can be restored by setting::
+
+ mpl.rcParams['patch.force_edgecolor'] = True
+ mpl.rcParams['patch.facecolor'] = True
+
+or by setting::
+
+ patch.facecolor : b
+ patch.force_edgecolor : True
+
+in your :file:`matplotlibrc` file.
+
+
+
+Other
+=====
+
+- lines.color change, only hits raw usage of Line2D
+
+Hatching
+========
+
+- The width of the lines in a hatch pattern is now configurable by the
+ rcParam `hatch.linewidth`, with a default of 1 point. The old
+ behavior was different depending on backend:
+
+ - PDF: 0.1 pt
+ - SVG: 1.0 pt
+ - PS: 1 px
+ - Agg: 1 px
+
+Plot layout
+===========
+
+- The number of ticks on an axis is now automatically determined based
+ on the length of the axis.
+
+- The limits of an axes are scaled to exactly the dimensions of the data,
+ plus 5% padding. The old behavior was to scale to the nearest "round"
+ numbers. To use the old behavior, set the ``rcParam``
+ ``axes.autolimit_mode`` to ``round_numbers``. To control the
+ margins on a particular side individually, pass any of the following
+ to any artist or plotting function:
+
+ - ``top_margin=False``
+ - ``bottom_margin=False``
+ - ``left_margin=False``
+ - ``right_margin=False``
+
+- Ticks now point outward by default. To have ticks pointing inward,
+ use the ``rcParams`` ``xtick.direction`` and ``ytick.direction``.
+
+- Ticks and grids are now plotted above solid elements such as
+ filled contours, but below lines. To return to the previous
+ behavior of plotting ticks and grids above lines, set
+ ``rcParams['axes.axisbelow'] = False``.
+
+- By default, caps on the ends of errorbars are not present. Use the
+ rcParam ``errorbar.capsize`` to control this.
+
+Images
+======
+
+- The default mode for image interpolation, in the rcParam
+ ``image.interpolation``, is now ``nearest``.
+
+- The default shading mode for light source shading, in
+ ``matplotlib.colors.LightSource.shade``, is now ``overlay``.
+ Formerly, it was ``hsv``.
+
+- The default value for the rcParam ``image.resample`` is now
+ ``True``. This will apply interpolation for both upsampling and
+ downsampling of an image.
+
+Fonts
+=====
+
+- The default font has changed from "Bitstream Vera Sans" to "DejaVu
+ Sans". "DejaVu Sans" is an improvement on "Bistream Vera Sans" that
+ adds more international and math characters, but otherwise has the
+ same appearance.
+
+- The default math font when using the built-in math rendering engine
+ (mathtext) has changed from "Computer Modern" (i.e. LaTeX-like) to
+ "DejaVu Sans". To revert to the old behavior, set the ``rcParam``
+ ``mathtext.fontset`` to ``cm``. This change has no effect if the
+ TeX backend is used (i.e. ``text.usetex`` is ``True``).
+
+Dates
+=====
+
+- The default date formats are now all based on ISO format, i.e., with
+ the slowest-moving value first. The date formatters are still
+ changeable through the ``date.autoformatter.*`` rcParams. Python's
+ ``%x`` and ``%X`` date formats may be of particular interest to
+ format dates based on the current locale.
+
+Legends
+=======
+
+- By default, the number of points displayed in a legend is now 1.
+
+- The default legend location is ``best``, so the legend will be
+ automatically placed in a location to obscure the least amount of
+ data possible.
+
+- The legend now has rounded corners by default.
+
+mplot3d
+=======
+
+- mplot3d now obeys some style-related rcParams, rather than using
+ hard-coded defaults. These include:
+
+ - xtick.major.width
+ - ytick.major.width
+ - xtick.color
+ - ytick.color
+ - axes.linewidth
+ - axes.edgecolor
+ - grid.color
+ - grid.linewidth
+ - grid.linestyle
diff --git a/doc/users/examples_index.rst b/doc/users/examples_index.rst
new file mode 100644
index 000000000000..e71c1db6d8a8
--- /dev/null
+++ b/doc/users/examples_index.rst
@@ -0,0 +1,8 @@
+===================
+ Selected Examples
+===================
+
+.. toctree::
+
+ screenshots.rst
+ recipes.rst
diff --git a/doc/users/index.rst b/doc/users/index.rst
index aadd1f60bbfd..566205ba8a3a 100644
--- a/doc/users/index.rst
+++ b/doc/users/index.rst
@@ -13,10 +13,13 @@ User's Guide
:maxdepth: 2
intro.rst
- configuration.rst
- beginner.rst
- developer.rst
- colors.rst
+ installing.rst
+ tutorials.rst
+ index_text.rst
+ color_index.rst
+ customizing.rst
+ interactive.rst
+ examples_index
whats_new.rst
github_stats.rst
license.rst
diff --git a/doc/users/index_text.rst b/doc/users/index_text.rst
index bba1f330299f..7904d7e3173e 100644
--- a/doc/users/index_text.rst
+++ b/doc/users/index_text.rst
@@ -7,9 +7,7 @@ Working with text
text_intro.rst
text_props.rst
+ annotations.rst
mathtext.rst
- pgf.rst
usetex.rst
- annotations_intro.rst
-
-
+ pgf.rst
diff --git a/doc/users/interactive.rst b/doc/users/interactive.rst
new file mode 100644
index 000000000000..e8af8df9409e
--- /dev/null
+++ b/doc/users/interactive.rst
@@ -0,0 +1,12 @@
+.. _dump-index:
+
+===================
+ Interactive plots
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ navigation_toolbar.rst
+ shell.rst
+ event_handling.rst
diff --git a/doc/users/prev_whats_new/whats_new_0.98.4.rst b/doc/users/prev_whats_new/whats_new_0.98.4.rst
new file mode 100644
index 000000000000..e5749caa0403
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_0.98.4.rst
@@ -0,0 +1,285 @@
+.. _whats-new-0-98-4:
+
+New in matplotlib 0.98.4
+========================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+
+
+It's been four months since the last matplotlib release, and there are
+a lot of new features and bug-fixes.
+
+Thanks to Charlie Moad for testing and preparing the source release,
+including binaries for OS X and Windows for python 2.4 and 2.5 (2.6
+and 3.0 will not be available until numpy is available on those
+releases). Thanks to the many developers who contributed to this
+release, with contributions from Jae-Joon Lee, Michael Droettboom,
+Ryan May, Eric Firing, Manuel Metz, Jouni K. Seppänen, Jeff Whitaker,
+Darren Dale, David Kaplan, Michiel de Hoon and many others who
+submitted patches
+
+.. _legend-refactor:
+
+Legend enhancements
+--------------------
+
+Jae-Joon has rewritten the legend class, and added support for
+multiple columns and rows, as well as fancy box drawing. See
+:func:`~matplotlib.pyplot.legend` and
+:class:`matplotlib.legend.Legend`.
+
+.. plot:: pyplots/whats_new_98_4_legend.py
+
+.. _fancy-annotations:
+
+Fancy annotations and arrows
+-----------------------------
+
+Jae-Joon has added lots of support to annotations for drawing fancy
+boxes and connectors in annotations. See
+:func:`~matplotlib.pyplot.annotate` and
+:class:`~matplotlib.patches.BoxStyle`,
+:class:`~matplotlib.patches.ArrowStyle`, and
+:class:`~matplotlib.patches.ConnectionStyle`.
+
+.. plot:: pyplots/whats_new_98_4_fancy.py
+
+.. _psd-amplitude:
+
+
+Native OS X backend
+--------------------
+
+Michiel de Hoon has provided a native Mac OSX backend that is almost
+completely implemented in C. The backend can therefore use Quartz
+directly and, depending on the application, can be orders of magnitude
+faster than the existing backends. In addition, no third-party
+libraries are needed other than Python and NumPy. The backend is
+interactive from the usual terminal application on Mac using regular
+Python. It hasn't been tested with ipython yet, but in principle it
+should to work there as well. Set 'backend : macosx' in your
+matplotlibrc file, or run your script with::
+
+ > python myfile.py -dmacosx
+
+psd amplitude scaling
+-------------------------
+
+Ryan May did a lot of work to rationalize the amplitude scaling of
+:func:`~matplotlib.pyplot.psd` and friends. See
+:ref:`pylab_examples-psd_demo2`. and :ref:`pylab_examples-psd_demo3`.
+The changes should increase MATLAB
+compatibility and increase scaling options.
+
+.. _fill-between:
+
+Fill between
+------------------
+
+Added a :func:`~matplotlib.pyplot.fill_between` function to make it
+easier to do shaded region plots in the presence of masked data. You
+can pass an *x* array and a *ylower* and *yupper* array to fill
+between, and an optional *where* argument which is a logical mask
+where you want to do the filling.
+
+.. plot:: pyplots/whats_new_98_4_fill_between.py
+
+Lots more
+-----------
+
+Here are the 0.98.4 notes from the CHANGELOG::
+
+ Added mdehoon's native macosx backend from sf patch 2179017 - JDH
+
+ Removed the prints in the set_*style commands. Return the list of
+ pretty-printed strings instead - JDH
+
+ Some of the changes Michael made to improve the output of the
+ property tables in the rest docs broke of made difficult to use
+ some of the interactive doc helpers, e.g., setp and getp. Having all
+ the rest markup in the ipython shell also confused the docstrings.
+ I added a new rc param docstring.harcopy, to format the docstrings
+ differently for hardcopy and other use. The ArtistInspector
+ could use a little refactoring now since there is duplication of
+ effort between the rest out put and the non-rest output - JDH
+
+ Updated spectral methods (psd, csd, etc.) to scale one-sided
+ densities by a factor of 2 and, optionally, scale all densities by
+ the sampling frequency. This gives better MATLAB
+ compatibility. -RM
+
+ Fixed alignment of ticks in colorbars. -MGD
+
+ drop the deprecated "new" keyword of np.histogram() for numpy 1.2
+ or later. -JJL
+
+ Fixed a bug in svg backend that new_figure_manager() ignores
+ keywords arguments such as figsize, etc. -JJL
+
+ Fixed a bug that the handlelength of the new legend class set too
+ short when numpoints=1 -JJL
+
+ Added support for data with units (e.g., dates) to
+ Axes.fill_between. -RM
+
+ Added fancybox keyword to legend. Also applied some changes for
+ better look, including baseline adjustment of the multiline texts
+ so that it is center aligned. -JJL
+
+ The transmuter classes in the patches.py are reorganized as
+ subclasses of the Style classes. A few more box and arrow styles
+ are added. -JJL
+
+ Fixed a bug in the new legend class that didn't allowed a tuple of
+ coordinate values as loc. -JJL
+
+ Improve checks for external dependencies, using subprocess
+ (instead of deprecated popen*) and distutils (for version
+ checking) - DSD
+
+ Reimplementation of the legend which supports baseline alignment,
+ multi-column, and expand mode. - JJL
+
+ Fixed histogram autoscaling bug when bins or range are given
+ explicitly (fixes Debian bug 503148) - MM
+
+ Added rcParam axes.unicode_minus which allows plain hyphen for
+ minus when False - JDH
+
+ Added scatterpoints support in Legend. patch by Erik Tollerud -
+ JJL
+
+ Fix crash in log ticking. - MGD
+
+ Added static helper method BrokenHBarCollection.span_where and
+ Axes/pyplot method fill_between. See
+ examples/pylab/fill_between.py - JDH
+
+ Add x_isdata and y_isdata attributes to Artist instances, and use
+ them to determine whether either or both coordinates are used when
+ updating dataLim. This is used to fix autoscaling problems that
+ had been triggered by axhline, axhspan, axvline, axvspan. - EF
+
+ Update the psd(), csd(), cohere(), and specgram() methods of Axes
+ and the csd() cohere(), and specgram() functions in mlab to be in
+ sync with the changes to psd(). In fact, under the hood, these
+ all call the same core to do computations. - RM
+
+ Add 'pad_to' and 'sides' parameters to mlab.psd() to allow
+ controlling of zero padding and returning of negative frequency
+ components, respectively. These are added in a way that does not
+ change the API. - RM
+
+ Fix handling of c kwarg by scatter; generalize is_string_like to
+ accept numpy and numpy.ma string array scalars. - RM and EF
+
+ Fix a possible EINTR problem in dviread, which might help when
+ saving pdf files from the qt backend. - JKS
+
+ Fix bug with zoom to rectangle and twin axes - MGD
+
+ Added Jae Joon's fancy arrow, box and annotation enhancements --
+ see examples/pylab_examples/annotation_demo2.py
+
+ Autoscaling is now supported with shared axes - EF
+
+ Fixed exception in dviread that happened with Minion - JKS
+
+ set_xlim, ylim now return a copy of the viewlim array to avoid
+ modify inplace surprises
+
+ Added image thumbnail generating function
+ matplotlib.image.thumbnail. See examples/misc/image_thumbnail.py
+ - JDH
+
+ Applied scatleg patch based on ideas and work by Erik Tollerud and
+ Jae-Joon Lee. - MM
+
+ Fixed bug in pdf backend: if you pass a file object for output
+ instead of a filename, e.g., in a wep app, we now flush the object
+ at the end. - JKS
+
+ Add path simplification support to paths with gaps. - EF
+
+ Fix problem with AFM files that don't specify the font's full name
+ or family name. - JKS
+
+ Added 'scilimits' kwarg to Axes.ticklabel_format() method, for
+ easy access to the set_powerlimits method of the major
+ ScalarFormatter. - EF
+
+ Experimental new kwarg borderpad to replace pad in legend, based
+ on suggestion by Jae-Joon Lee. - EF
+
+ Allow spy to ignore zero values in sparse arrays, based on patch
+ by Tony Yu. Also fixed plot to handle empty data arrays, and
+ fixed handling of markers in figlegend. - EF
+
+ Introduce drawstyles for lines. Transparently split linestyles
+ like 'steps--' into drawstyle 'steps' and linestyle '--'. Legends
+ always use drawstyle 'default'. - MM
+
+ Fixed quiver and quiverkey bugs (failure to scale properly when
+ resizing) and added additional methods for determining the arrow
+ angles - EF
+
+ Fix polar interpolation to handle negative values of theta - MGD
+
+ Reorganized cbook and mlab methods related to numerical
+ calculations that have little to do with the goals of those two
+ modules into a separate module numerical_methods.py Also, added
+ ability to select points and stop point selection with keyboard in
+ ginput and manual contour labeling code. Finally, fixed contour
+ labeling bug. - DMK
+
+ Fix backtick in Postscript output. - MGD
+
+ [ 2089958 ] Path simplification for vector output backends
+ Leverage the simplification code exposed through path_to_polygons
+ to simplify certain well-behaved paths in the vector backends
+ (PDF, PS and SVG). "path.simplify" must be set to True in
+ matplotlibrc for this to work. - MGD
+
+ Add "filled" kwarg to Path.intersects_path and
+ Path.intersects_bbox. - MGD
+
+ Changed full arrows slightly to avoid an xpdf rendering problem
+ reported by Friedrich Hagedorn. - JKS
+
+ Fix conversion of quadratic to cubic Bezier curves in PDF and PS
+ backends. Patch by Jae-Joon Lee. - JKS
+
+ Added 5-point star marker to plot command q- EF
+
+ Fix hatching in PS backend - MGD
+
+ Fix log with base 2 - MGD
+
+ Added support for bilinear interpolation in
+ NonUniformImage; patch by Gregory Lielens. - EF
+
+ Added support for multiple histograms with data of
+ different length - MM
+
+ Fix step plots with log scale - MGD
+
+ Fix masked arrays with markers in non-Agg backends - MGD
+
+ Fix clip_on kwarg so it actually works correctly - MGD
+
+ Fix locale problems in SVG backend - MGD
+
+ fix quiver so masked values are not plotted - JSW
+
+ improve interactive pan/zoom in qt4 backend on windows - DSD
+
+ Fix more bugs in NaN/inf handling. In particular, path
+ simplification (which does not handle NaNs or infs) will be turned
+ off automatically when infs or NaNs are present. Also masked
+ arrays are now converted to arrays with NaNs for consistent
+ handling of masks and NaNs - MGD and EF
+
+ Added support for arbitrary rasterization resolutions to the SVG
+ backend. - MW
diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst
new file mode 100644
index 000000000000..b4e787fd9cac
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_0.99.rst
@@ -0,0 +1,60 @@
+.. _whats-new-0-99:
+
+New in matplotlib 0.99
+======================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+
+
+New documentation
+-----------------
+
+Jae-Joon Lee has written two new guides :ref:`plotting-guide-legend`
+and :ref:`plotting-guide-annotation`. Michael Sarahan has written
+:ref:`image_tutorial`. John Hunter has written two new tutorials on
+working with paths and transformations: :ref:`path_tutorial` and
+:ref:`transforms_tutorial`.
+
+.. _whats-new-mplot3d:
+
+mplot3d
+--------
+
+
+Reinier Heeres has ported John Porter's mplot3d over to the new
+matplotlib transformations framework, and it is now available as a
+toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl
+installs). See :ref:`mplot3d-examples-index` and
+:ref:`toolkit_mplot3d-tutorial`
+
+.. plot:: pyplots/whats_new_99_mplot3d.py
+
+.. _whats-new-axes-grid:
+
+axes grid toolkit
+-----------------
+
+Jae-Joon Lee has added a new toolkit to ease displaying multiple images in
+matplotlib, as well as some support for curvilinear grids to support
+the world coordinate system. The toolkit is included standard with all
+new mpl installs. See :ref:`axes_grid-examples-index` and
+:ref:`axes_grid_users-guide-index`.
+
+.. plot:: pyplots/whats_new_99_axes_grid.py
+
+.. _whats-new-spine:
+
+Axis spine placement
+--------------------
+
+Andrew Straw has added the ability to place "axis spines" -- the lines
+that denote the data limits -- in various arbitrary locations. No
+longer are your axis lines constrained to be a simple rectangle around
+the figure -- you can turn on or off left, bottom, right and top, as
+well as "detach" the spine to offset it away from the data. See
+:ref:`pylab_examples-spine_placement_demo` and
+:class:`matplotlib.spines.Spine`.
+
+.. plot:: pyplots/whats_new_99_spines.py
diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst
new file mode 100644
index 000000000000..5af33dd4fcbe
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.0.rst
@@ -0,0 +1,134 @@
+.. _whats-new-1-0:
+
+New in matplotlib 1.0
+======================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+.. _whats-new-html5:
+
+HTML5/Canvas backend
+---------------------
+
+Simon Ratcliffe and Ludwig Schwardt have released an `HTML5/Canvas
+`__ backend for matplotlib. The
+backend is almost feature complete, and they have done a lot of work
+comparing their html5 rendered images with our core renderer Agg. The
+backend features client/server interactive navigation of matplotlib
+figures in an html5 compliant browser.
+
+Sophisticated subplot grid layout
+---------------------------------
+
+Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
+doing complex subplot layouts, featuring row and column spans and
+more. See :ref:`gridspec-guide` for a tutorial overview.
+
+.. plot:: users/plotting/examples/demo_gridspec01.py
+
+Easy pythonic subplots
+-----------------------
+
+Fernando Perez got tired of all the boilerplate code needed to create a
+figure and multiple subplots when using the matplotlib API, and wrote
+a :func:`~matplotlib.pyplot.subplots` helper function. Basic usage
+allows you to create the figure and an array of subplots with numpy
+indexing (starts with 0). e.g.::
+
+ fig, axarr = plt.subplots(2, 2)
+ axarr[0,0].plot([1,2,3]) # upper, left
+
+See :ref:`pylab_examples-subplots_demo` for several code examples.
+
+Contour fixes and and triplot
+---------------------------------
+
+Ian Thomas has fixed a long-standing bug that has vexed our most
+talented developers for years. :func:`~matplotlib.pyplot.contourf`
+now handles interior masked regions, and the boundaries of line and
+filled contours coincide.
+
+Additionally, he has contributed a new module :mod:`~matplotlib.tri` and
+helper function :func:`~matplotlib.pyplot.triplot` for creating and
+plotting unstructured triangular grids.
+
+.. plot:: mpl_examples/pylab_examples/triplot_demo.py
+
+multiple calls to show supported
+---------------------------------
+
+A long standing request is to support multiple calls to
+:func:`~matplotlib.pyplot.show`. This has been difficult because it
+is hard to get consistent behavior across operating systems, user
+interface toolkits and versions. Eric Firing has done a lot of work
+on rationalizing show across backends, with the desired behavior to
+make show raise all newly created figures and block execution until
+they are closed. Repeated calls to show should raise newly created
+figures since the last call. Eric has done a lot of testing on the
+user interface toolkits and versions and platforms he has access to,
+but it is not possible to test them all, so please report problems to
+the `mailing list
+`__
+and `bug tracker
+`__.
+
+
+mplot3d graphs can be embedded in arbitrary axes
+-------------------------------------------------
+
+You can now place an mplot3d graph into an arbitrary axes location,
+supporting mixing of 2D and 3D graphs in the same figure, and/or
+multiple 3D graphs in a single figure, using the "projection" keyword
+argument to add_axes or add_subplot. Thanks Ben Root.
+
+.. plot:: pyplots/whats_new_1_subplot3d.py
+
+tick_params
+------------
+
+Eric Firing wrote tick_params, a convenience method for changing the
+appearance of ticks and tick labels. See pyplot function
+:func:`~matplotlib.pyplot.tick_params` and associated Axes method
+:meth:`~matplotlib.axes.Axes.tick_params`.
+
+Lots of performance and feature enhancements
+---------------------------------------------
+
+
+* Faster magnification of large images, and the ability to zoom in to
+ a single pixel
+
+* Local installs of documentation work better
+
+* Improved "widgets" -- mouse grabbing is supported
+
+* More accurate snapping of lines to pixel boundaries
+
+* More consistent handling of color, particularly the alpha channel,
+ throughout the API
+
+Much improved software carpentry
+---------------------------------
+
+The matplotlib trunk is probably in as good a shape as it has ever
+been, thanks to improved `software carpentry
+`__. We now have a `buildbot
+`__ which runs a suite of `nose
+`__ regression tests on every
+svn commit, auto-generating a set of images and comparing them against
+a set of known-goods, sending emails to developers on failures with a
+pixel-by-pixel image comparison. Releases and release
+bugfixes happen in branches, allowing active new feature development
+to happen in the trunk while keeping the release branches stable.
+Thanks to Andrew Straw, Michael Droettboom and other matplotlib
+developers for the heavy lifting.
+
+Bugfix marathon
+----------------
+
+Eric Firing went on a bug fixing and closing marathon, closing over
+100 bugs on the `bug tracker
+`__ with
+help from Jae-Joon Lee, Michael Droettboom, Christoph Gohlke and
+Michiel de Hoon.
diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst
new file mode 100644
index 000000000000..8002e830d2e7
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.1.rst
@@ -0,0 +1,209 @@
+.. _whats-new-1-1:
+
+New in matplotlib 1.1
+=====================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+
+.. note::
+
+ matplotlib 1.1 supports Python 2.4 to 2.7
+
+
+Sankey Diagrams
+---------------
+
+Kevin Davies has extended Yannick Copin's original Sankey example into a module
+(:mod:`~matplotlib.sankey`) and provided new examples
+(:ref:`api-sankey_demo_basics`, :ref:`api-sankey_demo_links`,
+:ref:`api-sankey_demo_rankine`).
+
+.. plot:: mpl_examples/api/sankey_demo_rankine.py
+
+Animation
+---------
+
+Ryan May has written a backend-independent framework for creating
+animated figures. The :mod:`~matplotlib.animation` module is intended
+to replace the backend-specific examples formerly in the
+:ref:`examples-index` listings. Examples using the new framework are
+in :ref:`animation-examples-index`; see the entrancing :ref:`double
+pendulum ` which uses
+:meth:`matplotlib.animation.Animation.save` to create the movie below.
+
+.. raw:: html
+
+
+
+This should be considered as a beta release of the framework;
+please try it and provide feedback.
+
+
+Tight Layout
+------------
+
+A frequent issue raised by users of matplotlib is the lack of a layout
+engine to nicely space out elements of the plots. While matplotlib still
+adheres to the philosophy of giving users complete control over the placement
+of plot elements, Jae-Joon Lee created the :mod:`~matplotlib.tight_layout`
+module and introduced a new
+command :func:`~matplotlib.pyplot.tight_layout`
+to address the most common layout issues.
+
+.. plot::
+
+ plt.rcParams['savefig.facecolor'] = "0.8"
+ plt.rcParams['figure.figsize'] = 4, 3
+
+ fig, axes_list = plt.subplots(2, 1)
+ for ax in axes_list.flat:
+ ax.set(xlabel="x-label", ylabel="y-label", title="before tight_layout")
+ ax.locator_params(nbins=3)
+
+ plt.show()
+
+ plt.rcParams['savefig.facecolor'] = "0.8"
+ plt.rcParams['figure.figsize'] = 4, 3
+
+ fig, axes_list = plt.subplots(2, 1)
+ for ax in axes_list.flat:
+ ax.set(xlabel="x-label", ylabel="y-label", title="after tight_layout")
+ ax.locator_params(nbins=3)
+
+ plt.tight_layout()
+ plt.show()
+
+The usage of this functionality can be as simple as ::
+
+ plt.tight_layout()
+
+and it will adjust the spacing between subplots
+so that the axis labels do not overlap with neighboring subplots. A
+:ref:`plotting-guide-tight-layout` has been created to show how to use
+this new tool.
+
+PyQT4, PySide, and IPython
+--------------------------
+
+Gerald Storer made the Qt4 backend compatible with PySide as
+well as PyQT4. At present, however, PySide does not support
+the PyOS_InputHook mechanism for handling gui events while
+waiting for text input, so it cannot be used with the new
+version 0.11 of `IPython `__. Until this
+feature appears in PySide, IPython users should use
+the PyQT4 wrapper for QT4, which remains the matplotlib default.
+
+An rcParam entry, "backend.qt4", has been added to allow users
+to select PyQt4, PyQt4v2, or PySide. The latter two use the
+Version 2 Qt API. In most cases, users can ignore this rcParam
+variable; it is available to aid in testing, and to provide control
+for users who are embedding matplotlib in a PyQt4 or PySide app.
+
+
+Legend
+------
+
+Jae-Joon Lee has improved plot legends. First,
+legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots
+will now display correctly. Second, the 'best' placement of a legend has
+been improved in the presence of NANs.
+
+See the :ref:`plotting-guide-legend` for more detailed explanation and
+examples.
+
+.. plot:: mpl_examples/pylab_examples/legend_demo4.py
+
+mplot3d
+-------
+
+In continuing the efforts to make 3D plotting in matplotlib just as easy
+as 2D plotting, Ben Root has made several improvements to the
+:mod:`~mpl_toolkits.mplot3d` module.
+
+* :class:`~mpl_toolkits.mplot3d.axes3d.Axes3D` has been
+ improved to bring the class towards feature-parity with regular
+ Axes objects
+
+* Documentation for :ref:`toolkit_mplot3d-index` was significantly expanded
+
+* Axis labels and orientation improved
+
+* Most 3D plotting functions now support empty inputs
+
+* Ticker offset display added:
+
+.. plot:: mpl_examples/mplot3d/offset_demo.py
+
+* :meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.contourf`
+ gains *zdir* and *offset* kwargs. You can now do this:
+
+.. plot:: mpl_examples/mplot3d/contourf3d_demo2.py
+
+Numerix support removed
+-----------------------
+
+After more than two years of deprecation warnings, Numerix support has
+now been completely removed from matplotlib.
+
+Markers
+-------
+
+The list of available markers for :meth:`~matplotlib.pyplot.plot` and
+:meth:`~matplotlib.pyplot.scatter` has now been merged. While they
+were mostly similar, some markers existed for one function, but not
+the other. This merge did result in a conflict for the 'd' diamond
+marker. Now, 'd' will be interpreted to always mean "thin" diamond
+while 'D' will mean "regular" diamond.
+
+Thanks to Michael Droettboom for this effort.
+
+Other improvements
+------------------
+
+* Unit support for polar axes and :func:`~matplotlib.axes.Axes.arrow`
+
+* :class:`~matplotlib.projections.polar.PolarAxes` gains getters and setters for
+ "theta_direction", and "theta_offset" to allow for theta to go in
+ either the clock-wise or counter-clockwise direction and to specify where zero
+ degrees should be placed.
+ :meth:`~matplotlib.projections.polar.PolarAxes.set_theta_zero_location` is an
+ added convenience function.
+
+* Fixed error in argument handling for tri-functions such as
+ :meth:`~matplotlib.pyplot.tripcolor`
+
+* ``axes.labelweight`` parameter added to rcParams.
+
+* For :meth:`~matplotlib.pyplot.imshow`, *interpolation='nearest'* will
+ now always perform an interpolation. A "none" option has been added to
+ indicate no interpolation at all.
+
+* An error in the Hammer projection has been fixed.
+
+* *clabel* for :meth:`~matplotlib.pyplot.contour` now accepts a callable.
+ Thanks to Daniel Hyams for the original patch.
+
+* Jae-Joon Lee added the :class:`~mpl_toolkits.axes_grid1.axes_divider.HBox`
+ and :class:`~mpl_toolkits.axes_grid1.axes_divider.VBox` classes.
+
+* Christoph Gohlke reduced memory usage in :meth:`~matplotlib.pyplot.imshow`.
+
+* :meth:`~matplotlib.pyplot.scatter` now accepts empty inputs.
+
+* The behavior for 'symlog' scale has been fixed, but this may result
+ in some minor changes to existing plots. This work was refined by
+ ssyr.
+
+* Peter Butterworth added named figure support to
+ :func:`~matplotlib.pyplot.figure`.
+
+* Michiel de Hoon has modified the MacOSX backend to make
+ its interactive behavior consistent with the other backends.
+
+* Pim Schellart added a new colormap called "cubehelix".
+ Sameer Grover also added a colormap called "coolwarm". See it and all
+ other colormaps :ref:`here `.
+
+* Many bug fixes and documentation improvements.
diff --git a/doc/users/prev_whats_new/whats_new_1.2.2.rst b/doc/users/prev_whats_new/whats_new_1.2.2.rst
new file mode 100644
index 000000000000..51c43403d22c
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.2.2.rst
@@ -0,0 +1,22 @@
+.. _whats-new-1-2-2:
+
+New in matplotlib 1.2.2
+=======================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+
+
+Improved collections
+--------------------
+
+The individual items of a collection may now have different alpha
+values and be rendered correctly. This also fixes a bug where
+collections were always filled in the PDF backend.
+
+Multiple images on same axes are correctly transparent
+------------------------------------------------------
+
+When putting multiple images onto the same axes, the background color
+of the axes will now show through correctly.
diff --git a/doc/users/prev_whats_new/whats_new_1.2.rst b/doc/users/prev_whats_new/whats_new_1.2.rst
new file mode 100644
index 000000000000..7f64c1e724c1
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.2.rst
@@ -0,0 +1,203 @@
+.. _whats-new-1-2:
+
+
+New in matplotlib 1.2
+=====================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+.. note::
+
+ matplotlib 1.2 supports Python 2.6, 2.7, and 3.1
+
+Python 3.x support
+------------------
+
+Matplotlib 1.2 is the first version to support Python 3.x,
+specifically Python 3.1 and 3.2. To make this happen in a reasonable
+way, we also had to drop support for Python versions earlier than 2.6.
+
+This work was done by Michael Droettboom, the Cape Town Python Users'
+Group, many others and supported financially in part by the SAGE
+project.
+
+The following GUI backends work under Python 3.x: Gtk3Cairo, Qt4Agg,
+TkAgg and MacOSX. The other GUI backends do not yet have adequate
+bindings for Python 3.x, but continue to work on Python 2.6 and 2.7,
+particularly the Qt and QtAgg backends (which have been
+deprecated). The non-GUI backends, such as PDF, PS and SVG, work on
+both Python 2.x and 3.x.
+
+Features that depend on the Python Imaging Library, such as JPEG
+handling, do not work, since the version of PIL for Python 3.x is not
+sufficiently mature.
+
+PGF/TikZ backend
+----------------
+Peter Würtz wrote a backend that allows matplotlib to export figures as
+drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or
+LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are
+found in :ref:`pgf-tutorial`.
+
+.. image:: /_static/pgf_preamble.*
+
+Locator interface
+-----------------
+
+Philip Elson exposed the intelligence behind the tick Locator classes with a
+simple interface. For instance, to get no more than 5 sensible steps which
+span the values 10 and 19.5::
+
+ >>> import matplotlib.ticker as mticker
+ >>> locator = mticker.MaxNLocator(nbins=5)
+ >>> print(locator.tick_values(10, 19.5))
+ [ 10. 12. 14. 16. 18. 20.]
+
+Tri-Surface Plots
+-----------------
+
+Damon McDougall added a new plotting method for the
+:mod:`~mpl_toolkits.mplot3d` toolkit called
+:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf`.
+
+.. plot:: mpl_examples/mplot3d/trisurf3d_demo.py
+
+Control the lengths of colorbar extensions
+------------------------------------------
+
+Andrew Dawson added a new keyword argument *extendfrac* to
+:meth:`~matplotlib.pyplot.colorbar` to control the length of
+minimum and maximum colorbar extensions.
+
+.. plot::
+
+ import matplotlib.pyplot as plt
+ import numpy as np
+
+ x = y = np.linspace(0., 2*np.pi, 100)
+ X, Y = np.meshgrid(x, y)
+ Z = np.cos(X) * np.sin(0.5*Y)
+
+ clevs = [-.75, -.5, -.25, 0., .25, .5, .75]
+ cmap = plt.cm.get_cmap(name='jet', lut=8)
+
+ ax1 = plt.subplot(211)
+ cs1 = plt.contourf(x, y, Z, clevs, cmap=cmap, extend='both')
+ cb1 = plt.colorbar(orientation='horizontal', extendfrac=None)
+ cb1.set_label('Default length colorbar extensions')
+
+ ax2 = plt.subplot(212)
+ cs2 = plt.contourf(x, y, Z, clevs, cmap=cmap, extend='both')
+ cb2 = plt.colorbar(orientation='horizontal', extendfrac='auto')
+ cb2.set_label('Custom length colorbar extensions')
+
+ plt.show()
+
+
+Figures are picklable
+---------------------
+
+Philip Elson added an experimental feature to make figures picklable
+for quick and easy short-term storage of plots. Pickle files
+are not designed for long term storage, are unsupported when restoring a pickle
+saved in another matplotlib version and are insecure when restoring a pickle
+from an untrusted source. Having said this, they are useful for short term
+storage for later modification inside matplotlib.
+
+
+Set default bounding box in matplotlibrc
+------------------------------------------
+
+Two new defaults are available in the matplotlibrc configuration file:
+``savefig.bbox``, which can be set to 'standard' or 'tight', and
+``savefig.pad_inches``, which controls the bounding box padding.
+
+
+New Boxplot Functionality
+-------------------------
+
+Users can now incorporate their own methods for computing the median and its
+confidence intervals into the :meth:`~matplotlib.axes.boxplot` method. For
+every column of data passed to boxplot, the user can specify an accompanying
+median and confidence interval.
+
+.. plot:: mpl_examples/pylab_examples/boxplot_demo3.py
+
+
+New RC parameter functionality
+------------------------------
+
+Matthew Emmett added a function and a context manager to help manage RC
+parameters: :func:`~matplotlib.rc_file` and :class:`~matplotlib.rc_context`.
+To load RC parameters from a file::
+
+ >>> mpl.rc_file('mpl.rc')
+
+To temporarily use RC parameters::
+
+ >>> with mpl.rc_context(fname='mpl.rc', rc={'text.usetex': True}):
+ >>> ...
+
+
+Streamplot
+----------
+
+Tom Flannaghan and Tony Yu have added a new
+:meth:`~matplotlib.pyplot.streamplot` function to plot the streamlines of
+a vector field. This has been a long-requested feature and complements the
+existing :meth:`~matplotlib.pyplot.quiver` function for plotting vector fields.
+In addition to simply plotting the streamlines of the vector field,
+:meth:`~matplotlib.pyplot.streamplot` allows users to map the colors and/or
+line widths of the streamlines to a separate parameter, such as the speed or
+local intensity of the vector field.
+
+.. plot:: mpl_examples/images_contours_and_fields/streamplot_demo_features.py
+
+
+New hist functionality
+----------------------
+
+Nic Eggert added a new `stacked` kwarg to :meth:`~matplotlib.pyplot.hist` that
+allows creation of stacked histograms using any of the histogram types.
+Previously, this functionality was only available by using the `barstacked`
+histogram type. Now, when `stacked=True` is passed to the function, any of the
+histogram types can be stacked. The `barstacked` histogram type retains its
+previous functionality for backwards compatibility.
+
+Updated shipped dependencies
+----------------------------
+
+The following dependencies that ship with matplotlib and are
+optionally installed alongside it have been updated:
+
+ - `pytz ` 2012d
+
+ - `dateutil ` 1.5 on Python 2.x,
+ and 2.1 on Python 3.x
+
+
+Face-centred colors in tripcolor plots
+--------------------------------------
+
+Ian Thomas extended :meth:`~matplotlib.pyplot.tripcolor` to allow one color
+value to be specified for each triangular face rather than for each point in
+a triangulation.
+
+.. plot:: mpl_examples/pylab_examples/tripcolor_demo.py
+
+Hatching patterns in filled contour plots, with legends
+-------------------------------------------------------
+
+Phil Elson added support for hatching to
+:func:`~matplotlib.pyplot.contourf`, together with the ability
+to use a legend to identify contoured ranges.
+
+.. plot:: mpl_examples/pylab_examples/contourf_hatching.py
+
+Known issues in the matplotlib 1.2 release
+------------------------------------------
+
+- When using the Qt4Agg backend with IPython 0.11 or later, the save
+ dialog will not display. This should be fixed in a future version
+ of IPython.
diff --git a/doc/users/prev_whats_new/whats_new_1.3.rst b/doc/users/prev_whats_new/whats_new_1.3.rst
new file mode 100644
index 000000000000..e6372b004d28
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.3.rst
@@ -0,0 +1,372 @@
+.. _whats-new-1-3:
+
+New in matplotlib 1.3
+=====================
+
+.. contents:: Table of Contents
+ :depth: 2
+
+.. note::
+
+ matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3
+
+New in 1.3.1
+------------
+
+1.3.1 is a bugfix release, primarily dealing with improved setup and
+handling of dependencies, and correcting and enhancing the
+documentation.
+
+The following changes were made in 1.3.1 since 1.3.0.
+
+Enhancements
+````````````
+
+- Added a context manager for creating multi-page pdfs (see
+ `matplotlib.backends.backend_pdf.PdfPages`).
+
+- The WebAgg backend should now have lower latency over heterogeneous
+ Internet connections.
+
+Bug fixes
+`````````
+
+- Histogram plots now contain the endline.
+
+- Fixes to the Molleweide projection.
+
+- Handling recent fonts from Microsoft and Macintosh-style fonts with
+ non-ascii metadata is improved.
+
+- Hatching of fill between plots now works correctly in the PDF
+ backend.
+
+- Tight bounding box support now works in the PGF backend.
+
+- Transparent figures now display correctly in the Qt4Agg backend.
+
+- Drawing lines from one subplot to another now works.
+
+- Unit handling on masked arrays has been improved.
+
+Setup and dependencies
+``````````````````````
+
+- Now works with any version of pyparsing 1.5.6 or later, without displaying
+ hundreds of warnings.
+
+- Now works with 64-bit versions of Ghostscript on MS-Windows.
+
+- When installing from source into an environment without Numpy, Numpy
+ will first be downloaded and built and then used to build
+ matplotlib.
+
+- Externally installed backends are now always imported using a
+ fully-qualified path to the module.
+
+- Works with newer version of wxPython.
+
+- Can now build with a PyCXX installed globally on the system from source.
+
+- Better detection of Gtk3 dependencies.
+
+Testing
+```````
+
+- Tests should now work in non-English locales.
+
+- PEP8 conformance tests now report on locations of issues.
+
+
+New plotting features
+---------------------
+
+`xkcd`-style sketch plotting
+````````````````````````````
+To give your plots a sense of authority that they may be missing,
+Michael Droettboom (inspired by the work of many others in
+:ghpull:`1329`) has added an `xkcd-style `__ sketch
+plotting mode. To use it, simply call :func:`matplotlib.pyplot.xkcd`
+before creating your plot. For really fine control, it is also possible
+to modify each artist's sketch parameters individually with
+:meth:`matplotlib.artist.Artist.set_sketch_params`.
+
+.. plot:: mpl_examples/showcase/xkcd.py
+
+Updated Axes3D.contour methods
+------------------------------
+Damon McDougall updated the
+:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontour` and
+:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontourf` methods to allow 3D
+contour plots on abitrary unstructured user-specified triangulations.
+
+.. plot:: mpl_examples/mplot3d/tricontour3d_demo.py
+
+New eventplot plot type
+```````````````````````
+Todd Jennings added a :func:`~matplotlib.pyplot.eventplot` function to
+create multiple rows or columns of identical line segments
+
+.. plot:: mpl_examples/pylab_examples/eventplot_demo.py
+
+As part of this feature, there is a new
+:class:`~matplotlib.collections.EventCollection` class that allows for
+plotting and manipulating rows or columns of identical line segments.
+
+Triangular grid interpolation
+`````````````````````````````
+Geoffroy Billotey and Ian Thomas added classes to perform
+interpolation within triangular grids:
+(:class:`~matplotlib.tri.LinearTriInterpolator` and
+:class:`~matplotlib.tri.CubicTriInterpolator`) and a utility class to
+find the triangles in which points lie
+(:class:`~matplotlib.tri.TrapezoidMapTriFinder`). A helper class to
+perform mesh refinement and smooth contouring was also added
+(:class:`~matplotlib.tri.UniformTriRefiner`). Finally, a class
+implementing some basic tools for triangular mesh improvement was
+added (:class:`~matplotlib.tri.TriAnalyzer`).
+
+.. plot:: mpl_examples/pylab_examples/tricontour_smooth_user.py
+
+Baselines for stackplot
+```````````````````````
+Till Stensitzki added non-zero baselines to
+:func:`~matplotlib.pyplot.stackplot`. They may be symmetric or
+weighted.
+
+.. plot:: mpl_examples/pylab_examples/stackplot_demo2.py
+
+Rectangular colorbar extensions
+```````````````````````````````
+Andrew Dawson added a new keyword argument *extendrect* to
+:meth:`~matplotlib.pyplot.colorbar` to optionally make colorbar
+extensions rectangular instead of triangular.
+
+More robust boxplots
+````````````````````
+Paul Hobson provided a fix to the :func:`~matplotlib.pyplot.boxplot`
+method that prevent whiskers from being drawn inside the box for
+oddly distributed data sets.
+
+Calling subplot() without arguments
+```````````````````````````````````
+A call to :func:`~matplotlib.pyplot.subplot` without any arguments now
+acts the same as `subplot(111)` or `subplot(1,1,1)` -- it creates one
+axes for the whole figure. This was already the behavior for both
+:func:`~matplotlib.pyplot.axes` and
+:func:`~matplotlib.pyplot.subplots`, and now this consistency is
+shared with :func:`~matplotlib.pyplot.subplot`.
+
+Drawing
+-------
+
+Independent alpha values for face and edge colors
+`````````````````````````````````````````````````
+Wes Campaigne modified how :class:`~matplotlib.patches.Patch` objects are
+drawn such that (for backends supporting transparency) you can set different
+alpha values for faces and edges, by specifying their colors in RGBA format.
+Note that if you set the alpha attribute for the patch object (e.g. using
+:meth:`~matplotlib.patches.Patch.set_alpha` or the ``alpha`` keyword
+argument), that value will override the alpha components set in both the
+face and edge colors.
+
+Path effects on lines
+`````````````````````
+Thanks to Jae-Joon Lee, path effects now also work on plot lines.
+
+.. plot:: mpl_examples/pylab_examples/patheffect_demo.py
+
+Easier creation of colormap and normalizer for levels with colors
+`````````````````````````````````````````````````````````````````
+Phil Elson added the :func:`matplotlib.colors.from_levels_and_colors`
+function to easily create a colormap and normalizer for representation
+of discrete colors for plot types such as
+:func:`matplotlib.pyplot.pcolormesh`, with a similar interface to that
+of :func:`contourf`.
+
+Full control of the background color
+````````````````````````````````````
+Wes Campaigne and Phil Elson fixed the Agg backend such that PNGs are
+now saved with the correct background color when
+:meth:`fig.patch.get_alpha` is not 1.
+
+Improved ``bbox_inches="tight"`` functionality
+``````````````````````````````````````````````
+Passing ``bbox_inches="tight"`` through to :func:`plt.save` now takes
+into account *all* artists on a figure - this was previously not the
+case and led to several corner cases which did not function as
+expected.
+
+Initialize a rotated rectangle
+``````````````````````````````
+Damon McDougall extended the :class:`~matplotlib.patches.Rectangle`
+constructor to accept an `angle` kwarg, specifying the rotation of a
+rectangle in degrees.
+
+Text
+----
+
+Anchored text support
+`````````````````````
+The `svg` and `pgf` backends are now able to save text alignment
+information to their output formats. This allows to edit text elements
+in saved figures, using Inkscape for example, while preserving their
+intended position. For `svg` please note that you'll have to disable
+the default text-to-path conversion (``mpl.rc('svg',
+fonttype='none')``).
+
+Better vertical text alignment and multi-line text
+``````````````````````````````````````````````````
+The vertical alignment of text is now consistent across backends. You
+may see small differences in text placement, particularly with rotated
+text.
+
+If you are using a custom backend, note that the `draw_text` renderer
+method is now passed the location of the baseline, not the location of
+the bottom of the text bounding box.
+
+Multi-line text will now leave enough room for the height of very tall
+or very low text, such as superscripts and subscripts.
+
+Left and right side axes titles
+```````````````````````````````
+Andrew Dawson added the ability to add axes titles flush with the left
+and right sides of the top of the axes using a new keyword argument
+`loc` to :func:`~matplotlib.pyplot.title`.
+
+Improved manual contour plot label positioning
+``````````````````````````````````````````````
+Brian Mattern modified the manual contour plot label positioning code
+to interpolate along line segments and find the actual closest point
+on a contour to the requested position. Previously, the closest path
+vertex was used, which, in the case of straight contours was sometimes
+quite distant from the requested location. Much more precise label
+positioning is now possible.
+
+Configuration (rcParams)
+------------------------
+
+Quickly find rcParams
+`````````````````````
+Phil Elson made it easier to search for rcParameters by passing a
+valid regular expression to :func:`matplotlib.RcParams.find_all`.
+:class:`matplotlib.RcParams` now also has a pretty repr and str
+representation so that search results are printed prettily:
+
+ >>> import matplotlib
+ >>> print(matplotlib.rcParams.find_all('\.size'))
+ RcParams({'font.size': 12,
+ 'xtick.major.size': 4,
+ 'xtick.minor.size': 2,
+ 'ytick.major.size': 4,
+ 'ytick.minor.size': 2})
+
+``axes.xmargin`` and ``axes.ymargin`` added to rcParams
+```````````````````````````````````````````````````````
+``rcParam`` values (``axes.xmargin`` and ``axes.ymargin``) were added
+to configure the default margins used. Previously they were
+hard-coded to default to 0, default value of both rcParam values is 0.
+
+Changes to font rcParams
+````````````````````````
+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.
+
+``savefig.jpeg_quality`` added to rcParams
+``````````````````````````````````````````
+rcParam value ``savefig.jpeg_quality`` was added so that the user can
+configure the default quality used when a figure is written as a JPEG.
+The default quality is 95; previously, the default quality was 75.
+This change minimizes the artifacting inherent in JPEG images,
+particularly with images that have sharp changes in color as plots
+often do.
+
+Backends
+--------
+
+WebAgg backend
+``````````````
+Michael Droettboom, Phil Elson and others have developed a new
+backend, WebAgg, to display figures in a web browser. It works with
+animations as well as being fully interactive.
+
+.. image:: /_static/webagg_screenshot.png
+
+Future versions of matplotlib will integrate this backend with the
+IPython notebook for a fully web browser based plotting frontend.
+
+Remember save directory
+```````````````````````
+Martin Spacek made the save figure dialog remember the last directory
+saved to. The default is configurable with the new `savefig.directory`
+rcParam in `matplotlibrc`.
+
+Documentation and examples
+--------------------------
+
+Numpydoc docstrings
+```````````````````
+Nelle Varoquaux has started an ongoing project to convert matplotlib's
+docstrings to numpydoc format. See `MEP10
+`__ for more
+information.
+
+Example reorganization
+``````````````````````
+Tony Yu has begun work reorganizing the examples into more meaningful
+categories. The new gallery page is the fruit of this ongoing work.
+See `MEP12 `__ for
+more information.
+
+Examples now use subplots()
+```````````````````````````
+For the sake of brevity and clarity, most of the :ref:`examples
+` now use the newer
+:func:`~matplotlib.pyplot.subplots`, which creates a figure and one
+(or multiple) axes object(s) in one call. The old way involved a call
+to :func:`~matplotlib.pyplot.figure`, followed by one (or multiple)
+:func:`~matplotlib.pyplot.subplot` calls.
+
+Infrastructure
+--------------
+
+Housecleaning
+`````````````
+A number of features that were deprecated in 1.2 or earlier, or have
+not been in a working state for a long time have been removed.
+Highlights include removing the Qt version 3 backends, and the FltkAgg
+and Emf backends. See :ref:`changes_in_1_3` for a complete list.
+
+New setup script
+````````````````
+matplotlib 1.3 includes an entirely rewritten setup script. We now
+ship fewer dependencies with the tarballs and installers themselves.
+Notably, `pytz`, `dateutil`, `pyparsing` and `six` are no longer
+included with matplotlib. You can either install them manually first,
+or let `pip` install them as dependencies along with matplotlib. It
+is now possible to not include certain subcomponents, such as the unit
+test data, in the install. See `setup.cfg.template` for more
+information.
+
+XDG base directory support
+``````````````````````````
+On Linux, matplotlib now uses the `XDG base directory specification
+`
+to find the `matplotlibrc` configuration file. `matplotlibrc` should
+now be kept in `~/.config/matplotlib`, rather than `~/.matplotlib`.
+If your configuration is found in the old location, it will still be
+used, but a warning will be displayed.
+
+Catch opening too many figures using pyplot
+```````````````````````````````````````````
+Figures created through `pyplot.figure` are retained until they are
+explicitly closed. It is therefore common for new users of matplotlib
+to run out of memory when creating a large series of figures in a loop
+without closing them.
+
+matplotlib will now display a `RuntimeWarning` when too many figures
+have been opened at once. By default, this is displayed for 20 or
+more figures, but the exact number may be controlled using the
+``figure.max_open_warning`` rcParam.
diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst
new file mode 100644
index 000000000000..d2e35a5cefa5
--- /dev/null
+++ b/doc/users/prev_whats_new/whats_new_1.4.rst
@@ -0,0 +1,419 @@
+.. _whats-new-1-4:
+
+
+New in matplotlib 1.4
+=====================
+
+Thomas A. Caswell served as the release manager for the 1.4 release.
+
+
+.. contents:: Table of Contents
+ :depth: 2
+
+
+.. note::
+
+ matplotlib 1.4 supports Python 2.6, 2.7, 3.3, and 3.4
+
+
+New colormap
+------------
+In heatmaps, a green-to-red spectrum is often used to indicate intensity of
+activity, but this can be problematic for the red/green colorblind. A new,
+colorblind-friendly colormap is now available at :class:`matplotlib.cm.Wistia`.
+This colormap maintains the red/green symbolism while achieving deuteranopic
+legibility through brightness variations. See
+`here `__
+for more information.
+
+The nbagg backend
+-----------------
+Phil Elson added a new backend, named "nbagg", which enables interactive
+figures in a live IPython notebook session. The backend makes use of the
+infrastructure developed for the webagg backend, which itself gives
+standalone server backed interactive figures in the browser, however nbagg
+does not require a dedicated matplotlib server as all communications are
+handled through the IPython Comm machinery.
+
+As with other backends nbagg can be enabled inside the IPython notebook with::
+
+ import matplotlib
+ matplotlib.use('nbagg')
+
+Once figures are created and then subsequently shown, they will placed in an
+interactive widget inside the notebook allowing panning and zooming in the
+same way as any other matplotlib backend. Because figures require a connection
+to the IPython notebook server for their interactivity, once the notebook is
+saved, each figure will be rendered as a static image - thus allowing
+non-interactive viewing of figures on services such as
+`nbviewer `__.
+
+
+
+New plotting features
+---------------------
+
+Power-law normalization
+```````````````````````
+Ben Gamari added a power-law normalization method,
+:class:`~matplotlib.colors.PowerNorm`. This class maps a range of
+values to the interval [0,1] with power-law scaling with the exponent
+provided by the constructor's `gamma` argument. Power law normalization
+can be useful for, e.g., emphasizing small populations in a histogram.
+
+Fully customizable boxplots
+```````````````````````````
+Paul Hobson overhauled the :func:`~matplotlib.pyplot.boxplot` method such
+that it is now completely customizable in terms of the styles and positions
+of the individual artists. Under the hood, :func:`~matplotlib.pyplot.boxplot`
+relies on a new function (:func:`~matplotlib.cbook.boxplot_stats`), which
+accepts any data structure currently compatible with
+:func:`~matplotlib.pyplot.boxplot`, and returns a list of dictionaries
+containing the positions for each element of the boxplots. Then
+a second method, :func:`~matplotlib.Axes.bxp` is called to draw the boxplots
+based on the stats.
+
+The :func:`~matplotlib.pyplot.boxplot` function can be used as before to
+generate boxplots from data in one step. But now the user has the
+flexibility to generate the statistics independently, or to modify the
+output of :func:`~matplotlib.cbook.boxplot_stats` prior to plotting
+with :func:`~matplotlib.Axes.bxp`.
+
+Lastly, each artist (e.g., the box, outliers, cap, notches) can now be
+toggled on or off and their styles can be passed in through individual
+kwargs. See the examples:
+:ref:`statistics-boxplot_demo` and
+:ref:`statistics-bxp_demo`
+
+Added a bool kwarg, :code:`manage_xticks`, which if False disables the management
+of the ticks and limits on the x-axis by :func:`~matplotlib.axes.Axes.bxp`.
+
+Support for datetime axes in 2d plots
+`````````````````````````````````````
+Andrew Dawson added support for datetime axes to
+:func:`~matplotlib.pyplot.contour`, :func:`~matplotlib.pyplot.contourf`,
+:func:`~matplotlib.pyplot.pcolormesh` and :func:`~matplotlib.pyplot.pcolor`.
+
+Support for additional spectrum types
+`````````````````````````````````````
+Todd Jennings added support for new types of frequency spectrum plots:
+:func:`~matplotlib.pyplot.magnitude_spectrum`,
+:func:`~matplotlib.pyplot.phase_spectrum`, and
+:func:`~matplotlib.pyplot.angle_spectrum`, as well as corresponding functions
+in mlab.
+
+He also added these spectrum types to :func:`~matplotlib.pyplot.specgram`,
+as well as adding support for linear scaling there (in addition to the
+existing dB scaling). Support for additional spectrum types was also added to
+:func:`~matplotlib.mlab.specgram`.
+
+He also increased the performance for all of these functions and plot types.
+
+Support for detrending and windowing 2D arrays in mlab
+``````````````````````````````````````````````````````
+Todd Jennings added support for 2D arrays in the
+:func:`~matplotlib.mlab.detrend_mean`, :func:`~matplotlib.mlab.detrend_none`,
+and :func:`~matplotlib.mlab.detrend`, as well as adding
+:func:`~matplotlib.mlab.apply_window` which support windowing 2D arrays.
+
+Support for strides in mlab
+```````````````````````````
+Todd Jennings added some functions to mlab to make it easier to use numpy
+strides to create memory-efficient 2D arrays. This includes
+:func:`~matplotlib.mlab.stride_repeat`, which repeats an array to create a 2D
+array, and :func:`~matplotlib.mlab.stride_windows`, which uses a moving window
+to create a 2D array from a 1D array.
+
+Formatter for new-style formatting strings
+``````````````````````````````````````````
+Added `FormatStrFormatterNewStyle` which does the same job as
+`FormatStrFormatter`, but accepts new-style formatting strings
+instead of printf-style formatting strings
+
+Consistent grid sizes in streamplots
+````````````````````````````````````
+:func:`~matplotlib.pyplot.streamplot` uses a base grid size of 30x30 for both
+`density=1` and `density=(1, 1)`. Previously a grid size of 30x30 was used for
+`density=1`, but a grid size of 25x25 was used for `density=(1, 1)`.
+
+Get a list of all tick labels (major and minor)
+```````````````````````````````````````````````
+Added the `kwarg` 'which' to :func:`~matplotlib.Axes.get_xticklabels`,
+:func:`~matplotlib.Axes.get_yticklabels` and
+:func:`~matplotlib.Axis.get_ticklabels`. 'which' can be 'major', 'minor', or
+'both' select which ticks to return, like
+:func:`~matplotlib.Axis.set_ticks_position`. If 'which' is `None` then the old
+behaviour (controlled by the bool `minor`).
+
+Separate horizontal/vertical axes padding support in ImageGrid
+``````````````````````````````````````````````````````````````
+The `kwarg` 'axes_pad' to :class:`mpl_toolkits.axes_grid1.ImageGrid` can now
+be a tuple if separate horizontal/vertical padding is needed.
+This is supposed to be very helpful when you have a labelled legend next to
+every subplot and you need to make some space for legend's labels.
+
+Support for skewed transformations
+``````````````````````````````````
+The :class:`~matplotlib.transforms.Affine2D` gained additional methods
+`skew` and `skew_deg` to create skewed transformations. Additionally,
+matplotlib internals were cleaned up to support using such transforms in
+:class:`~matplotlib.Axes`. This transform is important for some plot types,
+specifically the Skew-T used in meteorology.
+
+.. plot:: mpl_examples/api/skewt.py
+
+Support for specifying properties of wedge and text in pie charts.
+``````````````````````````````````````````````````````````````````
+Added the `kwargs` 'wedgeprops' and 'textprops' to :func:`~matplotlib.Axes.pie`
+to accept properties for wedge and text objects in a pie. For example, one can
+specify wedgeprops = {'linewidth':3} to specify the width of the borders of
+the wedges in the pie. For more properties that the user can specify, look at
+the docs for the wedge and text objects.
+
+Fixed the direction of errorbar upper/lower limits
+``````````````````````````````````````````````````
+Larry Bradley fixed the :func:`~matplotlib.pyplot.errorbar` method such
+that the upper and lower limits (*lolims*, *uplims*, *xlolims*,
+*xuplims*) now point in the correct direction.
+
+More consistent add-object API for Axes
+```````````````````````````````````````
+Added the Axes method `~matplotlib.axes.Axes.add_image` to put image
+handling on a par with artists, collections, containers, lines, patches,
+and tables.
+
+Violin Plots
+````````````
+Per Parker, Gregory Kelsie, Adam Ortiz, Kevin Chan, Geoffrey Lee, Deokjae
+Donald Seo, and Taesu Terry Lim added a basic implementation for violin
+plots. Violin plots can be used to represent the distribution of sample data.
+They are similar to box plots, but use a kernel density estimation function to
+present a smooth approximation of the data sample used. The added features are:
+
+:func:`~matplotlib.Axes.violin` - Renders a violin plot from a collection of
+statistics.
+:func:`~matplotlib.cbook.violin_stats` - Produces a collection of statistics
+suitable for rendering a violin plot.
+:func:`~matplotlib.pyplot.violinplot` - Creates a violin plot from a set of
+sample data. This method makes use of :func:`~matplotlib.cbook.violin_stats`
+to process the input data, and :func:`~matplotlib.cbook.violin_stats` to
+do the actual rendering. Users are also free to modify or replace the output of
+:func:`~matplotlib.cbook.violin_stats` in order to customize the violin plots
+to their liking.
+
+This feature was implemented for a software engineering course at the
+University of Toronto, Scarborough, run in Winter 2014 by Anya Tafliovich.
+
+More `markevery` options to show only a subset of markers
+`````````````````````````````````````````````````````````
+Rohan Walker extended the `markevery` property in
+:class:`~matplotlib.lines.Line2D`. You can now specify a subset of markers to
+show with an int, slice object, numpy fancy indexing, or float. Using a float
+shows markers at approximately equal display-coordinate-distances along the
+line.
+
+Added size related functions to specialized `Collections`
+`````````````````````````````````````````````````````````
+
+Added the `get_size` and `set_size` functions to control the size of
+elements of specialized collections (
+:class:`~matplotlib.collections.AsteriskPolygonCollection`
+:class:`~matplotlib.collections.BrokenBarHCollection`
+:class:`~matplotlib.collections.CircleCollection`
+:class:`~matplotlib.collections.PathCollection`
+:class:`~matplotlib.collections.PolyCollection`
+:class:`~matplotlib.collections.RegularPolyCollection`
+:class:`~matplotlib.collections.StarPolygonCollection`).
+
+
+Fixed the mouse coordinates giving the wrong theta value in Polar graph
+```````````````````````````````````````````````````````````````````````
+Added code to
+:func:`~matplotlib.InvertedPolarTransform.transform_non_affine`
+to ensure that the calculated theta value was between the range of 0 and 2 * pi
+since the problem was that the value can become negative after applying the
+direction and rotation to the theta calculation.
+
+Simple quiver plot for mplot3d toolkit
+``````````````````````````````````````
+A team of students in an *Engineering Large Software Systems* course, taught
+by Prof. Anya Tafliovich at the University of Toronto, implemented a simple
+version of a quiver plot in 3D space for the mplot3d toolkit as one of their
+term project. This feature is documented in :func:`~mpl_toolkits.mplot3d.Axes3D.quiver`.
+The team members are: Ryan Steve D'Souza, Victor B, xbtsw, Yang Wang, David,
+Caradec Bisesar and Vlad Vassilovski.
+
+.. plot:: mpl_examples/mplot3d/quiver3d_demo.py
+
+polar-plot r-tick locations
+```````````````````````````
+Added the ability to control the angular position of the r-tick labels
+on a polar plot via :func:`~matplotlib.Axes.axes.set_rlabel_position`.
+
+
+Date handling
+-------------
+
+n-d array support for date conversion
+``````````````````````````````````````
+Andrew Dawson added support for n-d array handling to
+:func:`matplotlib.dates.num2date`, :func:`matplotlib.dates.date2num`
+and :func:`matplotlib.dates.datestr2num`. Support is also added to the unit
+conversion interfaces :class:`matplotlib.dates.DateConverter` and
+:class:`matplotlib.units.Registry`.
+
+
+Configuration (rcParams)
+------------------------
+
+
+``savefig.transparent`` added
+`````````````````````````````
+Controls whether figures are saved with a transparent
+background by default. Previously `savefig` always defaulted
+to a non-transparent background.
+
+
+``axes.titleweight``
+````````````````````
+Added rcParam to control the weight of the title
+
+``axes.formatter.useoffset`` added
+``````````````````````````````````
+Controls the default value of `useOffset` in `ScalarFormatter`. If
+`True` and the data range is much smaller than the data average, then
+an offset will be determined such that the tick labels are
+meaningful. If `False` then the full number will be formatted in all
+conditions.
+
+``nbagg.transparent`` added
+`````````````````````````````
+Controls whether nbagg figures have a transparent
+background. ``nbagg.transparent`` is ``True`` by default.
+
+
+XDG compliance
+``````````````
+Matplotlib now looks for configuration files (both rcparams and style) in XDG
+compliant locations.
+
+``style`` package added
+-----------------------
+You can now easily switch between different styles using the new ``style``
+package::
+
+ >>> from matplotlib import style
+ >>> style.use('dark_background')
+
+Subsequent plots will use updated colors, sizes, etc. To list all available
+styles, use::
+
+ >>> print style.available
+
+You can add your own custom ``