diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst index 3727aa434925..2b6f94c890aa 100644 --- a/doc/api/api_changes.rst +++ b/doc/api/api_changes.rst @@ -3,19 +3,402 @@ API Changes =========== -This chapter is a log of changes to matplotlib that affect the -outward-facing API. If updating matplotlib breaks your scripts, this -list may help describe what changes may be necessary in your code or -help figure out possible sources of the changes you are experiencing. +Log of changes to matplotlib that affect the outward-facing API. If +updating matplotlib breaks your scripts, this list may help describe +what changes may be necessary in your code or help figure out possible +sources of the changes you are experiencing. For new features that were added to matplotlib, please see :ref:`whats-new`. -Changes in 2.0.x +Changes in 1.5.0 ================ -* The spacing commands in mathtext have been changed to more closely - match vanilla TeX. +Code Changes +------------ + +Split `matplotlib.cbook.ls_mapper` in two +````````````````````````````````````````` + +The `matplotlib.cbook.ls_mapper` dictionary is split into two now to +distinguish between qualified linestyle used by backends and +unqualified ones. `ls_mapper` now maps from the short symbols +(e.g. `"--"`) to qualified names (`"solid"`). The new ls_mapper_r is +the reversed mapping. + +Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes +`````````````````````````````````````````````````````````````````````````````````````````````` + +The reason this was done was to prevent adding an Artist that is +already associated with an Axes to be moved/added to a different Axes. +This was never supported as it causes havoc with the transform stack. +The apparent support for this (as it did not raise an exception) was +the source of multiple bug reports and questions on SO. + +For almost all use-cases, the assignment of the axes to an artist should be +taken care of by the axes as part of the ``Axes.add_*`` method, hence the +deprecation {get,set}_axes. + +Removing the ``set_axes`` method will also remove the 'axes' line from +the ACCEPTS kwarg tables (assuming that the removal date gets here +before that gets overhauled). + +Tighted input validation on 'pivot' kwarg to quiver +``````````````````````````````````````````````````` + +Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'} +(but any capitalization) are valid values for the 'pivot' kwarg in +the `Quiver.__init__` (and hence `Axes.quiver` and +`plt.quiver` which both fully delegate to `Quiver`). Previously any +input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as +'tip' and any string not matching one of those patterns as 'tail'. + +The value of `Quiver.pivot` is normalized to be in the set {'tip', +'tail', 'middle'} in `Quiver.__init__`. + +Reordered `Axes.get_children` +````````````````````````````` + +The artist order returned by `Axes.get_children` did not +match the one used by `Axes.draw`. They now use the same +order, as `Axes.draw` now calls `Axes.get_children`. + +Changed behaviour of contour plots +`````````````````````````````````` + +The default behaviour of :func:`~matplotlib.pyplot.contour` and +:func:`~matplotlib.pyplot.contourf` when using a masked array is now determined +by the new keyword argument `corner_mask`, or if this is not specified then +the new rcParam `contour.corner_mask` instead. The new default behaviour is +equivalent to using `corner_mask=True`; the previous behaviour can be obtained +using `corner_mask=False` or by changing the rcParam. The example +http://matplotlib.org/examples/pylab_examples/contour_corner_mask.py +demonstrates the difference. Use of the old contouring algorithm, which is +obtained with `corner_mask='legacy'`, is now deprecated. + +Contour labels may now appear in different places than in earlier versions of +matplotlib. + +In addition, the keyword argument `nchunk` now applies to +:func:`~matplotlib.pyplot.contour` as well as +:func:`~matplotlib.pyplot.contourf`, and it subdivides the domain into +subdomains of exactly `nchunk` by `nchunk` quads, whereas previously it was +only roughly `nchunk` by `nchunk` quads. + +The C/C++ object that performs contour calculations used to be stored in the +public attribute QuadContourSet.Cntr, but is now stored in a private attribute +and should not be accessed by end users. + +Added set_params function to all Locator types +`````````````````````````````````````````````` + +This was a bug fix targeted at making the api for Locators more consistent. + +In the old behavior, only locators of type MaxNLocator have set_params() +defined, causing its use on any other Locator to throw an AttributeError *( +aside: set_params(args) is a function that sets the parameters of a Locator +instance to be as specified within args)*. The fix involves moving set_params() +to the Locator class such that all subtypes will have this function defined. + +Since each of the Locator subtype have their own modifiable parameters, a +universal set_params() in Locator isn't ideal. Instead, a default no-operation +function that raises a warning is implemented in Locator. Subtypes extending +Locator will then override with their own implementations. Subtypes that do +not have a need for set_params() will fall back onto their parent's +implementation, which raises a warning as intended. + +In the new behavior, all Locator instances will not throw an AttributeError +when set_param() is called. For Locators that do not implement set_params(), +the default implementation in Locator is used. + +Disallow ``None`` as x or y value in ax.plot +```````````````````````````````````````````` + +Do not allow ``None`` as a valid input for the ``x`` or ``y`` args in +`ax.plot`. This may break some user code, but this was never officially +supported (ex documented) and allowing ``None`` objects through can lead +to confusing exceptions downstream. + +To create an empty line use :: + + ln1, = ax.plot([], [], ...) + ln2, = ax.plot([], ...) + +In either case to update the data in the `Line2D` object you must update +both the ``x`` and ``y`` data. + + +Removed `args` and `kwargs` from `MicrosecondLocator.__call__` +`````````````````````````````````````````````````````````````` + +The call signature of :meth:`~matplotlib.dates.MicrosecondLocator.__call__` +has changed from `__call__(self, *args, **kwargs)` to `__call__(self)`. +This is consistent with the super class :class:`~matplotlib.ticker.Locator` +and also all the other Locators derived from this super class. + + +No `ValueError` for the MicrosecondLocator and YearLocator +`````````````````````````````````````````````````````````` + +The :class:`~matplotlib.dates.MicrosecondLocator` and +:class:`~matplotlib.dates.YearLocator` objects when called will return +an empty list if the axes have no data or the view has no interval. +Previously, they raised a `ValueError`. This is consistent with all +the Date Locators. + +'OffsetBox.DrawingArea' respects the 'clip' keyword argument +```````````````````````````````````````````````````````````` + +The call signature was `OffsetBox.DrawingArea(..., clip=True)` but nothing +was done with the `clip` argument. The object did not do any clipping +regardless of that parameter. Now the object can and does clip the child `Artists` if they are set to be clipped. + +You can turn off the clipping on a per-child basis using `child.set_clip_on(False)`. + +Add salt to cilpPath id +``````````````````````` + +Add salt to the hash used to determine the id of the ``clipPath`` +nodes. This is to avoid conflicts in two svg documents with the same +clip path are included in the same document (see +https://github.com/ipython/ipython/issues/8133 and +https://github.com/matplotlib/matplotlib/issues/4349 ), however this +means that the svg output is no longer deterministic if the same +figure is saved twice. It is not expected that this will affect any +users as the current ids are generated from an md5 hash of properties +of the clip path and any user would have a very difficult time +anticipating the value of the id. + +Changed snap threshold for circle markers to inf +```````````````````````````````````````````````` + +When drawing circle markers above some marker size (previously 6.0) +the path used to generate the marker was snapped to pixel centers. However, +this ends up distorting the marker away from a circle. By setting the +snap threshold to inf snapping is never done on circles. + +This change broke several tests, but is an improvement. + +Preserve units with Text position +````````````````````````````````` + +Previously the 'get_position' method on Text would strip away unit information +even though the units were still present. There was no inherent need to do +this, so it has been changed so that unit data (if present) will be preserved. +Essentially a call to 'get_position' will return the exact value from a call to +'set_position'. + +If you wish to get the old behaviour, then you can use the new method called +'get_unitless_position'. + +New API for custom Axes view changes +```````````````````````````````````` + +Interactive pan and zoom were previously implemented using a Cartesian-specific +algorithm that was not necessarily applicable to custom Axes. Three new private +methods, :meth:`~matplotlib.axes._base._AxesBase._get_view`, +:meth:`~matplotlib.axes._base._AxesBase._set_view`, and +:meth:`~matplotlib.axes._base._AxesBase._set_view_from_bbox`, allow for custom +``Axes`` classes to override the pan and zoom algorithms. Implementors of +custom ``Axes`` who override these methods may provide suitable behaviour for +both pan and zoom as well as the view navigation buttons on the interactive +toolbars. + +MathTex visual changes +---------------------- + +The spacing commands in mathtext have been changed to more closely +match vanilla TeX. + + +Improved spacing in mathtext +```````````````````````````` + +The extra space that appeared after subscripts and superscripts has +been removed. + +No annotation coordinates wrap +`````````````````````````````` + +In #2351 for 1.4.0 the behavior of ['axes points', 'axes pixel', +'figure points', 'figure pixel'] as coordinates was change to +no longer wrap for negative values. In 1.4.3 this change was +reverted for 'axes points' and 'axes pixel' and in addition caused +'axes fraction' to wrap. For 1.5 the behavior has been reverted to +as it was in 1.4.0-1.4.2, no wrapping for any type of coordinate. + +Deprecation +----------- + +Deprecated `GraphicsContextBase.set_graylevel` +`````````````````````````````````````````````` + +The `GraphicsContextBase.set_graylevel` function has been deprecated in 1.5 and +will be removed in 1.6. It has been unused. The +`GraphicsContextBase.set_foreground` could be used instead. + +deprecated idle_event +````````````````````` + +The `idle_event` was broken or missing in most backends and causes spurious +warnings in some cases, and its use in creating animations is now obsolete due +to the animations module. Therefore code involving it has been removed from all +but the wx backend (where it partially works), and its use is deprecated. The +animations module may be used instead to create animations. + +`color_cycle` deprecated +```````````````````````` + +In light of the new property cycling feature, +the Axes method *set_color_cycle* is now deprecated. +Calling this method will replace the current property cycle with +one that cycles just the given colors. + +Similarly, the rc parameter *axes.color_cycle* is also deprecated in +lieu of the new *axes.prop_cycle* parameter. Having both parameters in +the same rc file is not recommended as the result cannot be +predicted. For compatibility, setting *axes.color_cycle* will +replace the cycler in *axes.prop_cycle* with a color cycle. +Accessing *axes.color_cycle* will return just the color portion +of the property cycle, if it exists. + +Timeline for removal has not been set. + + +Code Removed +------------ + +Removed `Image` from main namespace +``````````````````````````````````` + +`Image` was imported from PIL/pillow to test if PIL is available, but there is no +reason to keep `Image` in the namespace once the availability has been determined. + +Removed `lod` from Artist +````````````````````````` + +Removed the method *set_lod* and all references to +the attribute *_lod* as the are not used anywhere else in the +code base. It appears to be a feature stub that was never built +out. + +Removed threading related classes from cbook +```````````````````````````````````````````` +The classes ``Scheduler``, ``Timeout``, and ``Idle`` were in cbook, but +are not used internally. They appear to be a prototype for the idle event +system which was not working and has recently been pulled out. + +Removed `Lena` images from sample_data +`````````````````````````````````````` + +The ``lena.png`` and ``lena.jpg`` images have been removed from +matplotlibs sample_data directory. The images are also no longer +available from `matplotlib.cbook.get_sample_data`. We suggest using +`matplotlib.cbook.get_sample_data('grace_hopper.png')` or +`matplotlib.cbook.get_sample_data('grace_hopper.jpg')` instead. + + +Legend +`````` +Removed handling of `loc` as a positional argument to `Legend` + + +Legend handlers +``````````````` +Remove code to allow legend handlers to be callable. They must now +implement a method ``legend_artist``. + + +Axis +```` +Removed method ``set_scale``. This is now handled via a private method which +should not be used directly by users. It is called via ``Axes.set_{x,y}scale`` +which takes care of ensuring the coupled changes are also made to the Axes object. + +finance.py +`````````` + +Removed functions with ambiguous argument order from finance.py + + +Annotation +`````````` + +Removed ``textcoords`` and ``xytext`` proprieties from Annotation objects. + + +spinxext.ipython_*.py +````````````````````` + +Both ``ipython_console_highlighting`` and ``ipython_directive`` have been moved to +`IPython`. + +Change your import from 'matplotlib.sphinxext.ipython_directive' to +'IPython.sphinxext.ipython_directive' and from 'matplotlib.sphinxext.ipython_directive' to +'IPython.sphinxext.ipython_directive' + + +LineCollection.color +```````````````````` + +Deprecated in 2005, use ``set_color`` + + +remove ``'faceted'`` as a valid value for `shading` in ``tri.tripcolor`` +```````````````````````````````````````````````````````````````````````` + +Use `edgecolor` instead. Added validation on ``shading`` to +only be valid values. + + +Remove ``faceted`` kwarg from scatter +````````````````````````````````````` + +Remove support for the ``faceted`` kwarg. This was deprecated in +d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by +``edgecolor``. + + +Remove ``set_colorbar`` method from ``ScalarMappable`` +`````````````````````````````````````````````````````` + +Remove ``set_colorbar`` method, use `colorbar` attribute directly. + + +patheffects.svg +``````````````` + + - remove ``get_proxy_renderer`` method from ``AbstarctPathEffect`` class + - remove ``patch_alpha`` and ``offset_xy`` from ``SimplePatchShadow`` + + +Remove ``testing.image_util.py`` +```````````````````````````````` +Contained only a no-longer used port of functionality from PIL + + +Remove ``mlab.FIFOBuffer`` +`````````````````````````` + +Not used internally and not part of core mission of mpl. + + +Remove ``mlab.prepca`` +`````````````````````` +Deprecated in 2009. + + +Remove ``NavigationToolbar2QTAgg`` +`````````````````````````````````` +Added no functionality over the base ``NavigationToolbar2Qt`` + + +mpl.py +`````` + +Remove the module `matplotlib.mpl`. Deprecated in 1.3 by +PR #1670 and commit 78ce67d161625833cacff23cfe5d74920248c5b2 + Changes in 1.4.x ================ @@ -967,7 +1350,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 @@ -1032,7 +1415,7 @@ Old method New method :attr:`~matplotlib.transforms.Bbox.xmin`. :mod:`matplotlib.axes` -~~~~~~~~~~~~~~~~~~~~~~ +`````````````````````` ============================================================ ============================================================ Old method New method @@ -1060,7 +1443,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 @@ -1074,7 +1457,7 @@ Old method New method the path immediately before clipping. :mod:`matplotlib.collections` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````````` ============================================================ ============================================================ Old method New method @@ -1087,7 +1470,7 @@ Old method New method provided. :mod:`matplotlib.colors` -~~~~~~~~~~~~~~~~~~~~~~~~ +```````````````````````` ============================================================ ============================================================ Old method New method @@ -1098,7 +1481,7 @@ Old method New method ============================================================ ============================================================ :mod:`matplotlib.contour` -~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````` ============================================================ ============================================================ Old method New method @@ -1108,7 +1491,7 @@ Old method New method ============================================================ ============================================================ :mod:`matplotlib.figure` -~~~~~~~~~~~~~~~~~~~~~~~~ +```````````````````````` ============================================================ ============================================================ Old method New method @@ -1117,7 +1500,7 @@ Old method New method ============================================================ ============================================================ :mod:`matplotlib.patches` -~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````` ============================================================ ============================================================ Old method New method @@ -1127,7 +1510,7 @@ Old method New method ============================================================ ============================================================ :mod:`matplotlib.backend_bases` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``````````````````````````````` ============================================================ ============================================================ Old method New method @@ -1918,7 +2301,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 @@ -1929,7 +2312,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 @@ -1970,7 +2353,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 @@ -1986,13 +2369,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:: @@ -2012,13 +2395,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 @@ -2042,7 +2425,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 @@ -2072,7 +2455,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/2014-11-07_remove_IMAGE.rst b/doc/api/api_changes/2014-11-07_remove_IMAGE.rst deleted file mode 100644 index 74ef3d594d21..000000000000 --- a/doc/api/api_changes/2014-11-07_remove_IMAGE.rst +++ /dev/null @@ -1,5 +0,0 @@ -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. diff --git a/doc/api/api_changes/2014-11-11_ELF_split_lsmapper.rst b/doc/api/api_changes/2014-11-11_ELF_split_lsmapper.rst deleted file mode 100644 index e32da0a0898f..000000000000 --- a/doc/api/api_changes/2014-11-11_ELF_split_lsmapper.rst +++ /dev/null @@ -1,9 +0,0 @@ -Split `matplotlib.cbook.ls_mapper` in two -````````````````````````````````````````` - -The `matplotlib.cbook.ls_mapper` dictionary is split into two now to -distinguish between qualified linestyle used by backends and -unqualified ones. `ls_mapper` now maps from the short symbols -(e.g. `"--"`) to qualified names (`"solid"`). The new ls_mapper_r is -the reversed mapping. - diff --git a/doc/api/api_changes/2014-11-19_remove_set_graylevel.rst b/doc/api/api_changes/2014-11-19_remove_set_graylevel.rst deleted file mode 100644 index b346a227c7c2..000000000000 --- a/doc/api/api_changes/2014-11-19_remove_set_graylevel.rst +++ /dev/null @@ -1,6 +0,0 @@ -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. diff --git a/doc/api/api_changes/2014-11-22-remove_lod.rst b/doc/api/api_changes/2014-11-22-remove_lod.rst deleted file mode 100644 index 5d58ade72b31..000000000000 --- a/doc/api/api_changes/2014-11-22-remove_lod.rst +++ /dev/null @@ -1,7 +0,0 @@ -Removed `lod` from Artist -````````````````````````` - -Removed the method *set_lod* and all references to -the attribute *_lod* as the are not used anywhere else in the -code base. It appears to be a feature stub that was never built -out. diff --git a/doc/api/api_changes/2014-12-12_axes_property.rst b/doc/api/api_changes/2014-12-12_axes_property.rst deleted file mode 100644 index 3e98a5cbd4a5..000000000000 --- a/doc/api/api_changes/2014-12-12_axes_property.rst +++ /dev/null @@ -1,16 +0,0 @@ -Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes -`````````````````````````````````````````````````````````````````````````````````````````````` - -The reason this was done was to prevent adding an Artist that is -already associated with an Axes to be moved/added to a different Axes. -This was never supported as it causes havoc with the transform stack. -The apparent support for this (as it did not raise an exception) was -the source of multiple bug reports and questions on SO. - -For almost all use-cases, the assignment of the axes to an artist should be -taken care of by the axes as part of the ``Axes.add_*`` method, hence the -deprecation {get,set}_axes. - -Removing the ``set_axes`` method will also remove the 'axes' line from -the ACCEPTS kwarg tables (assuming that the removal date gets here -before that gets overhauled). diff --git a/doc/api/api_changes/2014-12-28_quiver.rst b/doc/api/api_changes/2014-12-28_quiver.rst deleted file mode 100644 index 98fc5aed97f5..000000000000 --- a/doc/api/api_changes/2014-12-28_quiver.rst +++ /dev/null @@ -1,12 +0,0 @@ -Tighted input validation on 'pivot' kwarg to quiver -``````````````````````````````````````````````````` - -Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'} -(but any capitalization) are valid values for the 'pivot' kwarg in -the `Quiver.__init__` (and hence `Axes.quiver` and -`plt.quiver` which both fully delegate to `Quiver`). Previously any -input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as -'tip' and any string not matching one of those patterns as 'tail'. - -The value of `Quiver.pivot` is normalized to be in the set {'tip', -'tail', 'middle'} in `Quiver.__init__`. diff --git a/doc/api/api_changes/2015-01-19_reorder_axes_get_children.rst b/doc/api/api_changes/2015-01-19_reorder_axes_get_children.rst deleted file mode 100644 index 49d2da6a8d81..000000000000 --- a/doc/api/api_changes/2015-01-19_reorder_axes_get_children.rst +++ /dev/null @@ -1,6 +0,0 @@ -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`. diff --git a/doc/api/api_changes/2015-02-19-IMT.rst b/doc/api/api_changes/2015-02-19-IMT.rst deleted file mode 100644 index 86a6033eb620..000000000000 --- a/doc/api/api_changes/2015-02-19-IMT.rst +++ /dev/null @@ -1,25 +0,0 @@ -Changed behaviour of contour plots -`````````````````````````````````` - -The default behaviour of :func:`~matplotlib.pyplot.contour` and -:func:`~matplotlib.pyplot.contourf` when using a masked array is now determined -by the new keyword argument `corner_mask`, or if this is not specified then -the new rcParam `contour.corner_mask` instead. The new default behaviour is -equivalent to using `corner_mask=True`; the previous behaviour can be obtained -using `corner_mask=False` or by changing the rcParam. The example -http://matplotlib.org/examples/pylab_examples/contour_corner_mask.py -demonstrates the difference. Use of the old contouring algorithm, which is -obtained with `corner_mask='legacy'`, is now deprecated. - -Contour labels may now appear in different places than in earlier versions of -matplotlib. - -In addition, the keyword argument `nchunk` now applies to -:func:`~matplotlib.pyplot.contour` as well as -:func:`~matplotlib.pyplot.contourf`, and it subdivides the domain into -subdomains of exactly `nchunk` by `nchunk` quads, whereas previously it was -only roughly `nchunk` by `nchunk` quads. - -The C/C++ object that performs contour calculations used to be stored in the -public attribute QuadContourSet.Cntr, but is now stored in a private attribute -and should not be accessed by end users. diff --git a/doc/api/api_changes/2015-03-03-LEO.rst b/doc/api/api_changes/2015-03-03-LEO.rst deleted file mode 100755 index 270affdf33ed..000000000000 --- a/doc/api/api_changes/2015-03-03-LEO.rst +++ /dev/null @@ -1,21 +0,0 @@ -Added set_params function to all Locator types -```````````````````````````````````````````````` - -This was a bug fix targeted at making the api for Locators more consistent. - -In the old behavior, only locators of type MaxNLocator have set_params() -defined, causing its use on any other Locator to throw an AttributeError *( -aside: set_params(args) is a function that sets the parameters of a Locator -instance to be as specified within args)*. The fix involves moving set_params() -to the Locator class such that all subtypes will have this function defined. - -Since each of the Locator subtype have their own modifiable parameters, a -universal set_params() in Locator isn't ideal. Instead, a default no-operation -function that raises a warning is implemented in Locator. Subtypes extending -Locator will then override with their own implementations. Subtypes that do -not have a need for set_params() will fall back onto their parent's -implementation, which raises a warning as intended. - -In the new behavior, all Locator instances will not throw an AttributeError -when set_param() is called. For Locators that do not implement set_params(), -the default implementation in Locator is used. diff --git a/doc/api/api_changes/2015-04-08_plot_noNone.rst b/doc/api/api_changes/2015-04-08_plot_noNone.rst deleted file mode 100644 index afab7505cee8..000000000000 --- a/doc/api/api_changes/2015-04-08_plot_noNone.rst +++ /dev/null @@ -1,15 +0,0 @@ -Disallow ``None`` as x or y value in ax.plot -```````````````````````````````````````````` - -Do not allow ``None`` as a valid input for the ``x`` or ``y`` args in -`ax.plot`. This may break some user code, but this was never officially -supported (ex documented) and allowing ``None`` objects through can lead -to confusing exceptions downstream. - -To create an empty line use :: - - ln1, = ax.plot([], [], ...) - ln2, = ax.plot([], ...) - -In either case to update the data in the `Line2D` object you must update -both the ``x`` and ``y`` data. diff --git a/doc/api/api_changes/2015-04-12_microsecondlocator.rst b/doc/api/api_changes/2015-04-12_microsecondlocator.rst deleted file mode 100644 index d8366041c535..000000000000 --- a/doc/api/api_changes/2015-04-12_microsecondlocator.rst +++ /dev/null @@ -1,17 +0,0 @@ -Removed `args` and `kwargs` from `MicrosecondLocator.__call__` -`````````````````````````````````````````````````````````````` - -The call signature of :meth:`~matplotlib.dates.MicrosecondLocator.__call__` -has changed from `__call__(self, *args, **kwargs)` to `__call__(self)`. -This is consistent with the super class :class:`~matplotlib.ticker.Locator` -and also all the other Locators derived from this super class. - - -No `ValueError` for the MicrosecondLocator and YearLocator -`````````````````````````````````````````````````````````` - -The :class:`~matplotlib.dates.MicrosecondLocator` and -:class:`~matplotlib.dates.YearLocator` objects when called will return -an empty list if the axes have no data or the view has no interval. -Previously, they raised a `ValueError`. This is consistent with all -the Date Locators. diff --git a/doc/api/api_changes/2015-04-18-drawingarea.rst b/doc/api/api_changes/2015-04-18-drawingarea.rst deleted file mode 100644 index c977dd93e01c..000000000000 --- a/doc/api/api_changes/2015-04-18-drawingarea.rst +++ /dev/null @@ -1,8 +0,0 @@ -'OffsetBox.DrawingArea' respects the 'clip' keyword argument -```````````````````````````````````````````````````````````` - -The call signature was `OffsetBox.DrawingArea(..., clip=True)` but nothing -was done with the `clip` argument. The object did not do any clipping -regardless of that parameter. Now the object can and does clip the child `Artists` if they are set to be clipped. - -You can turn off the clipping on a per-child basis using `child.set_clip_on(False)`. diff --git a/doc/api/api_changes/2015-04-27_svgclip_url.rst b/doc/api/api_changes/2015-04-27_svgclip_url.rst deleted file mode 100644 index 5572fb388c76..000000000000 --- a/doc/api/api_changes/2015-04-27_svgclip_url.rst +++ /dev/null @@ -1,13 +0,0 @@ -Add salt to cilpPath id -``````````````````````` - -Add salt to the hash used to determine the id of the ``clipPath`` -nodes. This is to avoid conflicts in two svg documents with the same -clip path are included in the same document (see -https://github.com/ipython/ipython/issues/8133 and -https://github.com/matplotlib/matplotlib/issues/4349 ), however this -means that the svg output is no longer deterministic if the same -figure is saved twice. It is not expected that this will affect any -users as the current ids are generated from an md5 hash of properties -of the clip path and any user would have a very difficult time -anticipating the value of the id. diff --git a/doc/api/api_changes/2015-05-08_mathtext_spacing.rst b/doc/api/api_changes/2015-05-08_mathtext_spacing.rst deleted file mode 100644 index eaa4691f55c3..000000000000 --- a/doc/api/api_changes/2015-05-08_mathtext_spacing.rst +++ /dev/null @@ -1,5 +0,0 @@ -Improved spacing in mathtext -```````````````````````````` - -The extra space that appeared after subscripts and superscripts has -been removed. diff --git a/doc/api/api_changes/2015-05-12_circle_marker_snap.rst b/doc/api/api_changes/2015-05-12_circle_marker_snap.rst deleted file mode 100644 index 9c18f26b613b..000000000000 --- a/doc/api/api_changes/2015-05-12_circle_marker_snap.rst +++ /dev/null @@ -1,9 +0,0 @@ -Changed snap threshold for circle markers to inf -```````````````````````````````````````````````` - -When drawing circle markers above some marker size (previously 6.0) -the path used to generate the marker was snapped to pixel centers. However, -this ends up distorting the marker away from a circle. By setting the -snap threshold to inf snapping is never done on circles. - -This change broke several tests, but is an improvement. diff --git a/doc/api/api_changes/2015-06-21_idle_event.rst b/doc/api/api_changes/2015-06-21_idle_event.rst deleted file mode 100644 index 1defdb4faa3f..000000000000 --- a/doc/api/api_changes/2015-06-21_idle_event.rst +++ /dev/null @@ -1,9 +0,0 @@ -deprecated idle_event -````````````````````` - -The `idle_event` was broken or missing in most backends and causes spurious -warnings in some cases, and its use in creating animations is now obsolete due -to the animations module. Therefore code involving it has been removed from all -but the wx backend (where it partially works), and its use is deprecated. The -animations module may be used instead to create animations. - diff --git a/doc/api/api_changes/2015-07-16_remove_threading.rst b/doc/api/api_changes/2015-07-16_remove_threading.rst deleted file mode 100644 index 97b931714470..000000000000 --- a/doc/api/api_changes/2015-07-16_remove_threading.rst +++ /dev/null @@ -1,5 +0,0 @@ -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. diff --git a/doc/api/api_changes/2015-07-30_annotation_wrap.rst b/doc/api/api_changes/2015-07-30_annotation_wrap.rst deleted file mode 100644 index ead5a085d037..000000000000 --- a/doc/api/api_changes/2015-07-30_annotation_wrap.rst +++ /dev/null @@ -1,9 +0,0 @@ -No annotation coordinates wrap -`````````````````````````````` - -In #2351 for 1.4.0 the behavior of ['axes points', 'axes pixel', -'figure points', 'figure pixel'] as coordinates was change to -no longer wrap for negative values. In 1.4.3 this change was -reverted for 'axes points' and 'axes pixel' and in addition caused -'axes fraction' to wrap. For 1.5 the behavior has been reverted to -as it was in 1.4.0-1.4.2, no wrapping for any type of coordinate. diff --git a/doc/api/api_changes/2015-08-16_remove_lena_from_sample_data.rst b/doc/api/api_changes/2015-08-16_remove_lena_from_sample_data.rst deleted file mode 100644 index 0d854e9afd8e..000000000000 --- a/doc/api/api_changes/2015-08-16_remove_lena_from_sample_data.rst +++ /dev/null @@ -1,8 +0,0 @@ -Removed `Lena` images from sample_data -`````````````````````````````````````` - -The ``lena.png`` and ``lena.jpg`` images have been removed from -matplotlibs sample_data directory. The images are also no longer -available from `matplotlib.cbook.get_sample_data`. We suggest using -`matplotlib.cbook.get_sample_data('grace_hopper.png')` or -`matplotlib.cbook.get_sample_data('grace_hopper.jpg')` instead. diff --git a/doc/api/api_changes/2015-08-17-JRE.rst b/doc/api/api_changes/2015-08-17-JRE.rst deleted file mode 100644 index 0f15fbac4852..000000000000 --- a/doc/api/api_changes/2015-08-17-JRE.rst +++ /dev/null @@ -1,11 +0,0 @@ - Preserve units with Text position - ````````````````````````````````` - -Previously the 'get_position' method on Text would strip away unit information -even though the units were still present. There was no inherent need to do -this, so it has been changed so that unit data (if present) will be preserved. -Essentially a call to 'get_position' will return the exact value from a call to -'set_position'. - -If you wish to get the old behaviour, then you can use the new method called -'get_unitless_position'. diff --git a/doc/api/api_changes/2015-08-17-remove_color_cycle.rst b/doc/api/api_changes/2015-08-17-remove_color_cycle.rst deleted file mode 100644 index 1d92d74ab1cf..000000000000 --- a/doc/api/api_changes/2015-08-17-remove_color_cycle.rst +++ /dev/null @@ -1,17 +0,0 @@ -`color_cycle` deprecated -```````````````````````` - -In light of the new property cycling feature, -the Axes method *set_color_cycle* is now deprecated. -Calling this method will replace the current property cycle with -one that cycles just the given colors. - -Similarly, the rc parameter *axes.color_cycle* is also deprecated in -lieu of the new *axes.prop_cycle* parameter. Having both parameters in -the same rc file is not recommended as the result cannot be -predicted. For compatibility, setting *axes.color_cycle* will -replace the cycler in *axes.prop_cycle* with a color cycle. -Accessing *axes.color_cycle* will return just the color portion -of the property cycle, if it exists. - -Timeline for removal has not been set. diff --git a/doc/api/api_changes/2015-08-29-custom-axes-view.rst b/doc/api/api_changes/2015-08-29-custom-axes-view.rst deleted file mode 100644 index 34918f8efa78..000000000000 --- a/doc/api/api_changes/2015-08-29-custom-axes-view.rst +++ /dev/null @@ -1,12 +0,0 @@ -New API for custom Axes view changes -```````````````````````````````````` - -Interactive pan and zoom were previously implemented using a Cartesian-specific -algorithm that was not necessarily applicable to custom Axes. Three new private -methods, :meth:`~matplotlib.axes._base._AxesBase._get_view`, -:meth:`~matplotlib.axes._base._AxesBase._set_view`, and -:meth:`~matplotlib.axes._base._AxesBase._set_view_from_bbox`, allow for custom -``Axes`` classes to override the pan and zoom algorithms. Implementors of -custom ``Axes`` who override these methods may provide suitable behaviour for -both pan and zoom as well as the view navigation buttons on the interactive -toolbars. diff --git a/doc/api/api_changes/code_removal.rst b/doc/api/api_changes/code_removal.rst deleted file mode 100644 index eec6a5ea6c65..000000000000 --- a/doc/api/api_changes/code_removal.rst +++ /dev/null @@ -1,95 +0,0 @@ -Code Removal -```````````` - -Legend ------- -Removed handling of `loc` as a positional argument to `Legend` - - -Legend handlers -~~~~~~~~~~~~~~~ -Remove code to allow legend handlers to be callable. They must now -implement a method ``legend_artist``. - - -Axis ----- -Removed method ``set_scale``. This is now handled via a private method which -should not be used directly by users. It is called via ``Axes.set_{x,y}scale`` -which takes care of ensuring the coupled changes are also made to the Axes object. - -finance.py ----------- -Removed functions with ambiguous argument order from finance.py - - -Annotation ----------- -Removed ``textcoords`` and ``xytext`` proprieties from Annotation objects. - - -spinxext.ipython_*.py ---------------------- -Both ``ipython_console_highlighting`` and ``ipython_directive`` have been moved to -`IPython`. - -Change your import from 'matplotlib.sphinxext.ipython_directive' to -'IPython.sphinxext.ipython_directive' and from 'matplotlib.sphinxext.ipython_directive' to -'IPython.sphinxext.ipython_directive' - - -LineCollection.color --------------------- -Deprecated in 2005, use ``set_color`` - - -remove 'faceted' as a valid value for `shading` in ``tri.tripcolor`` --------------------------------------------------------------------- -Use `edgecolor` instead. Added validation on ``shading`` to -only be valid values. - - -Remove ``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 - - -Remove ``faceted`` kwarg from scatter -------------------------------------- - -Remove support for the ``faceted`` kwarg. This was deprecated in -d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by -``edgecolor``. diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst index f37dd29cbe69..ad60b0d7f075 100644 --- a/doc/users/whats_new.rst +++ b/doc/users/whats_new.rst @@ -4,13 +4,12 @@ What's new in matplotlib ************************ -This page just covers the highlights -- for the full story, see the -`CHANGELOG `_ - For a list of all of the issues and pull requests since the last revision, see the :ref:`github-stats`. .. note:: + matplotlib 1.5 supports Python 2.6, 2.7, 3.3, 3.4, and 3.5 + matplotlib 1.4 supports Python 2.6, 2.7, 3.3, and 3.4 matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3 @@ -29,10 +28,154 @@ revision, see the :ref:`github-stats`. new in matplotlib-1.5 ===================== -Legend ------- -Added ability to place the label before the marker in a legend box with -``markerfirst`` keyword +Interactive OO usage +-------------------- + +All `Artists` now keep track of if their internal state has been +changed but not reflected in the display ('stale') by a call to +``draw``. It is thus possible to pragmatically determine if a given +`Figure` needs to be re-drawn in an interactive session. + +To facilitate interactive usage a ``draw_all`` method has been added +to ``pyplot`` which will redraw all of the figures which are 'stale'. + +To make this convenient for interactive use matplotlib now registers +a function either with IPython's 'post_execute' event or with the +displayhook in the standard python REPL to automatically call +``plt.draw_all`` just before control is returned to the REPL. This ensures +that the draw command is deferred and only called once. + +The upshot of this is that for interactive backends (including +``%matplotlib notebook``) in interactive mode (with ``plt.ion()``) + +.. ipython :: python + + import matplotlib.pyplot as plt + + fig, ax = plt.subplots() + + ln, = ax.plot([0, 1, 4, 9, 16]) + + plt.show() + + ln.set_color('g') + + +will automatically update the plot to be green. Any subsequent +modifications to the ``Artist`` objects will do likewise. + +This is the first step of a larger consolidation and simplification of +the pyplot internals. + + +Working with labeled data like pandas DataFrames +------------------------------------------------ +Plot methods which take arrays as inputs can now also work with labeled data +and unpack such data. + +This means that the following two examples produce the same plot: + +Example :: + + df = pandas.DataFrame({"var1":[1,2,3,4,5,6], "var2":[1,2,3,4,5,6]}) + plt.plot(df["var1"], df["var2"]) + + +Example :: + + plt.plot("var1", "var2", data=df) + +This works for most plotting methods, which expect arrays/sequences as +inputs. ``data`` can be anything which supports ``__getitem__`` +(``dict``, ``pandas.DataFrame``, ``h5py``, ...) to access ``array`` like +values with string keys. + +In addition to this, some other changes were made, which makes working with +labeled data (ex ``pandas.Series``) easier: + +* For plotting methods with ``label`` keyword argument, one of the + data inputs is designated as the label source. If the user does not + supply a ``label`` that value object will be introspected for a + label, currently by looking for a ``name`` attribute. If the value + object does not have a ``name`` attribute but was specified by as a + key into the ``data`` kwarg, then the key is used. In the above + examples, this results in an implicit ``label="var2"`` for both + cases. + +* ``plot()`` now uses the index of a ``Series`` instead of + ``np.arange(len(y))``, if no ``x`` argument is supplied. + + +Added ``axes.prop_cycle`` key to rcParams +----------------------------------------- + +This is a more generic form of the now-deprecated ``axes.color_cycle`` param. +Now, we can cycle more than just colors, but also linestyles, hatches, +and just about any other artist property. Cycler notation is used for +defining proprty cycles. Adding cyclers together will be like you are +`zip()`-ing together two or more property cycles together:: + + axes.prop_cycle: cycler('color', 'rgb') + cycler('lw', [1, 2, 3]) + +You can even multiply cyclers, which is like using `itertools.product()` +on two or more property cycles. Remember to use parentheses if writing +a multi-line `prop_cycle` parameter. + +..plot:: mpl_examples/color/color_cycle_demo.py + + +Allow Artists to Display Pixel Data in Cursor +--------------------------------------------- + +Adds `get_pixel_data` and `format_pixel_data` methods to artists +which can be used to add zdata to the cursor display +in the status bar. Also adds an implementation for Images. + + +Auto-wrapping Text +------------------ + +Added the keyword argument "wrap" to Text, which automatically breaks +long lines of text when being drawn. Works for any rotated text, +different modes of alignment, and for text that are either labels or +titles. This breaks at the ``Figure``, not ``Axes`` edge. + +.. plot:: + + fig, ax = plt.subplots() + fig.patch.set_color('.9') + ax.text(.5, .75, + "This is a really long string that should be wrapped so that " + "it does not go outside the figure.", wrap=True) + +New Color maps +-------------- + +All four of the color maps proposed as the new default are available +as ``'viridis'`` (the new default), ``'magma'``, ``'plasma'``, and +``'inferno'`` + +.. plot:: + + import numpy as np + from cycler import cycler + cmap = cycler('cmap', ['viridis', 'magma','plasma', 'inferno']) + x_mode = cycler('x', [1, 2]) + y_mode = cycler('y', x_mode) + + cy = (x_mode * y_mode) + cmap + + def demo(ax, x, y, cmap): + X, Y = np.ogrid[0:2*np.pi:200j, 0:2*np.pi:200j] + data = np.sin(X*x) * np.cos(Y*y) + ax.imshow(data, interpolation='none', cmap=cmap) + ax.set_title(cmap) + + fig, axes = plt.subplots(2, 2) + for ax, sty in zip(axes.ravel(), cy): + demo(ax, **sty) + + fig.tight_layout() Widgets @@ -46,26 +189,536 @@ called when accessing the ``active`` property) to properly update and query whether they are active. +Moved ``ignore``, ``set_active``, and ``get_active`` methods to base class ``Widget`` +````````````````````````````````````````````````````````````````````````````````````` + +Pushes up duplicate methods in child class to parent class to avoid duplication of code. + + +Adds enable/disable feature to MultiCursor +`````````````````````````````````````````` + +A MultiCursor object can be disabled (and enabled) after it has been created without destroying the object. +Example:: + + multi_cursor.active = False + + +Improved RectangleSelector and new EllipseSelector Widget +````````````````````````````````````````````````````````` + +Adds an `interactive` keyword which enables visible handles for manipulating the shape after it has been drawn. + +Adds keyboard modifiers for: + +- Moving the existing shape (default key = 'space') +- Making the shape square (default 'shift') +- Make the initial point the center of the shape (default 'control') +- Square and center can be combined + + New plotting features --------------------- + +Legend marker order +``````````````````` + +Added ability to place the label before the marker in a legend box with +``markerfirst`` keyword + + + Support for legend for PolyCollection and stackplot ``````````````````````````````````````````````````` + Added a `legend_handler` for :class:`~matplotlib.collections.PolyCollection` as well as a `labels` argument to :func:`~matplotlib.axes.Axes.stackplot`. + Support for alternate pivots in mplot3d quiver plot ``````````````````````````````````````````````````` + Added a :code:`pivot` kwarg to :func:`~mpl_toolkits.mplot3d.Axes3D.quiver` that controls the pivot point around which the quiver line rotates. This also determines the placement of the arrow head along the quiver line. + +Logit Scale +``````````` + +Added support for the 'logit' axis scale, a nonlinear transformation + +.. math:: + + x -> \log10(x / (1-x)) + +for data between 0 and 1 excluded. + + +Add step kwargs to fill_between +``````````````````````````````` + +Added ``step`` kwarg to `Axes.fill_between` to allow to fill between +lines drawn using the 'step' draw style. The values of ``step`` match +those of the ``where`` kwarg of `Axes.step`. The asymmetry of of the +kwargs names is not ideal, but `Axes.fill_between` already has a +``where`` kwarg. + +This is particularly useful for plotting pre-binned histograms. + +.. plot:: mpl_examples/api/filled_step.py + + +Square Plot +``````````` + + +Implemented square plots feature as a new parameter in the axis +function. When argument 'square' is specified, equal scaling is set, +and the limits are set such that xmax-xmin == ymax-ymin. + +.. plot:: + + fig, ax = plt.subplots() + ax.axis('square') + + +updated figimage to take optional resize parameter +`````````````````````````````````````````````````` + +Added the ability to plot simple 2D-Array using ``plt.figimage(X, resize=True)``. +This is useful for plotting simple 2D-Array without the Axes or whitespacing +around the image. + +.. plot:: + + data = np.random.random( [500, 500] ) + plt.figimage(data, resize=True) + +Updated Figure.savefig() +```````````````````````` + +Added support to save the figure with the same dpi as the figure on the screen using dpi='figure' + +Example:: + + f = plt.figure(dpi=25) # dpi set to 25 + S = plt.scatter([1,2,3],[4,5,6]) + f.savefig('output.png', dpi='figure') # output savefig dpi set to 25 (same as figure) + + +Updated Table and to control edge visibility +```````````````````````````````````````````` + +Added the ability to toggle the visibility of lines in Tables. +Functionality added to the table() factory function under the keyword +argument "edges". Values can be the strings "open", "closed", +"horizontal", "vertical" or combinations of the letters "L", "R", "T", +"B" which represent left, right, top, and bottom respectively. + +Example:: + + table(..., edges="open") # No line visible + table(..., edges="closed") # All lines visible + table(..., edges="horizontal") # Only top and bottom lines visible + table(..., edges="LT") # Only left and top lines visible. + +Zero r/cstride support in plot_wireframe +```````````````````````````````````````` + +Adam Hughes added support to mplot3d's plot_wireframe to draw only row or +column line plots. + + +.. plot:: + + from mpl_toolkits.mplot3d import Axes3D, axes3d + fig = plt.figure() + ax = fig.add_subplot(111, projection='3d') + X, Y, Z = axes3d.get_test_data(0.05) + ax.plot_wireframe(X, Y, Z, rstride=10, cstride=0) + + +Plot bar and barh with labels +````````````````````````````` + +Added kwarg ``"tick_label"`` to `bar` and `barh` to support plotting bar graphs with a +text label for each bar. + +.. plot:: + + plt.bar([1, 2], [.5, .75], tick_label=['bar1', 'bar2'], + align='center') + +Added center and frame kwargs to pie +```````````````````````````````````` + +These control where the center of the pie graph are and if +the Axes frame is shown. + +Contour plot corner masking +``````````````````````````` + +Ian Thomas rewrote the C++ code that calculates contours to add support for +corner masking. This is controlled by a new keyword argument +``corner_mask`` in the functions :func:`~matplotlib.pyplot.contour` and +:func:`~matplotlib.pyplot.contourf`. The previous behaviour, which is now +obtained using ``corner_mask=False``, was for a single masked point to +completely mask out all four quads touching that point. The new behaviour, +obtained using ``corner_mask=True``, only masks the corners of those +quads touching the point; any triangular corners comprising three unmasked +points are contoured as usual. If the ``corner_mask`` keyword argument is not +specified, the default value is taken from rcParams. + +.. plot:: mpl_examples/pylab_examples/contour_corner_mask.py + +Fixed 3D filled contour plot polygon rendering +`````````````````````````````````````````````` + +Certain cases of 3D filled contour plots that produce polygons with multiple +holes produced improper rendering due to a loss of path information between +:class:`~matplotlib.collections.PolyCollection` and +:class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`. A function +:func:`~matplotlib.collections.PolyCollection.set_verts_and_codes` was +added to allow path information to be retained for proper rendering. + +Dense colorbars are rasterized +`````````````````````````````` + +Vector file formats (pdf, ps, svg) are efficient for +many types of plot element, but for some they can yield +excessive file size and even rendering artifacts, depending +on the renderer used for screen display. This is a problem +for colorbars that show a large number of shades, as is +most commonly the case. Now, if a colorbar is showing +50 or more colors, it will be rasterized in vector +backends. + + +DateFormatter strftime +`````````````````````` +Date formatters' (:class:`~matplotlib.dates.DateFormatter`) +:meth:`~matplotlib.dates.DateFormatter.strftime` method will format +a :class:`datetime.datetime` object with the format string passed to +the formatter's constructor. This method accepts datetimes with years +before 1900, unlike :meth:`datetime.datetime.strftime`. + +Artist-level {get,set}_usetex for text +`````````````````````````````````````` + +Add ``{get,set}_usetex`` methods to `text.Text` objects which allow +artist-level control of LaTeX rendering vs the internal mathtex +rendering. + +API Consistency fix within Locators set_params() function +````````````````````````````````````````````````````````` + +set_params() function, which sets parameters within a Locator type +instance, is now available to all Locator types. The implementation +also prevents unsafe usage by strictly defining the parameters that a +user can set. + +To use, simply call ``set_params()`` on a Locator instance with desired arguments: +:: + + loc = matplotlib.ticker.LogLocator() + # Set given attributes for loc. + loc.set_params(numticks=8, numdecs=8, subs=[2.0], base=8) + # The below will error, as there is no such parameter for LogLocator + # named foo + # loc.set_params(foo='bar') + +`ax.remove()` works as expected +``````````````````````````````` + +As with artists added to as `Axes`, `Axes` can be removed from their +figure via ``ax.remove()`` + + +Date Locators +````````````` + +Date Locators (derived from :class:`~matplotlib.dates.DateLocator`) now +implement the :meth:`~matplotlib.tickers.Locator.tick_values` method. +This is expected of all Locators derived from :class:`~matplotlib.tickers.Locator`. + +The Date Locators can now be used easily without creating axes :: + + from datetime import datetime + from matplotlib.dates import YearLocator + t0 = datetime(2002, 10, 9, 12, 10) + tf = datetime(2005, 10, 9, 12, 15) + loc = YearLocator() + values = loc.tick_values(t0, tf) + +Mostly unified linestyles for `Line2D`, `Patche` and `Collection` +````````````````````````````````````````````````````````````````` + +The handling of linestyles for Lines, Patches and Collections has been +unified. Now they all support defining linestyles with short symbols, +like `"--"`, as well as with full names, like ``"dashed"``. Also the +definition using a dash pattern (``(0., [3., 3.])``) is supported for all +methods using `Line2D`, `Patche` or ``Collection*``. + +OffsetBoxes now support clipping +```````````````````````````````` + +`Artists` draw onto objects of type :class:`~OffsetBox` +through :class:`~OffsetBox.DrawingArea` and :class:`~OffsetBox.TextArea`. +The `TextArea` calculates the required space for the text and so the +text is always within the bounds, for this nothing has changed. + +However, `DrawingArea` acts as a parent for zero or more `Artists` that +draw on it and may do so beyond the bounds. Now child `Artists` can be +clipped to the bounds of the `DrawingArea`. + + +OffsetBoxes now considered by tight_layout +`````````````````````````````````````````` + +When `pyplot.tight_layout()` or `Figure.tight_layout()` +or `GridSpec.tight_layout()` is called, `OffsetBoxes` that are +anchored outside the axes will not get chopped out. The `OffsetBoxes` will +also not get overlapped by other axes in case of multiple subplots. + +Per-page pdf notes in multi-page pdfs (PdfPages) +```````````````````````````````````````````````` + +Add a new method attach_note to the PdfPages class, allowing the +attachment of simple text notes to pages in a multi-page pdf of +figures. The new note is visible in the list of pdf annotations in a +viewer that has this facility (Adobe Reader, OSX Preview, Skim, +etc.). Per default the note itself is kept off-page to prevent it to +appear in print-outs. + +`PdfPages.attach_note` needs to be called before savefig in order to be +added to the correct figure. + +Updated fignum_exists to take figure name +````````````````````````````````````````` + +Added the ability to check the existence of a figure using it's name +instead of just the figure number. +Example:: + + figure('figure') + fignum_exists('figure') #true + + + +ToolManager +----------- + +Federico Ariza wrote the new `matplotlib.backend_managers.ToolManager` +that comes as replacement for `NavigationToolbar2` + +`ToolManager` offers a new way of looking at the user interactions +with the figures. Before we had the `NavigationToolbar2` with its own +tools like `zoom/pan/home/save/...` and also we had the shortcuts like +`yscale/grid/quit/....` `Toolmanager` relocate all those actions as +`Tools` (located in `matplotlib.backend_tools`), and defines a way to +`access/trigger/reconfigure` them. + +The `Toolbars` are replaced for `ToolContainers` that are just GUI +interfaces to `trigger` the tools. But don't worry the default +backends include a `ToolContainer` called `toolbar` + + +.. note:: + At the moment we release this primarily for feedback purposes and should + get treated as experimental until further notice as API changes will occur. + For the moment the `ToolManager` works only with the `GTK3` and `Tk` backends. + Make sure you use one of those. + Port for the rest of the backends is comming soon. + + To activate the `ToolManager` include the following at the top of your file :: + + >>> matplotlib.rcParams['toolbar'] = 'toolmanager' + + +Interact with the ToolContainer +``````````````````````````````` + +The most important feature is the ability to easily reconfigure the ToolContainer (aka toolbar). +For example, if we want to remove the "forward" button we would just do. :: + + >>> fig.canvas.manager.toolmanager.remove_tool('forward') + +Now if you want to programmatically trigger the "home" button :: + + >>> fig.canvas.manager.toolmanager.trigger_tool('home') + + +New Tools for ToolManager +````````````````````````` + +It is possible to add new tools to the ToolManager + +A very simple tool that prints "You're awesome" would be:: + + from matplotlib.backend_tools import ToolBase + class AwesomeTool(ToolBase): + def trigger(self, *args, **kwargs): + print("You're awesome") + + +To add this tool to `ToolManager` + + >>> fig.canvas.manager.toolmanager.add_tool('Awesome', AwesomeTool) + +If we want to add a shortcut ("d") for the tool + + >>> fig.canvas.manager.toolmanager.update_keymap('Awesome', 'd') + + +To add it to the toolbar inside the group 'foo' + + >>> fig.canvas.manager.toolbar.add_tool('Awesome', 'foo') + + +There is a second class of tools, "Toggleable Tools", this are almost +the same as our basic tools, just that belong to a group, and are +mutually exclusive inside that group. For tools derived from +`ToolToggleBase` there are two basic methods `enable` and `disable` +that are called automatically whenever it is toggled. + + +A full example is located in :ref:`user_interfaces-toolmanager` + +Styles +------ + +Several new styles have been added, including many styles from the +Seaborn project. Additionally, in order to prep for the upcoming 2.0 +style-change release, a 'classic' and 'default' style has been added. +For this release, the 'default' and 'classic' styles are identical. +By using them now in your scripts, you can help ensure a smooth +transition during future upgrades of matplotlib, so that you can +upgrade to the snazzy new defaults when you are ready! :: + + import matplotlib.style + matplotlib.style.use('classic') + +The 'default' style will give you matplotlib's latest plotting styles:: + + matplotlib.style.use('default') + + + +Configuration (rcParams) +------------------------ + + +Fixed labelpad in Axis3D +```````````````````````` + +Axis3D now looks at xaxis.labelpad (from rcParams or set by +``set_xlabel('X LABEL', labelpad=30)`` or ``ax.zaxis.labelpad=20)`` to +determine the position of axis labels in 3D plots. + +cbook.is_sequence_of_strings recognizes string objects +`````````````````````````````````````````````````````` + +This is primarily how pandas stores a sequence of strings :: + + import pandas as pd + import matplotlib.cbook as cbook + + a = np.array(['a', 'b', 'c']) + print(cbook.is_sequence_of_strings(a)) # True + + a = np.array(['a', 'b', 'c'], dtype=object) + print(cbook.is_sequence_of_strings(a)) # True + + s = pd.Series(['a', 'b', 'c']) + print(cbook.is_sequence_of_strings(s)) # True + +Previously, the last two prints returned false. + +Added ``errorbar.capsize`` key to rcParams +`````````````````````````````````````````` +Controls the length of end caps on error bars. If set to zero, errorbars +are turned off by default. + +Added ``xtick.minor.visible`` and ``ytick.minor.visible`` key to rcParams +````````````````````````````````````````````````````````````````````````` +Two new keys to control the minor ticks on x/y axis respectively, default set to ``False`` (no minor ticks on the axis). + +When ``True``, the minor ticks are shown and located via a ``mticker.AutoMinorLocator()``. + +Added "legend.framealpha" key to rcParams +````````````````````````````````````````` +Added a key and the corresponding logic to control the default transparency of +legend frames. This feature was written into the docstring of axes.legend(), +but not yet implemented. + +Added "figure.titlesize" and "figure.titleweight" keys to rcParams +`````````````````````````````````````````````````````````````````` + +Two new keys were added to rcParams to control the default font size +and weight used by the figure title (as emitted by +``pyplot.suptitle()``). + +Added ``legend.facecolor`` and ``legend.edgecolor`` keys to rcParams +```````````````````````````````````````````````````````````````````` + +The new keys control colors (background and edge) of legend patches. +The value ``'inherit'`` for these rcParams falls uses the value of +``axes.facecolor`` and ``axes.edgecolor``. + + +``image.composite_image`` added to rcParams +``````````````````````````````````````````` +Controls whether vector graphics backends (i.e. PDF, PS, and SVG) combine +multiple images on a set of axes into a single composite image. Saving each +image individually can be useful if you generate vector graphics files in +matplotlib and then edit the files further in Inkscape or other programs. + +Added ``markers.fillstyle`` key to rcParams +``````````````````````````````````````````` +Controls the default fillstyle of markers. Possible values are ``'full'`` (the +default), ``'left'``, ``'right'``, ``'bottom'``, ``'top'`` and ``'none'``. + +Added "toolmanager" to "toolbar" possible values +```````````````````````````````````````````````` + +The new value enables the use of ``ToolManager``. Note at the moment we +release this for feedback and should get treated as experimental until further +notice. + + +Added ``axes.labelpad`` +``````````````````````` + +This new value controls the space between the axis and the label + +Backends +-------- + New backend selection ---------------------- +````````````````````` The environment variable :envvar:`MPLBACKEND` can now be used to set the matplotlib backend. + +wx backend has been updated +``````````````````````````` + +The wx backend can now be used with both wxPython classic and +`Phoenix `__. + +wxPython classic has to be at least version 2.8.12 and works on Python 2.x. As +of May 2015 no official release of wxPython Phoenix is available but a +current snapshot will work on Python 2.7+ and 3.4+. + +If you have multiple versions of wxPython installed, then the user code is +responsible setting the wxPython version. How to do this is +explained in the comment at the beginning of the example +`examples\user_interfaces\embedding_in_wx2.py`. + + New ``close-figs`` argument for plot directive ---------------------------------------------- @@ -101,14 +754,13 @@ IPython's ``HTML`` display class:: Prefixed pkg-config for building -------------------------------- -Handling of `pkg-config` has been fixed in so far as it is now possible to set -it using the environment variable `PKG_CONFIG`. This is important if your -toolchain is prefixed. This is done in a simpilar way as setting `CC` or `CXX` -before building. An example follows. +Handling of `pkg-config` has been fixed in so far as it is now +possible to set it using the environment variable `PKG_CONFIG`. This +is important if your toolchain is prefixed. This is done in a simpilar +way as setting `CC` or `CXX` before building. An example follows. export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config - .. _whats-new-1-4: new in matplotlib-1.4 @@ -278,7 +930,7 @@ that the upper and lower limits (*lolims*, *uplims*, *xlolims*, More consistent add-object API for Axes ``````````````````````````````````````` -Added the Axes method :meth:`~matplotlib.axes.Axes.add_image` to put image +Added the Axes method `~matplotlib.axes.Axes.add_image` to put image handling on a par with artists, collections, containers, lines, patches, and tables. diff --git a/doc/users/whats_new/2014-12-23_usetex.rst b/doc/users/whats_new/2014-12-23_usetex.rst deleted file mode 100644 index ebc71e88670a..000000000000 --- a/doc/users/whats_new/2014-12-23_usetex.rst +++ /dev/null @@ -1,5 +0,0 @@ -Artist-level {get,set}_usetex for text --------------------------------------- - -Add ``{get,set}_usetex`` methods to `text.Text` objects which allow artist-level -control of LaTeX rendering vs the internal mathtex rendering. diff --git a/doc/users/whats_new/2015-01-19_cursor_pixel_data.rst b/doc/users/whats_new/2015-01-19_cursor_pixel_data.rst deleted file mode 100644 index 4490e9df35e4..000000000000 --- a/doc/users/whats_new/2015-01-19_cursor_pixel_data.rst +++ /dev/null @@ -1,6 +0,0 @@ -Allow Artists to Display Pixel Data in Cursor ---------------------------------------------- - -Adds `get_pixel_data` and `format_pixel_data` methods to artists -which can be used to add zdata to the cursor display -in the status bar. Also adds an implementation for Images. diff --git a/doc/users/whats_new/2015-03-03_locator-set_params.rst b/doc/users/whats_new/2015-03-03_locator-set_params.rst deleted file mode 100755 index baf53e527959..000000000000 --- a/doc/users/whats_new/2015-03-03_locator-set_params.rst +++ /dev/null @@ -1,16 +0,0 @@ -API Consistency fix within Locators set_params() function ---------------------------------------------------------- - -set_params() function, which sets parameters within a Locator type instance, -is now available to all Locator types. The implementation also prevents unsafe -usage by strictly defining the parameters that a user can set. - -To use, simply call ``set_params()`` on a Locator instance with desired arguments: -:: - - loc = matplotlib.ticker.LogLocator() - # Set given attributes for loc. - loc.set_params(numticks=8, numdecs=8, subs=[2.0], base=8) - # The below will error, as there is no such parameter for LogLocator - # named foo - # loc.set_params(foo='bar') diff --git a/doc/users/whats_new/2015-05_filledstep.rst b/doc/users/whats_new/2015-05_filledstep.rst deleted file mode 100644 index d9d0a3073b3a..000000000000 --- a/doc/users/whats_new/2015-05_filledstep.rst +++ /dev/null @@ -1,12 +0,0 @@ -Add step kwargs to fill_between -------------------------------- - -Added ``step`` kwarg to `Axes.fill_between` to allow to fill between -lines drawn using the 'step' draw style. The values of ``step`` match -those of the ``where`` kwarg of `Axes.step`. The asymmetry of of the -kwargs names is not ideal, but `Axes.fill_between` already has a -``where`` kwarg. - -This is particularly useful for plotting pre-binned histograms. - -.. plot:: mpl_examples/api/filled_step.py diff --git a/doc/users/whats_new/2015-05_interactive_OO.rst b/doc/users/whats_new/2015-05_interactive_OO.rst deleted file mode 100644 index 926a2edbfe2c..000000000000 --- a/doc/users/whats_new/2015-05_interactive_OO.rst +++ /dev/null @@ -1,38 +0,0 @@ -Interactive OO usage --------------------- - -All `Artists` now keep track of if their internal state has been -changed but not reflected in the display ('stale') by a call to -``draw``. It is thus possible to pragmatically determine if a given -`Figure` needs to be re-drawn in an interactive session. - -To facilitate interactive usage a ``draw_all`` method has been added -to ``pyplot`` which will redraw all of the figures which are 'stale'. - -To make this convenient for interactive use matplotlib now registers -a function either with IPython's 'post_execute' event or with the -displayhook in the standard python REPL to automatically call -``plt.draw_all`` just before control is returned to the REPL. This ensures -that the draw command is deferred and only called once. - -The upshot of this is that for interactive backends (including -``%matplotlib notebook``) in interactive mode (with ``plt.ion()``) - -.. ipython :: python - - import matplotlib.pyplot as plt - - fig, ax = plt.subplots() - - ln, = ax.plot([0, 1, 4, 9, 16]) - - plt.show() - - ln.set_color('g') - - -will automatically update the plot to be green. Any subsequent -modifications to the ``Artist`` objects will do likewise. - -This is the first step of a larger consolidation and simplification of -the pyplot internals. diff --git a/doc/users/whats_new/2015-07-23_axes_remove_method.rst b/doc/users/whats_new/2015-07-23_axes_remove_method.rst deleted file mode 100644 index 759445288048..000000000000 --- a/doc/users/whats_new/2015-07-23_axes_remove_method.rst +++ /dev/null @@ -1,5 +0,0 @@ -`ax.remove()` works as expected -------------------------------- - -As with artists added to as `Axes`, `Axes` can be -removed from their figure via ``ax.remove()`` diff --git a/doc/users/whats_new/2015-07-30_unpack_labeled_data.rst b/doc/users/whats_new/2015-07-30_unpack_labeled_data.rst deleted file mode 100644 index 04d5e5985563..000000000000 --- a/doc/users/whats_new/2015-07-30_unpack_labeled_data.rst +++ /dev/null @@ -1,36 +0,0 @@ -Working with labeled data like pandas DataFrames ------------------------------------------------- -Plot methods which take arrays as inputs can now also work with labeled data -and unpack such data. - -This means that the following two examples produce the same plot: - -Example :: - - df = pandas.DataFrame({"var1":[1,2,3,4,5,6], "var2":[1,2,3,4,5,6]}) - plt.plot(df["var1"], df["var2"]) - - -Example :: - - plt.plot("var1", "var2", data=df) - -This works for most plotting methods, which expect arrays/sequences as -inputs. ``data`` can be anything which supports ``__getitem__`` -(``dict``, ``pandas.DataFrame``, ``h5py``, ...) to access ``array`` like -values with string keys. - -In addition to this, some other changes were made, which makes working with -labeled data (ex ``pandas.Series``) easier: - -* For plotting methods with ``label`` keyword argument, one of the - data inputs is designated as the label source. If the user does not - supply a ``label`` that value object will be introspected for a - label, currently by looking for a ``name`` attribute. If the value - object does not have a ``name`` attribute but was specified by as a - key into the ``data`` kwarg, then the key is used. In the above - examples, this results in an implicit ``label="var2"`` for both - cases. - -* ``plot()`` now uses the index of a ``Series`` instead of - ``np.arange(len(y))``, if no ``x`` argument is supplied. diff --git a/doc/users/whats_new/autowrap_text.rst b/doc/users/whats_new/autowrap_text.rst deleted file mode 100644 index 649fb4e0fb7b..000000000000 --- a/doc/users/whats_new/autowrap_text.rst +++ /dev/null @@ -1,10 +0,0 @@ -Auto-wrapping Text ------------------- -Added the keyword argument "wrap" to Text, which automatically breaks long lines of text when being drawn. -Works for any rotated text, different modes of alignment, and for text that are either labels or titles. - -Example :: - - plt.text(1, 1, - "This is a really long string that should be wrapped so that " - "it does not go outside the figure.", wrap=True) diff --git a/doc/users/whats_new/axis3d.rst b/doc/users/whats_new/axis3d.rst deleted file mode 100644 index 6a6df37494bc..000000000000 --- a/doc/users/whats_new/axis3d.rst +++ /dev/null @@ -1,6 +0,0 @@ -Fixed labelpad in Axis3D -```````````````````````` - -Axis3D now looks at xaxis.labelpad (from rcParams or set by -``set_xlabel('X LABEL', labelpad=30)`` or ``ax.zaxis.labelpad=20)`` to -determine the position of axis labels in 3D plots. diff --git a/doc/users/whats_new/cbook.rst b/doc/users/whats_new/cbook.rst deleted file mode 100644 index e4e98139e436..000000000000 --- a/doc/users/whats_new/cbook.rst +++ /dev/null @@ -1,18 +0,0 @@ -cbook.is_sequence_of_strings recognizes string objects -`````````````````````````````````````````````````````` - -This is primarily how pandas stores a sequence of strings :: - - import pandas as pd - import matplotlib.cbook as cbook - - a = np.array(['a', 'b', 'c']) - print(cbook.is_sequence_of_strings(a)) # True - - a = np.array(['a', 'b', 'c'], dtype=object) - print(cbook.is_sequence_of_strings(a)) # True - - s = pd.Series(['a', 'b', 'c']) - print(cbook.is_sequence_of_strings(s)) # True - -Previously, the last two prints returned false. diff --git a/doc/users/whats_new/datelocators.rst b/doc/users/whats_new/datelocators.rst deleted file mode 100644 index bd143894f389..000000000000 --- a/doc/users/whats_new/datelocators.rst +++ /dev/null @@ -1,15 +0,0 @@ -Date Locators -------------- - -Date Locators (derived from :class:`~matplotlib.dates.DateLocator`) now -implement the :meth:`~matplotlib.tickers.Locator.tick_values` method. -This is expected of all Locators derived from :class:`~matplotlib.tickers.Locator`. - -The Date Locators can now be used easily without creating axes :: - - from datetime import datetime - from matplotlib.dates import YearLocator - t0 = datetime(2002, 10, 9, 12, 10) - tf = datetime(2005, 10, 9, 12, 15) - loc = YearLocator() - values = loc.tick_values(t0, tf) diff --git a/doc/users/whats_new/linestyles.rst b/doc/users/whats_new/linestyles.rst deleted file mode 100644 index e62f6b45d779..000000000000 --- a/doc/users/whats_new/linestyles.rst +++ /dev/null @@ -1,8 +0,0 @@ -Mostly unified linestyles for `Line2D`, `Patche` and `Collection` -````````````````````````````````````````````````````````````````` - -The handling of linestyles for Lines, Patches and Collections has been -unified. Now they all support defining linestyles with short symbols, -like `"--"`, as well as with full names, like ``"dashed"``. Also the -definition using a dash pattern (``(0., [3., 3.])``) is supported for all -methods using `Line2D`, `Patche` or ``Collection*``. diff --git a/doc/users/whats_new/offsetbox.rst b/doc/users/whats_new/offsetbox.rst deleted file mode 100644 index 23b958066176..000000000000 --- a/doc/users/whats_new/offsetbox.rst +++ /dev/null @@ -1,20 +0,0 @@ -OffsetBoxes now support clipping -```````````````````````````````` - -`Artists` draw onto objects of type :class:`~OffsetBox` -through :class:`~OffsetBox.DrawingArea` and :class:`~OffsetBox.TextArea`. -The `TextArea` calculates the required space for the text and so the -text is always within the bounds, for this nothing has changed. - -However, `DrawingArea` acts as a parent for zero or more `Artists` that -draw on it and may do so beyond the bounds. Now child `Artists` can be -clipped to the bounds of the `DrawingArea`. - - -OffsetBoxes now considered by tight_layout -`````````````````````````````````````````` - -When :method:`pyplot.tight_layout()` or :method:`Figure.tight_layout()` -or :method:`GridSpec.tight_layout()` is called, `OffsetBoxes` that are -anchored outside the axes will not get chopped out. The `OffsetBoxes` will -also not get overlapped by other axes in case of multiple subplots. diff --git a/doc/users/whats_new/pdfpages_notes.rst b/doc/users/whats_new/pdfpages_notes.rst deleted file mode 100644 index ba4ecab7d660..000000000000 --- a/doc/users/whats_new/pdfpages_notes.rst +++ /dev/null @@ -1,12 +0,0 @@ -Per-page pdf notes in multi-page pdfs (PdfPages) ------------------------------------------------- - -Add a new method attach_note to the PdfPages class, allowing the -attachment of simple text notes to pages in a multi-page pdf of -figures. The new note is visible in the list of pdf annotations in a -viewer that has this facility (Adobe Reader, OSX Preview, Skim, -etc.). Per default the note itself is kept off-page to prevent it to -appear in print-outs. - -`PdfPages.attach_note` needs to be called before savefig in order to be -added to the correct figure. diff --git a/doc/users/whats_new/plotting.rst b/doc/users/whats_new/plotting.rst deleted file mode 100644 index 1b7047f08ee3..000000000000 --- a/doc/users/whats_new/plotting.rst +++ /dev/null @@ -1,41 +0,0 @@ -Plot bar and barh with labels -````````````````````````````` - -Added kwarg ``"tick_label"`` to `bar` and `barh` to support plotting bar graphs with a -text label for each bar. - -Example: :: - - bar([1, 2], [1, 1], tick_label=['bar1', 'bar2']) - -Added center and frame kwargs to pie -```````````````````````````````````` - -These control where the center of the pie graph are and if -the Axes frame is shown. - -Contour plot corner masking -``````````````````````````` - -Ian Thomas rewrote the C++ code that calculates contours to add support for -corner masking. This is controlled by a new keyword argument -``corner_mask`` in the functions :func:`~matplotlib.pyplot.contour` and -:func:`~matplotlib.pyplot.contourf`. The previous behaviour, which is now -obtained using ``corner_mask=False``, was for a single masked point to -completely mask out all four quads touching that point. The new behaviour, -obtained using ``corner_mask=True``, only masks the corners of those -quads touching the point; any triangular corners comprising three unmasked -points are contoured as usual. If the ``corner_mask`` keyword argument is not -specified, the default value is taken from rcParams. - -.. plot:: mpl_examples/pylab_examples/contour_corner_mask.py - -Fixed 3D filled contour plot polygon rendering -`````````````````````````````````````````````` - -Certain cases of 3D filled contour plots that produce polygons with multiple -holes produced improper rendering due to a loss of path information between -:class:`~matplotlib.collections.PolyCollection` and -:class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`. A function -:func:`~matplotlib.collections.PolyCollection.set_verts_and_codes` was -added to allow path information to be retained for proper rendering. diff --git a/doc/users/whats_new/rasterized_colorbar.rst b/doc/users/whats_new/rasterized_colorbar.rst deleted file mode 100644 index 77360dd9e017..000000000000 --- a/doc/users/whats_new/rasterized_colorbar.rst +++ /dev/null @@ -1,10 +0,0 @@ -Dense colorbars are rasterized -`````````````````````````````` -Vector file formats (pdf, ps, svg) are efficient for -many types of plot element, but for some they can yield -excessive file size and even rendering artifacts, depending -on the renderer used for screen display. This is a problem -for colorbars that show a large number of shades, as is -most commonly the case. Now, if a colorbar is showing -50 or more colors, it will be rasterized in vector -backends. diff --git a/doc/users/whats_new/rcparams.rst b/doc/users/whats_new/rcparams.rst deleted file mode 100644 index d97620c86465..000000000000 --- a/doc/users/whats_new/rcparams.rst +++ /dev/null @@ -1,72 +0,0 @@ -Added ``axes.prop_cycle`` key to rcParams -````````````````````````````````````````` -This is a more generic form of the now-deprecated ``axes.color_cycle`` param. -Now, we can cycle more than just colors, but also linestyles, hatches, -and just about any other artist property. Cycler notation is used for -defining proprty cycles. Adding cyclers together will be like you are -`zip()`-ing together two or more property cycles together:: - - axes.prop_cycle: cycler('color', 'rgb') + cycler('lw', [1, 2, 3]) - -You can even multiply cyclers, which is like using `itertools.product()` -on two or more property cycles. Remember to use parentheses if writing -a multi-line `prop_cycle` parameter. - -..plot:: mpl_examples/color/color_cycle_demo.py - -Added ``errorbar.capsize`` key to rcParams -`````````````````````````````````````````` -Controls the length of end caps on error bars. If set to zero, errorbars -are turned off by default. - -Added ``xtick.minor.visible`` and ``ytick.minor.visible`` key to rcParams -````````````````````````````````````````````````````````````````````````` -Two new keys to control the minor ticks on x/y axis respectively, default set to ``False`` (no minor ticks on the axis). - -When ``True``, the minor ticks are shown and located via a ``mticker.AutoMinorLocator()``. - -Added "legend.framealpha" key to rcParams -````````````````````````````````````````` -Added a key and the corresponding logic to control the default transparency of -legend frames. This feature was written into the docstring of axes.legend(), -but not yet implemented. - -Added "figure.titlesize" and "figure.titleweight" keys to rcParams -`````````````````````````````````````````````````````````````````` - -Two new keys were added to rcParams to control the default font size -and weight used by the figure title (as emitted by -``pyplot.suptitle()``). - -Added ``legend.facecolor`` and ``legend.edgecolor`` keys to rcParams -``````````````````````````````````````````````````````````````````` - -The new keys control colors (background and edge) of legend patches. -The value ``'inherit'`` for these rcParams falls uses the value of -``axes.facecolor`` and ``axes.edgecolor``. - - -``image.composite_image`` added to rcParams -``````````````````````````````````````````` -Controls whether vector graphics backends (i.e. PDF, PS, and SVG) combine -multiple images on a set of axes into a single composite image. Saving each -image individually can be useful if you generate vector graphics files in -matplotlib and then edit the files further in Inkscape or other programs. - -Added ``markers.fillstyle`` key to rcParams -``````````````````````````````````````````` -Controls the default fillstyle of markers. Possible values are ``'full'`` (the -default), ``'left'``, ``'right'``, ``'bottom'``, ``'top'`` and ``'none'``. - -Added "toolmanager" to "toolbar" possible values -```````````````````````````````````````````````` - -The new value enables the use of ``ToolManager``. Note at the moment we -release this for feedback and should get treated as experimental until further -notice. - - -Added ``axes.labelpad`` -``````````````````````` - -This new value controls the space between the axis and the label diff --git a/doc/users/whats_new/square_plot_feature.rst b/doc/users/whats_new/square_plot_feature.rst deleted file mode 100644 index e3851e0189d3..000000000000 --- a/doc/users/whats_new/square_plot_feature.rst +++ /dev/null @@ -1,11 +0,0 @@ -Square Plot -------------------------- - -Square plot: - -Implemented square plots feature as a new parameter in the axis function. When argument 'square' is specified, equal scaling is set, and the limits are set such that xmax-xmin == ymax-ymin. - -Example: - -``ax.axis('square')`` - diff --git a/doc/users/whats_new/styles.rst b/doc/users/whats_new/styles.rst deleted file mode 100644 index 77e2974a7497..000000000000 --- a/doc/users/whats_new/styles.rst +++ /dev/null @@ -1,15 +0,0 @@ -Styles ------- - -Several new styles have been added, including many styles from the Seaborn project. -Additionally, in order to prep for the upcoming 2.0 style-change release, a 'classic' and 'default' style has been added. -For this release, the 'default' and 'classic' styles are identical. -By using them now in your scripts, you can help ensure a smooth transition during future upgrades of matplotlib, so that you can upgrade to the snazzy new defaults when you are ready! :: - - import matplotlib.style - matplotlib.style.use('classic') - -The 'default' style will give you matplotlib's latest plotting styles:: - - matplotlib.style.use('default') - diff --git a/doc/users/whats_new/toolmanager.rst b/doc/users/whats_new/toolmanager.rst deleted file mode 100644 index 27c6929eacac..000000000000 --- a/doc/users/whats_new/toolmanager.rst +++ /dev/null @@ -1,70 +0,0 @@ -ToolManager ------------ - -Federico Ariza wrote the new `matplotlib.backend_managers.ToolManager` that comes as replacement for `NavigationToolbar2` - -`ToolManager` offers a new way of looking at the user interactions with the figures. -Before we had the `NavigationToolbar2` with its own tools like `zoom/pan/home/save/...` and also we had the shortcuts like -`yscale/grid/quit/....` -`Toolmanager` relocate all those actions as `Tools` (located in `matplotlib.backend_tools`), and defines a way to `access/trigger/reconfigure` them. - -The `Toolbars` are replaced for `ToolContainers` that are just GUI interfaces to `trigger` the tools. But don't worry the default backends include a `ToolContainer` called `toolbar` - - -.. note:: - At the moment we release this primarily for feedback purposes and should - get treated as experimental until further notice as API changes will occur. - For the moment the `ToolManager` works only with the `GTK3` and `Tk` backends. - Make sure you use one of those. - Port for the rest of the backends is comming soon. - - To activate the `ToolManager` include the following at the top of your file: - - >>> matplotlib.rcParams['toolbar'] = 'toolmanager' - - -Interact with the ToolContainer -``````````````````````````````` - -The most important feature is the ability to easily reconfigure the ToolContainer (aka toolbar). -For example, if we want to remove the "forward" button we would just do. - - >>> fig.canvas.manager.toolmanager.remove_tool('forward') - -Now if you want to programmatically trigger the "home" button - - >>> fig.canvas.manager.toolmanager.trigger_tool('home') - - -New Tools -````````` - -It is possible to add new tools to the ToolManager - -A very simple tool that prints "You're awesome" would be:: - - from matplotlib.backend_tools import ToolBase - class AwesomeTool(ToolBase): - def trigger(self, *args, **kwargs): - print("You're awesome") - - -To add this tool to `ToolManager` - - >>> fig.canvas.manager.toolmanager.add_tool('Awesome', AwesomeTool) - -If we want to add a shortcut ("d") for the tool - - >>> fig.canvas.manager.toolmanager.update_keymap('Awesome', 'd') - - -To add it to the toolbar inside the group 'foo' - - >>> fig.canvas.manager.toolbar.add_tool('Awesome', 'foo') - - -There is a second class of tools, "Toggleable Tools", this are almost the same as our basic tools, just that belong to a group, and are mutually exclusive inside that group. -For tools derived from `ToolToggleBase` there are two basic methods `enable` and `disable` that are called automatically whenever it is toggled. - - -A full example is located in :ref:`user_interfaces-toolmanager` diff --git a/doc/users/whats_new/updated_backend_wx.rst b/doc/users/whats_new/updated_backend_wx.rst deleted file mode 100644 index cbfb7995f241..000000000000 --- a/doc/users/whats_new/updated_backend_wx.rst +++ /dev/null @@ -1,14 +0,0 @@ -wx backend has been updated ---------------------------- - -The wx backend can now be used with both wxPython classic and -`Phoenix `__. - -wxPython classic has to be at least version 2.8.12 and works on Python 2.x. As -of May 2015 no official release of wxPython Phoenix is available but a -current snapshot will work on Python 2.7+ and 3.4+. - -If you have multiple versions of wxPython installed, then the user code is -responsible setting the wxPython version. How to do this is -explained in the comment at the beginning of the example -`examples\user_interfaces\embedding_in_wx2.py`. diff --git a/doc/users/whats_new/updated_date_formatter.rst b/doc/users/whats_new/updated_date_formatter.rst deleted file mode 100644 index 8e99ef11d538..000000000000 --- a/doc/users/whats_new/updated_date_formatter.rst +++ /dev/null @@ -1,7 +0,0 @@ -DateFormatter strftime ----------------------- -Date formatters' (:class:`~matplotlib.dates.DateFormatter`) -:meth:`~matplotlib.dates.DateFormatter.strftime` method will format -a :class:`datetime.datetime` object with the format string passed to -the formatter's constructor. This method accepts datetimes with years -before 1900, unlike :meth:`datetime.datetime.strftime`. diff --git a/doc/users/whats_new/updated_figimage.rst b/doc/users/whats_new/updated_figimage.rst deleted file mode 100644 index 22fd6e79d9cf..000000000000 --- a/doc/users/whats_new/updated_figimage.rst +++ /dev/null @@ -1,10 +0,0 @@ -updated figimage to take optional resize parameter ----------------------------------------------------- - -Added the ability to plot simple 2D-Array using ``plt.figimage(X, resize=True)``. -This is useful for plotting simple 2D-Array without the Axes or whitespacing -around the image. -Example:: - - data = np.random.random( [500, 500] ) - plt.figimage(data, resize=True) diff --git a/doc/users/whats_new/updated_figure.rst b/doc/users/whats_new/updated_figure.rst deleted file mode 100644 index 16cb8686125c..000000000000 --- a/doc/users/whats_new/updated_figure.rst +++ /dev/null @@ -1,10 +0,0 @@ -Updated Figure.savefig() ------------------------- - -Added support to save the figure with the same dpi as the figure on the screen using dpi='figure' - -Example:: - - f = plt.figure(dpi=25) # dpi set to 25 - S = plt.scatter([1,2,3],[4,5,6]) - f.savefig('output.png', dpi='figure') # output savefig dpi set to 25 (same as figure) diff --git a/doc/users/whats_new/updated_pyplot.rst b/doc/users/whats_new/updated_pyplot.rst deleted file mode 100644 index daff292ef1e2..000000000000 --- a/doc/users/whats_new/updated_pyplot.rst +++ /dev/null @@ -1,9 +0,0 @@ -Updated fignum_exists to take figure name -------------------------------------------- - -Added the ability to check the existence of a figure using it's name -instead of just the figure number. -Example:: - - figure('figure') - fignum_exists('figure') #true diff --git a/doc/users/whats_new/updated_scale.rst b/doc/users/whats_new/updated_scale.rst deleted file mode 100644 index b8d86c4c9ad2..000000000000 --- a/doc/users/whats_new/updated_scale.rst +++ /dev/null @@ -1,10 +0,0 @@ -Logit Scale ------------ - -Added support for the 'logit' axis scale, a nonlinear transformation - -.. math:: - - x -> \log10(x / (1-x)) - -for data between 0 and 1 excluded. diff --git a/doc/users/whats_new/updated_table.rst b/doc/users/whats_new/updated_table.rst deleted file mode 100644 index bed0d5cd88d4..000000000000 --- a/doc/users/whats_new/updated_table.rst +++ /dev/null @@ -1,15 +0,0 @@ -Updated Table and to control edge visibility --------------------------------------------- - -Added the ability to toggle the visibility of lines in Tables. -Functionality added to the table() factory function under the keyword -argument "edges". Values can be the strings "open", "closed", -"horizontal", "vertical" or combinations of the letters "L", "R", "T", -"B" which represent left, right, top, and bottom respectively. - -Example:: - - table(..., edges="open") # No line visible - table(..., edges="closed") # All lines visible - table(..., edges="horizontal") # Only top and bottom lines visible - table(..., edges="LT") # Only left and top lines visible. diff --git a/doc/users/whats_new/updated_widgets.rst b/doc/users/whats_new/updated_widgets.rst deleted file mode 100644 index 67db7fb744e0..000000000000 --- a/doc/users/whats_new/updated_widgets.rst +++ /dev/null @@ -1,26 +0,0 @@ -Moved ``ignore``, ``set_active``, and ``get_active`` methods to base class ``Widget`` -````````````````````````````````````````````````````````````````````````````````````` - -Pushes up duplicate methods in child class to parent class to avoid duplication of code. - - -Adds enable/disable feature to MultiCursor -`````````````````````````````````````````` - -A MultiCursor object can be disabled (and enabled) after it has been created without destroying the object. -Example:: - - multi_cursor.active = False - - -Improved RectangleSelector and new EllipseSelector Widget -````````````````````````````````````````````````````````` - -Adds an `interactive` keyword which enables visible handles for manipulating the shape after it has been drawn. - -Adds keyboard modifiers for: - -- Moving the existing shape (default key = 'space') -- Making the shape square (default 'shift') -- Make the initial point the center of the shape (default 'control') -- Square and center can be combined diff --git a/doc/users/whats_new/wireframe3d.rst b/doc/users/whats_new/wireframe3d.rst deleted file mode 100644 index d7bfe31a5391..000000000000 --- a/doc/users/whats_new/wireframe3d.rst +++ /dev/null @@ -1,14 +0,0 @@ -Zero r/cstride support in plot_wireframe ----------------------------------------- - -Adam Hughes added support to mplot3d's plot_wireframe to draw only row or -column line plots. - - -Example:: - - from mpl_toolkits.mplot3d import Axes3D, axes3d - fig = plt.figure() - ax = fig.add_subplot(111, projection='3d') - X, Y, Z = axes3d.get_test_data(0.05) - ax.plot_wireframe(X, Y, Z, rstride=10, cstride=0) diff --git a/examples/api/filled_step.py b/examples/api/filled_step.py index 1c31dea72b88..42d61dc91766 100644 --- a/examples/api/filled_step.py +++ b/examples/api/filled_step.py @@ -3,6 +3,7 @@ import numpy as np import matplotlib.pyplot as plt +import matplotlib.ticker as mticker from cycler import cycler from six.moves import zip @@ -146,7 +147,7 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None, arts = {} for j, (data, label, sty) in loop_iter: if label is None: - label = 'default set {n}'.format(n=j) + label = 'dflt set {n}'.format(n=j) label = sty.pop('label', label) vals, edges = hist_func(data) if bottoms is None: @@ -159,7 +160,7 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None, label=label, **sty) bottoms = top arts[label] = ret - ax.legend() + ax.legend(fontsize=10) return arts @@ -178,7 +179,7 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None, stack_data)} # work with plain arrays -fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 6), tight_layout=True) +fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4.5), tight_layout=True) arts = stack_hist(ax1, stack_data, color_cycle + label_cycle + hatch_cycle, hist_func=hist_func) @@ -192,7 +193,7 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None, # work with labeled data -fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 6), +fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4.5), tight_layout=True, sharey=True) arts = stack_hist(ax1, dict_data, color_cycle + hatch_cycle, @@ -200,7 +201,7 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None, arts = stack_hist(ax2, dict_data, color_cycle + hatch_cycle, hist_func=hist_func, labels=['set 0', 'set 3']) - -ax1.set_ylabel('counts') -ax1.set_xlabel('x') -ax2.set_xlabel('x') +ax1.xaxis.set_major_locator(mticker.MaxNLocator(5)) +ax1.set_xlabel('counts') +ax1.set_ylabel('x') +ax2.set_ylabel('x')