1.. _whats-new-1-3:
2
3New in matplotlib 1.3
4=====================
5
6.. contents:: Table of Contents
7   :depth: 2
8
9.. note::
10
11   matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3
12
13New in 1.3.1
14------------
15
161.3.1 is a bugfix release, primarily dealing with improved setup and
17handling of dependencies, and correcting and enhancing the
18documentation.
19
20The following changes were made in 1.3.1 since 1.3.0.
21
22Enhancements
23````````````
24
25- Added a context manager for creating multi-page pdfs (see
26  `matplotlib.backends.backend_pdf.PdfPages`).
27
28- The WebAgg backend should now have lower latency over heterogeneous
29  Internet connections.
30
31Bug fixes
32`````````
33
34- Histogram plots now contain the endline.
35
36- Fixes to the Molleweide projection.
37
38- Handling recent fonts from Microsoft and Macintosh-style fonts with
39  non-ascii metadata is improved.
40
41- Hatching of fill between plots now works correctly in the PDF
42  backend.
43
44- Tight bounding box support now works in the PGF backend.
45
46- Transparent figures now display correctly in the Qt4Agg backend.
47
48- Drawing lines from one subplot to another now works.
49
50- Unit handling on masked arrays has been improved.
51
52Setup and dependencies
53``````````````````````
54
55- Now works with any version of pyparsing 1.5.6 or later, without displaying
56  hundreds of warnings.
57
58- Now works with 64-bit versions of Ghostscript on MS-Windows.
59
60- When installing from source into an environment without Numpy, Numpy
61  will first be downloaded and built and then used to build
62  matplotlib.
63
64- Externally installed backends are now always imported using a
65  fully-qualified path to the module.
66
67- Works with newer version of wxPython.
68
69- Can now build with a PyCXX installed globally on the system from source.
70
71- Better detection of Gtk3 dependencies.
72
73Testing
74```````
75
76- Tests should now work in non-English locales.
77
78- PEP8 conformance tests now report on locations of issues.
79
80
81New plotting features
82---------------------
83
84`~.xkcd`-style sketch plotting
85``````````````````````````````
86To give your plots a sense of authority that they may be missing,
87Michael Droettboom (inspired by the work of many others in
88:ghpull:`1329`) has added an `xkcd-style <https://xkcd.com/>`__ sketch
89plotting mode.  To use it, simply call `matplotlib.pyplot.xkcd`
90before creating your plot. For really fine control, it is also possible
91to modify each artist's sketch parameters individually with
92:meth:`matplotlib.artist.Artist.set_sketch_params`.
93
94.. figure:: ../../gallery/showcase/images/sphx_glr_xkcd_001.png
95   :target: ../../gallery/showcase/xkcd.html
96   :align: center
97   :scale: 50
98
99   xkcd
100
101Updated Axes3D.contour methods
102------------------------------
103Damon McDougall updated the
104:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontour` and
105:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontourf` methods to allow 3D
106contour plots on abitrary unstructured user-specified triangulations.
107
108.. figure:: ../../gallery/mplot3d/images/sphx_glr_tricontour3d_001.png
109   :target: ../../gallery/mplot3d/tricontour3d.html
110   :align: center
111   :scale: 50
112
113   Tricontour3d
114
115New eventplot plot type
116```````````````````````
117Todd Jennings added a :func:`~matplotlib.pyplot.eventplot` function to
118create multiple rows or columns of identical line segments
119
120.. figure:: ../../gallery/lines_bars_and_markers/images/sphx_glr_eventplot_demo_001.png
121   :target: ../../gallery/lines_bars_and_markers/eventplot_demo.html
122   :align: center
123   :scale: 50
124
125   Eventplot Demo
126
127As part of this feature, there is a new
128:class:`~matplotlib.collections.EventCollection` class that allows for
129plotting and manipulating rows or columns of identical line segments.
130
131Triangular grid interpolation
132`````````````````````````````
133Geoffroy Billotey and Ian Thomas added classes to perform
134interpolation within triangular grids:
135(:class:`~matplotlib.tri.LinearTriInterpolator` and
136:class:`~matplotlib.tri.CubicTriInterpolator`) and a utility class to
137find the triangles in which points lie
138(:class:`~matplotlib.tri.TrapezoidMapTriFinder`).  A helper class to
139perform mesh refinement and smooth contouring was also added
140(:class:`~matplotlib.tri.UniformTriRefiner`).  Finally, a class
141implementing some basic tools for triangular mesh improvement was
142added (:class:`~matplotlib.tri.TriAnalyzer`).
143
144.. figure:: ../../gallery/images_contours_and_fields/images/sphx_glr_tricontour_smooth_user_001.png
145   :target: ../../gallery/images_contours_and_fields/tricontour_smooth_user.html
146   :align: center
147   :scale: 50
148
149   Tricontour Smooth User
150
151Baselines for stackplot
152```````````````````````
153Till Stensitzki added non-zero baselines to
154:func:`~matplotlib.pyplot.stackplot`.  They may be symmetric or
155weighted.
156
157.. figure:: ../../gallery/lines_bars_and_markers/images/sphx_glr_stackplot_demo_001.png
158   :target: ../../gallery/lines_bars_and_markers/stackplot_demo.html
159   :align: center
160   :scale: 50
161
162   Stackplot Demo2
163
164Rectangular colorbar extensions
165```````````````````````````````
166Andrew Dawson added a new keyword argument *extendrect* to
167:meth:`~matplotlib.pyplot.colorbar` to optionally make colorbar
168extensions rectangular instead of triangular.
169
170More robust boxplots
171````````````````````
172Paul Hobson provided a fix to the :func:`~matplotlib.pyplot.boxplot`
173method that prevent whiskers from being drawn inside the box for
174oddly distributed data sets.
175
176Calling subplot() without arguments
177```````````````````````````````````
178A call to :func:`~matplotlib.pyplot.subplot` without any arguments now
179acts the same as ``subplot(111)`` or ``subplot(1, 1, 1)`` -- it creates one
180axes for the whole figure. This was already the behavior for both
181:func:`~matplotlib.pyplot.axes` and
182:func:`~matplotlib.pyplot.subplots`, and now this consistency is
183shared with :func:`~matplotlib.pyplot.subplot`.
184
185Drawing
186-------
187
188Independent alpha values for face and edge colors
189`````````````````````````````````````````````````
190Wes Campaigne modified how :class:`~matplotlib.patches.Patch` objects are
191drawn such that (for backends supporting transparency) you can set different
192alpha values for faces and edges, by specifying their colors in RGBA format.
193Note that if you set the alpha attribute for the patch object (e.g. using
194:meth:`~matplotlib.patches.Patch.set_alpha` or the ``alpha`` keyword
195argument), that value will override the alpha components set in both the
196face and edge colors.
197
198Path effects on lines
199`````````````````````
200Thanks to Jae-Joon Lee, path effects now also work on plot lines.
201
202.. figure:: ../../gallery/misc/images/sphx_glr_patheffect_demo_001.png
203   :target: ../../gallery/misc/patheffect_demo.html
204   :align: center
205   :scale: 50
206
207   Patheffect Demo
208
209Easier creation of colormap and normalizer for levels with colors
210`````````````````````````````````````````````````````````````````
211Phil Elson added the :func:`matplotlib.colors.from_levels_and_colors`
212function to easily create a colormap and normalizer for representation
213of discrete colors for plot types such as
214:func:`matplotlib.pyplot.pcolormesh`, with a similar interface to that
215of `matplotlib.pyplot.contourf`.
216
217Full control of the background color
218````````````````````````````````````
219Wes Campaigne and Phil Elson fixed the Agg backend such that PNGs are
220now saved with the correct background color when
221``fig.patch.get_alpha()`` is not 1.
222
223Improved ``bbox_inches="tight"`` functionality
224``````````````````````````````````````````````
225Passing ``bbox_inches="tight"`` through to `.pyplot.savefig` now takes
226into account *all* artists on a figure - this was previously not the
227case and led to several corner cases which did not function as
228expected.
229
230Initialize a rotated rectangle
231``````````````````````````````
232Damon McDougall extended the :class:`~matplotlib.patches.Rectangle`
233constructor to accept an *angle* kwarg, specifying the rotation of a
234rectangle in degrees.
235
236Text
237----
238
239Anchored text support
240`````````````````````
241The SVG and pgf backends are now able to save text alignment
242information to their output formats. This allows to edit text elements
243in saved figures, using Inkscape for example, while preserving their
244intended position. For SVG please note that you'll have to disable
245the default text-to-path conversion (``mpl.rc('svg',
246fonttype='none')``).
247
248Better vertical text alignment and multi-line text
249``````````````````````````````````````````````````
250The vertical alignment of text is now consistent across backends.  You
251may see small differences in text placement, particularly with rotated
252text.
253
254If you are using a custom backend, note that the `~.RendererBase.draw_text` renderer
255method is now passed the location of the baseline, not the location of
256the bottom of the text bounding box.
257
258Multi-line text will now leave enough room for the height of very tall
259or very low text, such as superscripts and subscripts.
260
261Left and right side axes titles
262```````````````````````````````
263Andrew Dawson added the ability to add axes titles flush with the left
264and right sides of the top of the axes using a new keyword argument
265*loc* to :func:`~matplotlib.pyplot.title`.
266
267Improved manual contour plot label positioning
268``````````````````````````````````````````````
269Brian Mattern modified the manual contour plot label positioning code
270to interpolate along line segments and find the actual closest point
271on a contour to the requested position. Previously, the closest path
272vertex was used, which, in the case of straight contours was sometimes
273quite distant from the requested location. Much more precise label
274positioning is now possible.
275
276Configuration (rcParams)
277------------------------
278
279Quickly find rcParams
280`````````````````````
281Phil Elson made it easier to search for rcParameters by passing a
282valid regular expression to :func:`matplotlib.RcParams.find_all`.
283:class:`matplotlib.RcParams` now also has a pretty repr and str
284representation so that search results are printed prettily:
285
286    >>> import matplotlib
287    >>> print(matplotlib.rcParams.find_all('\.size'))
288    RcParams({'font.size': 12,
289              'xtick.major.size': 4,
290              'xtick.minor.size': 2,
291              'ytick.major.size': 4,
292              'ytick.minor.size': 2})
293
294``axes.xmargin`` and ``axes.ymargin`` added to rcParams
295```````````````````````````````````````````````````````
296:rc:`axes.xmargin` and :rc:`axes.ymargin` were added
297to configure the default margins used.  Previously they were
298hard-coded to default to 0, default value of both rcParam values is 0.
299
300Changes to font rcParams
301````````````````````````
302The `font.*` rcParams now affect only text objects created after the
303rcParam has been set, and will not retroactively affect already
304existing text objects.  This brings their behavior in line with most
305other rcParams.
306
307Added :rc:`savefig.jpeg_quality`
308````````````````````````````````
309rcParam value :rc:`savefig.jpeg_quality` was added so that the user can
310configure the default quality used when a figure is written as a JPEG.
311The default quality is 95; previously, the default quality was 75.
312This change minimizes the artifacting inherent in JPEG images,
313particularly with images that have sharp changes in color as plots
314often do.
315
316Backends
317--------
318
319WebAgg backend
320``````````````
321Michael Droettboom, Phil Elson and others have developed a new
322backend, WebAgg, to display figures in a web browser.  It works with
323animations as well as being fully interactive.
324
325.. image:: /_static/webagg_screenshot.png
326
327Future versions of matplotlib will integrate this backend with the
328IPython notebook for a fully web browser based plotting frontend.
329
330Remember save directory
331```````````````````````
332Martin Spacek made the save figure dialog remember the last directory
333saved to. The default is configurable with the new :rc:`savefig.directory`
334rcParam in :file:`matplotlibrc`.
335
336Documentation and examples
337--------------------------
338
339Numpydoc docstrings
340```````````````````
341Nelle Varoquaux has started an ongoing project to convert matplotlib's
342docstrings to numpydoc format.  See `MEP10
343<https://github.com/matplotlib/matplotlib/wiki/Mep10>`__ for more
344information.
345
346Example reorganization
347``````````````````````
348Tony Yu has begun work reorganizing the examples into more meaningful
349categories.  The new gallery page is the fruit of this ongoing work.
350See `MEP12 <https://github.com/matplotlib/matplotlib/wiki/MEP12>`__ for
351more information.
352
353Examples now use subplots()
354```````````````````````````
355For the sake of brevity and clarity, most of the :ref:`examples
356<examples-index>` now use the newer
357:func:`~matplotlib.pyplot.subplots`, which creates a figure and one
358(or multiple) axes object(s) in one call. The old way involved a call
359to :func:`~matplotlib.pyplot.figure`, followed by one (or multiple)
360:func:`~matplotlib.pyplot.subplot` calls.
361
362Infrastructure
363--------------
364
365Housecleaning
366`````````````
367A number of features that were deprecated in 1.2 or earlier, or have
368not been in a working state for a long time have been removed.
369Highlights include removing the Qt version 3 backends, and the FltkAgg
370and Emf backends.  See :ref:`changes_in_1_3` for a complete list.
371
372New setup script
373````````````````
374matplotlib 1.3 includes an entirely rewritten setup script.  We now
375ship fewer dependencies with the tarballs and installers themselves.
376Notably, pytz_, dateutil_, pyparsing_ and six_ are no longer
377included with matplotlib.  You can either install them manually first,
378or let pip_ install them as dependencies along with matplotlib.  It
379is now possible to not include certain subcomponents, such as the unit
380test data, in the install.  See :file:`setup.cfg.template` for more
381information.
382
383.. _dateutil: https://pypi.org/project/python-dateutil/
384.. _pip: https://pypi.org/project/pip/
385.. _pyparsing: https://pypi.org/project/pyparsing/
386.. _pytz: https://pypi.org/project/pytz/
387.. _six: https://pypi.org/project/six/
388
389XDG base directory support
390``````````````````````````
391On Linux, matplotlib now uses the `XDG base directory specification
392<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_ to
393find the :file:`matplotlibrc` configuration file. :file:`matplotlibrc` should
394now be kept in :file:`~/.config/matplotlib`, rather than :file:`~/.matplotlib`.
395If your configuration is found in the old location, it will still be used, but
396a warning will be displayed.
397
398Catch opening too many figures using pyplot
399```````````````````````````````````````````
400Figures created through `.pyplot.figure` are retained until they are
401explicitly closed.  It is therefore common for new users of matplotlib
402to run out of memory when creating a large series of figures in a loop
403without closing them.
404
405matplotlib will now display a `RuntimeWarning` when too many figures
406have been opened at once.  By default, this is displayed for 20 or
407more figures, but the exact number may be controlled using the
408``figure.max_open_warning`` rcParam.
409