1 2============= 3 API Changes 4============= 5 6Log of changes to Matplotlib that affect the outward-facing API. If 7updating Matplotlib breaks your scripts, this list may help you figure 8out what caused the breakage and how to fix it by updating your code. 9 10For new features that were added to Matplotlib, please see 11:ref:`whats-new`. 12 13.. for a release comment out the toctree below 14 15 16 .. toctree:: 17 :glob: 18 :maxdepth: 1 19 20 next_api_changes/* 21 22 23API Changes in 2.2.0 24==================== 25 26 27 28New dependency 29-------------- 30 31`kiwisolver <https://github.com/nucleic/kiwi>`__ is now a required 32dependency to support the new constrained_layout, see 33:doc:`/tutorials/intermediate/constrainedlayout_guide` for 34more details. 35 36 37Deprecations 38------------ 39 40Classes, functions, and methods 41~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42 43The unused and untested ``Artist.onRemove`` and ``Artist.hitlist`` methods have 44been deprecated. 45 46The now unused ``mlab.less_simple_linear_interpolation`` function is 47deprecated. 48 49The unused ``ContourLabeler.get_real_label_width`` method is deprecated. 50 51The unused ``FigureManagerBase.show_popup`` method is deprecated. This 52introduced in e945059b327d42a99938b939a1be867fa023e7ba in 2005 but never built 53out into any of the backends. 54 55:class:`backend_tkagg.AxisMenu` is deprecated, as it has become 56unused since the removal of "classic" toolbars. 57 58 59Changed function signatures 60~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 62kwarg ``fig`` to `.GridSpec.get_subplot_params` is 63deprecated, use ``figure`` instead. 64 65Using `.pyplot.axes` with an `~matplotlib.axes.Axes` as argument is deprecated. This sets 66the current axes, i.e. it has the same effect as `.pyplot.sca`. For clarity 67``plt.sca(ax)`` should be preferred over ``plt.axes(ax)``. 68 69 70Using strings instead of booleans to control grid and tick visibility 71is deprecated. Using ``"on"``, ``"off"``, ``"true"``, or ``"false"`` 72to control grid and tick visibility has been deprecated. Instead, use 73normal booleans (``True``/``False``) or boolean-likes. In the future, 74all non-empty strings may be interpreted as ``True``. 75 76When given 2D inputs with non-matching numbers of columns, `~.pyplot.plot` 77currently cycles through the columns of the narrower input, until all the 78columns of the wider input have been plotted. This behavior is deprecated; in 79the future, only broadcasting (1 column to *n* columns) will be performed. 80 81 82rcparams 83~~~~~~~~ 84 85The :rc:`backend.qt4` and :rc:`backend.qt5` rcParams were deprecated 86in version 2.2. In order to force the use of a specific Qt binding, 87either import that binding first, or set the ``QT_API`` environment 88variable. 89 90Deprecation of the ``nbagg.transparent`` rcParam. To control 91transparency of figure patches in the nbagg (or any other) backend, 92directly set ``figure.patch.facecolor``, or the ``figure.facecolor`` 93rcParam. 94 95Deprecated `Axis.unit_data` 96~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 98Use `Axis.units` (which has long existed) instead. 99 100 101Removals 102-------- 103 104Function Signatures 105~~~~~~~~~~~~~~~~~~~ 106 107Contouring no longer supports ``legacy`` corner masking. The 108deprecated ``ContourSet.vmin`` and ``ContourSet.vmax`` properties have 109been removed. 110 111Passing ``None`` instead of ``"none"`` as format to `~.Axes.errorbar` is no 112longer supported. 113 114The ``bgcolor`` keyword argument to ``Axes`` has been removed. 115 116Modules, methods, and functions 117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119The ``matplotlib.finance``, ``mpl_toolkits.exceltools`` and 120``mpl_toolkits.gtktools`` modules have been removed. ``matplotlib.finance`` 121remains available at https://github.com/matplotlib/mpl_finance. 122 123The ``mpl_toolkits.mplot3d.art3d.iscolor`` function has been removed. 124 125The ``Axes.get_axis_bgcolor``, ``Axes.set_axis_bgcolor``, 126``Bbox.update_from_data``, ``Bbox.update_datalim_numerix``, 127``MaxNLocator.bin_boundaries`` methods have been removed. 128 129``mencoder`` can no longer be used to encode animations. 130 131The unused `FONT_SCALE` and `fontd` attributes of the `RendererSVG` 132class have been removed. 133 134color maps 135~~~~~~~~~~ 136 137The ``spectral`` colormap has been removed. The ``Vega*`` colormaps, which 138were aliases for the ``tab*`` colormaps, have been removed. 139 140 141rcparams 142~~~~~~~~ 143 144The following deprecated rcParams have been removed: 145 146- ``axes.color_cycle`` (see ``axes.prop_cycle``), 147- ``legend.isaxes``, 148- ``svg.embed_char_paths`` (see ``svg.fonttype``), 149- ``text.fontstyle``, ``text.fontangle``, ``text.fontvariant``, 150 ``text.fontweight``, ``text.fontsize`` (renamed to ``text.style``, etc.), 151- ``tick.size`` (renamed to ``tick.major.size``). 152 153 154 155Only accept string-like for Categorical input 156--------------------------------------------- 157 158Do not accept mixed string / float / int input, only 159strings are valid categoricals. 160 161Removal of unused imports 162------------------------- 163Many unused imports were removed from the codebase. As a result, 164trying to import certain classes or functions from the "wrong" module 165(e.g. `~.Figure` from :mod:`matplotlib.backends.backend_agg` instead of 166:mod:`matplotlib.figure`) will now raise an `ImportError`. 167 168 169``Axes3D.get_xlim``, ``get_ylim`` and ``get_zlim`` now return a tuple 170--------------------------------------------------------------------- 171 172They previously returned an array. Returning a tuple is consistent with the 173behavior for 2D axes. 174 175 176Exception type changes 177---------------------- 178 179If `MovieWriterRegistry` can't find the requested `MovieWriter`, a 180more helpful `RuntimeError` message is now raised instead of the 181previously raised `KeyError`. 182 183`~.tight_layout.auto_adjust_subplotpars` now raises `ValueError` 184instead of `RuntimeError` when sizes of input lists don't match 185 186 187`Figure.set_figwidth` and `Figure.set_figheight` default forward to True 188------------------------------------------------------------------------ 189 190`matplotlib.Figure.set_figwidth` and `matplotlib.Figure.set_figheight` 191had the kwarg `forward=False` 192by default, but `Figure.set_size_inches` now defaults to `forward=True`. 193This makes these functions conistent. 194 195 196Do not truncate svg sizes to nearest point 197------------------------------------------ 198 199There is no reason to size the SVG out put in integer points, change 200to out putting floats for the *height*, *width*, and *viewBox* attributes 201of the *svg* element. 202 203 204Fontsizes less than 1 pt are clipped to be 1 pt. 205------------------------------------------------ 206 207FreeType doesn't allow fonts to get smaller than 1 pt, so all Agg 208backends were silently rounding up to 1 pt. PDF (other vector 209backends?) were letting us write fonts that were less than 1 pt, but 210they could not be placed properly because position information comes from 211FreeType. This change makes it so no backends can use fonts smaller than 2121 pt, consistent with FreeType and ensuring more consistent results across 213backends. 214 215 216 217Changes to Qt backend class MRO 218------------------------------- 219 220To support both Agg and cairo rendering for Qt backends all of the 221non-Agg specific code previously in 222:class:`.backend_qt5agg.FigureCanvasQTAggBase` has been moved to 223:class:`.backend_qt5.FigureCanvasQT` so it can be shared with the cairo 224implementation. The :meth:`.FigureCanvasQTAggBase.paintEvent`, 225:meth:`.FigureCanvasQTAggBase.blit`, and 226:meth:`.FigureCanvasQTAggBase.print_figure` methods have moved to 227:meth:`.FigureCanvasQTAgg.paintEvent`, :meth:`.FigureCanvasQTAgg.blit`, and 228:meth:`.FigureCanvasQTAgg.print_figure`. The first two methods assume that 229the instance is also a :class:`QWidget` so to use 230:class:`FigureCanvasQTAggBase` it was required to multiple inherit 231from a :class:`QWidget` sub-class. 232 233Having moved all of its methods either up or down the class hierarchy 234:class:`FigureCanvasQTAggBase` has been deprecated. To do this with 235out warning and to preserve as much API as possible, 236:class:`.backend_qt5.FigureCanvasQTAggBase` now inherits from 237:class:`.backend_qt5.FigureCanvasQTAgg`. 238 239The MRO for :class:`FigureCanvasQTAgg` and 240:class:`FigureCanvasQTAggBase` used to be :: 241 242 243 [matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg, 244 matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase, 245 matplotlib.backends.backend_agg.FigureCanvasAgg, 246 matplotlib.backends.backend_qt5.FigureCanvasQT, 247 PyQt5.QtWidgets.QWidget, 248 PyQt5.QtCore.QObject, 249 sip.wrapper, 250 PyQt5.QtGui.QPaintDevice, 251 sip.simplewrapper, 252 matplotlib.backend_bases.FigureCanvasBase, 253 object] 254 255and :: 256 257 258 [matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase, 259 matplotlib.backends.backend_agg.FigureCanvasAgg, 260 matplotlib.backend_bases.FigureCanvasBase, 261 object] 262 263 264respectively. They are now :: 265 266 [matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg, 267 matplotlib.backends.backend_agg.FigureCanvasAgg, 268 matplotlib.backends.backend_qt5.FigureCanvasQT, 269 PyQt5.QtWidgets.QWidget, 270 PyQt5.QtCore.QObject, 271 sip.wrapper, 272 PyQt5.QtGui.QPaintDevice, 273 sip.simplewrapper, 274 matplotlib.backend_bases.FigureCanvasBase, 275 object] 276 277and :: 278 279 [matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase, 280 matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg, 281 matplotlib.backends.backend_agg.FigureCanvasAgg, 282 matplotlib.backends.backend_qt5.FigureCanvasQT, 283 PyQt5.QtWidgets.QWidget, 284 PyQt5.QtCore.QObject, 285 sip.wrapper, 286 PyQt5.QtGui.QPaintDevice, 287 sip.simplewrapper, 288 matplotlib.backend_bases.FigureCanvasBase, 289 object] 290 291 292 293 294`Axes.imshow` clips RGB values to the valid range 295------------------------------------------------- 296 297When `Axes.imshow` is passed an RGB or RGBA value with out-of-range 298values, it now logs a warning and clips them to the valid range. 299The old behaviour, wrapping back in to the range, often hid outliers 300and made interpreting RGB images unreliable. 301 302 303GTKAgg and GTKCairo backends deprecated 304--------------------------------------- 305 306The GTKAgg and GTKCairo backends have been deprecated. These obsolete backends 307allow figures to be rendered via the GTK+ 2 toolkit. They are untested, known 308to be broken, will not work with Python 3, and their use has been discouraged 309for some time. Instead, use the `GTK3Agg` and `GTK3Cairo` backends for 310rendering to GTK+ 3 windows. 311 312 313 314API Changes in 2.1.2 315==================== 316 317`Figure.legend` no longer checks for repeated lines to ignore 318------------------------------------------------------------- 319 320`matplotlib.Figure.legend` used to check if a line had the 321same label as an existing legend entry. If it also had the same line color 322or marker color legend didn't add a new entry for that line. However, the 323list of conditions was incomplete, didn't handle RGB tuples, 324didn't handle linewidths or linestyles etc. 325 326This logic did not exist in `Axes.legend`. It was included (erroneously) 327in Matplotlib 2.1.1 when the legend argument parsing was unified 328[#9324](https://github.com/matplotlib/matplotlib/pull/9324). This change 329removes that check in `Axes.legend` again to restore the old behavior. 330 331This logic has also been dropped from `.Figure.legend`, where it 332was previously undocumented. Repeated 333lines with the same label will now each have an entry in the legend. If 334you do not want the duplicate entries, don't add a label to the line, or 335prepend the label with an underscore. 336 337API Changes in 2.1.1 338==================== 339 340Default behavior of log scales reverted to clip <= 0 values 341----------------------------------------------------------- 342 343The change it 2.1.0 to mask in logscale by default had more disruptive 344changes than anticipated and has been reverted, however the clipping is now 345done in a way that fixes the issues that motivated changing the default behavior 346to ``'mask'``. 347 348As a side effect of this change, error bars which go negative now work as expected 349on log scales. 350 351API Changes in 2.1.0 352==================== 353 354 355Default behavior of log scales changed to mask <= 0 values 356---------------------------------------------------------- 357 358Calling `matplotlib.axes.Axes.set_xscale` or `matplotlib.axes.Axes.set_yscale` 359now uses 'mask' as the default method to handle invalid values (as opposed to 360'clip'). This means that any values <= 0 on a log scale will not be shown. 361 362Previously they were clipped to a very small number and shown. 363 364 365:meth:`matplotlib.cbook.CallbackRegistry.process` suppresses exceptions by default 366---------------------------------------------------------------------------------- 367 368Matplotlib uses instances of :obj:`~matplotlib.cbook.CallbackRegistry` 369as a bridge between user input event from the GUI and user callbacks. 370Previously, any exceptions raised in a user call back would bubble out 371of of the ``process`` method, which is typically in the GUI event 372loop. Most GUI frameworks simple print the traceback to the screen 373and continue as there is not always a clear method of getting the 374exception back to the user. However PyQt5 now exits the process when 375it receives an un-handled python exception in the event loop. Thus, 376:meth:`~matplotlib.cbook.CallbackRegistry.process` now suppresses and 377prints tracebacks to stderr by default. 378 379What :meth:`~matplotlib.cbook.CallbackRegistry.process` does with exceptions 380is now user configurable via the ``exception_handler`` attribute and kwarg. To 381restore the previous behavior pass ``None`` :: 382 383 cb = CallbackRegistry(exception_handler=None) 384 385 386A function which take and ``Exception`` as its only argument may also be passed :: 387 388 def maybe_reraise(exc): 389 if isinstance(exc, RuntimeError): 390 pass 391 else: 392 raise exc 393 394 cb = CallbackRegistry(exception_handler=maybe_reraise) 395 396 397 398Improved toggling of the axes grids 399----------------------------------- 400 401The `g` key binding now switches the states of the `x` and `y` grids 402independently (by cycling through all four on/off combinations). 403 404The new `G` key binding switches the states of the minor grids. 405 406Both bindings are disabled if only a subset of the grid lines (in either 407direction) is visible, to avoid making irreversible changes to the figure. 408 409 410Ticklabels are turned off instead of being invisible 411---------------------------------------------------- 412 413Internally, the `Tick`'s :func:`~matplotlib.axis.Tick.label1On` attribute 414is now used to hide tick labels instead of setting the visibility on the tick 415label objects. 416This improves overall performance and fixes some issues. 417As a consequence, in case those labels ought to be shown, 418:func:`~matplotlib.axes.Axes.tick_params` 419needs to be used, e.g. 420 421:: 422 423 ax.tick_params(labelbottom=True) 424 425 426Removal of warning on empty legends 427----------------------------------- 428 429``plt.legend`` used to issue a warning when no labeled artist could be 430found. This warning has been removed. 431 432 433More accurate legend autopositioning 434------------------------------------ 435 436Automatic positioning of legends now prefers using the area surrounded 437by a `Line2D` rather than placing the legend over the line itself. 438 439 440Cleanup of stock sample data 441---------------------------- 442 443The sample data of stocks has been cleaned up to remove redundancies and 444increase portability. The ``AAPL.dat.gz``, ``INTC.dat.gz`` and ``aapl.csv`` 445files have been removed entirely and will also no longer be available from 446`matplotlib.cbook.get_sample_data`. If a CSV file is required, we suggest using 447the ``msft.csv`` that continues to be shipped in the sample data. If a NumPy 448binary file is acceptable, we suggest using one of the following two new files. 449The ``aapl.npy.gz`` and ``goog.npy`` files have been replaced by ``aapl.npz`` 450and ``goog.npz``, wherein the first column's type has changed from 451`datetime.date` to `np.datetime64` for better portability across Python 452versions. Note that Matplotlib does not fully support `np.datetime64` as yet. 453 454 455Updated qhull to 2015.2 456----------------------- 457 458The version of qhull shipped with Matplotlib, which is used for 459Delaunay triangulation, has been updated from version 2012.1 to 4602015.2. 461 462Improved Delaunay triangulations with large offsets 463--------------------------------------------------- 464 465Delaunay triangulations now deal with large x,y offsets in a better 466way. This can cause minor changes to any triangulations calculated 467using Matplotlib, i.e. any use of `matplotlib.tri.Triangulation` that 468requests that a Delaunay triangulation is calculated, which includes 469`matplotlib.pyplot.tricontour`, `matplotlib.pyplot.tricontourf`, 470`matplotlib.pyplot.tripcolor`, `matplotlib.pyplot.triplot`, 471`matplotlib.mlab.griddata` and 472`mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf`. 473 474 475 476Use ``backports.functools_lru_cache`` instead of ``functools32`` 477---------------------------------------------------------------- 478 479It's better maintained and more widely used (by pylint, jaraco, etc). 480 481 482 483``cbook.is_numlike`` only performs an instance check 484---------------------------------------------------- 485 486:func:`~matplotlib.cbook.is_numlike` now only checks that its argument 487is an instance of ``(numbers.Number, np.Number)``. In particular, 488this means that arrays are now not num-like. 489 490 491 492Elliptical arcs now drawn between correct angles 493------------------------------------------------ 494 495The `matplotlib.patches.Arc` patch is now correctly drawn between the given 496angles. 497 498Previously a circular arc was drawn and then stretched into an ellipse, 499so the resulting arc did not lie between *theta1* and *theta2*. 500 501 502 503``-d$backend`` no longer sets the backend 504----------------------------------------- 505 506It is no longer possible to set the backend by passing ``-d$backend`` 507at the command line. Use the ``MPLBACKEND`` environment variable 508instead. 509 510 511Path.intersects_bbox always treats the bounding box as filled 512------------------------------------------------------------- 513 514Previously, when ``Path.intersects_bbox`` was called with ``filled`` set to 515``False``, it would treat both the path and the bounding box as unfilled. This 516behavior was not well documented and it is usually not the desired behavior, 517since bounding boxes are used to represent more complex shapes located inside 518the bounding box. This behavior has now been changed: when ``filled`` is 519``False``, the path will be treated as unfilled, but the bounding box is still 520treated as filled. The old behavior was arguably an implementation bug. 521 522When ``Path.intersects_bbox`` is called with ``filled`` set to ``True`` 523(the default value), there is no change in behavior. For those rare cases where 524``Path.intersects_bbox`` was called with ``filled`` set to ``False`` and where 525the old behavior is actually desired, the suggested workaround is to call 526``Path.intersects_path`` with a rectangle as the path:: 527 528 from matplotlib.path import Path 529 from matplotlib.transforms import Bbox, BboxTransformTo 530 rect = Path.unit_rectangle().transformed(BboxTransformTo(bbox)) 531 result = path.intersects_path(rect, filled=False) 532 533 534 535 536WX no longer calls generates ``IdleEvent`` events or calls ``idle_event`` 537------------------------------------------------------------------------- 538 539Removed unused private method ``_onIdle`` from ``FigureCanvasWx``. 540 541The ``IdleEvent`` class and ``FigureCanvasBase.idle_event`` method 542will be removed in 2.2 543 544 545 546Correct scaling of :func:`magnitude_spectrum()` 547----------------------------------------------- 548 549The functions :func:`matplotlib.mlab.magnitude_spectrum()` and :func:`matplotlib.pyplot.magnitude_spectrum()` implicitly assumed the sum 550of windowing function values to be one. In Matplotlib and Numpy the 551standard windowing functions are scaled to have maximum value of one, 552which usually results in a sum of the order of n/2 for a n-point 553signal. Thus the amplitude scaling :func:`magnitude_spectrum()` was 554off by that amount when using standard windowing functions (`Bug 8417 555<https://github.com/matplotlib/matplotlib/issues/8417>`_ ). Now the 556behavior is consistent with :func:`matplotlib.pyplot.psd()` and 557:func:`scipy.signal.welch()`. The following example demonstrates the 558new and old scaling:: 559 560 import matplotlib.pyplot as plt 561 import numpy as np 562 563 tau, n = 10, 1024 # 10 second signal with 1024 points 564 T = tau/n # sampling interval 565 t = np.arange(n)*T 566 567 a = 4 # amplitude 568 x = a*np.sin(40*np.pi*t) # 20 Hz sine with amplitude a 569 570 # New correct behavior: Amplitude at 20 Hz is a/2 571 plt.magnitude_spectrum(x, Fs=1/T, sides='onesided', scale='linear') 572 573 # Original behavior: Amplitude at 20 Hz is (a/2)*(n/2) for a Hanning window 574 w = np.hanning(n) # default window is a Hanning window 575 plt.magnitude_spectrum(x*np.sum(w), Fs=1/T, sides='onesided', scale='linear') 576 577 578 579 580 581Change to signatures of :meth:`~matplotlib.axes.Axes.bar` & :meth:`~matplotlib.axes.Axes.barh` 582---------------------------------------------------------------------------------------------- 583 584For 2.0 the :ref:`default value of *align* <barbarh_align>` changed to 585``'center'``. However this caused the signature of 586:meth:`~matplotlib.axes.Axes.bar` and 587:meth:`~matplotlib.axes.Axes.barh` to be misleading as the first parameters were 588still *left* and *bottom* respectively:: 589 590 bar(left, height, *, align='center', **kwargs) 591 barh(bottom, width, *, align='center', **kwargs) 592 593despite behaving as the center in both cases. The methods now take 594``*args, **kwargs`` as input and are documented to have the primary 595signatures of:: 596 597 bar(x, height, *, align='center', **kwargs) 598 barh(y, width, *, align='center', **kwargs) 599 600Passing *left* and *bottom* as keyword arguments to 601:meth:`~matplotlib.axes.Axes.bar` and 602:meth:`~matplotlib.axes.Axes.barh` respectively will warn. 603Support will be removed in Matplotlib 3.0. 604 605 606Font cache as json 607------------------ 608 609The font cache is now saved as json, rather than a pickle. 610 611 612Invalid (Non-finite) Axis Limit Error 613------------------------------------- 614 615When using :func:`~matplotlib.axes.Axes.set_xlim` and 616:func:`~matplotlib.axes.Axes.set_ylim`, passing non-finite values now 617results in a ``ValueError``. The previous behavior resulted in the 618limits being erroneously reset to ``(-0.001, 0.001)``. 619 620``scatter`` and ``Collection`` offsets are no longer implicitly flattened 621------------------------------------------------------------------------- 622 623`~matplotlib.collections.Collection` (and thus both 2D 624`~matplotlib.axes.Axes.scatter` and 3D 625`~mpl_toolkits.mplot3d.axes3d.Axes3D.scatter`) no 626longer implicitly flattens its offsets. As a consequence, ``scatter``'s ``x`` 627and ``y`` arguments can no longer be 2+-dimensional arrays. 628 629Deprecations 630------------ 631 632``GraphicsContextBase``\'s ``linestyle`` property. 633~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 634 635The ``GraphicsContextBase.get_linestyle`` and 636``GraphicsContextBase.set_linestyle`` methods, which had no effect, 637have been deprecated. All of the backends Matplotlib ships use 638``GraphicsContextBase.get_dashes`` and 639``GraphicsContextBase.set_dashes`` which are more general. 640Third-party backends should also migrate to the ``*_dashes`` methods. 641 642 643``NavigationToolbar2.dynamic_update`` 644~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 645 646Use :meth:`draw_idle` method on the ``Canvas`` instance instead. 647 648 649Testing 650~~~~~~~ 651 652`matplotlib.testing.noseclasses` is deprecated and will be removed in 2.3 653 654 655``EngFormatter`` *num* arg as string 656~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 657 658Passing a string as *num* argument when calling an instance of 659`matplotlib.ticker.EngFormatter` is deprecated and will be removed in 2.3. 660 661 662``mpl_toolkits.axes_grid`` module 663~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 664 665All functionally from `mpl_toolkits.axes_grid` can be found in either 666`mpl_toolkits.axes_grid1` or `mpl_toolkits.axisartist`. Axes classes 667from `mpl_toolkits.axes_grid` based on `Axis` from 668`mpl_toolkits.axisartist` can be found in `mpl_toolkits.axisartist`. 669 670 671``Axes`` collision in ``Figure.add_axes`` 672~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 673 674Adding an axes instance to a figure by using the same arguments as for 675a previous axes instance currently reuses the earlier instance. This 676behavior has been deprecated in Matplotlib 2.1. In a future version, a 677*new* instance will always be created and returned. Meanwhile, in such 678a situation, a deprecation warning is raised by 679:class:`~matplotlib.figure.AxesStack`. 680 681This warning can be suppressed, and the future behavior ensured, by passing 682a *unique* label to each axes instance. See the docstring of 683:meth:`~matplotlib.figure.Figure.add_axes` for more information. 684 685Additional details on the rationale behind this deprecation can be found 686in :ghissue:`7377` and :ghissue:`9024`. 687 688 689Former validators for ``contour.negative_linestyle`` 690~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 691 692 693The former public validation functions ``validate_negative_linestyle`` 694and ``validate_negative_linestyle_legacy`` will be deprecated in 2.1 and 695may be removed in 2.3. There are no public functions to replace them. 696 697 698 699``cbook`` 700~~~~~~~~~ 701 702Many unused or near-unused :mod:`matplotlib.cbook` functions and 703classes have been deprecated: ``converter``, ``tostr``, 704``todatetime``, ``todate``, ``tofloat``, ``toint``, ``unique``, 705``is_string_like``, ``is_sequence_of_strings``, ``is_scalar``, 706``Sorter``, ``Xlator``, ``soundex``, ``Null``, ``dict_delall``, 707``RingBuffer``, ``get_split_ind``, ``wrap``, 708``get_recursive_filelist``, ``pieces``, ``exception_to_str``, 709``allequal``, ``alltrue``, ``onetrue``, ``allpairs``, ``finddir``, 710``reverse_dict``, ``restrict_dict``, ``issubclass_safe``, 711``recursive_remove``, ``unmasked_index_ranges``. 712 713 714Code Removal 715------------ 716 717qt4_compat.py 718~~~~~~~~~~~~~ 719 720Moved to ``qt_compat.py``. Renamed because it now handles Qt5 as well. 721 722 723Previously Deprecated methods 724~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 725 726The ``GraphicsContextBase.set_graylevel``, ``FigureCanvasBase.onHilite`` and 727``mpl_toolkits.axes_grid1.mpl_axes.Axes.toggle_axisline`` methods have been 728removed. 729 730The ``ArtistInspector.findobj`` method, which was never working due to the lack 731of a ``get_children`` method, has been removed. 732 733The deprecated ``point_in_path``, ``get_path_extents``, 734``point_in_path_collection``, ``path_intersects_path``, 735``convert_path_to_polygons``, ``cleanup_path`` and ``clip_path_to_rect`` 736functions in the ``matplotlib.path`` module have been removed. Their 737functionality remains exposed as methods on the ``Path`` class. 738 739The deprecated ``Artist.get_axes`` and ``Artist.set_axes`` methods 740have been removed 741 742 743The ``matplotlib.backends.backend_ps.seq_allequal`` function has been removed. 744Use ``np.array_equal`` instead. 745 746The deprecated ``matplotlib.rcsetup.validate_maskedarray``, 747``matplotlib.rcsetup.deprecate_savefig_extension`` and 748``matplotlib.rcsetup.validate_tkpythoninspect`` functions, and associated 749``savefig.extension`` and ``tk.pythoninspect`` rcparams entries have been 750removed. 751 752 753The kwarg ``resolution`` of 754:class:`matplotlib.projections.polar.PolarAxes` has been removed. It 755has deprecation with no effect from version `0.98.x`. 756 757 758``Axes.set_aspect("normal")`` 759~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 760 761Support for setting an ``Axes``\'s aspect to ``"normal"`` has been 762removed, in favor of the synonym ``"auto"``. 763 764 765``shading`` kwarg to ``pcolor`` 766~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 767 768The ``shading`` kwarg to `~matplotlib.axes.Axes.pcolor` has been 769removed. Set ``edgecolors`` appropriately instead. 770 771 772Functions removed from the `lines` module 773~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 774 775The :mod:`matplotlib.lines` module no longer imports the 776``pts_to_prestep``, ``pts_to_midstep`` and ``pts_to_poststep`` 777functions from :mod:`matplotlib.cbook`. 778 779 780PDF backend functions 781~~~~~~~~~~~~~~~~~~~~~ 782 783The methods ``embedTeXFont`` and ``tex_font_mapping`` of 784:class:`matplotlib.backqend_pdf.PdfFile` have been removed. It is 785unlikely that external users would have called these methods, which 786are related to the font system internal to the PDF backend. 787 788 789matplotlib.delaunay 790~~~~~~~~~~~~~~~~~~~ 791 792Remove the delaunay triangulation code which is now handled by Qhull 793via :mod:`matplotlib.tri`. 794 795API Changes in 2.0.1 796==================== 797 798Extensions to `matplotlib.backend_bases.GraphicsContextBase` 799------------------------------------------------------------ 800 801To better support controlling the color of hatches, the method 802`matplotlib.backend_bases.GraphicsContextBase.set_hatch_color` was 803added to the expected API of ``GraphicsContext`` classes. Calls to 804this method are currently wrapped with a ``try:...except Attribute:`` 805block to preserve back-compatibility with any third-party backends 806which do not extend `~matplotlib.backend_bases.GraphicsContextBase`. 807 808This value can be accessed in the backends via 809`matplotlib.backend_bases.GraphicsContextBase.get_hatch_color` (which 810was added in 2.0 see :ref:`gc_get_hatch_color_wn`) and should be used 811to color the hatches. 812 813In the future there may also be ``hatch_linewidth`` and 814``hatch_density`` related methods added. It is encouraged, but not 815required that third-party backends extend 816`~matplotlib.backend_bases.GraphicsContextBase` to make adapting to 817these changes easier. 818 819 820`afm.get_fontconfig_fonts` returns a list of paths and does not check for existence 821----------------------------------------------------------------------------------- 822 823`afm.get_fontconfig_fonts` used to return a set of paths encoded as a 824``{key: 1, ...}`` dict, and checked for the existence of the paths. It now 825returns a list and dropped the existence check, as the same check is performed 826by the caller (`afm.findSystemFonts`) as well. 827 828 829`bar` now returns rectangles of negative height or width if the corresponding input is negative 830----------------------------------------------------------------------------------------------- 831 832`plt.bar` used to normalize the coordinates of the rectangles that it created, 833to keep their height and width positives, even if the corresponding input was 834negative. This normalization has been removed to permit a simpler computation 835of the correct `sticky_edges` to use. 836 837 838Do not clip line width when scaling dashes 839------------------------------------------ 840 841The algorithm to scale dashes was changed to no longer clip the 842scaling factor: the dash patterns now continue to shrink at thin line widths. 843If the line width is smaller than the effective pixel size, this may result in 844dashed lines turning into solid gray-ish lines. This also required slightly 845tweaking the default patterns for '--', ':', and '.-' so that with the default 846line width the final patterns would not change. 847 848There is no way to restore the old behavior. 849 850 851Deprecate 'Vega' color maps 852--------------------------- 853 854The "Vega" colormaps are deprecated in Matplotlib 2.0.1 and will be 855removed in Matplotlib 2.2. Use the "tab" colormaps instead: "tab10", 856"tab20", "tab20b", "tab20c". 857 858 859API Changes in 2.0.0 860==================== 861 862Deprecation and removal 863----------------------- 864 865Color of Axes 866~~~~~~~~~~~~~ 867The ``axisbg`` and ``axis_bgcolor`` properties on *Axes* have been 868deprecated in favor of ``facecolor``. 869 870GTK and GDK backends deprecated 871~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 872The GDK and GTK backends have been deprecated. These obsolete backends 873allow figures to be rendered via the GDK API to files and GTK2 figures. 874They are untested and known to be broken, and their use has been 875discouraged for some time. Instead, use the `GTKAgg` and `GTKCairo` 876backends for rendering to GTK2 windows. 877 878WX backend deprecated 879~~~~~~~~~~~~~~~~~~~~~ 880The WX backend has been deprecated. It is untested, and its 881use has been discouraged for some time. Instead, use the `WXAgg` 882backend for rendering figures to WX windows. 883 884CocoaAgg backend removed 885~~~~~~~~~~~~~~~~~~~~~~~~ 886The deprecated and not fully functional CocoaAgg backend has been removed. 887 888`round` removed from TkAgg Backend 889~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 890The TkAgg backend had its own implementation of the `round` function. This 891was unused internally and has been removed. Instead, use either the 892`round` builtin function or `numpy.round`. 893 894'hold' functionality deprecated 895~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 896The 'hold' keyword argument and all functions and methods related 897to it are deprecated, along with the 'axes.hold' `rcParams` entry. 898The behavior will remain consistent with the default ``hold=True`` 899state that has long been in place. Instead of using a function 900or keyword argument (``hold=False``) to change that behavior, 901explicitly clear the axes or figure as needed prior to subsequent 902plotting commands. 903 904 905`Artist.update` has return value 906-------------------------------- 907 908The methods `matplotlib.artist.Artist.set`, 909`matplotlib.Artist.update`, and the function `matplotlib.artist.setp` 910now use a common codepath to look up how to update the given artist 911properties (either using the setter methods or an attribute/property). 912 913The behavior of `matplotlib.Artist.update` is slightly changed to 914return a list of the values returned from the setter methods to avoid 915changing the API of `matplotlib.Artist.set` and 916`matplotlib.artist.setp`. 917 918The keys passed into `matplotlib.Artist.update` are now converted to 919lower case before being processed, to match the behavior of 920`matplotlib.Artist.set` and `matplotlib.artist.setp`. This should not 921break any user code because there are no set methods with capitals in 922their names, but this puts a constraint on naming properties in the future. 923 924 925`Legend` initializers gain edgecolor and facecolor kwargs 926--------------------------------------------------------- 927 928The :class:`~matplotlib.legend.Legend` background patch (or 'frame') 929can have its ``edgecolor`` and ``facecolor`` determined by the 930corresponding keyword arguments to the :class:`matplotlib.legend.Legend` 931initializer, or to any of the methods or functions that call that 932initializer. If left to their default values of `None`, their values 933will be taken from ``matplotlib.rcParams``. The previously-existing 934``framealpha`` kwarg still controls the alpha transparency of the 935patch. 936 937 938Qualitative colormaps 939--------------------- 940 941Colorbrewer's qualitative/discrete colormaps ("Accent", "Dark2", "Paired", 942"Pastel1", "Pastel2", "Set1", "Set2", "Set3") are now implemented as 943``ListedColormap`` instead of ``LinearSegmentedColormap``. 944 945To use these for images where categories are specified as integers, for 946instance, use:: 947 948 plt.imshow(x, cmap='Dark2', norm=colors.NoNorm()) 949 950 951Change in the ``draw_image`` backend API 952---------------------------------------- 953 954The ``draw_image`` method implemented by backends has changed its interface. 955 956This change is only relevant if the backend declares that it is able 957to transform images by returning ``True`` from ``option_scale_image``. 958See the ``draw_image`` docstring for more information. 959 960 961 962`matplotlib.ticker.LinearLocator` algorithm update 963-------------------------------------------------- 964 965The ``matplotlib.ticker.LinearLocator`` is used to define the range and 966location of axis ticks when the user wants an exact number of ticks. 967``LinearLocator`` thus differs from the default locator ``MaxNLocator``, 968for which the user specifies a maximum number of intervals rather than 969a precise number of ticks. 970 971The view range algorithm in ``matplotlib.ticker.LinearLocator`` has been 972changed so that more convenient tick locations are chosen. The new algorithm 973returns a plot view range that is a multiple of the user-requested number of 974ticks. This ensures tick marks will be located at whole integers more 975consistently. For example, when both y-axes of a``twinx`` plot use 976``matplotlib.ticker.LinearLocator`` with the same number of ticks, 977their y-tick locations and grid lines will coincide. 978 979`matplotlib.ticker.LogLocator` gains numticks kwarg 980--------------------------------------------------- 981 982The maximum number of ticks generated by the 983`~matplotlib.ticker.LogLocator` can now be controlled explicitly 984via setting the new 'numticks' kwarg to an integer. By default 985the kwarg is None which internally sets it to the 'auto' string, 986triggering a new algorithm for adjusting the maximum according 987to the axis length relative to the ticklabel font size. 988 989`matplotlib.ticker.LogFormatter`: two new kwargs 990------------------------------------------------ 991 992Previously, minor ticks on log-scaled axes were not labeled by 993default. An algorithm has been added to the 994`~matplotlib.ticker.LogFormatter` to control the labeling of 995ticks between integer powers of the base. The algorithm uses 996two parameters supplied in a kwarg tuple named 'minor_thresholds'. 997See the docstring for further explanation. 998 999To improve support for axes using `~matplotlib.ticker.SymmetricLogLocator`, 1000a 'linthresh' kwarg was added. 1001 1002 1003New defaults for 3D quiver function in mpl_toolkits.mplot3d.axes3d.py 1004--------------------------------------------------------------------- 1005 1006Matplotlib has both a 2D and a 3D ``quiver`` function. These changes 1007affect only the 3D function and make the default behavior of the 3D 1008function match the 2D version. There are two changes: 1009 10101) The 3D quiver function previously normalized the arrows to be the 1011 same length, which makes it unusable for situations where the 1012 arrows should be different lengths and does not match the behavior 1013 of the 2D function. This normalization behavior is now controlled 1014 with the ``normalize`` keyword, which defaults to False. 1015 10162) The ``pivot`` keyword now defaults to ``tail`` instead of 1017 ``tip``. This was done in order to match the default behavior of 1018 the 2D quiver function. 1019 1020To obtain the previous behavior with the 3D quiver function, one can 1021call the function with :: 1022 1023 ax.quiver(x, y, z, u, v, w, normalize=True, pivot='tip') 1024 1025where "ax" is an ``Axes3d`` object created with something like :: 1026 1027 import mpl_toolkits.mplot3d.axes3d 1028 ax = plt.sublot(111, projection='3d') 1029 1030 1031Stale figure behavior 1032--------------------- 1033 1034Attempting to draw the figure will now mark it as not stale (independent if 1035the draw succeeds). This change is to prevent repeatedly trying to re-draw a 1036figure which is raising an error on draw. The previous behavior would only mark 1037a figure as not stale after a full re-draw succeeded. 1038 1039 1040The spectral colormap is now nipy_spectral 1041------------------------------------------ 1042 1043The colormaps formerly known as ``spectral`` and ``spectral_r`` have been 1044replaced by ``nipy_spectral`` and ``nipy_spectral_r`` since Matplotlib 10451.3.0. Even though the colormap was deprecated in Matplotlib 1.3.0, it never 1046raised a warning. As of Matplotlib 2.0.0, using the old names raises a 1047deprecation warning. In the future, using the old names will raise an error. 1048 1049Default install no longer includes test images 1050---------------------------------------------- 1051 1052To reduce the size of wheels and source installs, the tests and 1053baseline images are no longer included by default. 1054 1055To restore installing the tests and images, use a `setup.cfg` with :: 1056 1057 [packages] 1058 tests = True 1059 toolkits_tests = True 1060 1061in the source directory at build/install time. 1062 1063Changes in 1.5.3 1064================ 1065 1066``ax.plot(..., marker=None)`` gives default marker 1067-------------------------------------------------- 1068 1069Prior to 1.5.3 kwargs passed to `~matplotlib.Axes.plot` were handled 1070in two parts -- default kwargs generated internal to 1071`~matplotlib.Axes.plot` (such as the cycled styles) and user supplied 1072kwargs. The internally generated kwargs were passed to the 1073`matplotlib.lines.Line2D.__init__` and the user kwargs were passed to 1074``ln.set(**kwargs)`` to update the artist after it was created. Now 1075both sets of kwargs are merged and passed to 1076`~matplotlib.lines.Line2D.__init__`. This change was made to allow `None` 1077to be passed in via the user kwargs to mean 'do the default thing' as 1078is the convention through out mpl rather than raising an exception. 1079 1080Unlike most `~matplotlib.lines.Line2D` setter methods 1081`~matplotlib.lines.Line2D.set_marker` did accept `None` as a valid 1082input which was mapped to 'no marker'. Thus, by routing this 1083``marker=None`` through ``__init__`` rather than ``set(...)`` the meaning 1084of ``ax.plot(..., marker=None)`` changed from 'no markers' to 'default markers 1085from rcparams'. 1086 1087This is change is only evident if ``mpl.rcParams['lines.marker']`` has a value 1088other than ``'None'`` (which is string ``'None'`` which means 'no marker'). 1089 1090 1091Changes in 1.5.2 1092================ 1093 1094 1095Default Behavior Changes 1096------------------------ 1097 1098Changed default ``autorange`` behavior in boxplots 1099~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1100 1101Prior to v1.5.2, the whiskers of boxplots would extend to the minimum 1102and maximum values if the quartiles were all equal (i.e., Q1 = median 1103= Q3). This behavior has been disabled by default to restore consistency 1104with other plotting packages. 1105 1106To restore the old behavior, simply set ``autorange=True`` when 1107calling ``plt.boxplot``. 1108 1109 1110Changes in 1.5.0 1111================ 1112 1113Code Changes 1114------------ 1115 1116Reversed `matplotlib.cbook.ls_mapper`, added `ls_mapper_r` 1117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1118 1119Formerly, `matplotlib.cbook.ls_mapper` was a dictionary with 1120the long-form line-style names (`"solid"`) as keys and the short 1121forms (`"-"`) as values. This long-to-short mapping is now done 1122by `ls_mapper_r`, and the short-to-long mapping is done by the 1123`ls_mapper`. 1124 1125Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes 1126~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1127 1128This was done to prevent an Artist that is 1129already associated with an Axes from being moved/added to a different Axes. 1130This was never supported as it causes havoc with the transform stack. 1131The apparent support for this (as it did not raise an exception) was 1132the source of multiple bug reports and questions on SO. 1133 1134For almost all use-cases, the assignment of the axes to an artist should be 1135taken care of by the axes as part of the ``Axes.add_*`` method, hence the 1136deprecation of {get,set}_axes. 1137 1138Removing the ``set_axes`` method will also remove the 'axes' line from 1139the ACCEPTS kwarg tables (assuming that the removal date gets here 1140before that gets overhauled). 1141 1142Tightened input validation on 'pivot' kwarg to quiver 1143~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1144 1145Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'} 1146(but any capitalization) are valid values for the 'pivot' kwarg in 1147the `Quiver.__init__` (and hence `Axes.quiver` and 1148`plt.quiver` which both fully delegate to `Quiver`). Previously any 1149input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as 1150'tip' and any string not matching one of those patterns as 'tail'. 1151 1152The value of `Quiver.pivot` is normalized to be in the set {'tip', 1153'tail', 'middle'} in `Quiver.__init__`. 1154 1155Reordered `Axes.get_children` 1156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1157 1158The artist order returned by `Axes.get_children` did not 1159match the one used by `Axes.draw`. They now use the same 1160order, as `Axes.draw` now calls `Axes.get_children`. 1161 1162Changed behaviour of contour plots 1163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1164 1165The default behaviour of :func:`~matplotlib.pyplot.contour` and 1166:func:`~matplotlib.pyplot.contourf` when using a masked array is now determined 1167by the new keyword argument `corner_mask`, or if this is not specified then 1168the new rcParam `contour.corner_mask` instead. The new default behaviour is 1169equivalent to using `corner_mask=True`; the previous behaviour can be obtained 1170using `corner_mask=False` or by changing the rcParam. The example 1171http://matplotlib.org/examples/pylab_examples/contour_corner_mask.html 1172demonstrates the difference. Use of the old contouring algorithm, which is 1173obtained with `corner_mask='legacy'`, is now deprecated. 1174 1175Contour labels may now appear in different places than in earlier versions of 1176Matplotlib. 1177 1178In addition, the keyword argument `nchunk` now applies to 1179:func:`~matplotlib.pyplot.contour` as well as 1180:func:`~matplotlib.pyplot.contourf`, and it subdivides the domain into 1181subdomains of exactly `nchunk` by `nchunk` quads, whereas previously it was 1182only roughly `nchunk` by `nchunk` quads. 1183 1184The C/C++ object that performs contour calculations used to be stored in the 1185public attribute QuadContourSet.Cntr, but is now stored in a private attribute 1186and should not be accessed by end users. 1187 1188Added set_params function to all Locator types 1189~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1190 1191This was a bug fix targeted at making the api for Locators more consistent. 1192 1193In the old behavior, only locators of type MaxNLocator have set_params() 1194defined, causing its use on any other Locator to raise an AttributeError *( 1195aside: set_params(args) is a function that sets the parameters of a Locator 1196instance to be as specified within args)*. The fix involves moving set_params() 1197to the Locator class such that all subtypes will have this function defined. 1198 1199Since each of the Locator subtypes have their own modifiable parameters, a 1200universal set_params() in Locator isn't ideal. Instead, a default no-operation 1201function that raises a warning is implemented in Locator. Subtypes extending 1202Locator will then override with their own implementations. Subtypes that do 1203not have a need for set_params() will fall back onto their parent's 1204implementation, which raises a warning as intended. 1205 1206In the new behavior, Locator instances will not raise an AttributeError 1207when set_params() is called. For Locators that do not implement set_params(), 1208the default implementation in Locator is used. 1209 1210Disallow ``None`` as x or y value in ax.plot 1211~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1212 1213Do not allow ``None`` as a valid input for the ``x`` or ``y`` args in 1214`ax.plot`. This may break some user code, but this was never officially 1215supported (ex documented) and allowing ``None`` objects through can lead 1216to confusing exceptions downstream. 1217 1218To create an empty line use :: 1219 1220 ln1, = ax.plot([], [], ...) 1221 ln2, = ax.plot([], ...) 1222 1223In either case to update the data in the `Line2D` object you must update 1224both the ``x`` and ``y`` data. 1225 1226 1227Removed `args` and `kwargs` from `MicrosecondLocator.__call__` 1228~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1229 1230The call signature of :meth:`~matplotlib.dates.MicrosecondLocator.__call__` 1231has changed from `__call__(self, *args, **kwargs)` to `__call__(self)`. 1232This is consistent with the superclass :class:`~matplotlib.ticker.Locator` 1233and also all the other Locators derived from this superclass. 1234 1235 1236No `ValueError` for the MicrosecondLocator and YearLocator 1237~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1238 1239The :class:`~matplotlib.dates.MicrosecondLocator` and 1240:class:`~matplotlib.dates.YearLocator` objects when called will return 1241an empty list if the axes have no data or the view has no interval. 1242Previously, they raised a `ValueError`. This is consistent with all 1243the Date Locators. 1244 1245'OffsetBox.DrawingArea' respects the 'clip' keyword argument 1246~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1247 1248The call signature was `OffsetBox.DrawingArea(..., clip=True)` but nothing 1249was done with the `clip` argument. The object did not do any clipping 1250regardless of that parameter. Now the object can and does clip the 1251child `Artists` if they are set to be clipped. 1252 1253You can turn off the clipping on a per-child basis using 1254`child.set_clip_on(False)`. 1255 1256Add salt to clipPath id 1257~~~~~~~~~~~~~~~~~~~~~~~ 1258 1259Add salt to the hash used to determine the id of the ``clipPath`` 1260nodes. This is to avoid conflicts when two svg documents with the same 1261clip path are included in the same document (see 1262https://github.com/ipython/ipython/issues/8133 and 1263https://github.com/matplotlib/matplotlib/issues/4349 ), however this 1264means that the svg output is no longer deterministic if the same 1265figure is saved twice. It is not expected that this will affect any 1266users as the current ids are generated from an md5 hash of properties 1267of the clip path and any user would have a very difficult time 1268anticipating the value of the id. 1269 1270Changed snap threshold for circle markers to inf 1271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1272 1273When drawing circle markers above some marker size (previously 6.0) 1274the path used to generate the marker was snapped to pixel centers. However, 1275this ends up distorting the marker away from a circle. By setting the 1276snap threshold to inf snapping is never done on circles. 1277 1278This change broke several tests, but is an improvement. 1279 1280Preserve units with Text position 1281~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1282 1283Previously the 'get_position' method on Text would strip away unit information 1284even though the units were still present. There was no inherent need to do 1285this, so it has been changed so that unit data (if present) will be preserved. 1286Essentially a call to 'get_position' will return the exact value from a call to 1287'set_position'. 1288 1289If you wish to get the old behaviour, then you can use the new method called 1290'get_unitless_position'. 1291 1292New API for custom Axes view changes 1293~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1294 1295Interactive pan and zoom were previously implemented using a Cartesian-specific 1296algorithm that was not necessarily applicable to custom Axes. Three new private 1297methods, :meth:`~matplotlib.axes._base._AxesBase._get_view`, 1298:meth:`~matplotlib.axes._base._AxesBase._set_view`, and 1299:meth:`~matplotlib.axes._base._AxesBase._set_view_from_bbox`, allow for custom 1300*Axes* classes to override the pan and zoom algorithms. Implementors of 1301custom *Axes* who override these methods may provide suitable behaviour for 1302both pan and zoom as well as the view navigation buttons on the interactive 1303toolbars. 1304 1305MathTex visual changes 1306---------------------- 1307 1308The spacing commands in mathtext have been changed to more closely 1309match vanilla TeX. 1310 1311 1312Improved spacing in mathtext 1313~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1314 1315The extra space that appeared after subscripts and superscripts has 1316been removed. 1317 1318No annotation coordinates wrap 1319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1320 1321In #2351 for 1.4.0 the behavior of ['axes points', 'axes pixel', 1322'figure points', 'figure pixel'] as coordinates was change to 1323no longer wrap for negative values. In 1.4.3 this change was 1324reverted for 'axes points' and 'axes pixel' and in addition caused 1325'axes fraction' to wrap. For 1.5 the behavior has been reverted to 1326as it was in 1.4.0-1.4.2, no wrapping for any type of coordinate. 1327 1328Deprecation 1329----------- 1330 1331Deprecated `GraphicsContextBase.set_graylevel` 1332~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1333 1334The `GraphicsContextBase.set_graylevel` function has been deprecated in 1.5 and 1335will be removed in 1.6. It has been unused. The 1336`GraphicsContextBase.set_foreground` could be used instead. 1337 1338deprecated idle_event 1339~~~~~~~~~~~~~~~~~~~~~ 1340 1341The `idle_event` was broken or missing in most backends and causes spurious 1342warnings in some cases, and its use in creating animations is now obsolete due 1343to the animations module. Therefore code involving it has been removed from all 1344but the wx backend (where it partially works), and its use is deprecated. The 1345animations module may be used instead to create animations. 1346 1347`color_cycle` deprecated 1348~~~~~~~~~~~~~~~~~~~~~~~~ 1349 1350In light of the new property cycling feature, 1351the Axes method *set_color_cycle* is now deprecated. 1352Calling this method will replace the current property cycle with 1353one that cycles just the given colors. 1354 1355Similarly, the rc parameter *axes.color_cycle* is also deprecated in 1356lieu of the new *axes.prop_cycle* parameter. Having both parameters in 1357the same rc file is not recommended as the result cannot be 1358predicted. For compatibility, setting *axes.color_cycle* will 1359replace the cycler in *axes.prop_cycle* with a color cycle. 1360Accessing *axes.color_cycle* will return just the color portion 1361of the property cycle, if it exists. 1362 1363Timeline for removal has not been set. 1364 1365 1366Bundled jquery 1367-------------- 1368 1369The version of jquery bundled with the webagg backend has been upgraded 1370from 1.7.1 to 1.11.3. If you are using the version of jquery bundled 1371with webagg you will need to update your html files as such 1372 1373.. code-block:: diff 1374 1375 - <script src="_static/jquery/js/jquery-1.7.1.min.js"></script> 1376 + <script src="_static/jquery/js/jquery-1.11.3.min.js"></script> 1377 1378 1379Code Removed 1380------------ 1381 1382Removed `Image` from main namespace 1383~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1384 1385`Image` was imported from PIL/pillow to test if PIL is available, but 1386there is no reason to keep `Image` in the namespace once the availability 1387has been determined. 1388 1389Removed `lod` from Artist 1390~~~~~~~~~~~~~~~~~~~~~~~~~ 1391 1392Removed the method *set_lod* and all references to 1393the attribute *_lod* as the are not used anywhere else in the 1394code base. It appears to be a feature stub that was never built 1395out. 1396 1397Removed threading related classes from cbook 1398~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1399The classes ``Scheduler``, ``Timeout``, and ``Idle`` were in cbook, but 1400are not used internally. They appear to be a prototype for the idle event 1401system which was not working and has recently been pulled out. 1402 1403Removed `Lena` images from sample_data 1404~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1405 1406The ``lena.png`` and ``lena.jpg`` images have been removed from 1407Matplotlib's sample_data directory. The images are also no longer 1408available from `matplotlib.cbook.get_sample_data`. We suggest using 1409`matplotlib.cbook.get_sample_data('grace_hopper.png')` or 1410`matplotlib.cbook.get_sample_data('grace_hopper.jpg')` instead. 1411 1412 1413Legend 1414~~~~~~ 1415Removed handling of `loc` as a positional argument to `Legend` 1416 1417 1418Legend handlers 1419~~~~~~~~~~~~~~~ 1420Remove code to allow legend handlers to be callable. They must now 1421implement a method ``legend_artist``. 1422 1423 1424Axis 1425~~~~ 1426Removed method ``set_scale``. This is now handled via a private method which 1427should not be used directly by users. It is called via ``Axes.set_{x,y}scale`` 1428which takes care of ensuring the related changes are also made to the Axes 1429object. 1430 1431finance.py 1432~~~~~~~~~~ 1433 1434Removed functions with ambiguous argument order from finance.py 1435 1436 1437Annotation 1438~~~~~~~~~~ 1439 1440Removed ``textcoords`` and ``xytext`` proprieties from Annotation objects. 1441 1442 1443spinxext.ipython_*.py 1444~~~~~~~~~~~~~~~~~~~~~ 1445 1446Both ``ipython_console_highlighting`` and ``ipython_directive`` have been 1447moved to `IPython`. 1448 1449Change your import from 'matplotlib.sphinxext.ipython_directive' to 1450'IPython.sphinxext.ipython_directive' and from 1451'matplotlib.sphinxext.ipython_directive' to 1452'IPython.sphinxext.ipython_directive' 1453 1454 1455LineCollection.color 1456~~~~~~~~~~~~~~~~~~~~ 1457 1458Deprecated in 2005, use ``set_color`` 1459 1460 1461remove ``'faceted'`` as a valid value for `shading` in ``tri.tripcolor`` 1462~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1463 1464Use `edgecolor` instead. Added validation on ``shading`` to 1465only be valid values. 1466 1467 1468Remove ``faceted`` kwarg from scatter 1469~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1470 1471Remove support for the ``faceted`` kwarg. This was deprecated in 1472d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by 1473``edgecolor``. 1474 1475 1476Remove ``set_colorbar`` method from ``ScalarMappable`` 1477~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1478 1479Remove ``set_colorbar`` method, use `colorbar` attribute directly. 1480 1481 1482patheffects.svg 1483~~~~~~~~~~~~~~~ 1484 1485 - remove ``get_proxy_renderer`` method from ``AbstarctPathEffect`` class 1486 - remove ``patch_alpha`` and ``offset_xy`` from ``SimplePatchShadow`` 1487 1488 1489Remove ``testing.image_util.py`` 1490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1491Contained only a no-longer used port of functionality from PIL 1492 1493 1494Remove ``mlab.FIFOBuffer`` 1495~~~~~~~~~~~~~~~~~~~~~~~~~~ 1496 1497Not used internally and not part of core mission of mpl. 1498 1499 1500Remove ``mlab.prepca`` 1501~~~~~~~~~~~~~~~~~~~~~~ 1502Deprecated in 2009. 1503 1504 1505Remove ``NavigationToolbar2QTAgg`` 1506~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1507Added no functionality over the base ``NavigationToolbar2Qt`` 1508 1509 1510mpl.py 1511~~~~~~ 1512 1513Remove the module `matplotlib.mpl`. Deprecated in 1.3 by 1514PR #1670 and commit 78ce67d161625833cacff23cfe5d74920248c5b2 1515 1516 1517Changes in 1.4.x 1518================ 1519 1520Code changes 1521------------ 1522 1523* A major refactoring of the axes module was made. The axes module has been 1524 split into smaller modules: 1525 1526 - the `_base` module, which contains a new private _AxesBase class. This 1527 class contains all methods except plotting and labelling methods. 1528 - the `axes` module, which contains the Axes class. This class inherits 1529 from _AxesBase, and contains all plotting and labelling methods. 1530 - the `_subplot` module, with all the classes concerning subplotting. 1531 1532There are a couple of things that do not exists in the `axes` module's 1533namespace anymore. If you use them, you need to import them from their 1534original location: 1535 1536 - math -> `import math` 1537 - ma -> `from numpy import ma` 1538 - cbook -> `from matplotlib import cbook` 1539 - docstring -> `from matplotlib import docstring` 1540 - is_sequence_of_strings -> `from matplotlib.cbook import is_sequence_of_strings` 1541 - is_string_like -> `from matplotlib.cbook import is_string_like` 1542 - iterable -> `from matplotlib.cbook import iterable` 1543 - itertools -> `import itertools` 1544 - martist -> `from matplotlib import artist as martist` 1545 - matplotlib -> `import matplotlib` 1546 - mcoll -> `from matplotlib import collections as mcoll` 1547 - mcolors -> `from matplotlib import colors as mcolors` 1548 - mcontour -> `from matplotlib import contour as mcontour` 1549 - mpatches -> `from matplotlib import patches as mpatches` 1550 - mpath -> `from matplotlib import path as mpath` 1551 - mquiver -> `from matplotlib import quiver as mquiver` 1552 - mstack -> `from matplotlib import stack as mstack` 1553 - mstream -> `from matplotlib import stream as mstream` 1554 - mtable -> `from matplotlib import table as mtable` 1555 1556* As part of the refactoring to enable Qt5 support, the module 1557 `matplotlib.backends.qt4_compat` was renamed to 1558 `matplotlib.qt_compat`. `qt4_compat` is deprecated in 1.4 and 1559 will be removed in 1.5. 1560 1561* The :func:`~matplotlib.pyplot.errorbar` method has been changed such that 1562 the upper and lower limits (*lolims*, *uplims*, *xlolims*, *xuplims*) now 1563 point in the correct direction. 1564 1565* The *fmt* kwarg for :func:`~matplotlib.pyplot.errorbar now supports 1566 the string 'none' to suppress drawing of a line and markers; use 1567 of the *None* object for this is deprecated. The default *fmt* 1568 value is changed to the empty string (''), so the line and markers 1569 are governed by the :func:`~matplotlib.pyplot.plot` defaults. 1570 1571* A bug has been fixed in the path effects rendering of fonts, which now means 1572 that the font size is consistent with non-path effect fonts. See 1573 https://github.com/matplotlib/matplotlib/issues/2889 for more detail. 1574 1575* The Sphinx extensions `ipython_directive` and 1576 `ipython_console_highlighting` have been moved to the IPython 1577 project itself. While they remain in Matplotlib for this release, 1578 they have been deprecated. Update your extensions in `conf.py` to 1579 point to `IPython.sphinxext.ipython_directive` instead of 1580 `matplotlib.sphinxext.ipython_directive`. 1581 1582* In `~matplotlib.finance`, almost all functions have been deprecated 1583 and replaced with a pair of functions name `*_ochl` and `*_ohlc`. 1584 The former is the 'open-close-high-low' order of quotes used 1585 previously in this module, and the latter is the 1586 'open-high-low-close' order that is standard in finance. 1587 1588* For consistency the ``face_alpha`` keyword to 1589 :class:`matplotlib.patheffects.SimplePatchShadow` has been deprecated in 1590 favour of the ``alpha`` keyword. Similarly, the keyword ``offset_xy`` is now 1591 named ``offset`` across all :class:`~matplotlib.patheffects.AbstractPathEffect`s. 1592 ``matplotlib.patheffects._Base`` has 1593 been renamed to :class:`matplotlib.patheffects.AbstractPathEffect`. 1594 ``matplotlib.patheffect.ProxyRenderer`` has been renamed to 1595 :class:`matplotlib.patheffects.PathEffectRenderer` and is now a full 1596 RendererBase subclass. 1597 1598* The artist used to draw the outline of a `colorbar` has been changed 1599 from a `matplotlib.lines.Line2D` to `matplotlib.patches.Polygon`, 1600 thus `colorbar.ColorbarBase.outline` is now a 1601 `matplotlib.patches.Polygon` object. 1602 1603* The legend handler interface has changed from a callable, to any object 1604 which implements the ``legend_artists`` method (a deprecation phase will 1605 see this interface be maintained for v1.4). See 1606 :doc:`/tutorials/intermediate/legend_guide` for further details. Further legend changes 1607 include: 1608 1609 * :func:`matplotlib.axes.Axes._get_legend_handles` now returns a generator 1610 of handles, rather than a list. 1611 1612 * The :func:`~matplotlib.pyplot.legend` function's "loc" positional 1613 argument has been deprecated. Use the "loc" keyword instead. 1614 1615* The rcParams `savefig.transparent` has been added to control 1616 default transparency when saving figures. 1617 1618* Slightly refactored the `Annotation` family. The text location in 1619 `Annotation` is now handled entirely handled by the underlying `Text` 1620 object so `set_position` works as expected. The attributes `xytext` and 1621 `textcoords` have been deprecated in favor of `xyann` and `anncoords` so 1622 that `Annotation` and `AnnotaionBbox` can share a common sensibly named 1623 api for getting/setting the location of the text or box. 1624 1625 - `xyann` -> set the location of the annotation 1626 - `xy` -> set where the arrow points to 1627 - `anncoords` -> set the units of the annotation location 1628 - `xycoords` -> set the units of the point location 1629 - `set_position()` -> `Annotation` only set location of annotation 1630 1631* `matplotlib.mlab.specgram`, `matplotlib.mlab.psd`, `matplotlib.mlab.csd`, 1632 `matplotlib.mlab.cohere`, `matplotlib.mlab.cohere_pairs`, 1633 `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`, 1634 `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere` now raise 1635 ValueError where they previously raised AssertionError. 1636 1637* For `matplotlib.mlab.psd`, `matplotlib.mlab.csd`, 1638 `matplotlib.mlab.cohere`, `matplotlib.mlab.cohere_pairs`, 1639 `matplotlib.pyplot.specgram`, `matplotlib.pyplot.psd`, 1640 `matplotlib.pyplot.csd`, and `matplotlib.pyplot.cohere`, in cases 1641 where a shape (n, 1) array is returned, this is now converted to a (n, ) 1642 array. Previously, (n, m) arrays were averaged to an (n, ) array, but 1643 (n, 1) arrays were returend unchanged. This change makes the dimensions 1644 consistent in both cases. 1645 1646* Added the rcParam `axes.fromatter.useoffset` to control the default value 1647 of `useOffset` in `ticker.ScalarFormatter` 1648 1649* Added `Formatter` sub-class `StrMethodFormatter` which 1650 does the exact same thing as `FormatStrFormatter`, but for new-style 1651 formatting strings. 1652 1653* Deprecated `matplotlib.testing.image_util` and the only function within, 1654 `matplotlib.testing.image_util.autocontrast`. These will be removed 1655 completely in v1.5.0. 1656 1657* The ``fmt`` argument of :meth:`~matplotlib.axes.Axes.plot_date` has been 1658 changed from ``bo`` to just ``o``, so color cycling can happen by default. 1659 1660* Removed the class `FigureManagerQTAgg` and deprecated `NavigationToolbar2QTAgg` 1661 which will be removed in 1.5. 1662 1663* Removed formerly public (non-prefixed) attributes `rect` and 1664 `drawRect` from `FigureCanvasQTAgg`; they were always an 1665 implementation detail of the (preserved) `drawRectangle()` function. 1666 1667* The function signatures of `tight_bbox.adjust_bbox` and 1668 `tight_bbox.process_figure_for_rasterizing` have been changed. A new 1669 `fixed_dpi` parameter allows for overriding the `figure.dpi` setting 1670 instead of trying to deduce the intended behaviour from the file format. 1671 1672* Added support for horizontal/vertical axes padding to 1673 `mpl_toolkits.axes_grid1.ImageGrid` --- argument ``axes_pad`` can now be 1674 tuple-like if separate axis padding is required. 1675 The original behavior is preserved. 1676 1677* Added support for skewed transforms to `matplotlib.transforms.Affine2D`, 1678 which can be created using the `skew` and `skew_deg` methods. 1679 1680* Added clockwise parameter to control sectors direction in `axes.pie` 1681 1682* In `matplotlib.lines.Line2D` the `markevery` functionality has been extended. 1683 Previously an integer start-index and stride-length could be specified using 1684 either a two-element-list or a two-element-tuple. Now this can only be done 1685 using a two-element-tuple. If a two-element-list is used then it will be 1686 treated as numpy fancy indexing and only the two markers corresponding to the 1687 given indexes will be shown. 1688 1689* removed prop kwarg from `mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar` 1690 call. It was passed through to the base-class `__init__` and is only used for 1691 setting padding. Now `fontproperties` (which is what is really used to set 1692 the font properties of `AnchoredSizeBar`) is passed through in place of `prop`. 1693 If `fontpropreties` is not passed in, but `prop` is, then `prop` is used inplace 1694 of `fontpropreties`. If both are passed in, `prop` is silently ignored. 1695 1696 1697* The use of the index 0 in `plt.subplot` and related commands is 1698 deprecated. Due to a lack of validation calling `plt.subplots(2, 2, 1699 0)` does not raise an exception, but puts an axes in the _last_ 1700 position. This is due to the indexing in subplot being 1-based (to 1701 mirror MATLAB) so before indexing into the `GridSpec` object used to 1702 determine where the axes should go, 1 is subtracted off. Passing in 1703 0 results in passing -1 to `GridSpec` which results in getting the 1704 last position back. Even though this behavior is clearly wrong and 1705 not intended, we are going through a deprecation cycle in an 1706 abundance of caution that any users are exploiting this 'feature'. 1707 The use of 0 as an index will raise a warning in 1.4 and an 1708 exception in 1.5. 1709 1710* Clipping is now off by default on offset boxes. 1711 1712* Matplotlib now uses a less-aggressive call to ``gc.collect(1)`` when 1713 closing figures to avoid major delays with large numbers of user objects 1714 in memory. 1715 1716* The default clip value of *all* pie artists now defaults to ``False``. 1717 1718 1719Code removal 1720------------ 1721 1722* Removed ``mlab.levypdf``. The code raised a numpy error (and has for 1723 a long time) and was not the standard form of the Levy distribution. 1724 ``scipy.stats.levy`` should be used instead 1725 1726 1727.. _changes_in_1_3: 1728 1729 1730Changes in 1.3.x 1731================ 1732 1733Changes in 1.3.1 1734---------------- 1735 1736It is rare that we make an API change in a bugfix release, however, 1737for 1.3.1 since 1.3.0 the following change was made: 1738 1739- `text.Text.cached` (used to cache font objects) has been made into a 1740 private variable. Among the obvious encapsulation benefit, this 1741 removes this confusing-looking member from the documentation. 1742 1743- The method :meth:`~matplotlib.axes.Axes.hist` now always returns bin 1744 occupancies as an array of type `float`. Previously, it was sometimes 1745 an array of type `int`, depending on the call. 1746 1747Code removal 1748------------ 1749 1750* The following items that were deprecated in version 1.2 or earlier 1751 have now been removed completely. 1752 1753 - The Qt 3.x backends (`qt` and `qtagg`) have been removed in 1754 favor of the Qt 4.x backends (`qt4` and `qt4agg`). 1755 1756 - The FltkAgg and Emf backends have been removed. 1757 1758 - The `matplotlib.nxutils` module has been removed. Use the 1759 functionality on `matplotlib.path.Path.contains_point` and 1760 friends instead. 1761 1762 - Instead of `axes.Axes.get_frame`, use `axes.Axes.patch`. 1763 1764 - The following `kwargs` to the `legend` function have been 1765 renamed: 1766 1767 - `pad` -> `borderpad` 1768 - `labelsep` -> `labelspacing` 1769 - `handlelen` -> `handlelength` 1770 - `handletextsep` -> `handletextpad` 1771 - `axespad` -> `borderaxespad` 1772 1773 Related to this, the following rcParams have been removed: 1774 1775 - `legend.pad`, `legend.labelsep`, `legend.handlelen`, 1776 `legend.handletextsep` and `legend.axespad` 1777 1778 - For the `hist` function, instead of `width`, use `rwidth` 1779 (relative width). 1780 1781 - On `patches.Circle`, the `resolution` kwarg has been removed. 1782 For a circle made up of line segments, use 1783 `patches.CirclePolygon`. 1784 1785 - The printing functions in the Wx backend have been removed due 1786 to the burden of keeping them up-to-date. 1787 1788 - `mlab.liaupunov` has been removed. 1789 1790 - `mlab.save`, `mlab.load`, `pylab.save` and `pylab.load` have 1791 been removed. We recommend using `numpy.savetxt` and 1792 `numpy.loadtxt` instead. 1793 1794 - `widgets.HorizontalSpanSelector` has been removed. Use 1795 `widgets.SpanSelector` instead. 1796 1797Code deprecation 1798---------------- 1799 1800* The CocoaAgg backend has been deprecated, with the possibility for 1801 deletion or resurrection in a future release. 1802 1803* The top-level functions in `matplotlib.path` that are implemented in 1804 C++ were never meant to be public. Instead, users should use the 1805 Pythonic wrappers for them in the `path.Path` and 1806 `collections.Collection` classes. Use the following mapping to update 1807 your code: 1808 1809 - `point_in_path` -> `path.Path.contains_point` 1810 - `get_path_extents` -> `path.Path.get_extents` 1811 - `point_in_path_collection` -> `collection.Collection.contains` 1812 - `path_in_path` -> `path.Path.contains_path` 1813 - `path_intersects_path` -> `path.Path.intersects_path` 1814 - `convert_path_to_polygons` -> `path.Path.to_polygons` 1815 - `cleanup_path` -> `path.Path.cleaned` 1816 - `points_in_path` -> `path.Path.contains_points` 1817 - `clip_path_to_rect` -> `path.Path.clip_to_bbox` 1818 1819* `matplotlib.colors.normalize` and `matplotlib.colors.no_norm` have 1820 been deprecated in favour of `matplotlib.colors.Normalize` and 1821 `matplotlib.colors.NoNorm` respectively. 1822 1823* The `ScalarMappable` class' `set_colorbar` is now 1824 deprecated. Instead, the 1825 :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be 1826 used. In previous Matplotlib versions this attribute was an 1827 undocumented tuple of ``(colorbar_instance, colorbar_axes)`` but is 1828 now just ``colorbar_instance``. To get the colorbar axes it is 1829 possible to just use the 1830 :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar 1831 instance. 1832 1833* The `~matplotlib.mpl` module is now deprecated. Those who relied on this 1834 module should transition to simply using ``import matplotlib as mpl``. 1835 1836Code changes 1837------------ 1838 1839* :class:`~matplotlib.patches.Patch` now fully supports using RGBA values for 1840 its ``facecolor`` and ``edgecolor`` attributes, which enables faces and 1841 edges to have different alpha values. If the 1842 :class:`~matplotlib.patches.Patch` object's ``alpha`` attribute is set to 1843 anything other than ``None``, that value will override any alpha-channel 1844 value in both the face and edge colors. Previously, if 1845 :class:`~matplotlib.patches.Patch` had ``alpha=None``, the alpha component 1846 of ``edgecolor`` would be applied to both the edge and face. 1847 1848* The optional ``isRGB`` argument to 1849 :meth:`~matplotlib.backend_bases.GraphicsContextBase.set_foreground` (and 1850 the other GraphicsContext classes that descend from it) has been renamed to 1851 ``isRGBA``, and should now only be set to ``True`` if the ``fg`` color 1852 argument is known to be an RGBA tuple. 1853 1854* For :class:`~matplotlib.patches.Patch`, the ``capstyle`` used is now 1855 ``butt``, to be consistent with the default for most other objects, and to 1856 avoid problems with non-solid ``linestyle`` appearing solid when using a 1857 large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used 1858 ``capstyle='projecting'``. 1859 1860* `Path` objects can now be marked as `readonly` by passing 1861 `readonly=True` to its constructor. The built-in path singletons, 1862 obtained through `Path.unit*` class methods return readonly paths. 1863 If you have code that modified these, you will need to make a 1864 deepcopy first, using either:: 1865 1866 import copy 1867 path = copy.deepcopy(Path.unit_circle()) 1868 1869 # or 1870 1871 path = Path.unit_circle().deepcopy() 1872 1873 Deep copying a `Path` always creates an editable (i.e. non-readonly) 1874 `Path`. 1875 1876* The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping 1877 Path codes to the number of expected vertices at 1878 :attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`. 1879 1880* To support XKCD style plots, the :func:`matplotlib.path.cleanup_path` 1881 method's signature was updated to require a sketch argument. Users of 1882 :func:`matplotlib.path.cleanup_path` are encouraged to use the new 1883 :meth:`~matplotlib.path.Path.cleaned` Path method. 1884 1885* Data limits on a plot now start from a state of having "null" 1886 limits, rather than limits in the range (0, 1). This has an effect 1887 on artists that only control limits in one direction, such as 1888 `axvline` and `axhline`, since their limits will not longer also 1889 include the range (0, 1). This fixes some problems where the 1890 computed limits would be dependent on the order in which artists 1891 were added to the axes. 1892 1893* Fixed a bug in setting the position for the right/top spine with data 1894 position type. Previously, it would draw the right or top spine at 1895 +1 data offset. 1896 1897* In :class:`~matplotlib.patches.FancyArrow`, the default arrow head 1898 width, ``head_width``, has been made larger to produce a visible 1899 arrow head. The new value of this kwarg is ``head_width = 20 * 1900 width``. 1901 1902* It is now possible to provide ``number of levels + 1`` colors in the case of 1903 `extend='both'` for contourf (or just ``number of levels`` colors for an 1904 extend value ``min`` or ``max``) such that the resulting colormap's 1905 ``set_under`` and ``set_over`` are defined appropriately. Any other number 1906 of colors will continue to behave as before (if more colors are provided 1907 than levels, the colors will be unused). A similar change has been applied 1908 to contour, where ``extend='both'`` would expect ``number of levels + 2`` 1909 colors. 1910 1911* A new keyword *extendrect* in :meth:`~matplotlib.pyplot.colorbar` and 1912 :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the shape 1913 of colorbar extensions. 1914 1915* The extension of :class:`~matplotlib.widgets.MultiCursor` to both vertical 1916 (default) and/or horizontal cursor implied that ``self.line`` is replaced 1917 by ``self.vline`` for vertical cursors lines and ``self.hline`` is added 1918 for the horizontal cursors lines. 1919 1920* On POSIX platforms, the :func:`~matplotlib.cbook.report_memory` function 1921 raises :class:`NotImplementedError` instead of :class:`OSError` if the 1922 :command:`ps` command cannot be run. 1923 1924* The :func:`matplotlib.cbook.check_output` function has been moved to 1925 :func:`matplotlib.compat.subprocess`. 1926 1927Configuration and rcParams 1928-------------------------- 1929 1930* On Linux, the user-specific `matplotlibrc` configuration file is now 1931 located in `~/.config/matplotlib/matplotlibrc` to conform to the 1932 `XDG Base Directory Specification 1933 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. 1934 1935* The `font.*` rcParams now affect only text objects created after the 1936 rcParam has been set, and will not retroactively affect already 1937 existing text objects. This brings their behavior in line with most 1938 other rcParams. 1939 1940* Removed call of :meth:`~matplotlib.axes.Axes.grid` in 1941 :meth:`~matplotlib.pyplot.plotfile`. To draw the axes grid, set the 1942 ``axes.grid`` rcParam to *True*, or explicitly call 1943 :meth:`~matplotlib.axes.Axes.grid`. 1944 1945Changes in 1.2.x 1946================ 1947 1948* The ``classic`` option of the rc parameter ``toolbar`` is deprecated 1949 and will be removed in the next release. 1950 1951* The :meth:`~matplotlib.cbook.isvector` method has been removed since it 1952 is no longer functional. 1953 1954* The `rasterization_zorder` property on `~matplotlib.axes.Axes` a 1955 zorder below which artists are rasterized. This has defaulted to 1956 -30000.0, but it now defaults to `None`, meaning no artists will be 1957 rasterized. In order to rasterize artists below a given zorder 1958 value, `set_rasterization_zorder` must be explicitly called. 1959 1960* In :meth:`~matplotlib.axes.Axes.scatter`, and `~pyplot.scatter`, 1961 when specifying a marker using a tuple, the angle is now specified 1962 in degrees, not radians. 1963 1964* Using :meth:`~matplotlib.axes.Axes.twinx` or 1965 :meth:`~matplotlib.axes.Axes.twiny` no longer overrides the current locaters 1966 and formatters on the axes. 1967 1968* In :meth:`~matplotlib.axes.Axes.contourf`, the handling of the *extend* 1969 kwarg has changed. Formerly, the extended ranges were mapped 1970 after to 0, 1 after being normed, so that they always corresponded 1971 to the extreme values of the colormap. Now they are mapped 1972 outside this range so that they correspond to the special 1973 colormap values determined by the 1974 :meth:`~matplotlib.colors.Colormap.set_under` and 1975 :meth:`~matplotlib.colors.Colormap.set_over` methods, which 1976 default to the colormap end points. 1977 1978* The new rc parameter ``savefig.format`` replaces ``cairo.format`` and 1979 ``savefig.extension``, and sets the default file format used by 1980 :meth:`matplotlib.figure.Figure.savefig`. 1981 1982* In :meth:`~matplotlib.pyplot.pie` and :meth:`~matplotlib.Axes.pie`, one can 1983 now set the radius of the pie; setting the *radius* to 'None' (the default 1984 value), will result in a pie with a radius of 1 as before. 1985 1986* Use of :func:`~matplotlib.projections.projection_factory` is now deprecated 1987 in favour of axes class identification using 1988 :func:`~matplotlib.projections.process_projection_requirements` followed by 1989 direct axes class invocation (at the time of writing, functions which do this 1990 are: :meth:`~matplotlib.figure.Figure.add_axes`, 1991 :meth:`~matplotlib.figure.Figure.add_subplot` and 1992 :meth:`~matplotlib.figure.Figure.gca`). Therefore:: 1993 1994 1995 key = figure._make_key(*args, **kwargs) 1996 ispolar = kwargs.pop('polar', False) 1997 projection = kwargs.pop('projection', None) 1998 if ispolar: 1999 if projection is not None and projection != 'polar': 2000 raise ValueError('polar and projection args are inconsistent') 2001 projection = 'polar' 2002 ax = projection_factory(projection, self, rect, **kwargs) 2003 key = self._make_key(*args, **kwargs) 2004 2005 # is now 2006 2007 projection_class, kwargs, key = \ 2008 process_projection_requirements(self, *args, **kwargs) 2009 ax = projection_class(self, rect, **kwargs) 2010 2011 This change means that third party objects can expose themselves as 2012 Matplotlib axes by providing a ``_as_mpl_axes`` method. See 2013 :ref:`adding-new-scales` for more detail. 2014 2015* A new keyword *extendfrac* in :meth:`~matplotlib.pyplot.colorbar` and 2016 :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the size of 2017 the triangular minimum and maximum extensions on colorbars. 2018 2019* A new keyword *capthick* in :meth:`~matplotlib.pyplot.errorbar` has been 2020 added as an intuitive alias to the *markeredgewidth* and *mew* keyword 2021 arguments, which indirectly controlled the thickness of the caps on 2022 the errorbars. For backwards compatibility, specifying either of the 2023 original keyword arguments will override any value provided by 2024 *capthick*. 2025 2026* Transform subclassing behaviour is now subtly changed. If your transform 2027 implements a non-affine transformation, then it should override the 2028 ``transform_non_affine`` method, rather than the generic ``transform`` method. 2029 Previously transforms would define ``transform`` and then copy the 2030 method into ``transform_non_affine``:: 2031 2032 class MyTransform(mtrans.Transform): 2033 def transform(self, xy): 2034 ... 2035 transform_non_affine = transform 2036 2037 2038 This approach will no longer function correctly and should be changed to:: 2039 2040 class MyTransform(mtrans.Transform): 2041 def transform_non_affine(self, xy): 2042 ... 2043 2044 2045* Artists no longer have ``x_isdata`` or ``y_isdata`` attributes; instead 2046 any artist's transform can be interrogated with 2047 ``artist_instance.get_transform().contains_branch(ax.transData)`` 2048 2049* Lines added to an axes now take into account their transform when updating the 2050 data and view limits. This means transforms can now be used as a pre-transform. 2051 For instance:: 2052 2053 >>> import matplotlib.pyplot as plt 2054 >>> import matplotlib.transforms as mtrans 2055 >>> ax = plt.axes() 2056 >>> ax.plot(range(10), transform=mtrans.Affine2D().scale(10) + ax.transData) 2057 >>> print(ax.viewLim) 2058 Bbox('array([[ 0., 0.],\n [ 90., 90.]])') 2059 2060* One can now easily get a transform which goes from one transform's coordinate 2061 system to another, in an optimized way, using the new subtract method on a 2062 transform. For instance, to go from data coordinates to axes coordinates:: 2063 2064 >>> import matplotlib.pyplot as plt 2065 >>> ax = plt.axes() 2066 >>> data2ax = ax.transData - ax.transAxes 2067 >>> print(ax.transData.depth, ax.transAxes.depth) 2068 3, 1 2069 >>> print(data2ax.depth) 2070 2 2071 2072 for versions before 1.2 this could only be achieved in a sub-optimal way, 2073 using ``ax.transData + ax.transAxes.inverted()`` (depth is a new concept, 2074 but had it existed it would return 4 for this example). 2075 2076* ``twinx`` and ``twiny`` now returns an instance of SubplotBase if 2077 parent axes is an instance of SubplotBase. 2078 2079* All Qt3-based backends are now deprecated due to the lack of py3k bindings. 2080 Qt and QtAgg backends will continue to work in v1.2.x for py2.6 2081 and py2.7. It is anticipated that the Qt3 support will be completely 2082 removed for the next release. 2083 2084* :class:`~matplotlib.colors.ColorConverter`, 2085 :class:`~matplotlib.colors.Colormap` and 2086 :class:`~matplotlib.colors.Normalize` now subclasses ``object`` 2087 2088* ContourSet instances no longer have a ``transform`` attribute. Instead, 2089 access the transform with the ``get_transform`` method. 2090 2091Changes in 1.1.x 2092================ 2093 2094* Added new :class:`matplotlib.sankey.Sankey` for generating Sankey diagrams. 2095 2096* In :meth:`~matplotlib.pyplot.imshow`, setting *interpolation* to 'nearest' 2097 will now always mean that the nearest-neighbor interpolation is performed. 2098 If you want the no-op interpolation to be performed, choose 'none'. 2099 2100* There were errors in how the tri-functions were handling input parameters 2101 that had to be fixed. If your tri-plots are not working correctly anymore, 2102 or you were working around apparent mistakes, please see issue #203 in the 2103 github tracker. When in doubt, use kwargs. 2104 2105* The 'symlog' scale had some bad behavior in previous versions. This has now 2106 been fixed and users should now be able to use it without frustrations. 2107 The fixes did result in some minor changes in appearance for some users who 2108 may have been depending on the bad behavior. 2109 2110* There is now a common set of markers for all plotting functions. Previously, 2111 some markers existed only for :meth:`~matplotlib.pyplot.scatter` or just for 2112 :meth:`~matplotlib.pyplot.plot`. This is now no longer the case. This merge 2113 did result in a conflict. The string 'd' now means "thin diamond" while 2114 'D' will mean "regular diamond". 2115 2116Changes beyond 0.99.x 2117===================== 2118 2119* The default behavior of :meth:`matplotlib.axes.Axes.set_xlim`, 2120 :meth:`matplotlib.axes.Axes.set_ylim`, and 2121 :meth:`matplotlib.axes.Axes.axis`, and their corresponding 2122 pyplot functions, has been changed: when view limits are 2123 set explicitly with one of these methods, autoscaling is turned 2124 off for the matching axis. A new *auto* kwarg is available to 2125 control this behavior. The limit kwargs have been renamed to 2126 *left* and *right* instead of *xmin* and *xmax*, and *bottom* 2127 and *top* instead of *ymin* and *ymax*. The old names may still 2128 be used, however. 2129 2130* There are five new Axes methods with corresponding pyplot 2131 functions to facilitate autoscaling, tick location, and tick 2132 label formatting, and the general appearance of ticks and 2133 tick labels: 2134 2135 + :meth:`matplotlib.axes.Axes.autoscale` turns autoscaling 2136 on or off, and applies it. 2137 2138 + :meth:`matplotlib.axes.Axes.margins` sets margins used to 2139 autoscale the :attr:`matplotlib.axes.Axes.viewLim` based on 2140 the :attr:`matplotlib.axes.Axes.dataLim`. 2141 2142 + :meth:`matplotlib.axes.Axes.locator_params` allows one to 2143 adjust axes locator parameters such as *nbins*. 2144 2145 + :meth:`matplotlib.axes.Axes.ticklabel_format` is a convenience 2146 method for controlling the :class:`matplotlib.ticker.ScalarFormatter` 2147 that is used by default with linear axes. 2148 2149 + :meth:`matplotlib.axes.Axes.tick_params` controls direction, size, 2150 visibility, and color of ticks and their labels. 2151 2152* The :meth:`matplotlib.axes.Axes.bar` method accepts a *error_kw* 2153 kwarg; it is a dictionary of kwargs to be passed to the 2154 errorbar function. 2155 2156* The :meth:`matplotlib.axes.Axes.hist` *color* kwarg now accepts 2157 a sequence of color specs to match a sequence of datasets. 2158 2159* The :class:`~matplotlib.collections.EllipseCollection` has been 2160 changed in two ways: 2161 2162 + There is a new *units* option, 'xy', that scales the ellipse with 2163 the data units. This matches the :class:'~matplotlib.patches.Ellipse` 2164 scaling. 2165 2166 + The *height* and *width* kwargs have been changed to specify 2167 the height and width, again for consistency with 2168 :class:`~matplotlib.patches.Ellipse`, and to better match 2169 their names; previously they specified the half-height and 2170 half-width. 2171 2172* There is a new rc parameter ``axes.color_cycle``, and the color 2173 cycle is now independent of the rc parameter ``lines.color``. 2174 :func:`matplotlib.Axes.set_default_color_cycle` is deprecated. 2175 2176* You can now print several figures to one pdf file and modify the 2177 document information dictionary of a pdf file. See the docstrings 2178 of the class :class:`matplotlib.backends.backend_pdf.PdfPages` for 2179 more information. 2180 2181* Removed configobj_ and `enthought.traits`_ packages, which are only 2182 required by the experimental traited config and are somewhat out of 2183 date. If needed, install them independently. 2184 2185.. _configobj: http://www.voidspace.org.uk/python/configobj.html 2186.. _`enthought.traits`: http://code.enthought.com/pages/traits.html 2187 2188* The new rc parameter ``savefig.extension`` sets the filename extension 2189 that is used by :meth:`matplotlib.figure.Figure.savefig` if its *fname* 2190 argument lacks an extension. 2191 2192* In an effort to simplify the backend API, all clipping rectangles 2193 and paths are now passed in using GraphicsContext objects, even 2194 on collections and images. Therefore:: 2195 2196 draw_path_collection(self, master_transform, cliprect, clippath, 2197 clippath_trans, paths, all_transforms, offsets, 2198 offsetTrans, facecolors, edgecolors, linewidths, 2199 linestyles, antialiaseds, urls) 2200 2201 # is now 2202 2203 draw_path_collection(self, gc, master_transform, paths, all_transforms, 2204 offsets, offsetTrans, facecolors, edgecolors, 2205 linewidths, linestyles, antialiaseds, urls) 2206 2207 2208 draw_quad_mesh(self, master_transform, cliprect, clippath, 2209 clippath_trans, meshWidth, meshHeight, coordinates, 2210 offsets, offsetTrans, facecolors, antialiased, 2211 showedges) 2212 2213 # is now 2214 2215 draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight, 2216 coordinates, offsets, offsetTrans, facecolors, 2217 antialiased, showedges) 2218 2219 2220 draw_image(self, x, y, im, bbox, clippath=None, clippath_trans=None) 2221 2222 # is now 2223 2224 draw_image(self, gc, x, y, im) 2225 2226* There are four new Axes methods with corresponding pyplot 2227 functions that deal with unstructured triangular grids: 2228 2229 + :meth:`matplotlib.axes.Axes.tricontour` draws contour lines 2230 on a triangular grid. 2231 2232 + :meth:`matplotlib.axes.Axes.tricontourf` draws filled contours 2233 on a triangular grid. 2234 2235 + :meth:`matplotlib.axes.Axes.tripcolor` draws a pseudocolor 2236 plot on a triangular grid. 2237 2238 + :meth:`matplotlib.axes.Axes.triplot` draws a triangular grid 2239 as lines and/or markers. 2240 2241Changes in 0.99 2242=============== 2243 2244* pylab no longer provides a load and save function. These are 2245 available in matplotlib.mlab, or you can use numpy.loadtxt and 2246 numpy.savetxt for text files, or np.save and np.load for binary 2247 numpy arrays. 2248 2249* User-generated colormaps can now be added to the set recognized 2250 by :func:`matplotlib.cm.get_cmap`. Colormaps can be made the 2251 default and applied to the current image using 2252 :func:`matplotlib.pyplot.set_cmap`. 2253 2254* changed use_mrecords default to False in mlab.csv2rec since this is 2255 partially broken 2256 2257* Axes instances no longer have a "frame" attribute. Instead, use the 2258 new "spines" attribute. Spines is a dictionary where the keys are 2259 the names of the spines (e.g., 'left','right' and so on) and the 2260 values are the artists that draw the spines. For normal 2261 (rectilinear) axes, these artists are Line2D instances. For other 2262 axes (such as polar axes), these artists may be Patch instances. 2263 2264* Polar plots no longer accept a resolution kwarg. Instead, each Path 2265 must specify its own number of interpolation steps. This is 2266 unlikely to be a user-visible change -- if interpolation of data is 2267 required, that should be done before passing it to Matplotlib. 2268 2269Changes for 0.98.x 2270================== 2271* psd(), csd(), and cohere() will now automatically wrap negative 2272 frequency components to the beginning of the returned arrays. 2273 This is much more sensible behavior and makes them consistent 2274 with specgram(). The previous behavior was more of an oversight 2275 than a design decision. 2276 2277* Added new keyword parameters *nonposx*, *nonposy* to 2278 :class:`matplotlib.axes.Axes` methods that set log scale 2279 parameters. The default is still to mask out non-positive 2280 values, but the kwargs accept 'clip', which causes non-positive 2281 values to be replaced with a very small positive value. 2282 2283* Added new :func:`matplotlib.pyplot.fignum_exists` and 2284 :func:`matplotlib.pyplot.get_fignums`; they merely expose 2285 information that had been hidden in :mod:`matplotlib._pylab_helpers`. 2286 2287* Deprecated numerix package. 2288 2289* Added new :func:`matplotlib.image.imsave` and exposed it to the 2290 :mod:`matplotlib.pyplot` interface. 2291 2292* Remove support for pyExcelerator in exceltools -- use xlwt 2293 instead 2294 2295* Changed the defaults of acorr and xcorr to use usevlines=True, 2296 maxlags=10 and normed=True since these are the best defaults 2297 2298* Following keyword parameters for :class:`matplotlib.label.Label` are now 2299 deprecated and new set of parameters are introduced. The new parameters 2300 are given as a fraction of the font-size. Also, *scatteryoffsets*, 2301 *fancybox* and *columnspacing* are added as keyword parameters. 2302 2303 ================ ================ 2304 Deprecated New 2305 ================ ================ 2306 pad borderpad 2307 labelsep labelspacing 2308 handlelen handlelength 2309 handlestextsep handletextpad 2310 axespad borderaxespad 2311 ================ ================ 2312 2313 2314* Removed the configobj and experimental traits rc support 2315 2316* Modified :func:`matplotlib.mlab.psd`, :func:`matplotlib.mlab.csd`, 2317 :func:`matplotlib.mlab.cohere`, and :func:`matplotlib.mlab.specgram` 2318 to scale one-sided densities by a factor of 2. Also, optionally 2319 scale the densities by the sampling frequency, which gives true values 2320 of densities that can be integrated by the returned frequency values. 2321 This also gives better MATLAB compatibility. The corresponding 2322 :class:`matplotlib.axes.Axes` methods and :mod:`matplotlib.pyplot` 2323 functions were updated as well. 2324 2325* Font lookup now uses a nearest-neighbor approach rather than an 2326 exact match. Some fonts may be different in plots, but should be 2327 closer to what was requested. 2328 2329* :meth:`matplotlib.axes.Axes.set_xlim`, 2330 :meth:`matplotlib.axes.Axes.set_ylim` now return a copy of the 2331 :attr:`viewlim` array to avoid modify-in-place surprises. 2332 2333* :meth:`matplotlib.afm.AFM.get_fullname` and 2334 :meth:`matplotlib.afm.AFM.get_familyname` no longer raise an 2335 exception if the AFM file does not specify these optional 2336 attributes, but returns a guess based on the required FontName 2337 attribute. 2338 2339* Changed precision kwarg in :func:`matplotlib.pyplot.spy`; default is 2340 0, and the string value 'present' is used for sparse arrays only to 2341 show filled locations. 2342 2343* :class:`matplotlib.collections.EllipseCollection` added. 2344 2345* Added ``angles`` kwarg to :func:`matplotlib.pyplot.quiver` for more 2346 flexible specification of the arrow angles. 2347 2348* Deprecated (raise NotImplementedError) all the mlab2 functions from 2349 :mod:`matplotlib.mlab` out of concern that some of them were not 2350 clean room implementations. 2351 2352* Methods :meth:`matplotlib.collections.Collection.get_offsets` and 2353 :meth:`matplotlib.collections.Collection.set_offsets` added to 2354 :class:`~matplotlib.collections.Collection` base class. 2355 2356* :attr:`matplotlib.figure.Figure.figurePatch` renamed 2357 :attr:`matplotlib.figure.Figure.patch`; 2358 :attr:`matplotlib.axes.Axes.axesPatch` renamed 2359 :attr:`matplotlib.axes.Axes.patch`; 2360 :attr:`matplotlib.axes.Axes.axesFrame` renamed 2361 :attr:`matplotlib.axes.Axes.frame`. 2362 :meth:`matplotlib.axes.Axes.get_frame`, which returns 2363 :attr:`matplotlib.axes.Axes.patch`, is deprecated. 2364 2365* Changes in the :class:`matplotlib.contour.ContourLabeler` attributes 2366 (:func:`matplotlib.pyplot.clabel` function) so that they all have a 2367 form like ``.labelAttribute``. The three attributes that are most 2368 likely to be used by end users, ``.cl``, ``.cl_xy`` and 2369 ``.cl_cvalues`` have been maintained for the moment (in addition to 2370 their renamed versions), but they are deprecated and will eventually 2371 be removed. 2372 2373* Moved several functions in :mod:`matplotlib.mlab` and 2374 :mod:`matplotlib.cbook` into a separate module 2375 :mod:`matplotlib.numerical_methods` because they were unrelated to 2376 the initial purpose of mlab or cbook and appeared more coherent 2377 elsewhere. 2378 2379Changes for 0.98.1 2380================== 2381 2382* Removed broken :mod:`matplotlib.axes3d` support and replaced it with 2383 a non-implemented error pointing to 0.91.x 2384 2385Changes for 0.98.0 2386================== 2387 2388* :func:`matplotlib.image.imread` now no longer always returns RGBA data---if 2389 the image is luminance or RGB, it will return a MxN or MxNx3 array 2390 if possible. Also uint8 is no longer always forced to float. 2391 2392* Rewrote the :class:`matplotlib.cm.ScalarMappable` callback 2393 infrastructure to use :class:`matplotlib.cbook.CallbackRegistry` 2394 rather than custom callback handling. Any users of 2395 :meth:`matplotlib.cm.ScalarMappable.add_observer` of the 2396 :class:`~matplotlib.cm.ScalarMappable` should use the 2397 :attr:`matplotlib.cm.ScalarMappable.callbacks` 2398 :class:`~matplotlib.cbook.CallbackRegistry` instead. 2399 2400* New axes function and Axes method provide control over the plot 2401 color cycle: :func:`matplotlib.axes.set_default_color_cycle` and 2402 :meth:`matplotlib.axes.Axes.set_color_cycle`. 2403 2404* Matplotlib now requires Python 2.4, so :mod:`matplotlib.cbook` will 2405 no longer provide :class:`set`, :func:`enumerate`, :func:`reversed` 2406 or :func:`izip` compatibility functions. 2407 2408* In Numpy 1.0, bins are specified by the left edges only. The axes 2409 method :meth:`matplotlib.axes.Axes.hist` now uses future Numpy 1.3 2410 semantics for histograms. Providing ``binedges``, the last value gives 2411 the upper-right edge now, which was implicitly set to +infinity in 2412 Numpy 1.0. This also means that the last bin doesn't contain upper 2413 outliers any more by default. 2414 2415* New axes method and pyplot function, 2416 :func:`~matplotlib.pyplot.hexbin`, is an alternative to 2417 :func:`~matplotlib.pyplot.scatter` for large datasets. It makes 2418 something like a :func:`~matplotlib.pyplot.pcolor` of a 2-D 2419 histogram, but uses hexagonal bins. 2420 2421* New kwarg, ``symmetric``, in :class:`matplotlib.ticker.MaxNLocator` 2422 allows one require an axis to be centered around zero. 2423 2424* Toolkits must now be imported from ``mpl_toolkits`` (not ``matplotlib.toolkits``) 2425 2426Notes about the transforms refactoring 2427-------------------------------------- 2428 2429A major new feature of the 0.98 series is a more flexible and 2430extensible transformation infrastructure, written in Python/Numpy 2431rather than a custom C extension. 2432 2433The primary goal of this refactoring was to make it easier to 2434extend matplotlib to support new kinds of projections. This is 2435mostly an internal improvement, and the possible user-visible 2436changes it allows are yet to come. 2437 2438See :mod:`matplotlib.transforms` for a description of the design of 2439the new transformation framework. 2440 2441For efficiency, many of these functions return views into Numpy 2442arrays. This means that if you hold on to a reference to them, 2443their contents may change. If you want to store a snapshot of 2444their current values, use the Numpy array method copy(). 2445 2446The view intervals are now stored only in one place -- in the 2447:class:`matplotlib.axes.Axes` instance, not in the locator instances 2448as well. This means locators must get their limits from their 2449:class:`matplotlib.axis.Axis`, which in turn looks up its limits from 2450the :class:`~matplotlib.axes.Axes`. If a locator is used temporarily 2451and not assigned to an Axis or Axes, (e.g., in 2452:mod:`matplotlib.contour`), a dummy axis must be created to store its 2453bounds. Call :meth:`matplotlib.ticker.Locator.create_dummy_axis` to 2454do so. 2455 2456The functionality of :class:`Pbox` has been merged with 2457:class:`~matplotlib.transforms.Bbox`. Its methods now all return 2458copies rather than modifying in place. 2459 2460The following lists many of the simple changes necessary to update 2461code from the old transformation framework to the new one. In 2462particular, methods that return a copy are named with a verb in the 2463past tense, whereas methods that alter an object in place are named 2464with a verb in the present tense. 2465 2466:mod:`matplotlib.transforms` 2467~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2468 2469============================================================ ============================================================ 2470Old method New method 2471============================================================ ============================================================ 2472:meth:`Bbox.get_bounds` :attr:`transforms.Bbox.bounds` 2473------------------------------------------------------------ ------------------------------------------------------------ 2474:meth:`Bbox.width` :attr:`transforms.Bbox.width` 2475------------------------------------------------------------ ------------------------------------------------------------ 2476:meth:`Bbox.height` :attr:`transforms.Bbox.height` 2477------------------------------------------------------------ ------------------------------------------------------------ 2478`Bbox.intervalx().get_bounds()` :attr:`transforms.Bbox.intervalx` 2479`Bbox.intervalx().set_bounds()` [:attr:`Bbox.intervalx` is now a property.] 2480------------------------------------------------------------ ------------------------------------------------------------ 2481`Bbox.intervaly().get_bounds()` :attr:`transforms.Bbox.intervaly` 2482`Bbox.intervaly().set_bounds()` [:attr:`Bbox.intervaly` is now a property.] 2483------------------------------------------------------------ ------------------------------------------------------------ 2484:meth:`Bbox.xmin` :attr:`transforms.Bbox.x0` or 2485 :attr:`transforms.Bbox.xmin` [1]_ 2486------------------------------------------------------------ ------------------------------------------------------------ 2487:meth:`Bbox.ymin` :attr:`transforms.Bbox.y0` or 2488 :attr:`transforms.Bbox.ymin` [1]_ 2489------------------------------------------------------------ ------------------------------------------------------------ 2490:meth:`Bbox.xmax` :attr:`transforms.Bbox.x1` or 2491 :attr:`transforms.Bbox.xmax` [1]_ 2492------------------------------------------------------------ ------------------------------------------------------------ 2493:meth:`Bbox.ymax` :attr:`transforms.Bbox.y1` or 2494 :attr:`transforms.Bbox.ymax` [1]_ 2495------------------------------------------------------------ ------------------------------------------------------------ 2496`Bbox.overlaps(bboxes)` `Bbox.count_overlaps(bboxes)` 2497------------------------------------------------------------ ------------------------------------------------------------ 2498`bbox_all(bboxes)` `Bbox.union(bboxes)` 2499 [:meth:`transforms.Bbox.union` is a staticmethod.] 2500------------------------------------------------------------ ------------------------------------------------------------ 2501`lbwh_to_bbox(l, b, w, h)` `Bbox.from_bounds(x0, y0, w, h)` 2502 [:meth:`transforms.Bbox.from_bounds` is a staticmethod.] 2503------------------------------------------------------------ ------------------------------------------------------------ 2504`inverse_transform_bbox(trans, bbox)` `Bbox.inverse_transformed(trans)` 2505------------------------------------------------------------ ------------------------------------------------------------ 2506`Interval.contains_open(v)` `interval_contains_open(tuple, v)` 2507------------------------------------------------------------ ------------------------------------------------------------ 2508`Interval.contains(v)` `interval_contains(tuple, v)` 2509------------------------------------------------------------ ------------------------------------------------------------ 2510`identity_transform()` :class:`matplotlib.transforms.IdentityTransform` 2511------------------------------------------------------------ ------------------------------------------------------------ 2512`blend_xy_sep_transform(xtrans, ytrans)` `blended_transform_factory(xtrans, ytrans)` 2513------------------------------------------------------------ ------------------------------------------------------------ 2514`scale_transform(xs, ys)` `Affine2D().scale(xs[, ys])` 2515------------------------------------------------------------ ------------------------------------------------------------ 2516`get_bbox_transform(boxin, boxout)` `BboxTransform(boxin, boxout)` or 2517 `BboxTransformFrom(boxin)` or 2518 `BboxTransformTo(boxout)` 2519------------------------------------------------------------ ------------------------------------------------------------ 2520`Transform.seq_xy_tup(points)` `Transform.transform(points)` 2521------------------------------------------------------------ ------------------------------------------------------------ 2522`Transform.inverse_xy_tup(points)` `Transform.inverted().transform(points)` 2523============================================================ ============================================================ 2524 2525.. [1] The :class:`~matplotlib.transforms.Bbox` is bound by the points 2526 (x0, y0) to (x1, y1) and there is no defined order to these points, 2527 that is, x0 is not necessarily the left edge of the box. To get 2528 the left edge of the :class:`Bbox`, use the read-only property 2529 :attr:`~matplotlib.transforms.Bbox.xmin`. 2530 2531:mod:`matplotlib.axes` 2532~~~~~~~~~~~~~~~~~~~~~~ 2533 2534============================================================ ============================================================ 2535Old method New method 2536============================================================ ============================================================ 2537`Axes.get_position()` :meth:`matplotlib.axes.Axes.get_position` [2]_ 2538------------------------------------------------------------ ------------------------------------------------------------ 2539`Axes.set_position()` :meth:`matplotlib.axes.Axes.set_position` [3]_ 2540------------------------------------------------------------ ------------------------------------------------------------ 2541`Axes.toggle_log_lineary()` :meth:`matplotlib.axes.Axes.set_yscale` [4]_ 2542------------------------------------------------------------ ------------------------------------------------------------ 2543`Subplot` class removed. 2544============================================================ ============================================================ 2545 2546The :class:`Polar` class has moved to :mod:`matplotlib.projections.polar`. 2547 2548.. [2] :meth:`matplotlib.axes.Axes.get_position` used to return a list 2549 of points, now it returns a :class:`matplotlib.transforms.Bbox` 2550 instance. 2551 2552.. [3] :meth:`matplotlib.axes.Axes.set_position` now accepts either 2553 four scalars or a :class:`matplotlib.transforms.Bbox` instance. 2554 2555.. [4] Since the recfactoring allows for more than two scale types 2556 ('log' or 'linear'), it no longer makes sense to have a toggle. 2557 `Axes.toggle_log_lineary()` has been removed. 2558 2559:mod:`matplotlib.artist` 2560~~~~~~~~~~~~~~~~~~~~~~~~ 2561 2562============================================================ ============================================================ 2563Old method New method 2564============================================================ ============================================================ 2565`Artist.set_clip_path(path)` `Artist.set_clip_path(path, transform)` [5]_ 2566============================================================ ============================================================ 2567 2568.. [5] :meth:`matplotlib.artist.Artist.set_clip_path` now accepts a 2569 :class:`matplotlib.path.Path` instance and a 2570 :class:`matplotlib.transforms.Transform` that will be applied to 2571 the path immediately before clipping. 2572 2573:mod:`matplotlib.collections` 2574~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2575 2576============================================================ ============================================================ 2577Old method New method 2578============================================================ ============================================================ 2579`linestyle` `linestyles` [6]_ 2580============================================================ ============================================================ 2581 2582.. [6] Linestyles are now treated like all other collection 2583 attributes, i.e. a single value or multiple values may be 2584 provided. 2585 2586:mod:`matplotlib.colors` 2587~~~~~~~~~~~~~~~~~~~~~~~~ 2588 2589============================================================ ============================================================ 2590Old method New method 2591============================================================ ============================================================ 2592`ColorConvertor.to_rgba_list(c)` `ColorConvertor.to_rgba_array(c)` 2593 [:meth:`matplotlib.colors.ColorConvertor.to_rgba_array` 2594 returns an Nx4 Numpy array of RGBA color quadruples.] 2595============================================================ ============================================================ 2596 2597:mod:`matplotlib.contour` 2598~~~~~~~~~~~~~~~~~~~~~~~~~ 2599 2600============================================================ ============================================================ 2601Old method New method 2602============================================================ ============================================================ 2603`Contour._segments` :meth:`matplotlib.contour.Contour.get_paths`` [Returns a 2604 list of :class:`matplotlib.path.Path` instances.] 2605============================================================ ============================================================ 2606 2607:mod:`matplotlib.figure` 2608~~~~~~~~~~~~~~~~~~~~~~~~ 2609 2610============================================================ ============================================================ 2611Old method New method 2612============================================================ ============================================================ 2613`Figure.dpi.get()` / `Figure.dpi.set()` :attr:`matplotlib.figure.Figure.dpi` *(a property)* 2614============================================================ ============================================================ 2615 2616:mod:`matplotlib.patches` 2617~~~~~~~~~~~~~~~~~~~~~~~~~ 2618 2619============================================================ ============================================================ 2620Old method New method 2621============================================================ ============================================================ 2622`Patch.get_verts()` :meth:`matplotlib.patches.Patch.get_path` [Returns a 2623 :class:`matplotlib.path.Path` instance] 2624============================================================ ============================================================ 2625 2626:mod:`matplotlib.backend_bases` 2627~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2628 2629============================================================ ============================================================ 2630Old method New method 2631============================================================ ============================================================ 2632`GraphicsContext.set_clip_rectangle(tuple)` `GraphicsContext.set_clip_rectangle(bbox)` 2633------------------------------------------------------------ ------------------------------------------------------------ 2634`GraphicsContext.get_clip_path()` `GraphicsContext.get_clip_path()` [7]_ 2635------------------------------------------------------------ ------------------------------------------------------------ 2636`GraphicsContext.set_clip_path()` `GraphicsContext.set_clip_path()` [8]_ 2637============================================================ ============================================================ 2638 2639:class:`~matplotlib.backend_bases.RendererBase` 2640~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2641 2642New methods: 2643 2644 * :meth:`draw_path(self, gc, path, transform, rgbFace) 2645 <matplotlib.backend_bases.RendererBase.draw_path>` 2646 2647 * :meth:`draw_markers(self, gc, marker_path, marker_trans, path, 2648 trans, rgbFace) 2649 <matplotlib.backend_bases.RendererBase.draw_markers>` 2650 2651 * :meth:`draw_path_collection(self, master_transform, cliprect, 2652 clippath, clippath_trans, paths, all_transforms, offsets, 2653 offsetTrans, facecolors, edgecolors, linewidths, linestyles, 2654 antialiaseds) 2655 <matplotlib.backend_bases.RendererBase.draw_path_collection>` 2656 *[optional]* 2657 2658Changed methods: 2659 2660 * `draw_image(self, x, y, im, bbox)` is now 2661 :meth:`draw_image(self, x, y, im, bbox, clippath, clippath_trans) 2662 <matplotlib.backend_bases.RendererBase.draw_image>` 2663 2664Removed methods: 2665 2666 * `draw_arc` 2667 2668 * `draw_line_collection` 2669 2670 * `draw_line` 2671 2672 * `draw_lines` 2673 2674 * `draw_point` 2675 2676 * `draw_quad_mesh` 2677 2678 * `draw_poly_collection` 2679 2680 * `draw_polygon` 2681 2682 * `draw_rectangle` 2683 2684 * `draw_regpoly_collection` 2685 2686.. [7] :meth:`matplotlib.backend_bases.GraphicsContext.get_clip_path` 2687 returns a tuple of the form (*path*, *affine_transform*), where 2688 *path* is a :class:`matplotlib.path.Path` instance and 2689 *affine_transform* is a :class:`matplotlib.transforms.Affine2D` 2690 instance. 2691 2692.. [8] :meth:`matplotlib.backend_bases.GraphicsContext.set_clip_path` 2693 now only accepts a :class:`matplotlib.transforms.TransformedPath` 2694 instance. 2695 2696Changes for 0.91.2 2697================== 2698 2699* For :func:`csv2rec`, checkrows=0 is the new default indicating all rows 2700 will be checked for type inference 2701 2702* A warning is issued when an image is drawn on log-scaled axes, since 2703 it will not log-scale the image data. 2704 2705* Moved :func:`rec2gtk` to :mod:`matplotlib.toolkits.gtktools` 2706 2707* Moved :func:`rec2excel` to :mod:`matplotlib.toolkits.exceltools` 2708 2709* Removed, dead/experimental ExampleInfo, Namespace and Importer 2710 code from :mod:`matplotlib.__init__` 2711 2712Changes for 0.91.1 2713================== 2714 2715Changes for 0.91.0 2716================== 2717 2718* Changed :func:`cbook.is_file_like` to 2719 :func:`cbook.is_writable_file_like` and corrected behavior. 2720 2721* Added ax kwarg to :func:`pyplot.colorbar` and 2722 :meth:`Figure.colorbar` so that one can specify the axes object from 2723 which space for the colorbar is to be taken, if one does not want to 2724 make the colorbar axes manually. 2725 2726* Changed :func:`cbook.reversed` so it yields a tuple rather than a 2727 (index, tuple). This agrees with the python reversed builtin, 2728 and cbook only defines reversed if python doesn't provide the 2729 builtin. 2730 2731* Made skiprows=1 the default on :func:`csv2rec` 2732 2733* The gd and paint backends have been deleted. 2734 2735* The errorbar method and function now accept additional kwargs 2736 so that upper and lower limits can be indicated by capping the 2737 bar with a caret instead of a straight line segment. 2738 2739* The :mod:`matplotlib.dviread` file now has a parser for files like 2740 psfonts.map and pdftex.map, to map TeX font names to external files. 2741 2742* The file :mod:`matplotlib.type1font` contains a new class for Type 1 2743 fonts. Currently it simply reads pfa and pfb format files and 2744 stores the data in a way that is suitable for embedding in pdf 2745 files. In the future the class might actually parse the font to 2746 allow e.g., subsetting. 2747 2748* :mod:`matplotlib.FT2Font` now supports :meth:`FT_Attach_File`. In 2749 practice this can be used to read an afm file in addition to a 2750 pfa/pfb file, to get metrics and kerning information for a Type 1 2751 font. 2752 2753* The :class:`AFM` class now supports querying CapHeight and stem 2754 widths. The get_name_char method now has an isord kwarg like 2755 get_width_char. 2756 2757* Changed :func:`pcolor` default to shading='flat'; but as noted now in the 2758 docstring, it is preferable to simply use the edgecolor kwarg. 2759 2760* The mathtext font commands (``\cal``, ``\rm``, ``\it``, ``\tt``) now 2761 behave as TeX does: they are in effect until the next font change 2762 command or the end of the grouping. Therefore uses of ``$\cal{R}$`` 2763 should be changed to ``${\cal R}$``. Alternatively, you may use the 2764 new LaTeX-style font commands (``\mathcal``, ``\mathrm``, 2765 ``\mathit``, ``\mathtt``) which do affect the following group, 2766 e.g., ``$\mathcal{R}$``. 2767 2768* Text creation commands have a new default linespacing and a new 2769 ``linespacing`` kwarg, which is a multiple of the maximum vertical 2770 extent of a line of ordinary text. The default is 1.2; 2771 ``linespacing=2`` would be like ordinary double spacing, for example. 2772 2773* Changed default kwarg in 2774 :meth:`matplotlib.colors.Normalize.__init__`` to ``clip=False``; 2775 clipping silently defeats the purpose of the special over, under, 2776 and bad values in the colormap, thereby leading to unexpected 2777 behavior. The new default should reduce such surprises. 2778 2779* Made the emit property of :meth:`~matplotlib.axes.Axes.set_xlim` and 2780 :meth:`~matplotlib.axes.Axes.set_ylim` ``True`` by default; removed 2781 the Axes custom callback handling into a 'callbacks' attribute which 2782 is a :class:`~matplotlib.cbook.CallbackRegistry` instance. This now 2783 supports the 'xlim_changed' and 'ylim_changed' Axes events. 2784 2785Changes for 0.90.1 2786================== 2787 2788:: 2789 2790 The file dviread.py has a (very limited and fragile) dvi reader 2791 for usetex support. The API might change in the future so don't 2792 depend on it yet. 2793 2794 Removed deprecated support for a float value as a gray-scale; 2795 now it must be a string, like '0.5'. Added alpha kwarg to 2796 ColorConverter.to_rgba_list. 2797 2798 New method set_bounds(vmin, vmax) for formatters, locators sets 2799 the viewInterval and dataInterval from floats. 2800 2801 Removed deprecated colorbar_classic. 2802 2803 Line2D.get_xdata and get_ydata valid_only=False kwarg is replaced 2804 by orig=True. When True, it returns the original data, otherwise 2805 the processed data (masked, converted) 2806 2807 Some modifications to the units interface. 2808 units.ConversionInterface.tickers renamed to 2809 units.ConversionInterface.axisinfo and it now returns a 2810 units.AxisInfo object rather than a tuple. This will make it 2811 easier to add axis info functionality (e.g., I added a default label 2812 on this iteration) w/o having to change the tuple length and hence 2813 the API of the client code every time new functionality is added. 2814 Also, units.ConversionInterface.convert_to_value is now simply 2815 named units.ConversionInterface.convert. 2816 2817 Axes.errorbar uses Axes.vlines and Axes.hlines to draw its error 2818 limits int he vertical and horizontal direction. As you'll see 2819 in the changes below, these functions now return a LineCollection 2820 rather than a list of lines. The new return signature for 2821 errorbar is ylins, caplines, errorcollections where 2822 errorcollections is a xerrcollection, yerrcollection 2823 2824 Axes.vlines and Axes.hlines now create and returns a LineCollection, not a list 2825 of lines. This is much faster. The kwarg signature has changed, 2826 so consult the docs 2827 2828 MaxNLocator accepts a new Boolean kwarg ('integer') to force 2829 ticks to integer locations. 2830 2831 Commands that pass an argument to the Text constructor or to 2832 Text.set_text() now accept any object that can be converted 2833 with '%s'. This affects xlabel(), title(), etc. 2834 2835 Barh now takes a **kwargs dict instead of most of the old 2836 arguments. This helps ensure that bar and barh are kept in sync, 2837 but as a side effect you can no longer pass e.g., color as a 2838 positional argument. 2839 2840 ft2font.get_charmap() now returns a dict that maps character codes 2841 to glyph indices (until now it was reversed) 2842 2843 Moved data files into lib/matplotlib so that setuptools' develop 2844 mode works. Re-organized the mpl-data layout so that this source 2845 structure is maintained in the installation. (i.e., the 'fonts' and 2846 'images' sub-directories are maintained in site-packages.). 2847 Suggest removing site-packages/matplotlib/mpl-data and 2848 ~/.matplotlib/ttffont.cache before installing 2849 2850Changes for 0.90.0 2851================== 2852 2853:: 2854 2855 All artists now implement a "pick" method which users should not 2856 call. Rather, set the "picker" property of any artist you want to 2857 pick on (the epsilon distance in points for a hit test) and 2858 register with the "pick_event" callback. See 2859 examples/pick_event_demo.py for details 2860 2861 Bar, barh, and hist have "log" binary kwarg: log=True 2862 sets the ordinate to a log scale. 2863 2864 Boxplot can handle a list of vectors instead of just 2865 an array, so vectors can have different lengths. 2866 2867 Plot can handle 2-D x and/or y; it plots the columns. 2868 2869 Added linewidth kwarg to bar and barh. 2870 2871 Made the default Artist._transform None (rather than invoking 2872 identity_transform for each artist only to have it overridden 2873 later). Use artist.get_transform() rather than artist._transform, 2874 even in derived classes, so that the default transform will be 2875 created lazily as needed 2876 2877 New LogNorm subclass of Normalize added to colors.py. 2878 All Normalize subclasses have new inverse() method, and 2879 the __call__() method has a new clip kwarg. 2880 2881 Changed class names in colors.py to match convention: 2882 normalize -> Normalize, no_norm -> NoNorm. Old names 2883 are still available for now. 2884 2885 Removed obsolete pcolor_classic command and method. 2886 2887 Removed lineprops and markerprops from the Annotation code and 2888 replaced them with an arrow configurable with kwarg arrowprops. 2889 See examples/annotation_demo.py - JDH 2890 2891Changes for 0.87.7 2892================== 2893 2894:: 2895 2896 Completely reworked the annotations API because I found the old 2897 API cumbersome. The new design is much more legible and easy to 2898 read. See matplotlib.text.Annotation and 2899 examples/annotation_demo.py 2900 2901 markeredgecolor and markerfacecolor cannot be configured in 2902 matplotlibrc any more. Instead, markers are generally colored 2903 automatically based on the color of the line, unless marker colors 2904 are explicitly set as kwargs - NN 2905 2906 Changed default comment character for load to '#' - JDH 2907 2908 math_parse_s_ft2font_svg from mathtext.py & mathtext2.py now returns 2909 width, height, svg_elements. svg_elements is an instance of Bunch ( 2910 cmbook.py) and has the attributes svg_glyphs and svg_lines, which are both 2911 lists. 2912 2913 Renderer.draw_arc now takes an additional parameter, rotation. 2914 It specifies to draw the artist rotated in degrees anti- 2915 clockwise. It was added for rotated ellipses. 2916 2917 Renamed Figure.set_figsize_inches to Figure.set_size_inches to 2918 better match the get method, Figure.get_size_inches. 2919 2920 Removed the copy_bbox_transform from transforms.py; added 2921 shallowcopy methods to all transforms. All transforms already 2922 had deepcopy methods. 2923 2924 FigureManager.resize(width, height): resize the window 2925 specified in pixels 2926 2927 barh: x and y args have been renamed to width and bottom 2928 respectively, and their order has been swapped to maintain 2929 a (position, value) order. 2930 2931 bar and barh: now accept kwarg 'edgecolor'. 2932 2933 bar and barh: The left, height, width and bottom args can 2934 now all be scalars or sequences; see docstring. 2935 2936 barh: now defaults to edge aligned instead of center 2937 aligned bars 2938 2939 bar, barh and hist: Added a keyword arg 'align' that 2940 controls between edge or center bar alignment. 2941 2942 Collections: PolyCollection and LineCollection now accept 2943 vertices or segments either in the original form [(x,y), 2944 (x,y), ...] or as a 2D numerix array, with X as the first column 2945 and Y as the second. Contour and quiver output the numerix 2946 form. The transforms methods Bbox.update() and 2947 Transformation.seq_xy_tups() now accept either form. 2948 2949 Collections: LineCollection is now a ScalarMappable like 2950 PolyCollection, etc. 2951 2952 Specifying a grayscale color as a float is deprecated; use 2953 a string instead, e.g., 0.75 -> '0.75'. 2954 2955 Collections: initializers now accept any mpl color arg, or 2956 sequence of such args; previously only a sequence of rgba 2957 tuples was accepted. 2958 2959 Colorbar: completely new version and api; see docstring. The 2960 original version is still accessible as colorbar_classic, but 2961 is deprecated. 2962 2963 Contourf: "extend" kwarg replaces "clip_ends"; see docstring. 2964 Masked array support added to pcolormesh. 2965 2966 Modified aspect-ratio handling: 2967 Removed aspect kwarg from imshow 2968 Axes methods: 2969 set_aspect(self, aspect, adjustable=None, anchor=None) 2970 set_adjustable(self, adjustable) 2971 set_anchor(self, anchor) 2972 Pylab interface: 2973 axis('image') 2974 2975 Backend developers: ft2font's load_char now takes a flags 2976 argument, which you can OR together from the LOAD_XXX 2977 constants. 2978 2979Changes for 0.86 2980================ 2981 2982:: 2983 2984 Matplotlib data is installed into the matplotlib module. 2985 This is similar to package_data. This should get rid of 2986 having to check for many possibilities in _get_data_path(). 2987 The MATPLOTLIBDATA env key is still checked first to allow 2988 for flexibility. 2989 2990 1) Separated the color table data from cm.py out into 2991 a new file, _cm.py, to make it easier to find the actual 2992 code in cm.py and to add new colormaps. Everything 2993 from _cm.py is imported by cm.py, so the split should be 2994 transparent. 2995 2) Enabled automatic generation of a colormap from 2996 a list of colors in contour; see modified 2997 examples/contour_demo.py. 2998 3) Support for imshow of a masked array, with the 2999 ability to specify colors (or no color at all) for 3000 masked regions, and for regions that are above or 3001 below the normally mapped region. See 3002 examples/image_masked.py. 3003 4) In support of the above, added two new classes, 3004 ListedColormap, and no_norm, to colors.py, and modified 3005 the Colormap class to include common functionality. Added 3006 a clip kwarg to the normalize class. 3007 3008Changes for 0.85 3009================ 3010 3011:: 3012 3013 Made xtick and ytick separate props in rc 3014 3015 made pos=None the default for tick formatters rather than 0 to 3016 indicate "not supplied" 3017 3018 Removed "feature" of minor ticks which prevents them from 3019 overlapping major ticks. Often you want major and minor ticks at 3020 the same place, and can offset the major ticks with the pad. This 3021 could be made configurable 3022 3023 Changed the internal structure of contour.py to a more OO style. 3024 Calls to contour or contourf in axes.py or pylab.py now return 3025 a ContourSet object which contains references to the 3026 LineCollections or PolyCollections created by the call, 3027 as well as the configuration variables that were used. 3028 The ContourSet object is a "mappable" if a colormap was used. 3029 3030 Added a clip_ends kwarg to contourf. From the docstring: 3031 * clip_ends = True 3032 If False, the limits for color scaling are set to the 3033 minimum and maximum contour levels. 3034 True (default) clips the scaling limits. Example: 3035 if the contour boundaries are V = [-100, 2, 1, 0, 1, 2, 100], 3036 then the scaling limits will be [-100, 100] if clip_ends 3037 is False, and [-3, 3] if clip_ends is True. 3038 Added kwargs linewidths, antialiased, and nchunk to contourf. These 3039 are experimental; see the docstring. 3040 3041 Changed Figure.colorbar(): 3042 kw argument order changed; 3043 if mappable arg is a non-filled ContourSet, colorbar() shows 3044 lines instead hof polygons. 3045 if mappable arg is a filled ContourSet with clip_ends=True, 3046 the endpoints are not labelled, so as to give the 3047 correct impression of open-endedness. 3048 3049 Changed LineCollection.get_linewidths to get_linewidth, for 3050 consistency. 3051 3052 3053Changes for 0.84 3054================ 3055 3056:: 3057 3058 Unified argument handling between hlines and vlines. Both now 3059 take optionally a fmt argument (as in plot) and a keyword args 3060 that can be passed onto Line2D. 3061 3062 Removed all references to "data clipping" in rc and lines.py since 3063 these were not used and not optimized. I'm sure they'll be 3064 resurrected later with a better implementation when needed. 3065 3066 'set' removed - no more deprecation warnings. Use 'setp' instead. 3067 3068 Backend developers: Added flipud method to image and removed it 3069 from to_str. Removed origin kwarg from backend.draw_image. 3070 origin is handled entirely by the frontend now. 3071 3072Changes for 0.83 3073================ 3074 3075:: 3076 3077 - Made HOME/.matplotlib the new config dir where the matplotlibrc 3078 file, the ttf.cache, and the tex.cache live. The new default 3079 filenames in .matplotlib have no leading dot and are not hidden. 3080 e.g., the new names are matplotlibrc, tex.cache, and ttffont.cache. 3081 This is how ipython does it so it must be right. 3082 3083 If old files are found, a warning is issued and they are moved to 3084 the new location. 3085 3086 - backends/__init__.py no longer imports new_figure_manager, 3087 draw_if_interactive and show from the default backend, but puts 3088 these imports into a call to pylab_setup. Also, the Toolbar is no 3089 longer imported from WX/WXAgg. New usage: 3090 3091 from backends import pylab_setup 3092 new_figure_manager, draw_if_interactive, show = pylab_setup() 3093 3094 - Moved Figure.get_width_height() to FigureCanvasBase. It now 3095 returns int instead of float. 3096 3097Changes for 0.82 3098================ 3099 3100:: 3101 3102 - toolbar import change in GTKAgg, GTKCairo and WXAgg 3103 3104 - Added subplot config tool to GTK* backends -- note you must now 3105 import the NavigationToolbar2 from your backend of choice rather 3106 than from backend_gtk because it needs to know about the backend 3107 specific canvas -- see examples/embedding_in_gtk2.py. Ditto for 3108 wx backend -- see examples/embedding_in_wxagg.py 3109 3110 3111 - hist bin change 3112 3113 Sean Richards notes there was a problem in the way we created 3114 the binning for histogram, which made the last bin 3115 underrepresented. From his post: 3116 3117 I see that hist uses the linspace function to create the bins 3118 and then uses searchsorted to put the values in their correct 3119 bin. That's all good but I am confused over the use of linspace 3120 for the bin creation. I wouldn't have thought that it does 3121 what is needed, to quote the docstring it creates a "Linear 3122 spaced array from min to max". For it to work correctly 3123 shouldn't the values in the bins array be the same bound for 3124 each bin? (i.e. each value should be the lower bound of a 3125 bin). To provide the correct bins for hist would it not be 3126 something like 3127 3128 def bins(xmin, xmax, N): 3129 if N==1: return xmax 3130 dx = (xmax-xmin)/N # instead of N-1 3131 return xmin + dx*arange(N) 3132 3133 3134 This suggestion is implemented in 0.81. My test script with these 3135 changes does not reveal any bias in the binning 3136 3137 from matplotlib.numerix.mlab import randn, rand, zeros, Float 3138 from matplotlib.mlab import hist, mean 3139 3140 Nbins = 50 3141 Ntests = 200 3142 results = zeros((Ntests,Nbins), typecode=Float) 3143 for i in range(Ntests): 3144 print 'computing', i 3145 x = rand(10000) 3146 n, bins = hist(x, Nbins) 3147 results[i] = n 3148 print mean(results) 3149 3150 3151Changes for 0.81 3152================ 3153 3154:: 3155 3156 - pylab and artist "set" functions renamed to setp to avoid clash 3157 with python2.4 built-in set. Current version will issue a 3158 deprecation warning which will be removed in future versions 3159 3160 - imshow interpolation arguments changes for advanced interpolation 3161 schemes. See help imshow, particularly the interpolation, 3162 filternorm and filterrad kwargs 3163 3164 - Support for masked arrays has been added to the plot command and 3165 to the Line2D object. Only the valid points are plotted. A 3166 "valid_only" kwarg was added to the get_xdata() and get_ydata() 3167 methods of Line2D; by default it is False, so that the original 3168 data arrays are returned. Setting it to True returns the plottable 3169 points. 3170 3171 - contour changes: 3172 3173 Masked arrays: contour and contourf now accept masked arrays as 3174 the variable to be contoured. Masking works correctly for 3175 contour, but a bug remains to be fixed before it will work for 3176 contourf. The "badmask" kwarg has been removed from both 3177 functions. 3178 3179 Level argument changes: 3180 3181 Old version: a list of levels as one of the positional 3182 arguments specified the lower bound of each filled region; the 3183 upper bound of the last region was taken as a very large 3184 number. Hence, it was not possible to specify that z values 3185 between 0 and 1, for example, be filled, and that values 3186 outside that range remain unfilled. 3187 3188 New version: a list of N levels is taken as specifying the 3189 boundaries of N-1 z ranges. Now the user has more control over 3190 what is colored and what is not. Repeated calls to contourf 3191 (with different colormaps or color specifications, for example) 3192 can be used to color different ranges of z. Values of z 3193 outside an expected range are left uncolored. 3194 3195 Example: 3196 Old: contourf(z, [0, 1, 2]) would yield 3 regions: 0-1, 1-2, and >2. 3197 New: it would yield 2 regions: 0-1, 1-2. If the same 3 regions were 3198 desired, the equivalent list of levels would be [0, 1, 2, 3199 1e38]. 3200 3201Changes for 0.80 3202================ 3203 3204:: 3205 3206 - xlim/ylim/axis always return the new limits regardless of 3207 arguments. They now take kwargs which allow you to selectively 3208 change the upper or lower limits while leaving unnamed limits 3209 unchanged. See help(xlim) for example 3210 3211Changes for 0.73 3212================ 3213 3214:: 3215 3216 - Removed deprecated ColormapJet and friends 3217 3218 - Removed all error handling from the verbose object 3219 3220 - figure num of zero is now allowed 3221 3222Changes for 0.72 3223================ 3224 3225:: 3226 3227 - Line2D, Text, and Patch copy_properties renamed update_from and 3228 moved into artist base class 3229 3230 - LineCollecitons.color renamed to LineCollections.set_color for 3231 consistency with set/get introspection mechanism, 3232 3233 - pylab figure now defaults to num=None, which creates a new figure 3234 with a guaranteed unique number 3235 3236 - contour method syntax changed - now it is MATLAB compatible 3237 3238 unchanged: contour(Z) 3239 old: contour(Z, x=Y, y=Y) 3240 new: contour(X, Y, Z) 3241 3242 see http://matplotlib.sf.net/matplotlib.pylab.html#-contour 3243 3244 3245 - Increased the default resolution for save command. 3246 3247 - Renamed the base attribute of the ticker classes to _base to avoid conflict 3248 with the base method. Sitt for subs 3249 3250 - subs=none now does autosubbing in the tick locator. 3251 3252 - New subplots that overlap old will delete the old axes. If you 3253 do not want this behavior, use fig.add_subplot or the axes 3254 command 3255 3256Changes for 0.71 3257================ 3258 3259:: 3260 3261 Significant numerix namespace changes, introduced to resolve 3262 namespace clashes between python built-ins and mlab names. 3263 Refactored numerix to maintain separate modules, rather than 3264 folding all these names into a single namespace. See the following 3265 mailing list threads for more information and background 3266 3267 http://sourceforge.net/mailarchive/forum.php?thread_id=6398890&forum_id=36187 3268 http://sourceforge.net/mailarchive/forum.php?thread_id=6323208&forum_id=36187 3269 3270 3271 OLD usage 3272 3273 from matplotlib.numerix import array, mean, fft 3274 3275 NEW usage 3276 3277 from matplotlib.numerix import array 3278 from matplotlib.numerix.mlab import mean 3279 from matplotlib.numerix.fft import fft 3280 3281 numerix dir structure mirrors numarray (though it is an incomplete 3282 implementation) 3283 3284 numerix 3285 numerix/mlab 3286 numerix/linear_algebra 3287 numerix/fft 3288 numerix/random_array 3289 3290 but of course you can use 'numerix : Numeric' and still get the 3291 symbols. 3292 3293 pylab still imports most of the symbols from Numerix, MLab, fft, 3294 etc, but is more cautious. For names that clash with python names 3295 (min, max, sum), pylab keeps the builtins and provides the numeric 3296 versions with an a* prefix, e.g., (amin, amax, asum) 3297 3298Changes for 0.70 3299================ 3300 3301:: 3302 3303 MplEvent factored into a base class Event and derived classes 3304 MouseEvent and KeyEvent 3305 3306 Removed definct set_measurement in wx toolbar 3307 3308Changes for 0.65.1 3309================== 3310 3311:: 3312 3313 removed add_axes and add_subplot from backend_bases. Use 3314 figure.add_axes and add_subplot instead. The figure now manages the 3315 current axes with gca and sca for get and set current axes. If you 3316 have code you are porting which called, e.g., figmanager.add_axes, you 3317 can now simply do figmanager.canvas.figure.add_axes. 3318 3319Changes for 0.65 3320================ 3321 3322:: 3323 3324 3325 mpl_connect and mpl_disconnect in the MATLAB interface renamed to 3326 connect and disconnect 3327 3328 Did away with the text methods for angle since they were ambiguous. 3329 fontangle could mean fontstyle (obligue, etc) or the rotation of the 3330 text. Use style and rotation instead. 3331 3332Changes for 0.63 3333================ 3334 3335:: 3336 3337 Dates are now represented internally as float days since 0001-01-01, 3338 UTC. 3339 3340 All date tickers and formatters are now in matplotlib.dates, rather 3341 than matplotlib.tickers 3342 3343 converters have been abolished from all functions and classes. 3344 num2date and date2num are now the converter functions for all date 3345 plots 3346 3347 Most of the date tick locators have a different meaning in their 3348 constructors. In the prior implementation, the first argument was a 3349 base and multiples of the base were ticked. e.g., 3350 3351 HourLocator(5) # old: tick every 5 minutes 3352 3353 In the new implementation, the explicit points you want to tick are 3354 provided as a number or sequence 3355 3356 HourLocator(range(0,5,61)) # new: tick every 5 minutes 3357 3358 This gives much greater flexibility. I have tried to make the 3359 default constructors (no args) behave similarly, where possible. 3360 3361 Note that YearLocator still works under the base/multiple scheme. 3362 The difference between the YearLocator and the other locators is 3363 that years are not recurrent. 3364 3365 3366 Financial functions: 3367 3368 matplotlib.finance.quotes_historical_yahoo(ticker, date1, date2) 3369 3370 date1, date2 are now datetime instances. Return value is a list 3371 of quotes where the quote time is a float - days since gregorian 3372 start, as returned by date2num 3373 3374 See examples/finance_demo.py for example usage of new API 3375 3376Changes for 0.61 3377================ 3378 3379:: 3380 3381 canvas.connect is now deprecated for event handling. use 3382 mpl_connect and mpl_disconnect instead. The callback signature is 3383 func(event) rather than func(widget, event) 3384 3385Changes for 0.60 3386================ 3387 3388:: 3389 3390 ColormapJet and Grayscale are deprecated. For backwards 3391 compatibility, they can be obtained either by doing 3392 3393 from matplotlib.cm import ColormapJet 3394 3395 or 3396 3397 from matplotlib.matlab import * 3398 3399 They are replaced by cm.jet and cm.grey 3400 3401Changes for 0.54.3 3402================== 3403 3404:: 3405 3406 removed the set_default_font / get_default_font scheme from the 3407 font_manager to unify customization of font defaults with the rest of 3408 the rc scheme. See examples/font_properties_demo.py and help(rc) in 3409 matplotlib.matlab. 3410 3411Changes for 0.54 3412================ 3413 3414MATLAB interface 3415---------------- 3416 3417dpi 3418~~~ 3419 3420Several of the backends used a PIXELS_PER_INCH hack that I added to 3421try and make images render consistently across backends. This just 3422complicated matters. So you may find that some font sizes and line 3423widths appear different than before. Apologies for the 3424inconvenience. You should set the dpi to an accurate value for your 3425screen to get true sizes. 3426 3427 3428pcolor and scatter 3429~~~~~~~~~~~~~~~~~~ 3430 3431There are two changes to the MATLAB interface API, both involving the 3432patch drawing commands. For efficiency, pcolor and scatter have been 3433rewritten to use polygon collections, which are a new set of objects 3434from matplotlib.collections designed to enable efficient handling of 3435large collections of objects. These new collections make it possible 3436to build large scatter plots or pcolor plots with no loops at the 3437python level, and are significantly faster than their predecessors. 3438The original pcolor and scatter functions are retained as 3439pcolor_classic and scatter_classic. 3440 3441The return value from pcolor is a PolyCollection. Most of the 3442propertes that are available on rectangles or other patches are also 3443available on PolyCollections, e.g., you can say:: 3444 3445 c = scatter(blah, blah) 3446 c.set_linewidth(1.0) 3447 c.set_facecolor('r') 3448 c.set_alpha(0.5) 3449 3450or:: 3451 3452 c = scatter(blah, blah) 3453 set(c, 'linewidth', 1.0, 'facecolor', 'r', 'alpha', 0.5) 3454 3455 3456Because the collection is a single object, you no longer need to loop 3457over the return value of scatter or pcolor to set properties for the 3458entire list. 3459 3460If you want the different elements of a collection to vary on a 3461property, e.g., to have different line widths, see matplotlib.collections 3462for a discussion on how to set the properties as a sequence. 3463 3464For scatter, the size argument is now in points^2 (the area of the 3465symbol in points) as in MATLAB and is not in data coords as before. 3466Using sizes in data coords caused several problems. So you will need 3467to adjust your size arguments accordingly or use scatter_classic. 3468 3469mathtext spacing 3470~~~~~~~~~~~~~~~~ 3471 3472For reasons not clear to me (and which I'll eventually fix) spacing no 3473longer works in font groups. However, I added three new spacing 3474commands which compensate for this '\ ' (regular space), '\/' (small 3475space) and '\hspace{frac}' where frac is a fraction of fontsize in 3476points. You will need to quote spaces in font strings, is:: 3477 3478 title(r'$\rm{Histogram\ of\ IQ:}\ \mu=100,\ \sigma=15$') 3479 3480 3481 3482Object interface - Application programmers 3483------------------------------------------ 3484 3485Autoscaling 3486~~~~~~~~~~~ 3487 3488 The x and y axis instances no longer have autoscale view. These are 3489 handled by axes.autoscale_view 3490 3491Axes creation 3492~~~~~~~~~~~~~ 3493 3494 You should not instantiate your own Axes any more using the OO API. 3495 Rather, create a Figure as before and in place of:: 3496 3497 f = Figure(figsize=(5,4), dpi=100) 3498 a = Subplot(f, 111) 3499 f.add_axis(a) 3500 3501 use:: 3502 3503 f = Figure(figsize=(5,4), dpi=100) 3504 a = f.add_subplot(111) 3505 3506 That is, add_axis no longer exists and is replaced by:: 3507 3508 add_axes(rect, axisbg=defaultcolor, frameon=True) 3509 add_subplot(num, axisbg=defaultcolor, frameon=True) 3510 3511Artist methods 3512~~~~~~~~~~~~~~ 3513 3514 If you define your own Artists, you need to rename the _draw method 3515 to draw 3516 3517Bounding boxes 3518~~~~~~~~~~~~~~ 3519 3520 matplotlib.transforms.Bound2D is replaced by 3521 matplotlib.transforms.Bbox. If you want to construct a bbox from 3522 left, bottom, width, height (the signature for Bound2D), use 3523 matplotlib.transforms.lbwh_to_bbox, as in 3524 3525 bbox = clickBBox = lbwh_to_bbox(left, bottom, width, height) 3526 3527 The Bbox has a different API than the Bound2D. e.g., if you want to 3528 get the width and height of the bbox 3529 3530 OLD:: 3531 width = fig.bbox.x.interval() 3532 height = fig.bbox.y.interval() 3533 3534 New:: 3535 width = fig.bbox.width() 3536 height = fig.bbox.height() 3537 3538 3539 3540 3541Object constructors 3542~~~~~~~~~~~~~~~~~~~ 3543 3544 You no longer pass the bbox, dpi, or transforms to the various 3545 Artist constructors. The old way or creating lines and rectangles 3546 was cumbersome because you had to pass so many attributes to the 3547 Line2D and Rectangle classes not related directly to the geometry 3548 and properties of the object. Now default values are added to the 3549 object when you call axes.add_line or axes.add_patch, so they are 3550 hidden from the user. 3551 3552 If you want to define a custom transformation on these objects, call 3553 o.set_transform(trans) where trans is a Transformation instance. 3554 3555 In prior versions of you wanted to add a custom line in data coords, 3556 you would have to do 3557 3558 l = Line2D(dpi, bbox, x, y, 3559 color = color, 3560 transx = transx, 3561 transy = transy, 3562 ) 3563 3564 now all you need is 3565 3566 l = Line2D(x, y, color=color) 3567 3568 and the axes will set the transformation for you (unless you have 3569 set your own already, in which case it will eave it unchanged) 3570 3571Transformations 3572~~~~~~~~~~~~~~~ 3573 3574 The entire transformation architecture has been rewritten. 3575 Previously the x and y transformations where stored in the xaxis and 3576 yaxis instances. The problem with this approach is it only allows 3577 for separable transforms (where the x and y transformations don't 3578 depend on one another). But for cases like polar, they do. Now 3579 transformations operate on x,y together. There is a new base class 3580 matplotlib.transforms.Transformation and two concrete 3581 implementations, matplotlib.transforms.SeparableTransformation and 3582 matplotlib.transforms.Affine. The SeparableTransformation is 3583 constructed with the bounding box of the input (this determines the 3584 rectangular coordinate system of the input, i.e., the x and y view 3585 limits), the bounding box of the display, and possibly nonlinear 3586 transformations of x and y. The 2 most frequently used 3587 transformations, data coordinates -> display and axes coordinates -> 3588 display are available as ax.transData and ax.transAxes. See 3589 alignment_demo.py which uses axes coords. 3590 3591 Also, the transformations should be much faster now, for two reasons 3592 3593 * they are written entirely in extension code 3594 3595 * because they operate on x and y together, they can do the entire 3596 transformation in one loop. Earlier I did something along the 3597 lines of:: 3598 3599 xt = sx*func(x) + tx 3600 yt = sy*func(y) + ty 3601 3602 Although this was done in numerix, it still involves 6 length(x) 3603 for-loops (the multiply, add, and function evaluation each for x 3604 and y). Now all of that is done in a single pass. 3605 3606 3607 If you are using transformations and bounding boxes to get the 3608 cursor position in data coordinates, the method calls are a little 3609 different now. See the updated examples/coords_demo.py which shows 3610 you how to do this. 3611 3612 Likewise, if you are using the artist bounding boxes to pick items 3613 on the canvas with the GUI, the bbox methods are somewhat 3614 different. You will need to see the updated 3615 examples/object_picker.py. 3616 3617 See unit/transforms_unit.py for many examples using the new 3618 transformations. 3619 3620 3621.. highlight:: none 3622 3623Changes for 0.50 3624================ 3625 3626:: 3627 3628 * refactored Figure class so it is no longer backend dependent. 3629 FigureCanvasBackend takes over the backend specific duties of the 3630 Figure. matplotlib.backend_bases.FigureBase moved to 3631 matplotlib.figure.Figure. 3632 3633 * backends must implement FigureCanvasBackend (the thing that 3634 controls the figure and handles the events if any) and 3635 FigureManagerBackend (wraps the canvas and the window for MATLAB 3636 interface). FigureCanvasBase implements a backend switching 3637 mechanism 3638 3639 * Figure is now an Artist (like everything else in the figure) and 3640 is totally backend independent 3641 3642 * GDFONTPATH renamed to TTFPATH 3643 3644 * backend faceColor argument changed to rgbFace 3645 3646 * colormap stuff moved to colors.py 3647 3648 * arg_to_rgb in backend_bases moved to class ColorConverter in 3649 colors.py 3650 3651 * GD users must upgrade to gd-2.0.22 and gdmodule-0.52 since new gd 3652 features (clipping, antialiased lines) are now used. 3653 3654 * Renderer must implement points_to_pixels 3655 3656 Migrating code: 3657 3658 MATLAB interface: 3659 3660 The only API change for those using the MATLAB interface is in how 3661 you call figure redraws for dynamically updating figures. In the 3662 old API, you did 3663 3664 fig.draw() 3665 3666 In the new API, you do 3667 3668 manager = get_current_fig_manager() 3669 manager.canvas.draw() 3670 3671 See the examples system_monitor.py, dynamic_demo.py, and anim.py 3672 3673 API 3674 3675 There is one important API change for application developers. 3676 Figure instances used subclass GUI widgets that enabled them to be 3677 placed directly into figures. e.g., FigureGTK subclassed 3678 gtk.DrawingArea. Now the Figure class is independent of the 3679 backend, and FigureCanvas takes over the functionality formerly 3680 handled by Figure. In order to include figures into your apps, 3681 you now need to do, for example 3682 3683 # gtk example 3684 fig = Figure(figsize=(5,4), dpi=100) 3685 canvas = FigureCanvasGTK(fig) # a gtk.DrawingArea 3686 canvas.show() 3687 vbox.pack_start(canvas) 3688 3689 If you use the NavigationToolbar, this in now initialized with a 3690 FigureCanvas, not a Figure. The examples embedding_in_gtk.py, 3691 embedding_in_gtk2.py, and mpl_with_glade.py all reflect the new 3692 API so use these as a guide. 3693 3694 All prior calls to 3695 3696 figure.draw() and 3697 figure.print_figure(args) 3698 3699 should now be 3700 3701 canvas.draw() and 3702 canvas.print_figure(args) 3703 3704 Apologies for the inconvenience. This refactorization brings 3705 significant more freedom in developing matplotlib and should bring 3706 better plotting capabilities, so I hope the inconvenience is worth 3707 it. 3708 3709Changes for 0.42 3710================ 3711 3712:: 3713 3714 * Refactoring AxisText to be backend independent. Text drawing and 3715 get_window_extent functionality will be moved to the Renderer. 3716 3717 * backend_bases.AxisTextBase is now text.Text module 3718 3719 * All the erase and reset functionality removed from AxisText - not 3720 needed with double buffered drawing. Ditto with state change. 3721 Text instances have a get_prop_tup method that returns a hashable 3722 tuple of text properties which you can use to see if text props 3723 have changed, e.g., by caching a font or layout instance in a dict 3724 with the prop tup as a key -- see RendererGTK.get_pango_layout in 3725 backend_gtk for an example. 3726 3727 * Text._get_xy_display renamed Text.get_xy_display 3728 3729 * Artist set_renderer and wash_brushes methods removed 3730 3731 * Moved Legend class from matplotlib.axes into matplotlib.legend 3732 3733 * Moved Tick, XTick, YTick, Axis, XAxis, YAxis from matplotlib.axes 3734 to matplotlib.axis 3735 3736 * moved process_text_args to matplotlib.text 3737 3738 * After getting Text handled in a backend independent fashion, the 3739 import process is much cleaner since there are no longer cyclic 3740 dependencies 3741 3742 * matplotlib.matlab._get_current_fig_manager renamed to 3743 matplotlib.matlab.get_current_fig_manager to allow user access to 3744 the GUI window attribute, e.g., figManager.window for GTK and 3745 figManager.frame for wx 3746 3747Changes for 0.40 3748================ 3749 3750:: 3751 3752 - Artist 3753 * __init__ takes a DPI instance and a Bound2D instance which is 3754 the bounding box of the artist in display coords 3755 * get_window_extent returns a Bound2D instance 3756 * set_size is removed; replaced by bbox and dpi 3757 * the clip_gc method is removed. Artists now clip themselves with 3758 their box 3759 * added _clipOn boolean attribute. If True, gc clip to bbox. 3760 3761 - AxisTextBase 3762 * Initialized with a transx, transy which are Transform instances 3763 * set_drawing_area removed 3764 * get_left_right and get_top_bottom are replaced by get_window_extent 3765 3766 - Line2D Patches now take transx, transy 3767 * Initialized with a transx, transy which are Transform instances 3768 3769 - Patches 3770 * Initialized with a transx, transy which are Transform instances 3771 3772 - FigureBase attributes dpi is a DPI instance rather than scalar and 3773 new attribute bbox is a Bound2D in display coords, and I got rid 3774 of the left, width, height, etc... attributes. These are now 3775 accessible as, for example, bbox.x.min is left, bbox.x.interval() 3776 is width, bbox.y.max is top, etc... 3777 3778 - GcfBase attribute pagesize renamed to figsize 3779 3780 - Axes 3781 * removed figbg attribute 3782 * added fig instance to __init__ 3783 * resizing is handled by figure call to resize. 3784 3785 - Subplot 3786 * added fig instance to __init__ 3787 3788 - Renderer methods for patches now take gcEdge and gcFace instances. 3789 gcFace=None takes the place of filled=False 3790 3791 - True and False symbols provided by cbook in a python2.3 compatible 3792 way 3793 3794 - new module transforms supplies Bound1D, Bound2D and Transform 3795 instances and more 3796 3797 - Changes to the MATLAB helpers API 3798 3799 * _matlab_helpers.GcfBase is renamed by Gcf. Backends no longer 3800 need to derive from this class. Instead, they provide a factory 3801 function new_figure_manager(num, figsize, dpi). The destroy 3802 method of the GcfDerived from the backends is moved to the derived 3803 FigureManager. 3804 3805 * FigureManagerBase moved to backend_bases 3806 3807 * Gcf.get_all_figwins renamed to Gcf.get_all_fig_managers 3808 3809 Jeremy: 3810 3811 Make sure to self._reset = False in AxisTextWX._set_font. This was 3812 something missing in my backend code. 3813
