.. _whats-new:

************************

What's new in matplotlib

************************

This page just covers the highlights -- for the full story, see the

`CHANGELOG <http://matplotlib.org/_static/CHANGELOG>`_

For a list of all of the issues and pull requests since the last

revision, see the :ref:`github-stats`.

.. note::

matplotlib 1.4 supports Python 2.6, 2.7, 3.3, and 3.4

matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3

matplotlib 1.2 supports Python 2.6, 2.7, and 3.1

matplotlib 1.1 supports Python 2.4 to 2.7

.. contents:: Table of Contents

:depth: 3

.. _whats-new-1-4:

new in matplotlib-1.4

=====================

Thomas A. Caswell served as the release manager for the 1.4 release.

New colormap

------------

In heatmaps, a green-to-red spectrum is often used to indicate intensity of

activity, but this can be problematic for the red/green colorblind. A new,

colorblind-friendly colormap is now available at :class:`matplotlib.cm.Wistia`.

This colormap maintains the red/green symbolism while achieving deuteranopic

legibility through brightness variations. See

`here <https://github.com/wistia/heatmap-palette>`_

for more information.

The nbagg backend

-----------------

Phil Elson added a new backend, named "nbagg", which enables interactive

figures in a live IPython notebook session. The backend makes use of the

infrastructure developed for the webagg backend, which itself gives

standalone server backed interactive figures in the browser, however nbagg

does not require a dedicated matplotlib server as all communications are

handled through the IPython Comm machinery.

As with other backends nbagg can be enabled inside the IPython notebook with::

import matplotlib

matplotlib.use('nbagg')

Once figures are created and then subsequently shown, they will placed in an

interactive widget inside the notebook allowing panning and zooming in the

same way as any other matplotlib backend. Because figures require a connection

to the IPython notebook server for their interactivity, once the notebook is

saved, each figure will be rendered as a static image - thus allowing

non-interactive viewing of figures on services such as

`nbviewer <http://nbviewer.ipython.org/>`_.

New plotting features

---------------------

Power-law normalization

```````````````````````

Ben Gamari added a power-law normalization method,

:class:`~matplotlib.colors.PowerNorm`. This class maps a range of

values to the interval [0,1] with power-law scaling with the exponent

provided by the constructor's `gamma` argument. Power law normalization

can be useful for, e.g., emphasizing small populations in a histogram.

Fully customizable boxplots

```````````````````````````

Paul Hobson overhauled the :func:`~matplotlib.pyplot.boxplot` method such

that it is now completely customizable in terms of the styles and positions

of the individual artists. Under the hood, :func:`~matplotlib.pyplot.boxplot`

relies on a new function (:func:`~matplotlib.cbook.boxplot_stats`), which

accepts any data structure currently compatible with

:func:`~matplotlib.pyplot.boxplot`, and returns a list of dictionaries

containing the positions for each element of the boxplots. Then

a second method, :func:`~matplotlib.Axes.bxp` is called to draw the boxplots

based on the stats.

The :func:`~matplotlib.pyplot.boxplot` function can be used as before to

generate boxplots from data in one step. But now the user has the

flexibility to generate the statistics independently, or to modify the

output of :func:`~matplotlib.cbook.boxplot_stats` prior to plotting

with :func:`~matplotlib.Axes.bxp`.

Lastly, each artist (e.g., the box, outliers, cap, notches) can now be

toggled on or off and their styles can be passed in through individual

kwargs. See the examples:

:ref:`statistics-boxplot_demo` and

:ref:`statistics-bxp_demo`

Added a bool kwarg, :code:`manage_xticks`, which if False disables the management

of the ticks and limits on the x-axis by :func:`~matplotlib.axes.Axes.bxp`.

Support for datetime axes in 2d plots

`````````````````````````````````````

Andrew Dawson added support for datetime axes to

:func:`~matplotlib.pyplot.contour`, :func:`~matplotlib.pyplot.contourf`,

:func:`~matplotlib.pyplot.pcolormesh` and :func:`~matplotlib.pyplot.pcolor`.

Support for additional spectrum types

`````````````````````````````````````

Todd Jennings added support for new types of frequency spectrum plots:

:func:`~matplotlib.pyplot.magnitude_spectrum`,

:func:`~matplotlib.pyplot.phase_spectrum`, and

:func:`~matplotlib.pyplot.angle_spectrum`, as well as corresponding functions

in mlab.

He also added these spectrum types to :func:`~matplotlib.pyplot.specgram`,

as well as adding support for linear scaling there (in addition to the

existing dB scaling). Support for additional spectrum types was also added to

:func:`~matplotlib.mlab.specgram`.

He also increased the performance for all of these functions and plot types.

Support for detrending and windowing 2D arrays in mlab

``````````````````````````````````````````````````````

Todd Jennings added support for 2D arrays in the

:func:`~matplotlib.mlab.detrend_mean`, :func:`~matplotlib.mlab.detrend_none`,

and :func:`~matplotlib.mlab.detrend`, as well as adding

:func:`~matplotlib.mlab.apply_window` which support windowing 2D arrays.

Support for strides in mlab

```````````````````````````

Todd Jennings added some functions to mlab to make it easier to use numpy

strides to create memory-efficient 2D arrays. This includes

:func:`~matplotlib.mlab.stride_repeat`, which repeats an array to create a 2D

array, and :func:`~matplotlib.mlab.stride_windows`, which uses a moving window

to create a 2D array from a 1D array.

Formatter for new-style formatting strings

``````````````````````````````````````````

Added `FormatStrFormatterNewStyle` which does the same job as

`FormatStrFormatter`, but accepts new-style formatting strings

instead of printf-style formatting strings

Consistent grid sizes in streamplots

````````````````````````````````````

:func:`~matplotlib.pyplot.streamplot` uses a base grid size of 30x30 for both

`density=1` and `density=(1, 1)`. Previously a grid size of 30x30 was used for

`density=1`, but a grid size of 25x25 was used for `density=(1, 1)`.

Get a list of all tick labels (major and minor)

```````````````````````````````````````````````

Added the `kwarg` 'which' to :func:`~matplotlib.Axes.get_xticklabels`,

:func:`~matplotlib.Axes.get_yticklabels` and

:func:`~matplotlib.Axis.get_ticklabels`. 'which' can be 'major', 'minor', or

'both' select which ticks to return, like

:func:`~matplotlib.Axis.set_ticks_position`. If 'which' is `None` then the old

behaviour (controlled by the bool `minor`).

Separate horizontal/vertical axes padding support in ImageGrid

``````````````````````````````````````````````````````````````

The `kwarg` 'axes_pad' to :class:`mpl_toolkits.axes_grid1.ImageGrid` can now

be a tuple if separate horizontal/vertical padding is needed.

This is supposed to be very helpful when you have a labelled legend next to

every subplot and you need to make some space for legend's labels.

Support for skewed transformations

``````````````````````````````````

The :class:`~matplotlib.transforms.Affine2D` gained additional methods

`skew` and `skew_deg` to create skewed transformations. Additionally,

matplotlib internals were cleaned up to support using such transforms in

:class:`~matplotlib.Axes`. This transform is important for some plot types,

specifically the Skew-T used in meteorology.

.. plot:: mpl_examples/api/skewt.py

Support for specifying properties of wedge and text in pie charts.

``````````````````````````````````````````````````````````````````

Added the `kwargs` 'wedgeprops' and 'textprops' to :func:`~matplotlib.Axes.pie`

to accept properties for wedge and text objects in a pie. For example, one can

specify wedgeprops = {'linewidth':3} to specify the width of the borders of

the wedges in the pie. For more properties that the user can specify, look at

the docs for the wedge and text objects.

Fixed the direction of errorbar upper/lower limits

``````````````````````````````````````````````````

Larry Bradley fixed the :func:`~matplotlib.pyplot.errorbar` method such

that the upper and lower limits (*lolims*, *uplims*, *xlolims*,

*xuplims*) now point in the correct direction.

More consistent add-object API for Axes

```````````````````````````````````````

Added the Axes method :meth:`~matplotlib.axes.Axes.add_image` to put image

handling on a par with artists, collections, containers, lines, patches,

and tables.

Violin Plots

````````````

Per Parker, Gregory Kelsie, Adam Ortiz, Kevin Chan, Geoffrey Lee, Deokjae

Donald Seo, and Taesu Terry Lim added a basic implementation for violin

plots. Violin plots can be used to represent the distribution of sample data.

They are similar to box plots, but use a kernel density estimation function to

present a smooth approximation of the data sample used. The added features are:

:func:`~matplotlib.Axes.violin` - Renders a violin plot from a collection of

statistics.

:func:`~matplotlib.cbook.violin_stats` - Produces a collection of statistics

suitable for rendering a violin plot.

:func:`~matplotlib.pyplot.violinplot` - Creates a violin plot from a set of

sample data. This method makes use of :func:`~matplotlib.cbook.violin_stats`

to process the input data, and :func:`~matplotlib.cbook.violin_stats` to

do the actual rendering. Users are also free to modify or replace the output of

:func:`~matplotlib.cbook.violin_stats` in order to customize the violin plots

to their liking.

This feature was implemented for a software engineering course at the

University of Toronto, Scarborough, run in Winter 2014 by Anya Tafliovich.

More `markevery` options to show only a subset of markers

`````````````````````````````````````````````````````````

Rohan Walker extended the `markevery` property in

:class:`~matplotlib.lines.Line2D`. You can now specify a subset of markers to

show with an int, slice object, numpy fancy indexing, or float. Using a float

shows markers at approximately equal display-coordinate-distances along the

line.

Added size related functions to specialized `Collections`

`````````````````````````````````````````````````````````

Added the `get_size` and `set_size` functions to control the size of

elements of specialized collections (

:class:`~matplotlib.collections.AsteriskPolygonCollection`

:class:`~matplotlib.collections.BrokenBarHCollection`

:class:`~matplotlib.collections.CircleCollection`

:class:`~matplotlib.collections.PathCollection`

:class:`~matplotlib.collections.PolyCollection`

:class:`~matplotlib.collections.RegularPolyCollection`

:class:`~matplotlib.collections.StarPolygonCollection`).

Fixed the mouse coordinates giving the wrong theta value in Polar graph

```````````````````````````````````````````````````````````````````````

Added code to

:func:`~matplotlib.InvertedPolarTransform.transform_non_affine`

to ensure that the calculated theta value was between the range of 0 and 2 * pi

since the problem was that the value can become negative after applying the

direction and rotation to the theta calculation.

Simple quiver plot for mplot3d toolkit

``````````````````````````````````````

A team of students in an *Engineering Large Software Systems* course, taught

by Prof. Anya Tafliovich at the University of Toronto, implemented a simple

version of a quiver plot in 3D space for the mplot3d toolkit as one of their

term project. This feature is documented in :func:`~mpl_toolkits.mplot3d.Axes3D.quiver`.

The team members are: Ryan Steve D'Souza, Victor B, xbtsw, Yang Wang, David,

Caradec Bisesar and Vlad Vassilovski.

.. plot:: mpl_examples/mplot3d/quiver3d_demo.py

polar-plot r-tick locations

```````````````````````````

Added the ability to control the angular position of the r-tick labels

on a polar plot via :func:`~matplotlib.Axes.axes.set_rlabel_position`.

Date handling

-------------

n-d array support for date conversion

``````````````````````````````````````

Andrew Dawson added support for n-d array handling to

:func:`matplotlib.dates.num2date`, :func:`matplotlib.dates.date2num`

and :func:`matplotlib.dates.datestr2num`. Support is also added to the unit

conversion interfaces :class:`matplotlib.dates.DateConverter` and

:class:`matplotlib.units.Registry`.

Configuration (rcParams)

------------------------

``savefig.transparent`` added

`````````````````````````````

Controls whether figures are saved with a transparent

background by default. Previously `savefig` always defaulted

to a non-transparent background.

``axes.titleweight``

````````````````````

Added rcParam to control the weight of the title

``axes.formatter.useoffset`` added

``````````````````````````````````

Controls the default value of `useOffset` in `ScalarFormatter`. If

`True` and the data range is much smaller than the data average, then

an offset will be determined such that the tick labels are

meaningful. If `False` then the full number will be formatted in all

conditions.

``nbagg.transparent`` added

`````````````````````````````

Controls whether nbagg figures have a transparent

background. ``nbagg.transparent`` is ``True`` by default.

XDG compliance

``````````````

Matplotlib now looks for configuration files (both rcparams and style) in XDG

compliant locations.

``style`` package added

-----------------------

You can now easily switch between different styles using the new ``style``

package::

>>> from matplotlib import style

>>> style.use('dark_background')

Subsequent plots will use updated colors, sizes, etc. To list all available

styles, use::

>>> print style.available

You can add your own custom ``<style name>.mplstyle`` files to

``~/.matplotlib/stylelib`` or call ``use`` with a URL pointing to a file with

``matplotlibrc`` settings.

*Note that this is an experimental feature*, and the interface may change as

users test out this new feature.

Backends

--------

Qt5 backend

```````````

Martin Fitzpatrick and Tom Badran implemented a Qt5 backend. The differences

in namespace locations between Qt4 and Qt5 was dealt with by shimming

Qt4 to look like Qt5, thus the Qt5 implementation is the primary implementation.

Backwards compatibility for Qt4 is maintained by wrapping the Qt5 implementation.

The Qt5Agg backend currently does not work with IPython's %matplotlib magic.

The 1.4.0 release has a known bug where the toolbar is broken. This can be

fixed by: ::

cd path/to/installed/matplotlib

wget https://github.com/matplotlib/matplotlib/pull/3322.diff

# unix2dos 3322.diff (if on windows to fix line endings)

patch -p2 < 3322.diff

Qt4 backend

```````````

Rudolf Höfler changed the appearance of the subplottool. All sliders are

vertically arranged now, buttons for tight layout and reset were

added. Furthermore, the the subplottool is now implemented as a modal

dialog. It was previously a QMainWindow, leaving the SPT open if one closed the

plot window.

In the figure options dialog one can now choose to (re-)generate a simple

automatic legend. Any explicitly set legend entries will be lost, but changes to

the curves' label, linestyle, et cetera will now be updated in the legend.

Interactive performance of the Qt4 backend has been dramatically improved

under windows.

The mapping of key-signals from Qt to values matplotlib understands

was greatly improved (For both Qt4 and Qt5).

Cairo backends

``````````````

The Cairo backends are now able to use the `cairocffi bindings

<https://github.com/SimonSapin/cairocffi>`__ which are more actively

maintained than the `pycairo bindings

<http://cairographics.org/pycairo/>`__.

Gtk3Agg backend

```````````````

The Gtk3Agg backend now works on Python 3.x, if the `cairocffi

bindings <https://github.com/SimonSapin/cairocffi>`__ are installed.

PDF backend

```````````

Added context manager for saving to multi-page PDFs.

Text

----

Text URLs supported by SVG backend

``````````````````````````````````

The `svg` backend will now render :class:`~matplotlib.text.Text` objects'

url as a link in output SVGs. This allows one to make clickable text in

saved figures using the url kwarg of the :class:`~matplotlib.text.Text`

class.

Anchored sizebar font

`````````````````````

Added the ``fontproperties`` kwarg to

:class:`~matplotilb.mpl_toolkits.axes_grid.anchored_artists.AnchoredSizeBar` to

control the font properties.

Sphinx extensions

-----------------

The ``:context:`` directive in the `~matplotlib.sphinxext.plot_directive`

Sphinx extension can now accept an optional ``reset`` setting, which will

cause the context to be reset. This allows more than one distinct context to

be present in documentation. To enable this option, use ``:context: reset``

instead of ``:context:`` any time you want to reset the context.

Legend and PathEffects documentation

------------------------------------

The :ref:`plotting-guide-legend` and :ref:`patheffects-guide` have both been

updated to better reflect the full potential of each of these powerful

features.

Widgets

-------

Span Selector

`````````````

Added an option ``span_stays`` to the

:class:`~matplotlib.widgets.SpanSelector` which makes the selector

rectangle stay on the axes after you release the mouse.

GAE integration

---------------

Matplotlib will now run on google app engine.

.. _whats-new-1-3:

new in matplotlib-1.3

=====================

New in 1.3.1

------------

1.3.1 is a bugfix release, primarily dealing with improved setup and

handling of dependencies, and correcting and enhancing the

documentation.

The following changes were made in 1.3.1 since 1.3.0.

Enhancements

````````````

- Added a context manager for creating multi-page pdfs (see

`matplotlib.backends.backend_pdf.PdfPages`).

- The WebAgg backend should now have lower latency over heterogeneous

Internet connections.

Bug fixes

`````````

- Histogram plots now contain the endline.

- Fixes to the Molleweide projection.

- Handling recent fonts from Microsoft and Macintosh-style fonts with

non-ascii metadata is improved.

- Hatching of fill between plots now works correctly in the PDF

backend.

- Tight bounding box support now works in the PGF backend.

- Transparent figures now display correctly in the Qt4Agg backend.

- Drawing lines from one subplot to another now works.

- Unit handling on masked arrays has been improved.

Setup and dependencies

``````````````````````

- Now works with any version of pyparsing 1.5.6 or later, without displaying

hundreds of warnings.

- Now works with 64-bit versions of Ghostscript on MS-Windows.

- When installing from source into an environment without Numpy, Numpy

will first be downloaded and built and then used to build

matplotlib.

- Externally installed backends are now always imported using a

fully-qualified path to the module.

- Works with newer version of wxPython.

- Can now build with a PyCXX installed globally on the system from source.

- Better detection of Gtk3 dependencies.

Testing

```````

- Tests should now work in non-English locales.

- PEP8 conformance tests now report on locations of issues.

New plotting features

---------------------

`xkcd`-style sketch plotting

````````````````````````````

To give your plots a sense of authority that they may be missing,

Michael Droettboom (inspired by the work of many others in

:ghpull:`1329`) has added an `xkcd-style <http://xkcd.com/>`_ sketch

plotting mode. To use it, simply call :func:`matplotlib.pyplot.xkcd`

before creating your plot. For really fine control, it is also possible

to modify each artist's sketch parameters individually with

:meth:`matplotlib.artist.Artist.set_sketch_params`.

.. plot:: mpl_examples/showcase/xkcd.py

Updated Axes3D.contour methods

------------------------------

Damon McDougall updated the

:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontour` and

:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.tricontourf` methods to allow 3D

contour plots on abitrary unstructured user-specified triangulations.

.. plot:: mpl_examples/mplot3d/tricontour3d_demo.py

New eventplot plot type

```````````````````````

Todd Jennings added a :func:`~matplotlib.pyplot.eventplot` function to

create multiple rows or columns of identical line segments

.. plot:: mpl_examples/pylab_examples/eventplot_demo.py

As part of this feature, there is a new

:class:`~matplotlib.collections.EventCollection` class that allows for

plotting and manipulating rows or columns of identical line segments.

Triangular grid interpolation

`````````````````````````````

Geoffroy Billotey and Ian Thomas added classes to perform

interpolation within triangular grids:

(:class:`~matplotlib.tri.LinearTriInterpolator` and

:class:`~matplotlib.tri.CubicTriInterpolator`) and a utility class to

find the triangles in which points lie

(:class:`~matplotlib.tri.TrapezoidMapTriFinder`). A helper class to

perform mesh refinement and smooth contouring was also added

(:class:`~matplotlib.tri.UniformTriRefiner`). Finally, a class

implementing some basic tools for triangular mesh improvement was

added (:class:`~matplotlib.tri.TriAnalyzer`).

.. plot:: mpl_examples/pylab_examples/tricontour_smooth_user.py

Baselines for stackplot

```````````````````````

Till Stensitzki added non-zero baselines to

:func:`~matplotlib.pyplot.stackplot`. They may be symmetric or

weighted.

.. plot:: mpl_examples/pylab_examples/stackplot_demo2.py

Rectangular colorbar extensions

```````````````````````````````

Andrew Dawson added a new keyword argument *extendrect* to

:meth:`~matplotlib.pyplot.colorbar` to optionally make colorbar

extensions rectangular instead of triangular.

More robust boxplots

````````````````````

Paul Hobson provided a fix to the :func:`~matplotlib.pyplot.boxplot`

method that prevent whiskers from being drawn inside the box for

oddly distributed data sets.

Calling subplot() without arguments

```````````````````````````````````

A call to :func:`~matplotlib.pyplot.subplot` without any arguments now

acts the same as `subplot(111)` or `subplot(1,1,1)` -- it creates one

axes for the whole figure. This was already the behavior for both

:func:`~matplotlib.pyplot.axes` and

:func:`~matplotlib.pyplot.subplots`, and now this consistency is

shared with :func:`~matplotlib.pyplot.subplot`.

Drawing

-------

Independent alpha values for face and edge colors

`````````````````````````````````````````````````

Wes Campaigne modified how :class:`~matplotlib.patches.Patch` objects are

drawn such that (for backends supporting transparency) you can set different

alpha values for faces and edges, by specifying their colors in RGBA format.

Note that if you set the alpha attribute for the patch object (e.g. using

:meth:`~matplotlib.patches.Patch.set_alpha` or the ``alpha`` keyword

argument), that value will override the alpha components set in both the

face and edge colors.

Path effects on lines

`````````````````````

Thanks to Jae-Joon Lee, path effects now also work on plot lines.

.. plot:: mpl_examples/pylab_examples/patheffect_demo.py

Easier creation of colormap and normalizer for levels with colors

`````````````````````````````````````````````````````````````````

Phil Elson added the :func:`matplotlib.colors.from_levels_and_colors`

function to easily create a colormap and normalizer for representation

of discrete colors for plot types such as

:func:`matplotlib.pyplot.pcolormesh`, with a similar interface to that

of :func:`contourf`.

Full control of the background color

````````````````````````````````````

Wes Campaigne and Phil Elson fixed the Agg backend such that PNGs are

now saved with the correct background color when

:meth:`fig.patch.get_alpha` is not 1.

Improved ``bbox_inches="tight"`` functionality

``````````````````````````````````````````````

Passing ``bbox_inches="tight"`` through to :func:`plt.save` now takes

into account *all* artists on a figure - this was previously not the

case and led to several corner cases which did not function as

expected.

Initialize a rotated rectangle

``````````````````````````````

Damon McDougall extended the :class:`~matplotlib.patches.Rectangle`

constructor to accept an `angle` kwarg, specifying the rotation of a

rectangle in degrees.

Text

----

Anchored text support

`````````````````````

The `svg` and `pgf` backends are now able to save text alignment

information to their output formats. This allows to edit text elements

in saved figures, using Inkscape for example, while preserving their

intended position. For `svg` please note that you'll have to disable

the default text-to-path conversion (``mpl.rc('svg',

fonttype='none')``).

Better vertical text alignment and multi-line text

``````````````````````````````````````````````````

The vertical alignment of text is now consistent across backends. You

may see small differences in text placement, particularly with rotated

text.

If you are using a custom backend, note that the `draw_text` renderer

method is now passed the location of the baseline, not the location of

the bottom of the text bounding box.

Multi-line text will now leave enough room for the height of very tall

or very low text, such as superscripts and subscripts.

Left and right side axes titles

```````````````````````````````

Andrew Dawson added the ability to add axes titles flush with the left

and right sides of the top of the axes using a new keyword argument

`loc` to :func:`~matplotlib.pyplot.title`.

Improved manual contour plot label positioning

``````````````````````````````````````````````

Brian Mattern modified the manual contour plot label positioning code

to interpolate along line segments and find the actual closest point

on a contour to the requested position. Previously, the closest path

vertex was used, which, in the case of straight contours was sometimes

quite distant from the requested location. Much more precise label

positioning is now possible.

Configuration (rcParams)

------------------------

Quickly find rcParams

`````````````````````

Phil Elson made it easier to search for rcParameters by passing a

valid regular expression to :func:`matplotlib.RcParams.find_all`.

:class:`matplotlib.RcParams` now also has a pretty repr and str

representation so that search results are printed prettily:

>>> import matplotlib

>>> print(matplotlib.rcParams.find_all('\.size'))

RcParams({'font.size': 12,

'xtick.major.size': 4,

'xtick.minor.size': 2,

'ytick.major.size': 4,

'ytick.minor.size': 2})

``axes.xmargin`` and ``axes.ymargin`` added to rcParams

```````````````````````````````````````````````````````

``rcParam`` values (``axes.xmargin`` and ``axes.ymargin``) were added

to configure the default margins used. Previously they were

hard-coded to default to 0, default value of both rcParam values is 0.

Changes to font rcParams

````````````````````````

The `font.*` rcParams now affect only text objects created after the

rcParam has been set, and will not retroactively affect already

existing text objects. This brings their behavior in line with most

other rcParams.

``savefig.jpeg_quality`` added to rcParams

``````````````````````````````````````````

rcParam value ``savefig.jpeg_quality`` was added so that the user can

configure the default quality used when a figure is written as a JPEG.

The default quality is 95; previously, the default quality was 75.

This change minimizes the artifacting inherent in JPEG images,

particularly with images that have sharp changes in color as plots

often do.

Backends

--------

WebAgg backend

``````````````

Michael Droettboom, Phil Elson and others have developed a new

backend, WebAgg, to display figures in a web browser. It works with

animations as well as being fully interactive.

.. image:: /_static/webagg_screenshot.png

Future versions of matplotlib will integrate this backend with the

IPython notebook for a fully web browser based plotting frontend.

Remember save directory

```````````````````````

Martin Spacek made the save figure dialog remember the last directory

saved to. The default is configurable with the new `savefig.directory`

rcParam in `matplotlibrc`.

Documentation and examples

--------------------------

Numpydoc docstrings

```````````````````

Nelle Varoquaux has started an ongoing project to convert matplotlib's

docstrings to numpydoc format. See `MEP10

<https://github.com/matplotlib/matplotlib/wiki/Mep10>`_ for more

information.

Example reorganization

``````````````````````

Tony Yu has begun work reorganizing the examples into more meaningful

categories. The new gallery page is the fruit of this ongoing work.

See `MEP12 <https://github.com/matplotlib/matplotlib/wiki/MEP12>`_ for

more information.

Examples now use subplots()

```````````````````````````

For the sake of brevity and clarity, most of the :ref:`examples

<examples-index>` now use the newer

:func:`~matplotlib.pyplot.subplots`, which creates a figure and one

(or multiple) axes object(s) in one call. The old way involved a call

to :func:`~matplotlib.pyplot.figure`, followed by one (or multiple)

:func:`~matplotlib.pyplot.subplot` calls.

Infrastructure

--------------

Housecleaning

`````````````

A number of features that were deprecated in 1.2 or earlier, or have

not been in a working state for a long time have been removed.

Highlights include removing the Qt version 3 backends, and the FltkAgg

and Emf backends. See :ref:`changes_in_1_3` for a complete list.

New setup script

````````````````

matplotlib 1.3 includes an entirely rewritten setup script. We now

ship fewer dependencies with the tarballs and installers themselves.

Notably, `pytz`, `dateutil`, `pyparsing` and `six` are no longer

included with matplotlib. You can either install them manually first,

or let `pip` install them as dependencies along with matplotlib. It

is now possible to not include certain subcomponents, such as the unit

test data, in the install. See `setup.cfg.template` for more

information.

XDG base directory support

``````````````````````````

On Linux, matplotlib now uses the `XDG base directory specification

<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`

to find the `matplotlibrc` configuration file. `matplotlibrc` should

now be kept in `~/.config/matplotlib`, rather than `~/.matplotlib`.

If your configuration is found in the old location, it will still be

used, but a warning will be displayed.

Catch opening too many figures using pyplot

```````````````````````````````````````````

Figures created through `pyplot.figure` are retained until they are

explicitly closed. It is therefore common for new users of matplotlib

to run out of memory when creating a large series of figures in a loop

without closing them.

matplotlib will now display a `RuntimeWarning` when too many figures

have been opened at once. By default, this is displayed for 20 or

more figures, but the exact number may be controlled using the

``figure.max_open_warning`` rcParam.

.. _whats-new-1-2-2:

new in matplotlib 1.2.2

=======================

Improved collections

--------------------

The individual items of a collection may now have different alpha

values and be rendered correctly. This also fixes a bug where

collections were always filled in the PDF backend.

Multiple images on same axes are correctly transparent

------------------------------------------------------

When putting multiple images onto the same axes, the background color

of the axes will now show through correctly.

.. _whats-new-1-2:

new in matplotlib-1.2

=====================

Python 3.x support

------------------

Matplotlib 1.2 is the first version to support Python 3.x,

specifically Python 3.1 and 3.2. To make this happen in a reasonable

way, we also had to drop support for Python versions earlier than 2.6.

This work was done by Michael Droettboom, the Cape Town Python Users'

Group, many others and supported financially in part by the SAGE

project.

The following GUI backends work under Python 3.x: Gtk3Cairo, Qt4Agg,

TkAgg and MacOSX. The other GUI backends do not yet have adequate

bindings for Python 3.x, but continue to work on Python 2.6 and 2.7,

particularly the Qt and QtAgg backends (which have been

deprecated). The non-GUI backends, such as PDF, PS and SVG, work on

both Python 2.x and 3.x.

Features that depend on the Python Imaging Library, such as JPEG

handling, do not work, since the version of PIL for Python 3.x is not

sufficiently mature.

PGF/TikZ backend

----------------

Peter Würtz wrote a backend that allows matplotlib to export figures as

drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or

LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are

found in :ref:`pgf-tutorial`.

.. image:: /_static/pgf_preamble.*

Locator interface

-----------------

Philip Elson exposed the intelligence behind the tick Locator classes with a

simple interface. For instance, to get no more than 5 sensible steps which

span the values 10 and 19.5::

>>> import matplotlib.ticker as mticker

>>> locator = mticker.MaxNLocator(nbins=5)

>>> print(locator.tick_values(10, 19.5))

[ 10. 12. 14. 16. 18. 20.]

Tri-Surface Plots

-----------------

Damon McDougall added a new plotting method for the

:mod:`~mpl_toolkits.mplot3d` toolkit called

:meth:`~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf`.

.. plot:: mpl_examples/mplot3d/trisurf3d_demo.py

Control the lengths of colorbar extensions

------------------------------------------

Andrew Dawson added a new keyword argument *extendfrac* to

:meth:`~matplotlib.pyplot.colorbar` to control the length of

minimum and maximum colorbar extensions.

.. plot::

import matplotlib.pyplot as plt

import numpy as np

x = y = np.linspace(0., 2*np.pi, 100)

X, Y = np.meshgrid(x, y)

Z = np.cos(X) * np.sin(0.5*Y)

clevs = [-.75, -.5, -.25, 0., .25, .5, .75]

cmap = plt.cm.get_cmap(name='jet', lut=8)

ax1 = plt.subplot(211)

cs1 = plt.contourf(x, y, Z, clevs, cmap=cmap, extend='both')

cb1 = plt.colorbar(orientation='horizontal', extendfrac=None)

cb1.set_label('Default length colorbar extensions')

ax2 = plt.subplot(212)

cs2 = plt.contourf(x, y, Z, clevs, cmap=cmap, extend='both')

cb2 = plt.colorbar(orientation='horizontal', extendfrac='auto')

cb2.set_label('Custom length colorbar extensions')

plt.show()

Figures are picklable

---------------------

Philip Elson added an experimental feature to make figures picklable

for quick and easy short-term storage of plots. Pickle files

are not designed for long term storage, are unsupported when restoring a pickle

saved in another matplotlib version and are insecure when restoring a pickle

from an untrusted source. Having said this, they are useful for short term

storage for later modification inside matplotlib.

Set default bounding box in matplotlibrc

------------------------------------------

Two new defaults are available in the matplotlibrc configuration file:

``savefig.bbox``, which can be set to 'standard' or 'tight', and

``savefig.pad_inches``, which controls the bounding box padding.

New Boxplot Functionality

-------------------------

Users can now incorporate their own methods for computing the median and its

confidence intervals into the :meth:`~matplotlib.axes.boxplot` method. For

every column of data passed to boxplot, the user can specify an accompanying

median and confidence interval.

.. plot:: mpl_examples/pylab_examples/boxplot_demo3.py

New RC parameter functionality

------------------------------

Matthew Emmett added a function and a context manager to help manage RC

parameters: :func:`~matplotlib.rc_file` and :class:`~matplotlib.rc_context`.

To load RC parameters from a file::

>>> mpl.rc_file('mpl.rc')

To temporarily use RC parameters::

>>> with mpl.rc_context(fname='mpl.rc', rc={'text.usetex': True}):

>>> ...

Streamplot

----------

Tom Flannaghan and Tony Yu have added a new

:meth:`~matplotlib.pyplot.streamplot` function to plot the streamlines of

a vector field. This has been a long-requested feature and complements the

existing :meth:`~matplotlib.pyplot.quiver` function for plotting vector fields.

In addition to simply plotting the streamlines of the vector field,

:meth:`~matplotlib.pyplot.streamplot` allows users to map the colors and/or

line widths of the streamlines to a separate parameter, such as the speed or

local intensity of the vector field.

.. plot:: mpl_examples/images_contours_and_fields/streamplot_demo_features.py

New hist functionality

----------------------

Nic Eggert added a new `stacked` kwarg to :meth:`~matplotlib.pyplot.hist` that

allows creation of stacked histograms using any of the histogram types.

Previously, this functionality was only available by using the `barstacked`

histogram type. Now, when `stacked=True` is passed to the function, any of the

histogram types can be stacked. The `barstacked` histogram type retains its

previous functionality for backwards compatibility.

Updated shipped dependencies

----------------------------

The following dependencies that ship with matplotlib and are

optionally installed alongside it have been updated:

- `pytz <http://pytz.sf.net/>` 2012d

- `dateutil <http://labix.org/python-dateutil>` 1.5 on Python 2.x,

and 2.1 on Python 3.x

Face-centred colors in tripcolor plots

--------------------------------------

Ian Thomas extended :meth:`~matplotlib.pyplot.tripcolor` to allow one color

value to be specified for each triangular face rather than for each point in

a triangulation.

.. plot:: mpl_examples/pylab_examples/tripcolor_demo.py

Hatching patterns in filled contour plots, with legends

-------------------------------------------------------