Matplotlib
Release 2.1.2
John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the ma
February 08, 2018
CONTENTS
I
User’s Guide
1
1
History
3
2
Installing
5
3
Tutorials
13
4
Interactive plots
279
5
What’s new in Matplotlib
295
6
GitHub Stats
471
7
License
481
8
Credits
485
II
9
The Matplotlib FAQ
Installation
487
489
10 How-To
495
11 Troubleshooting
509
12 Environment Variables
513
13 Working with Matplotlib in Virtual environments
515
14 Working with Matplotlib on OSX
517
III
521
Toolkits
15 mplot3d
525
16 axes_grid1
529
i
17 axisartist
531
IV
External Resources
533
18 Books, Chapters and Articles
535
19 Videos
537
20 Tutorials
539
V
541
Third party packages
21 Mapping toolkits
545
22 Declarative libraries
547
23 Specialty plots
549
24 Interactivity
553
25 Miscellaneous
555
VI
559
The Matplotlib API
26 The Pyplot API
563
27 The Object-Oriented API
567
28 Colors in Matplotlib
569
29 API Changes
575
30 The top level matplotlib module
633
31 afm (Adobe Font Metrics interface)
637
32 animation module
641
33 artist Module
693
34 Axes class
715
35 axis and tick API
897
36 backends
1017
37 cbook
1071
38 cm (colormap)
1087
ii
39 collections
1091
40 colorbar
1271
41 colors
1277
42 contour
1295
43 container
1303
44 dates
1305
45 dviread
1319
46 figure
1325
47 finance
1349
48 font_manager
1361
49 gridspec
1369
50 image
1373
51 legend and legend_handler
1379
52 lines
1391
53 markers
1403
54 mathtext
1407
55 mlab
1427
56 offsetbox
1461
57 patches
1473
58 path
1527
59 patheffects
1535
60 projections
1539
61 rcsetup
1553
62 sankey
1557
63 scale
1565
64 spines
1575
65 style
1579
iii
66 text
1581
67 ticker
1595
68 tight_layout
1609
69 Working with transformations
1611
70 triangular grids
1639
71 type1font
1649
72 units
1651
73 widgets
1653
74 matplotlib.pyplot
1671
75 Toolkits
1895
VII
1933
The Matplotlib Developers’ Guide
76 Contributing
1935
77 Developer’s tips for testing
1943
78 Writing documentation
1949
79 Developer’s guide for creating scales and transformations
1963
80 Developer’s tips for writing code for Python 2 and 3
1967
81 Working with Matplotlib source code
1971
82 Reviewers guideline
1991
83 Release Guide
1993
84 Matplotlib Enhancement Proposals
1999
85 Licenses
2061
86 Default Color changes
2063
VIII
2067
Glossary
Bibliography
2071
Python Module Index
2073
iv
Index
2075
v
vi
Part I
User’s Guide
1
CHAPTER
ONE
HISTORY
Note: The following introductory text was written in 2008 by John D. Hunter (1968-2012), the original
author of Matplotlib.
Matplotlib is a library for making 2D plots of arrays in Python. Although it has its origins in emulating
the MATLAB graphics commands, it is independent of MATLAB, and can be used in a Pythonic, object
oriented way. Although Matplotlib is written primarily in pure Python, it makes heavy use of NumPy and
other extension code to provide good performance even for large arrays.
Matplotlib is designed with the philosophy that you should be able to create simple plots with just a few
commands, or just one! If you want to see a histogram of your data, you shouldn’t need to instantiate objects,
call methods, set properties, and so on; it should just work.
For years, I used to use MATLAB exclusively for data analysis and visualization. MATLAB excels at making nice looking plots easy. When I began working with EEG data, I found that I needed to write applications
to interact with my data, and developed an EEG analysis application in MATLAB. As the application grew
in complexity, interacting with databases, http servers, manipulating complex data structures, I began to
strain against the limitations of MATLAB as a programming language, and decided to start over in Python.
Python more than makes up for all of MATLAB’s deficiencies as a programming language, but I was having
difficulty finding a 2D plotting package (for 3D VTK more than exceeds all of my needs).
When I went searching for a Python plotting package, I had several requirements:
• Plots should look great - publication quality. One important requirement for me is that the text looks
good (antialiased, etc.)
• Postscript output for inclusion with TeX documents
• Embeddable in a graphical user interface for application development
• Code should be easy enough that I can understand it and extend it
• Making plots should be easy
Finding no package that suited me just right, I did what any self-respecting Python programmer would do:
rolled up my sleeves and dived in. Not having any real experience with computer graphics, I decided to
emulate MATLAB’s plotting capabilities because that is something MATLAB does very well. This had the
added advantage that many people have a lot of MATLAB experience, and thus they can quickly get up to
steam plotting in python. From a developer’s perspective, having a fixed user interface (the pylab interface)
has been very useful, because the guts of the code base can be redesigned without affecting user code.
3
Matplotlib, Release 2.1.2
The Matplotlib code is conceptually divided into three parts: the pylab interface is the set of functions
provided by matplotlib.pylab which allow the user to create plots with code quite similar to MATLAB
figure generating code (Pyplot tutorial). The Matplotlib frontend or Matplotlib API is the set of classes that
do the heavy lifting, creating and managing figures, text, lines, plots and so on (Artist tutorial). This is an
abstract interface that knows nothing about output. The backends are device-dependent drawing devices, aka
renderers, that transform the frontend representation to hardcopy or a display device (What is a backend?).
Example backends: PS creates PostScript® hardcopy, SVG creates Scalable Vector Graphics hardcopy,
Agg creates PNG output using the high quality Anti-Grain Geometry library that ships with Matplotlib,
GTK embeds Matplotlib in a Gtk+ application, GTKAgg uses the Anti-Grain renderer to create a figure and
embed it in a Gtk+ application, and so on for PDF, WxWidgets, Tkinter, etc.
Matplotlib is used by many people in many different contexts. Some people want to automatically generate
PostScript files to send to a printer or publishers. Others deploy Matplotlib on a web application server to
generate PNG output for inclusion in dynamically-generated web pages. Some use Matplotlib interactively
from the Python shell in Tkinter on Windows. My primary use is to embed Matplotlib in a Gtk+ EEG
application that runs on Windows, Linux and Macintosh OS X.
Matplotlib’s original logo (2003 – 2008).
matplotlib
4
Chapter 1. History
CHAPTER
TWO
INSTALLING
Note: If you wish to contribute to the project, it’s recommended you install the latest development version.
Contents
• Installing
– Installing an official release
* Windows
* macOS
* Linux
* Test Data
– Third-party distributions of Matplotlib
* Scientific Python Distributions
* Linux : using your package manager
– Installing from source
* Dependencies
* Building on Linux
* Building on macOS
* Building on Windows
· Wheel builds using conda packages
· Conda packages
5
Matplotlib, Release 2.1.2
2.1 Installing an official release
Matplotlib and most of its dependencies are all available as wheel packages for macOS, Windows and Linux
distributions:
python -mpip install -U pip
python -mpip install -U matplotlib
Note: The following backends work out of the box: Agg, ps, pdf, svg and TkAgg.
For support of other GUI frameworks, LaTeX rendering, saving animations and a larger selection of file
formats, you may need to install additional dependencies.
Although not required, we suggest also installing IPython for interactive use. To easily install a complete
Scientific Python stack, see Scientific Python Distributions below.
2.1.1 Windows
In case Python 2.7 or 3.4 are not installed for all users, the Microsoft Visual C++ 2008 (64 bit or 32 bit for
Python 2.7) or Microsoft Visual C++ 2010 (64 bit or 32 bit for Python 3.4) redistributable packages need to
be installed.
2.1.2 macOS
If you are using Python 2.7 on a Mac you may need to do:
xcode-select --install
so that subprocess32, a dependency, may be compiled.
To use the native OSX backend you will need a framework build build of Python.
2.1.3 Linux
On extremely old versions of Linux and Python 2.7 you may need to install the master version of subprocess32 (see comments).
2.1.4 Test Data
The wheels (*.whl) on the PyPI download page do not contain test data or example code. If you want to
try the many demos that come in the Matplotlib source distribution, download the *.tar.gz file and look
in the examples subdirectory. To run the test suite:
• extract the lib\matplotlib\tests or lib\mpl_toolkits\tests directories from the source distribution;
6
Chapter 2. Installing
Matplotlib, Release 2.1.2
• install test dependencies: pytest, mock, Pillow, MiKTeX, GhostScript, ffmpeg, avconv, mencoder,
ImageMagick, and Inkscape;
• run py.test path\to\tests\directory.
2.2 Third-party distributions of Matplotlib
2.2.1 Scientific Python Distributions
Both Anaconda and Canopy are both excellent choices that “just work” out of the box for Windows, macOS
and common Linux platforms. WinPython is an option for windows users. All of these distributions include
Matplotlib and lots of other useful tools.
2.2.2 Linux : using your package manager
If you are on Linux, you might prefer to use your package manager. Matplotlib is packaged for almost every
major Linux distribution.
• Debian / Ubuntu: sudo apt-get install python3-matplotlib
• Fedora: sudo dnf install python3-matplotlib
• Red Hat: sudo yum install python3-matplotlib
• Arch: sudo pacman -S python-matplotlib
2.3 Installing from source
If you are interested in contributing to Matplotlib development, running the latest source code, or just like
to build everything yourself, it is not difficult to build Matplotlib from source. Grab the latest tar.gz release
file from the PyPI files page, or if you want to develop Matplotlib or just need the latest bugfixed version,
grab the latest git version Install from source.
The standard environment variables CC, CXX, PKG_CONFIG are respected. This means you can set them if
your toolchain is prefixed. This may be used for cross compiling.
export CC=x86_64-pc-linux-gnu-gcc
export CXX=x86_64-pc-linux-gnu-g++
export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config
Once you have satisfied the requirements detailed below (mainly Python, NumPy, libpng and FreeType),
you can build Matplotlib.
cd matplotlib
python -mpip install .
2.2. Third-party distributions of Matplotlib
7
Matplotlib, Release 2.1.2
We provide a setup.cfg file which you can use to customize the build process. For example, which default
backend to use, whether some of the optional libraries that Matplotlib ships with are installed, and so on.
This file will be particularly useful to those packaging Matplotlib.
If you have installed prerequisites to nonstandard places and need to inform Matplotlib where they are,
edit setupext.py and add the base dirs to the basedir dictionary entry for your sys.platform; e.g., if
the header of some required library is in /some/path/include/someheader.h, put /some/path in the
basedir list for your platform.
2.3.1 Dependencies
Matplotlib requires a large number of dependencies:
• Python (>= 2.7 or >= 3.4)
• NumPy (>= 1.7.1)
• setuptools
• dateutil (>= 2.1)
• pyparsing
• libpng (>= 1.2)
• pytz
• FreeType (>= 2.3)
• cycler (>= 0.10.0)
• six
• backports.functools_lru_cache (for Python 2.7 only)
• subprocess32 (for Python 2.7 only, on Linux and macOS only)
Optionally, you can also install a number of packages to enable better user interface toolkits. See What is a
backend? for more details on the optional Matplotlib backends and the capabilities they provide.
• tk (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
• PyQt4 (>= 4.4) or PySide: for the Qt4Agg backend;
• PyQt5: for the Qt5Agg backend;
• pygtk (>= 2.4): for the GTK and the GTKAgg backend;
• wxpython (>= 2.8 or later): for the WX or WXAgg backend;
• pycairo: for GTK3Cairo;
• Tornado: for the WebAgg backend.
For better support of animation output format and image file formats, LaTeX, etc., you can install the following:
• ffmpeg/avconv: for saving movies;
8
Chapter 2. Installing
Matplotlib, Release 2.1.2
• ImageMagick: for saving animated gifs;
• Pillow (>=2.0): for a larger selection of image file formats: JPEG, BMP, and TIFF image files;
• LaTeX and GhostScript (for rendering text with LaTeX).
Note: Matplotlib depends on a large number of non-Python libraries. pkg-config can be used to find
required non-Python libraries and thus make the install go more smoothly if the libraries and headers are not
in the expected locations.
Note: The following libraries are shipped with Matplotlib:
• Agg: the Anti-Grain Geometry C++ rendering engine;
• qhull: to compute Delaunay triangulation;
• ttconv: a true type font utility.
2.3.2 Building on Linux
It is easiest to use your system package manager to install the dependencies.
If you are on Debian/Ubuntu, you can get all the dependencies required to build Matplotlib with:
sudo apt-get build-dep python-matplotlib
If you are on Fedora, you can get all the dependencies required to build Matplotlib with:
sudo dnf builddep python-matplotlib
If you are on RedHat, you can get all the dependencies required to build Matplotlib by first installing
yum-builddep and then running:
su -c "yum-builddep python-matplotlib"
These commands do not build Matplotlib, but instead get and install the build dependencies, which will
make building from source easier.
2.3.3 Building on macOS
The build situation on macOS is complicated by the various places one can get the libpng and FreeType
requirements (MacPorts, Fink, /usr/X11R6), the different architectures (e.g., x86, ppc, universal), and the
different macOS versions (e.g., 10.4 and 10.5). We recommend that you build the way we do for the macOS
release: get the source from the tarball or the git repository and install the required dependencies through
a third-party package manager. Two widely used package managers are Homebrew, and MacPorts. The
following example illustrates how to install libpng and FreeType using brew:
2.3. Installing from source
9
Matplotlib, Release 2.1.2
brew install libpng freetype pkg-config
If you are using MacPorts, execute the following instead:
port install libpng freetype pkgconfig
After installing the above requirements, install Matplotlib from source by executing:
python -mpip install .
Note that your environment is somewhat important.
Some conda users have found that,
to run the tests, their PYTHONPATH must include /path/to/anaconda/. . . /site-packages and their
DYLD_FALLBACK_LIBRARY_PATH must include /path/to/anaconda/lib.
2.3.4 Building on Windows
The Python shipped from https://www.python.org is compiled with Visual Studio 2008 for versions before
3.3, Visual Studio 2010 for 3.3 and 3.4, and Visual Studio 2015 for 3.5 and 3.6. Python extensions are
recommended to be compiled with the same compiler.
Since there is no canonical Windows package manager, the methods for building FreeType, zlib, and libpng
from source code are documented as a build script at matplotlib-winbuild.
There are a few possibilities to build Matplotlib on Windows:
• Wheels via matplotlib-winbuild
• Wheels by using conda packages
• Conda packages
Wheel builds using conda packages
This is a wheel build, but we use conda packages to get all the requirements. The binary requirements (png,
FreeType,. . . ) are statically linked and therefore not needed during the wheel install.
The commands below assume that you can compile a native Python lib for the Python version of your choice.
See this howto for how to install and setup such environments. If in doubt: use Python >= 3.5 as it mostly
works without fiddling with environment variables:
# create a new environment with the required packages
conda create -n "matplotlib_build" python=3.5 numpy python-dateutil pyparsing pytz␣
,→tornado "cycler>=0.10" tk libpng zlib freetype
activate matplotlib_build
# if you want a qt backend, you also have to install pyqt (be aware that pyqt doesn't mix␣
,→well if
# you have created the environment with conda-forge already activated...)
conda install pyqt
# this package is only available in the conda-forge channel
conda install -c conda-forge msinttypes
# for Python 2.7
10
Chapter 2. Installing
Matplotlib, Release 2.1.2
conda install -c conda-forge backports.functools_lru_cache
# copy the libs which have "wrong" names
set LIBRARY_LIB=%CONDA_DEFAULT_ENV%\Library\lib
mkdir lib || cmd /c "exit /b 0"
copy %LIBRARY_LIB%\zlibstatic.lib lib\z.lib
copy %LIBRARY_LIB%\libpng_static.lib lib\png.lib
# Make the header files and the rest of the static libs available during the build
# CONDA_DEFAULT_ENV is a env variable which is set to the currently active environment␣
,→path
set MPLBASEDIRLIST=%CONDA_DEFAULT_ENV%\Library\;.
# build the wheel
python setup.py bdist_wheel
The build_alllocal.cmd script in the root folder automates these steps if you have already created and
activated the conda environment.
Conda packages
This needs a working installed C compiler for the version of Python you are compiling the package for but
you don’t need to setup the environment variables:
# only the first time...
conda install conda-build
# the Python version you want a package for...
set CONDA_PY=3.5
# builds the package, using a clean build environment
conda build ci\conda_recipe
# install the new package
conda install --use-local matplotlib
2.3. Installing from source
11
Matplotlib, Release 2.1.2
12
Chapter 2. Installing
CHAPTER
THREE
TUTORIALS
This page contains more in-depth guides for using Matplotlib. It is broken up into beginner, intermediate,
and advanced sections, as well as sections covering specific topics.
For shorter examples, see our examples page. You can also find external resources and a FAQ in our user
guide.
3.1 Introductory
These tutorials cover the basics of creating visualizations with Matplotlib, as well as some best-practices in
using the package effectively.
3.1.1 Sample plots in Matplotlib
Here you’ll find a host of example plots with the code that generated them.
Line Plot
Here’s how to create a line plot with text labels using plot().
Fig. 3.1: Simple Plot
13
Matplotlib, Release 2.1.2
Multiple subplots in one figure
Multiple axes (i.e. subplots) are created with the subplot() function:
Fig. 3.2: Subplot
Images
Matplotlib can display images (assuming equally spaced horizontal dimensions) using the imshow() function.
Fig. 3.3: Example of using imshow() to display a CT scan
Contouring and pseudocolor
The pcolormesh() function can make a colored representation of a two-dimensional array, even if the
horizontal dimensions are unevenly spaced. The contour() function is another way to represent the same
data:
14
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.4: Example comparing pcolormesh() and contour() for plotting two-dimensional data
Histograms
The hist() function automatically generates histograms and returns the bin counts or probabilities:
Fig. 3.5: Histogram Features
Paths
You can add arbitrary paths in Matplotlib using the matplotlib.path module:
Three-dimensional plotting
The mplot3d toolkit (see Getting started and mplot3d-examples-index) has support for simple 3d graphs
including surface, wireframe, scatter, and bar charts.
Thanks to John Porter, Jonathon Taylor, Reinier Heeres, and Ben Root for the mplot3d toolkit. This toolkit
is included with all standard Matplotlib installs.
3.1. Introductory
15
Matplotlib, Release 2.1.2
Fig. 3.6: Path Patch
Fig. 3.7: Surface3d
16
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Streamplot
The streamplot() function plots the streamlines of a vector field. In addition to simply plotting the
streamlines, it allows you to map the colors and/or line widths of streamlines to a separate parameter, such
as the speed or local intensity of the vector field.
Fig. 3.8: Streamplot with various plotting options.
This feature complements the quiver() function for plotting vector fields. Thanks to Tom Flannaghan and
Tony Yu for adding the streamplot function.
Ellipses
In support of the Phoenix mission to Mars (which used Matplotlib to display ground tracking of spacecraft),
Michael Droettboom built on work by Charlie Moad to provide an extremely accurate 8-spline approximation to elliptical arcs (see Arc), which are insensitive to zoom level.
Bar charts
Use the bar() function to make bar charts, which includes customizations such as error bars:
You can also create stacked bars (bar_stacked.py), or horizontal bar charts (barh.py).
3.1. Introductory
17
Matplotlib, Release 2.1.2
Fig. 3.9: Ellipse Demo
Fig. 3.10: Barchart Demo
18
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Pie charts
The pie() function allows you to create pie charts. Optional features include auto-labeling the percentage
of area, exploding one or more wedges from the center of the pie, and a shadow effect. Take a close look at
the attached code, which generates this figure in just a few lines of code.
Fig. 3.11: Pie Features
Tables
The table() function adds a text table to an axes.
Fig. 3.12: Table Demo
Scatter plots
The scatter() function makes a scatter plot with (optional) size and color arguments. This example plots
changes in Google’s stock price, with marker sizes reflecting the trading volume and colors varying with
time. Here, the alpha attribute is used to make semitransparent circle markers.
3.1. Introductory
19
Matplotlib, Release 2.1.2
Fig. 3.13: Scatter Demo2
GUI widgets
Matplotlib has basic GUI widgets that are independent of the graphical user interface you are using, allowing
you to write cross GUI figures and widgets. See matplotlib.widgets and the widget examples.
Fig. 3.14: Slider and radio-button GUI.
Filled curves
The fill() function lets you plot filled curves and polygons:
Thanks to Andrew Straw for adding this function.
Date handling
You can plot timeseries data with major and minor ticks and custom tick formatters for both.
See matplotlib.ticker and matplotlib.dates for details and usage.
20
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.15: Fill
Fig. 3.16: Date
3.1. Introductory
21
Matplotlib, Release 2.1.2
Log plots
The semilogx(), semilogy() and loglog() functions simplify the creation of logarithmic plots.
Fig. 3.17: Log Demo
Thanks to Andrew Straw, Darren Dale and Gregory Lielens for contributions log-scaling infrastructure.
Polar plots
The polar() function generates polar plots.
Fig. 3.18: Polar Demo
Legends
The legend() function automatically generates figure legends, with MATLAB-compatible legendplacement functions.
Thanks to Charles Twardy for input on the legend function.
22
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.19: Legend
TeX-notation for text objects
Below is a sampling of the many TeX expressions now supported by Matplotlib’s internal mathtext engine. The mathtext module provides TeX style mathematical expressions using FreeType and the DejaVu,
BaKoMa computer modern, or STIX fonts. See the matplotlib.mathtext module for additional details.
Fig. 3.20: Mathtext Examples
Matplotlib’s mathtext infrastructure is an independent implementation and does not require TeX or any
external packages installed on your computer. See the tutorial at Writing mathematical expressions.
3.1. Introductory
23
Matplotlib, Release 2.1.2
Native TeX rendering
Although Matplotlib’s internal math rendering engine is quite powerful, sometimes you need TeX. Matplotlib supports external TeX rendering of strings with the usetex option.
Fig. 3.21: Tex Demo
EEG GUI
You can embed Matplotlib into pygtk, wx, Tk, or Qt applications. Here is a screenshot of an EEG viewer
called pbrain.
24
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
The lower axes uses specgram() to plot the spectrogram of one of the EEG channels.
For examples of how to embed Matplotlib in different toolkits, see:
• /gallery/user_interfaces/embedding_in_gtk2_sgskip
• /gallery/user_interfaces/embedding_in_wx2_sgskip
• /gallery/user_interfaces/mpl_with_glade_sgskip
• /gallery/user_interfaces/embedding_in_qt_sgskip
• /gallery/user_interfaces/embedding_in_tk_sgskip
XKCD-style sketch plots
Just for fun, Matplotlib supports plotting in the style of xkcd.
3.1. Introductory
25
Matplotlib, Release 2.1.2
Fig. 3.22: Xkcd
Subplot example
Many plot types can be combined in one figure to create powerful and flexible representations of data.
import matplotlib.pyplot as plt
import numpy as np
np.random.seed(19680801)
data = np.random.randn(2, 100)
fig, axs = plt.subplots(2, 2, figsize=(5, 5))
axs[0, 0].hist(data[0])
axs[1, 0].scatter(data[0], data[1])
axs[0, 1].plot(data[0], data[1])
axs[1, 1].hist2d(data[0], data[1])
plt.show()
26
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.082 seconds)
3.1.2 Customizing matplotlib
Tips for customizing the properties and default styles of matplotlib.
Using style sheets
The style package adds support for easy-to-switch plotting “styles” with the same parameters as a matplotlibrc file (which is read at startup to configure matplotlib).
There are a number of pre-defined styles provided by matplotlib. For example, there’s a pre-defined style
called “ggplot”, which emulates the aesthetics of ggplot (a popular plotting package for R). To use this style,
just add:
import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl
plt.style.use('ggplot')
data = np.random.randn(50)
3.1. Introductory
27
Matplotlib, Release 2.1.2
To list all available styles, use:
print(plt.style.available)
Out:
['seaborn-ticks', 'ggplot', 'dark_background', 'bmh', 'seaborn-poster', 'seaborn-notebook
,→', 'fast', 'seaborn', 'classic', 'Solarize_Light2', 'seaborn-dark', 'seaborn-pastel',
,→'seaborn-muted', '_classic_test', 'seaborn-paper', 'seaborn-colorblind', 'seaborn,→bright', 'seaborn-talk', 'seaborn-dark-palette', 'seaborn-darkgrid', 'seaborn-whitegrid
,→', 'fivethirtyeight', 'grayscale', 'seaborn-white', 'seaborn-deep']
Defining your own style
You can create custom styles and use them by calling style.use with the path or URL to the style sheet.
Additionally, if you add your <style-name>.mplstyle file to mpl_configdir/stylelib, you can reuse
your custom style sheet with a call to style.use(<style-name>). By default mpl_configdir should
be ~/.config/matplotlib, but you can check where yours is with matplotlib.get_configdir();
you may need to create this directory. You also can change the directory where matplotlib looks for the
stylelib/ folder by setting the MPLCONFIGDIR environment variable, see matplotlib configuration and
cache directory locations.
Note that a custom style sheet in mpl_configdir/stylelib will override a style sheet defined by matplotlib if the styles have the same name.
For example, you might want to create mpl_configdir/stylelib/presentation.mplstyle with the
following:
axes.titlesize : 24
axes.labelsize : 20
lines.linewidth : 3
lines.markersize : 10
xtick.labelsize : 16
ytick.labelsize : 16
Then, when you want to adapt a plot designed for a paper to one that looks good in a presentation, you can
just add:
>>> import matplotlib.pyplot as plt
>>> plt.style.use('presentation')
Composing styles
Style sheets are designed to be composed together. So you can have a style sheet that customizes colors
and a separate style sheet that alters element sizes for presentations. These styles can easily be combined by
passing a list of styles:
>>> import matplotlib.pyplot as plt
>>> plt.style.use(['dark_background', 'presentation'])
28
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Note that styles further to the right will overwrite values that are already defined by styles on the left.
Temporary styling
If you only want to use a style for a specific block of code but don’t want to change the global styling, the
style package provides a context manager for limiting your changes to a specific scope. To isolate your
styling changes, you can write something like the following:
with plt.style.context(('dark_background')):
plt.plot(np.sin(np.linspace(0, 2 * np.pi)), 'r-o')
plt.show()
3.1.3 matplotlib rcParams
Dynamic rc settings
You can also dynamically change the default rc settings in a python script or interactively from the python
shell. All of the rc settings are stored in a dictionary-like variable called matplotlib.rcParams, which is
global to the matplotlib package. rcParams can be modified directly, for example:
3.1. Introductory
29
Matplotlib, Release 2.1.2
mpl.rcParams['lines.linewidth'] = 2
mpl.rcParams['lines.color'] = 'r'
plt.plot(data)
Matplotlib also provides a couple of convenience functions for modifying rc settings. The matplotlib.
rc() command can be used to modify multiple settings in a single group at once, using keyword arguments:
mpl.rc('lines', linewidth=4, color='g')
plt.plot(data)
30
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
The matplotlib.rcdefaults() command will restore the standard matplotlib default settings.
There is some degree of validation when setting the values of rcParams, see matplotlib.rcsetup for
details.
The matplotlibrc file
matplotlib uses matplotlibrc configuration files to customize all kinds of properties, which we call rc
settings or rc parameters. You can control the defaults of almost every property in matplotlib: figure
size and dpi, line width, color and style, axes, axis and grid properties, text and font properties and so on.
matplotlib looks for matplotlibrc in four locations, in the following order:
1. matplotlibrc in the current working directory, usually used for specific customizations that you do
not want to apply elsewhere.
2. $MATPLOTLIBRC if it is a file, else $MATPLOTLIBRC/matplotlibrc.
3. It next looks in a user-specific place, depending on your platform:
• On Linux and FreeBSD, it looks in .config/matplotlib/matplotlibrc (or
$XDG_CONFIG_HOME/matplotlib/matplotlibrc) if you’ve customized your environment.
• On other platforms, it looks in .matplotlib/matplotlibrc.
3.1. Introductory
31
Matplotlib, Release 2.1.2
See matplotlib configuration and cache directory locations.
4. INSTALL/matplotlib/mpl-data/matplotlibrc, where INSTALL is something like /usr/lib/
python3.5/site-packages on Linux, and maybe C:\Python35\Lib\site-packages on Windows. Every time you install matplotlib, this file will be overwritten, so if you want your customizations to be saved, please move this file to your user-specific matplotlib directory.
Once a matplotlibrc file has been found, it will not search any of the other paths.
To display where the currently active matplotlibrc file was loaded from, one can do the following:
>>> import matplotlib
>>> matplotlib.matplotlib_fname()
'/home/foo/.config/matplotlib/matplotlibrc'
See below for a sample matplotlibrc file. Although all parameters are optional, you should almost always
set the backend or else matplotlib will choose Agg, a non-interactive backend. This can lead to unexpected behavior, since if you do not have a matplotlibrc file, it would normally fall back to INSTALL/
matplotlib/mpl-data/matplotlibrc, which is often set to an interactive backend by the package maintainer.
A sample matplotlibrc file
### MATPLOTLIBRC FORMAT
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
This is a sample matplotlib configuration file - you can find a copy
of it on your system in
site-packages/matplotlib/mpl-data/matplotlibrc. If you edit it
there, please note that it will be overwritten in your next install.
If you want to keep a permanent local copy that will not be
overwritten, place it in the following location:
unix/linux:
$HOME/.config/matplotlib/matplotlibrc or
$XDG_CONFIG_HOME/matplotlib/matplotlibrc (if $XDG_CONFIG_HOME is set)
other platforms:
$HOME/.matplotlib/matplotlibrc
See http://matplotlib.org/users/customizing.html#the-matplotlibrc-file for
more details on the paths which are checked for the configuration file.
This file is best viewed in a editor which supports python mode
syntax highlighting. Blank lines, or lines starting with a comment
symbol, are ignored, as are trailing comments. Other lines must
have the format
key : val # optional comment
Colors: for the color values below, you can either use - a
matplotlib color string, such as r, k, or b - an rgb tuple, such as
(1.0, 0.5, 0.0) - a hex string, such as ff00ff - a scalar
grayscale intensity such as 0.75 - a legal html color name, e.g., red,
blue, darkslategray
32
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#### CONFIGURATION BEGINS HERE
# The default backend; one of GTK GTKAgg GTKCairo GTK3Agg GTK3Cairo
# MacOSX Qt4Agg Qt5Agg TkAgg WX WXAgg Agg Cairo GDK PS PDF SVG
# Template.
# You can also deploy your own backend outside of matplotlib by
# referring to the module name (which must be in the PYTHONPATH) as
# 'module://my_backend'.
#
# If you omit this parameter, it will always default to "Agg", which is a
# non-interactive backend.
backend
: qt5agg
#
#
#
#
Note that this can be overridden by the environment variable
QT_API used by Enthought Tool Suite (ETS); valid values are
"pyqt" and "pyside". The "pyqt" setting has the side effect of
forcing the use of Version 2 API for QString and QVariant.
# The port to use for the web server in the WebAgg backend.
# webagg.port : 8888
# The address on which the WebAgg web server should be reachable
# webagg.address : 127.0.0.1
# If webagg.port is unavailable, a number of other random ports will
# be tried until one that is available is found.
# webagg.port_retries : 50
# When True, open the webbrowser to the plot that is shown
# webagg.open_in_browser : True
# if you are running pyplot inside a GUI and your backend choice
# conflicts, we will automatically try to find a compatible one for
# you if backend_fallback is True
#backend_fallback: True
#interactive
#toolbar
#timezone
: False
: toolbar2
: UTC
# None | toolbar2 ("classic" is deprecated)
# a pytz timezone string, e.g., US/Central or Europe/Paris
# Where your matplotlib data lives if you installed to a non-default
# location. This is where the matplotlib fonts, bitmaps, etc reside
#datapath : /home/jdhunter/mpldata
### LINES
# See http://matplotlib.org/api/artist_api.html#module-matplotlib.lines for more
# information on line properties.
#lines.linewidth
: 1.5
# line width in points
#lines.linestyle
: # solid line
#lines.color
: C0
# has no affect on plot(); see axes.prop_cycle
#lines.marker
: None
# the default marker
#lines.markeredgewidth : 1.0
# the line width around the marker symbol
3.1. Introductory
33
Matplotlib, Release 2.1.2
#lines.markersize : 6
# markersize, in points
#lines.dash_joinstyle : miter
# miter|round|bevel
#lines.dash_capstyle : butt
# butt|round|projecting
#lines.solid_joinstyle : miter
# miter|round|bevel
#lines.solid_capstyle : projecting
# butt|round|projecting
#lines.antialiased : True
# render lines in antialiased (no jaggies)
# The three standard dash patterns. These are scaled by the linewidth.
#lines.dashed_pattern : 2.8, 1.2
#lines.dashdot_pattern : 4.8, 1.2, 0.8, 1.2
#lines.dotted_pattern : 1.1, 1.1
#lines.scale_dashes : True
#markers.fillstyle: full # full|left|right|bottom|top|none
### PATCHES
# Patches are graphical objects that fill 2D space, like polygons or
# circles. See
# http://matplotlib.org/api/artist_api.html#module-matplotlib.patches
# information on patch properties
#patch.linewidth
: 1
# edge width in points.
#patch.facecolor
: C0
#patch.edgecolor
: black
# if forced, or patch is not filled
#patch.force_edgecolor : False
# True to always use edgecolor
#patch.antialiased
: True
# render patches in antialiased (no jaggies)
### HATCHES
#hatch.color
: k
#hatch.linewidth : 1.0
### Boxplot
#boxplot.notch
#boxplot.vertical
#boxplot.whiskers
#boxplot.bootstrap
#boxplot.patchartist
#boxplot.showmeans
#boxplot.showcaps
#boxplot.showbox
#boxplot.showfliers
#boxplot.meanline
:
:
:
:
:
:
:
:
:
:
False
True
1.5
None
False
False
True
True
True
False
#boxplot.flierprops.color
#boxplot.flierprops.marker
#boxplot.flierprops.markerfacecolor
#boxplot.flierprops.markeredgecolor
#boxplot.flierprops.markersize
#boxplot.flierprops.linestyle
#boxplot.flierprops.linewidth
:
:
:
:
:
:
:
'k'
'o'
'none'
'k'
6
'none'
1.0
#boxplot.boxprops.color
: 'k'
#boxplot.boxprops.linewidth : 1.0
#boxplot.boxprops.linestyle : '-'
34
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#boxplot.whiskerprops.color
: 'k'
#boxplot.whiskerprops.linewidth : 1.0
#boxplot.whiskerprops.linestyle : '-'
#boxplot.capprops.color
: 'k'
#boxplot.capprops.linewidth : 1.0
#boxplot.capprops.linestyle : '-'
#boxplot.medianprops.color
: 'C1'
#boxplot.medianprops.linewidth : 1.0
#boxplot.medianprops.linestyle : '-'
#boxplot.meanprops.color
#boxplot.meanprops.marker
#boxplot.meanprops.markerfacecolor
#boxplot.meanprops.markeredgecolor
#boxplot.meanprops.markersize
#boxplot.meanprops.linestyle
#boxplot.meanprops.linewidth
:
:
:
:
:
:
:
'C2'
'^'
'C2'
'C2'
6
'none'
1.0
### FONT
#
# font properties used by text.Text. See
# http://matplotlib.org/api/font_manager_api.html for more
# information on font properties. The 6 font properties used for font
# matching are given below with their default values.
#
# The font.family property has five values: 'serif' (e.g., Times),
# 'sans-serif' (e.g., Helvetica), 'cursive' (e.g., Zapf-Chancery),
# 'fantasy' (e.g., Western), and 'monospace' (e.g., Courier). Each of
# these font families has a default list of font names in decreasing
# order of priority associated with them. When text.usetex is False,
# font.family may also be one or more concrete font names.
#
# The font.style property has three values: normal (or roman), italic
# or oblique. The oblique style will be used for italic, if it is not
# present.
#
# The font.variant property has two values: normal or small-caps. For
# TrueType fonts, which are scalable fonts, small-caps is equivalent
# to using a font size of 'smaller', or about 83%% of the current font
# size.
#
# The font.weight property has effectively 13 values: normal, bold,
# bolder, lighter, 100, 200, 300, ..., 900. Normal is the same as
# 400, and bold is 700. bolder and lighter are relative values with
# respect to the current weight.
#
# The font.stretch property has 11 values: ultra-condensed,
# extra-condensed, condensed, semi-condensed, normal, semi-expanded,
# expanded, extra-expanded, ultra-expanded, wider, and narrower. This
# property is not currently implemented.
3.1. Introductory
35
Matplotlib, Release 2.1.2
#
# The font.size property is the default font size for text, given in pts.
# 10 pt is the standard value.
#
#font.family
: sans-serif
#font.style
: normal
#font.variant
: normal
#font.weight
: medium
#font.stretch
: normal
# note that font.size controls default text sizes. To configure
# special text sizes tick labels, axes, labels, title, etc, see the rc
# settings for axes and ticks. Special text sizes can be defined
# relative to font.size, using the following values: xx-small, x-small,
# small, medium, large, x-large, xx-large, larger, or smaller
#font.size
: 10.0
#font.serif
: DejaVu Serif, Bitstream Vera Serif, New Century Schoolbook,␣
,→Century Schoolbook L, Utopia, ITC Bookman, Bookman, Nimbus Roman No9 L, Times New␣
,→Roman, Times, Palatino, Charter, serif
#font.sans-serif
: DejaVu Sans, Bitstream Vera Sans, Lucida Grande, Verdana, Geneva,␣
,→Lucid, Arial, Helvetica, Avant Garde, sans-serif
#font.cursive
: Apple Chancery, Textile, Zapf Chancery, Sand, Script MT, Felipa,␣
,→cursive
#font.fantasy
: Comic Sans MS, Chicago, Charcoal, Impact, Western, Humor Sans,␣
,→xkcd, fantasy
#font.monospace
: DejaVu Sans Mono, Bitstream Vera Sans Mono, Andale Mono, Nimbus␣
,→Mono L, Courier New, Courier, Fixed, Terminal, monospace
### TEXT
# text properties used by text.Text. See
# http://matplotlib.org/api/artist_api.html#module-matplotlib.text for more
# information on text properties
#text.color
: black
### LaTeX customizations. See http://wiki.scipy.org/Cookbook/Matplotlib/UsingTex
#text.usetex
: False # use latex for all text handling. The following fonts
# are supported through the usual rc parameter settings:
# new century schoolbook, bookman, times, palatino,
# zapf chancery, charter, serif, sans-serif, helvetica,
# avant garde, courier, monospace, computer modern roman,
# computer modern sans serif, computer modern typewriter
# If another font is desired which can loaded using the
# LaTeX \usepackage command, please inquire at the
# matplotlib mailing list
#text.latex.unicode : False # use "ucs" and "inputenc" LaTeX packages for handling
# unicode strings.
#text.latex.preamble : # IMPROPER USE OF THIS FEATURE WILL LEAD TO LATEX FAILURES
# AND IS THEREFORE UNSUPPORTED. PLEASE DO NOT ASK FOR HELP
# IF THIS FEATURE DOES NOT DO WHAT YOU EXPECT IT TO.
# preamble is a comma separated list of LaTeX statements
# that are included in the LaTeX document preamble.
# An example:
# text.latex.preamble : \usepackage{bm},\usepackage{euler}
36
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#text.hinting : auto
#
#
#
#
#
#
#
#
#
#
#text.hinting_factor : 8
# The following packages are always loaded with usetex, so
# beware of package collisions: color, geometry, graphicx,
# type1cm, textcomp. Adobe Postscript (PSSNFS) font packages
# may also be loaded, depending on your font settings
May be one of the following:
'none': Perform no hinting
'auto': Use FreeType's autohinter
'native': Use the hinting information in the
font file, if available, and if your
FreeType library supports it
'either': Use the native hinting information,
or the autohinter if none is available.
For backward compatibility, this value may also be
True === 'auto' or False === 'none'.
# Specifies the amount of softness for hinting in the
# horizontal direction. A value of 1 will hint to full
# pixels. A value of 2 will hint to half pixels etc.
#text.antialiased : True # If True (default), the text will be antialiased.
# This only affects the Agg backend.
# The following settings allow you to select the fonts in math mode.
# They map from a TeX font name to a fontconfig font pattern.
# These settings are only used if mathtext.fontset is 'custom'.
# Note that this "custom" mode is unsupported and may go away in the
# future.
#mathtext.cal : cursive
#mathtext.rm : serif
#mathtext.tt : monospace
#mathtext.it : serif:italic
#mathtext.bf : serif:bold
#mathtext.sf : sans
#mathtext.fontset : dejavusans # Should be 'dejavusans' (default),
# 'dejavuserif', 'cm' (Computer Modern), 'stix',
# 'stixsans' or 'custom'
#mathtext.fallback_to_cm : True # When True, use symbols from the Computer Modern
# fonts when a symbol can not be found in one of
# the custom math fonts.
#mathtext.default : it #
#
#
#
The default font to use for math.
Can be any of the LaTeX font names, including
the special name "regular" for the same font
used in regular text.
### AXES
# default face and edge color, default tick sizes,
# default fontsizes for ticklabels, and so on. See
# http://matplotlib.org/api/axes_api.html#module-matplotlib.axes
#axes.facecolor
: white
# axes background color
#axes.edgecolor
: black
# axes edge color
#axes.linewidth
: 0.8
# edge linewidth
#axes.grid
: False
# display grid or not
#axes.titlesize
: large
# fontsize of the axes title
3.1. Introductory
37
Matplotlib, Release 2.1.2
#axes.titlepad
#axes.labelsize
#axes.labelpad
#axes.labelweight
#axes.labelcolor
#axes.axisbelow
:
:
:
:
:
:
6.0
# pad between axes and title in points
medium # fontsize of the x any y labels
4.0
# space between label and axis
normal # weight of the x and y labels
black
'line' # draw axis gridlines and ticks below
# patches (True); above patches but below
# lines ('line'); or above all (False)
#axes.formatter.limits : -7, 7 # use scientific notation if log10
# of the axis range is smaller than the
# first or larger than the second
#axes.formatter.use_locale : False # When True, format tick labels
# according to the user's locale.
# For example, use ',' as a decimal
# separator in the fr_FR locale.
#axes.formatter.use_mathtext : False # When True, use mathtext for scientific
# notation.
#axes.formatter.min_exponent: 0 # minimum exponent to format in scientific notation
#axes.formatter.useoffset
: True
# If True, the tick label formatter
# will default to labeling ticks relative
# to an offset when the data range is
# small compared to the minimum absolute
# value of the data.
#axes.formatter.offset_threshold : 4
# When useoffset is True, the offset
# will be used when it can remove
# at least this number of significant
# digits from tick labels.
#
#
#
#
axes.spines.left
axes.spines.bottom
axes.spines.top
axes.spines.right
#axes.unicode_minus
:
:
:
:
True
True
True
True
: True
# display axis spines
# use unicode for the minus symbol
# rather than hyphen. See
# http://en.wikipedia.org/wiki/Plus_and_minus_signs
,→#Character_codes
# axes.prop_cycle
: cycler('color', ['1f77b4', 'ff7f0e', '2ca02c', 'd62728', '9467bd', '8c564b
,→', 'e377c2', '7f7f7f', 'bcbd22', '17becf'])
# color cycle for plot lines as list of string
# colorspecs: single letter, long name, or web-style hex
#axes.autolimit_mode : data # How to scale axes limits to the data.
# Use "data" to use data limits, plus some margin
# Use "round_number" move to the nearest "round" number
#axes.xmargin
: .05 # x margin. See `axes.Axes.margins`
#axes.ymargin
: .05 # y margin See `axes.Axes.margins`
#polaraxes.grid
#axes3d.grid
: True
: True
# display grid on polar axes
# display grid on 3d axes
### DATES
38
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#
#
#
#
#
#
#
These control the default format strings used in AutoDateFormatter.
Any valid format datetime format string can be used (see the python
`datetime` for details). For example using '%%x' will use the locale date representation
'%%X' will use the locale time representation and '%%c' will use the full locale datetime
representation.
These values map to the scales:
{'year': 365, 'month': 30, 'day': 1, 'hour': 1/24, 'minute': 1 / (24 * 60)}
#
#
#
#
#
#
#
date.autoformatter.year
: %Y
date.autoformatter.month
: %Y-%m
date.autoformatter.day
: %Y-%m-%d
date.autoformatter.hour
: %m-%d %H
date.autoformatter.minute
: %d %H:%M
date.autoformatter.second
: %H:%M:%S
date.autoformatter.microsecond
: %M:%S.%f
### TICKS
# see http://matplotlib.org/api/axis_api.html#matplotlib.axis.Tick
#xtick.top
: False
# draw ticks on the top side
#xtick.bottom
: True
# draw ticks on the bottom side
#xtick.major.size
: 3.5
# major tick size in points
#xtick.minor.size
: 2
# minor tick size in points
#xtick.major.width
: 0.8
# major tick width in points
#xtick.minor.width
: 0.6
# minor tick width in points
#xtick.major.pad
: 3.5
# distance to major tick label in points
#xtick.minor.pad
: 3.4
# distance to the minor tick label in points
#xtick.color
: k
# color of the tick labels
#xtick.labelsize
: medium # fontsize of the tick labels
#xtick.direction
: out
# direction: in, out, or inout
#xtick.minor.visible : False # visibility of minor ticks on x-axis
#xtick.major.top
: True
# draw x axis top major ticks
#xtick.major.bottom
: True
# draw x axis bottom major ticks
#xtick.minor.top
: True
# draw x axis top minor ticks
#xtick.minor.bottom
: True
# draw x axis bottom minor ticks
#ytick.left
#ytick.right
#ytick.major.size
#ytick.minor.size
#ytick.major.width
#ytick.minor.width
#ytick.major.pad
#ytick.minor.pad
#ytick.color
#ytick.labelsize
#ytick.direction
#ytick.minor.visible
#ytick.major.left
#ytick.major.right
#ytick.minor.left
#ytick.minor.right
3.1. Introductory
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
True
False
3.5
2
0.8
0.6
3.5
3.4
k
medium
out
False
True
True
True
True
# draw ticks on the left side
# draw ticks on the right side
# major tick size in points
# minor tick size in points
# major tick width in points
# minor tick width in points
# distance to major tick label in points
# distance to the minor tick label in points
# color of the tick labels
# fontsize of the tick labels
# direction: in, out, or inout
# visibility of minor ticks on y-axis
# draw y axis left major ticks
# draw y axis right major ticks
# draw y axis left minor ticks
# draw y axis right minor ticks
39
Matplotlib, Release 2.1.2
### GRIDS
#grid.color
#grid.linestyle
#grid.linewidth
#grid.alpha
:
:
:
:
### Legend
#legend.loc
#legend.frameon
#legend.framealpha
#legend.facecolor
#legend.edgecolor
#legend.fancybox
b0b0b0
0.8
1.0
:
:
:
:
:
:
best
True
0.8
inherit
0.8
True
#
#
#
#
grid color
solid
in points
transparency, between 0.0 and 1.0
#
#
#
#
#
#
#
#
#
#
if True, draw the legend on a background patch
legend patch transparency
inherit from axes.facecolor; or color spec
background patch boundary color
if True, use a rounded box for the
legend background, else a rectangle
if True, give background a shadow effect
the number of marker points in the legend line
number of scatter points
the relative size of legend markers vs. original
#legend.shadow
: False
#legend.numpoints
: 1
#legend.scatterpoints : 1
#legend.markerscale
: 1.0
#legend.fontsize
: medium
# Dimensions as fraction of fontsize:
#legend.borderpad
: 0.4
# border whitespace
#legend.labelspacing : 0.5
# the vertical space between the legend entries
#legend.handlelength : 2.0
# the length of the legend lines
#legend.handleheight : 0.7
# the height of the legend handle
#legend.handletextpad : 0.8
# the space between the legend line and legend text
#legend.borderaxespad : 0.5
# the border between the axes and legend edge
#legend.columnspacing : 2.0
# column separation
### FIGURE
# See http://matplotlib.org/api/figure_api.html#matplotlib.figure.Figure
#figure.titlesize : large
# size of the figure title (Figure.suptitle())
#figure.titleweight : normal
# weight of the figure title
#figure.figsize
: 6.4, 4.8
# figure size in inches
#figure.dpi
: 100
# figure dots per inch
#figure.facecolor : white
# figure facecolor; 0.75 is scalar gray
#figure.edgecolor : white
# figure edgecolor
#figure.autolayout : False # When True, automatically adjust subplot
# parameters to make the plot fit the figure
# using `tight_layout`
#figure.constrained_layout.use: False # When True, automatically make plot
# elements fit on the figure. (Not compatible
# with `autolayout`, above).
#figure.max_open_warning : 20 # The maximum number of figures to open through
# the pyplot interface before emitting a warning.
# If less than one this feature is disabled.
# The figure subplot parameters. All dimensions are a fraction of the
#figure.subplot.left
: 0.125 # the left side of the subplots of the figure
#figure.subplot.right
: 0.9
# the right side of the subplots of the figure
#figure.subplot.bottom : 0.11
# the bottom of the subplots of the figure
#figure.subplot.top
: 0.88
# the top of the subplots of the figure
#figure.subplot.wspace : 0.2
# the amount of width reserved for space between␣
,→subplots,
40
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#figure.subplot.hspace
,→subplots,
: 0.2
# expressed as a fraction of the average axis width
# the amount of height reserved for space between␣
# expressed as a fraction of the average axis height
### IMAGES
#image.aspect : equal
#image.interpolation : nearest
#image.cmap
: viridis
#image.lut
: 256
#image.origin : upper
#image.resample : True
#image.composite_image : True
#
#
#
#
#
equal | auto | a number
see help(imshow) for options
A colormap name, gray etc...
the size of the colormap lookup table
lower | upper
#
#
#
#
When True, all the images on a set of axes are
combined into a single composite image before
saving a figure as a vector graphics file,
such as a PDF.
### CONTOUR PLOTS
#contour.negative_linestyle : dashed # string or on-off ink sequence
#contour.corner_mask
: True
# True | False | legacy
### ERRORBAR PLOTS
#errorbar.capsize : 0
### HISTOGRAM PLOTS
#hist.bins : 10
### SCATTER PLOTS
#scatter.marker : o
# length of end cap on error bars in pixels
# The default number of histogram bins.
# If Numpy 1.11 or later is
# installed, may also be `auto`
# The default marker type for scatter plots.
### Agg rendering
### Warning: experimental, 2008/10/10
#agg.path.chunksize : 0
# 0 to disable; values in the range
# 10000 to 100000 can improve speed slightly
# and prevent an Agg rendering failure
# when plotting very large data sets,
# especially if they are very gappy.
# It may cause minor artifacts, though.
# A value of 20000 is probably a good
# starting point.
### SAVING FIGURES
#path.simplify : True
# When True, simplify paths by removing "invisible"
# points to reduce file size and increase rendering
# speed
#path.simplify_threshold : 0.1 # The threshold of similarity below which
# vertices will be removed in the simplification
# process
#path.snap : True # When True, rectilinear axis-aligned paths will be snapped to
# the nearest pixel when certain criteria are met. When False,
# paths will never be snapped.
3.1. Introductory
41
Matplotlib, Release 2.1.2
#path.sketch : None #
#
#
#
#
#
#
May be none, or a 3-tuple of the form (scale, length,
randomness).
*scale* is the amplitude of the wiggle
perpendicular to the line (in pixels). *length*
is the length of the wiggle along the line (in
pixels). *randomness* is the factor by which
the length is randomly scaled.
# the default savefig params can be different from the display params
# e.g., you may want a higher resolution, or to make the figure
# background white
#savefig.dpi
: figure
# figure dots per inch or 'figure'
#savefig.facecolor
: white
# figure facecolor when saving
#savefig.edgecolor
: white
# figure edgecolor when saving
#savefig.format
: png
# png, ps, pdf, svg
#savefig.bbox
: standard # 'tight' or 'standard'.
# 'tight' is incompatible with pipe-based animation
# backends but will workd with temporary file based ones:
# e.g. setting animation.writer to ffmpeg will not work,
# use ffmpeg_file instead
#savefig.pad_inches : 0.1
# Padding to be used when bbox is set to 'tight'
#savefig.jpeg_quality: 95
# when a jpeg is saved, the default quality parameter.
#savefig.directory
: ~
# default directory in savefig dialog box,
# leave empty to always use current working directory
#savefig.transparent : False
# setting that controls whether figures are saved with a
# transparent background by default
# tk backend params
#tk.window_focus
: False
# ps backend params
#ps.papersize
: letter
#ps.useafm
: False
#ps.usedistiller
: False
,→
# Maintain shell focus for TkAgg
# auto, letter, legal, ledger, A0-A10, B0-B10
# use of afm fonts, results in small files
# can be: None, ghostscript or xpdf
# Experimental: may produce smaller files.
# xpdf intended for production of publication␣
quality files,
#ps.distiller.res
#ps.fonttype
: 6000
: 3
# but requires ghostscript, xpdf and ps2eps
# dpi
# Output Type 3 (Type3) or Type 42 (TrueType)
# pdf backend params
#pdf.compression
: 6 # integer from 0 to 9
# 0 disables compression (good for debugging)
#pdf.fonttype
: 3
# Output Type 3 (Type3) or Type 42 (TrueType)
# svg backend params
#svg.image_inline : True
# write raster image data directly into the svg file
#svg.fonttype : 'path'
# How to handle SVG fonts:
#
'none': Assume fonts are installed on the machine where the SVG will be viewed.
#
'path': Embed characters as paths -- supported by most SVG renderers
#
'svgfont': Embed characters as SVG fonts -- supported only by Chrome,
#
Opera and Safari
42
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
#svg.hashsalt : None
# docstring params
#docstring.hardcopy = False
# if not None, use this string as hash salt
# instead of uuid4
# set this when you want to generate hardcopy docstring
# Event keys to interact with figures/plots via keyboard.
# Customize these settings according to your needs.
# Leave the field(s) empty if you don't need a key-map. (i.e., fullscreen : '')
#keymap.fullscreen : f, ctrl+f
#keymap.home : h, r, home
#keymap.back : left, c, backspace
#keymap.forward : right, v
#keymap.pan : p
#keymap.zoom : o
#keymap.save : s
#keymap.quit : ctrl+w, cmd+w
#keymap.grid : g
#keymap.grid_minor : G
#keymap.yscale : l
#keymap.xscale : L, k
#keymap.all_axes : a
#
#
#
#
#
#
#
#
#
#
#
#
#
toggling
home or reset mnemonic
forward / backward keys to enable
left handed quick navigation
pan mnemonic
zoom mnemonic
saving current figure
close the current figure
switching on/off major grids in current axes
switching on/off minor grids in current axes
toggle scaling of y-axes ('log'/'linear')
toggle scaling of x-axes ('log'/'linear')
enable all axes
# Control location of examples data files
#examples.directory : ''
# directory to look in for custom installation
###ANIMATION settings
#animation.html : 'none'
# How to display the animation as HTML in
# the IPython notebook. 'html5' uses
# HTML5 video tag.
#animation.writer : ffmpeg
# MovieWriter 'backend' to use
#animation.codec : h264
# Codec to use for writing movie
#animation.bitrate: -1
# Controls size/quality tradeoff for movie.
# -1 implies let utility auto-determine
#animation.frame_format: 'png'
# Controls frame format used by temp files
#animation.html_args: ''
# Additional arguments to pass to html writer
#animation.ffmpeg_path: 'ffmpeg'
# Path to ffmpeg binary. Without full path
# $PATH is searched
#animation.ffmpeg_args: ''
# Additional arguments to pass to ffmpeg
#animation.avconv_path: 'avconv'
# Path to avconv binary. Without full path
# $PATH is searched
#animation.avconv_args: ''
# Additional arguments to pass to avconv
#animation.convert_path: 'convert' # Path to ImageMagick's convert binary.
# On Windows use the full path since convert
# is also the name of a system tool.
#animation.convert_args: ''
# Additional arguments to pass to convert
Total running time of the script: ( 0 minutes 0.071 seconds)
3.1. Introductory
43
Matplotlib, Release 2.1.2
3.1.4 Image tutorial
A short tutorial on plotting images with Matplotlib.
Startup commands
First, let’s start IPython. It is a most excellent enhancement to the standard Python prompt, and it ties in
especially well with Matplotlib. Start IPython either at a shell, or the IPython Notebook now.
With IPython started, we now need to connect to a GUI event loop. This tells IPython where (and how) to
display plots. To connect to a GUI loop, execute the %matplotlib magic at your IPython prompt. There’s
more detail on exactly what this does at IPython’s documentation on GUI event loops.
If you’re using IPython Notebook, the same commands are available, but people commonly use a specific
argument to the %matplotlib magic:
In [1]: %matplotlib inline
This turns on inline plotting, where plot graphics will appear in your notebook. This has important implications for interactivity. For inline plotting, commands in cells below the cell that outputs a plot will not affect
the plot. For example, changing the color map is not possible from cells below the cell that creates a plot.
However, for other backends, such as qt4, that open a separate window, cells below those that create the plot
will change the plot - it is a live object in memory.
This tutorial will use matplotlib’s imperative-style plotting interface, pyplot. This interface maintains global
state, and is very useful for quickly and easily experimenting with various plot settings. The alternative is
the object-oriented interface, which is also very powerful, and generally more suitable for large application
development. If you’d like to learn about the object-oriented interface, a great place to start is our FAQ on
usage. For now, let’s get on with the imperative-style approach:
import matplotlib.pyplot as plt
import matplotlib.image as mpimg
import numpy as np
Importing image data into Numpy arrays
Loading image data is supported by the Pillow library. Natively, matplotlib only supports PNG images. The
commands shown below fall back on Pillow if the native read fails.
The image used in this example is a PNG file, but keep that Pillow requirement in mind for your own data.
Here’s the image we’re going to play with:
44
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
It’s a 24-bit RGB PNG image (8 bits for each of R, G, B). Depending on where you get your data, the other
kinds of image that you’ll most likely encounter are RGBA images, which allow for transparency, or singlechannel grayscale (luminosity) images. You can right click on it and choose “Save image as” to download
it to your computer for the rest of this tutorial.
And here we go. . .
img = mpimg.imread('../../doc/_static/stinkbug.png')
print(img)
Out:
[[[0.40784314
[0.40784314
[0.40784314
...
[0.42745098
[0.42745098
[0.42745098
[[0.4117647
[0.4117647
[0.4117647
0.40784314 0.40784314]
0.40784314 0.40784314]
0.40784314 0.40784314]
0.42745098 0.42745098]
0.42745098 0.42745098]
0.42745098 0.42745098]]
0.4117647
0.4117647
0.4117647
3.1. Introductory
0.4117647 ]
0.4117647 ]
0.4117647 ]
45
Matplotlib, Release 2.1.2
...
[0.42745098 0.42745098 0.42745098]
[0.42745098 0.42745098 0.42745098]
[0.42745098 0.42745098 0.42745098]]
[[0.41960785
[0.41568628
[0.41568628
...
[0.43137255
[0.43137255
[0.43137255
0.41960785 0.41960785]
0.41568628 0.41568628]
0.41568628 0.41568628]
0.43137255 0.43137255]
0.43137255 0.43137255]
0.43137255 0.43137255]]
...
[[0.4392157
[0.43529412
[0.43137255
...
[0.45490196
[0.4509804
[0.4509804
0.4392157 0.4392157 ]
0.43529412 0.43529412]
0.43137255 0.43137255]
[[0.44313726
[0.44313726
[0.4392157
...
[0.4509804
[0.44705883
[0.44705883
0.44313726 0.44313726]
0.44313726 0.44313726]
0.4392157 0.4392157 ]
[[0.44313726
[0.4509804
[0.4509804
...
[0.44705883
[0.44705883
[0.44313726
0.44313726 0.44313726]
0.4509804 0.4509804 ]
0.4509804 0.4509804 ]
0.45490196 0.45490196]
0.4509804 0.4509804 ]
0.4509804 0.4509804 ]]
0.4509804 0.4509804 ]
0.44705883 0.44705883]
0.44705883 0.44705883]]
0.44705883 0.44705883]
0.44705883 0.44705883]
0.44313726 0.44313726]]]
Note the dtype there - float32. Matplotlib has rescaled the 8 bit data from each channel to floating point
data between 0.0 and 1.0. As a side note, the only datatype that Pillow can work with is uint8. Matplotlib
plotting can handle float32 and uint8, but image reading/writing for any format other than PNG is limited
to uint8 data. Why 8 bits? Most displays can only render 8 bits per channel worth of color gradation. Why
can they only render 8 bits/channel? Because that’s about all the human eye can see. More here (from a
photography standpoint): Luminous Landscape bit depth tutorial.
Each inner list represents a pixel. Here, with an RGB image, there are 3 values. Since it’s a black and white
image, R, G, and B are all similar. An RGBA (where A is alpha, or transparency), has 4 values per inner list,
and a simple luminance image just has one value (and is thus only a 2-D array, not a 3-D array). For RGB
and RGBA images, matplotlib supports float32 and uint8 data types. For grayscale, matplotlib supports only
float32. If your array data does not meet one of these descriptions, you need to rescale it.
46
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Plotting numpy arrays as images
So, you have your data in a numpy array (either by importing it, or by generating it). Let’s render it. In
Matplotlib, this is performed using the imshow() function. Here we’ll grab the plot object. This object
gives you an easy way to manipulate the plot from the prompt.
imgplot = plt.imshow(img)
You can also plot any numpy array.
Applying pseudocolor schemes to image plots
Pseudocolor can be a useful tool for enhancing contrast and visualizing your data more easily. This is
especially useful when making presentations of your data using projectors - their contrast is typically quite
poor.
Pseudocolor is only relevant to single-channel, grayscale, luminosity images. We currently have an RGB
image. Since R, G, and B are all similar (see for yourself above or in your data), we can just pick one
channel of our data:
lum_img = img[:, :, 0]
3.1. Introductory
47
Matplotlib, Release 2.1.2
# This is array slicing. You can read more in the `Numpy tutorial
# <https://docs.scipy.org/doc/numpy-dev/user/quickstart.html>`_.
plt.imshow(lum_img)
Now, with a luminosity (2D, no color) image, the default colormap (aka lookup table, LUT), is applied. The
default is called viridis. There are plenty of others to choose from.
plt.imshow(lum_img, cmap="hot")
48
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Note that you can also change colormaps on existing plot objects using the set_cmap() method:
imgplot = plt.imshow(lum_img)
imgplot.set_cmap('nipy_spectral')
3.1. Introductory
49
Matplotlib, Release 2.1.2
Note: However, remember that in the IPython notebook with the inline backend, you can’t make changes
to plots that have already been rendered. If you create imgplot here in one cell, you cannot call set_cmap()
on it in a later cell and expect the earlier plot to change. Make sure that you enter these commands together
in one cell. plt commands will not change plots from earlier cells.
There are many other colormap schemes available. See the list and images of the colormaps.
Color scale reference
It’s helpful to have an idea of what value a color represents. We can do that by adding color bars.
imgplot = plt.imshow(lum_img)
plt.colorbar()
50
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
This adds a colorbar to your existing figure. This won’t automatically change if you change you switch to a
different colormap - you have to re-create your plot, and add in the colorbar again.
Examining a specific data range
Sometimes you want to enhance the contrast in your image, or expand the contrast in a particular region
while sacrificing the detail in colors that don’t vary much, or don’t matter. A good tool to find interesting
regions is the histogram. To create a histogram of our image data, we use the hist() function.
plt.hist(lum_img.ravel(), bins=256, range=(0.0, 1.0), fc='k', ec='k')
3.1. Introductory
51
Matplotlib, Release 2.1.2
Most often, the “interesting” part of the image is around the peak, and you can get extra contrast by clipping
the regions above and/or below the peak. In our histogram, it looks like there’s not much useful information
in the high end (not many white things in the image). Let’s adjust the upper limit, so that we effectively
“zoom in on” part of the histogram. We do this by passing the clim argument to imshow. You could also do
this by calling the set_clim() method of the image plot object, but make sure that you do so in the same
cell as your plot command when working with the IPython Notebook - it will not change plots from earlier
cells.
You can specify the clim in the call to plot.
imgplot = plt.imshow(lum_img, clim=(0.0, 0.7))
52
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
You can also specify the clim using the returned object
fig = plt.figure()
a = fig.add_subplot(1, 2, 1)
imgplot = plt.imshow(lum_img)
a.set_title('Before')
plt.colorbar(ticks=[0.1, 0.3, 0.5, 0.7], orientation='horizontal')
a = fig.add_subplot(1, 2, 2)
imgplot = plt.imshow(lum_img)
imgplot.set_clim(0.0, 0.7)
a.set_title('After')
plt.colorbar(ticks=[0.1, 0.3, 0.5, 0.7], orientation='horizontal')
3.1. Introductory
53
Matplotlib, Release 2.1.2
Array Interpolation schemes
Interpolation calculates what the color or value of a pixel “should” be, according to different mathematical
schemes. One common place that this happens is when you resize an image. The number of pixels change,
but you want the same information. Since pixels are discrete, there’s missing space. Interpolation is how
you fill that space. This is why your images sometimes come out looking pixelated when you blow them
up. The effect is more pronounced when the difference between the original image and the expanded image
is greater. Let’s take our image and shrink it. We’re effectively discarding pixels, only keeping a select few.
Now when we plot it, that data gets blown up to the size on your screen. The old pixels aren’t there anymore,
and the computer has to draw in pixels to fill that space.
We’ll use the Pillow library that we used to load the image also to resize the image.
from PIL import Image
img = Image.open('../../doc/_static/stinkbug.png')
img.thumbnail((64, 64), Image.ANTIALIAS) # resizes image in-place
imgplot = plt.imshow(img)
54
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Here we have the default interpolation, bilinear, since we did not give imshow() any interpolation argument.
Let’s try some others. Here’s “nearest”, which does no interpolation.
imgplot = plt.imshow(img, interpolation="nearest")
3.1. Introductory
55
Matplotlib, Release 2.1.2
and bucibic:
imgplot = plt.imshow(img, interpolation="bicubic")
56
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Bicubic interpolation is often used when blowing up photos - people tend to prefer blurry over pixelated.
Total running time of the script: ( 0 minutes 0.559 seconds)
3.1.5 Usage Guide
This tutorial covers some basic usage patterns and best-practices to help you get started with Matplotlib.
General Concepts
matplotlib has an extensive codebase that can be daunting to many new users. However, most of matplotlib can be understood with a fairly simple conceptual framework and knowledge of a few important
points.
Plotting requires action on a range of levels, from the most general (e.g., ‘contour this 2-D array’) to the
most specific (e.g., ‘color this screen pixel red’). The purpose of a plotting package is to assist you in
visualizing your data as easily as possible, with all the necessary control – that is, by using relatively highlevel commands most of the time, and still have the ability to use the low-level commands when needed.
Therefore, everything in matplotlib is organized in a hierarchy. At the top of the hierarchy is the matplotlib
“state-machine environment” which is provided by the matplotlib.pyplot module. At this level, simple
functions are used to add plot elements (lines, images, text, etc.) to the current axes in the current figure.
3.1. Introductory
57
Matplotlib, Release 2.1.2
Note: Pyplot’s state-machine environment behaves similarly to MATLAB and should be most familiar to
users with MATLAB experience.
The next level down in the hierarchy is the first level of the object-oriented interface, in which pyplot is used
only for a few functions such as figure creation, and the user explicitly creates and keeps track of the figure
and axes objects. At this level, the user uses pyplot to create figures, and through those figures, one or more
axes objects can be created. These axes objects are then used for most plotting actions.
For even more control – which is essential for things like embedding matplotlib plots in GUI applications –
the pyplot level may be dropped completely, leaving a purely object-oriented approach.
# sphinx_gallery_thumbnail_number = 3
import matplotlib.pyplot as plt
import numpy as np
58
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Parts of a Figure
Figure
The whole figure. The figure keeps track of all the child Axes, a smattering of ‘special’ artists (titles, figure
legends, etc), and the canvas. (Don’t worry too much about the canvas, it is crucial as it is the object that
actually does the drawing to get you your plot, but as the user it is more-or-less invisible to you). A figure
can have any number of Axes, but to be useful should have at least one.
The easiest way to create a new figure is with pyplot:
3.1. Introductory
59
Matplotlib, Release 2.1.2
fig = plt.figure() # an empty figure with no axes
fig.suptitle('No axes on this figure') # Add a title so we know which it is
fig, ax_lst = plt.subplots(2, 2)
# a figure with a 2x2 grid of Axes
•
•
Axes
This is what you think of as ‘a plot’, it is the region of the image with the data space. A given figure can
contain many Axes, but a given Axes object can only be in one Figure. The Axes contains two (or three
in the case of 3D) Axis objects (be aware of the difference between Axes and Axis) which take care of
the data limits (the data limits can also be controlled via set via the set_xlim() and set_ylim() Axes
methods). Each Axes has a title (set via set_title()), an x-label (set via set_xlabel()), and a y-label
set via set_ylabel()).
The Axes class and it’s member functions are the primary entry point to working with the OO interface.
Axis
These are the number-line-like objects. They take care of setting the graph limits and generating the ticks
(the marks on the axis) and ticklabels (strings labeling the ticks). The location of the ticks is determined by
60
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
a Locator object and the ticklabel strings are formatted by a Formatter. The combination of the correct
Locator and Formatter gives very fine control over the tick locations and labels.
Artist
Basically everything you can see on the figure is an artist (even the Figure, Axes, and Axis objects). This
includes Text objects, Line2D objects, collection objects, Patch objects . . . (you get the idea). When
the figure is rendered, all of the artists are drawn to the canvas. Most Artists are tied to an Axes; such an
Artist cannot be shared by multiple Axes, or moved from one to another.
Types of inputs to plotting functions
All of plotting functions expect np.array or np.ma.masked_array as input. Classes that are ‘array-like’
such as pandas data objects and np.matrix may or may not work as intended. It is best to convert these to
np.array objects prior to plotting.
For example, to convert a pandas.DataFrame
a = pandas.DataFrame(np.random.rand(4,5), columns = list('abcde'))
a_asndarray = a.values
and to covert a np.matrix
b = np.matrix([[1,2],[3,4]])
b_asarray = np.asarray(b)
Matplotlib, pyplot and pylab: how are they related?
Matplotlib is the whole package; matplotlib.pyplot is a module in matplotlib; and pylab is a module
that gets installed alongside matplotlib.
Pyplot provides the state-machine interface to the underlying object-oriented plotting library. The statemachine implicitly and automatically creates figures and axes to achieve the desired plot. For example:
x = np.linspace(0, 2, 100)
plt.plot(x, x, label='linear')
plt.plot(x, x**2, label='quadratic')
plt.plot(x, x**3, label='cubic')
plt.xlabel('x label')
plt.ylabel('y label')
plt.title("Simple Plot")
plt.legend()
plt.show()
3.1. Introductory
61
Matplotlib, Release 2.1.2
The first call to plt.plot will automatically create the necessary figure and axes to achieve the desired plot.
Subsequent calls to plt.plot re-use the current axes and each add another line. Setting the title, legend,
and axis labels also automatically use the current axes and set the title, create the legend, and label the axis
respectively.
pylab is a convenience module that bulk imports matplotlib.pyplot (for plotting) and numpy (for mathematics and working with arrays) in a single name space. Although many examples use pylab, it is no
longer recommended.
For non-interactive plotting it is suggested to use pyplot to create the figures and then the OO interface for
plotting.
Coding Styles
When viewing this documentation and examples, you will find different coding styles and usage patterns.
These styles are perfectly valid and have their pros and cons. Just about all of the examples can be converted
into another style and achieve the same results. The only caveat is to avoid mixing the coding styles for your
own code.
Note: Developers for matplotlib have to follow a specific style and guidelines. See The Matplotlib Devel-
62
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
opers’ Guide.
Of the different styles, there are two that are officially supported. Therefore, these are the preferred ways to
use matplotlib.
For the pyplot style, the imports at the top of your scripts will typically be:
import matplotlib.pyplot as plt
import numpy as np
Then one calls, for example, np.arange, np.zeros, np.pi, plt.figure, plt.plot, plt.show, etc. Use the pyplot
interface for creating figures, and then use the object methods for the rest:
x = np.arange(0, 10, 0.2)
y = np.sin(x)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(x, y)
plt.show()
So, why all the extra typing instead of the MATLAB-style (which relies on global state and a flat namespace)? For very simple things like this example, the only advantage is academic: the wordier styles are
more explicit, more clear as to where things come from and what is going on. For more complicated ap3.1. Introductory
63
Matplotlib, Release 2.1.2
plications, this explicitness and clarity becomes increasingly valuable, and the richer and more complete
object-oriented interface will likely make the program easier to write and maintain.
Typically one finds oneself making the same plots over and over again, but with different data sets, which
leads to needing to write specialized functions to do the plotting. The recommended function signature is
something like:
def my_plotter(ax, data1, data2, param_dict):
"""
A helper function to make a graph
Parameters
---------ax : Axes
The axes to draw to
data1 : array
The x data
data2 : array
The y data
param_dict : dict
Dictionary of kwargs to pass to ax.plot
Returns
------out : list
list of artists added
"""
out = ax.plot(data1, data2, **param_dict)
return out
# which you would then use as:
data1, data2, data3, data4 = np.random.randn(4, 100)
fig, ax = plt.subplots(1, 1)
my_plotter(ax, data1, data2, {'marker': 'x'})
64
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
or if you wanted to have 2 sub-plots:
fig, (ax1, ax2) = plt.subplots(1, 2)
my_plotter(ax1, data1, data2, {'marker': 'x'})
my_plotter(ax2, data3, data4, {'marker': 'o'})
3.1. Introductory
65
Matplotlib, Release 2.1.2
Again, for these simple examples this style seems like overkill, however once the graphs get slightly more
complex it pays off.
Backends
What is a backend?
A lot of documentation on the website and in the mailing lists refers to the “backend” and many new
users are confused by this term. matplotlib targets many different use cases and output formats. Some
people use matplotlib interactively from the python shell and have plotting windows pop up when they type
commands. Some people embed matplotlib into graphical user interfaces like wxpython or pygtk to build
rich applications. Others use matplotlib in batch scripts to generate postscript images from some numerical
simulations, and still others in web application servers to dynamically serve up graphs.
To support all of these use cases, matplotlib can target different outputs, and each of these capabilities is
called a backend; the “frontend” is the user facing code, i.e., the plotting code, whereas the “backend” does
all the hard work behind-the-scenes to make the figure. There are two types of backends: user interface
backends (for use in pygtk, wxpython, tkinter, qt4, or macosx; also referred to as “interactive backends”)
and hardcopy backends to make image files (PNG, SVG, PDF, PS; also referred to as “non-interactive
backends”).
66
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
There are four ways to configure your backend. If they conflict each other, the method mentioned last in the
following list will be used, e.g. calling use() will override the setting in your matplotlibrc.
1. The backend parameter in your matplotlibrc file (see Customizing matplotlib):
backend : WXAgg
# use wxpython with antigrain (agg) rendering
2. Setting the MPLBACKEND environment variable, either for your current shell or for a single script:
> export MPLBACKEND="module://my_backend"
> python simple_plot.py
> MPLBACKEND="module://my_backend" python simple_plot.py
Setting this environment variable will override the backend parameter in any matplotlibrc, even if
there is a matplotlibrc in your current working directory. Therefore setting MPLBACKEND globally,
e.g. in your .bashrc or .profile, is discouraged as it might lead to counter-intuitive behavior.
3. If your script depends on a specific backend you can use the use() function:
import matplotlib
matplotlib.use('PS')
# generate postscript output by default
If you use the use() function, this must be done before importing matplotlib.pyplot. Calling
use() after pyplot has been imported will have no effect. Using use() will require changes in your
code if users want to use a different backend. Therefore, you should avoid explicitly calling use()
unless absolutely necessary.
Note: Backend name specifications are not case-sensitive; e.g., ‘GTKAgg’ and ‘gtkagg’ are equivalent.
With a typical installation of matplotlib, such as from a binary installer or a linux distribution package, a
good default backend will already be set, allowing both interactive work and plotting from scripts, with
output to the screen and/or to a file, so at least initially you will not need to use any of the methods given
above.
If, however, you want to write graphical user interfaces, or a web application server (Matplotlib in a web
application server), or need a better understanding of what is going on, read on. To make things a little
more customizable for graphical user interfaces, matplotlib separates the concept of the renderer (the thing
that actually does the drawing) from the canvas (the place where the drawing goes). The canonical renderer
for user interfaces is Agg which uses the Anti-Grain Geometry C++ library to make a raster (pixel) image
of the figure. All of the user interfaces except macosx can be used with agg rendering, e.g., WXAgg, GTKAgg,
QT4Agg, QT5Agg, TkAgg. In addition, some of the user interfaces support other rendering engines. For
example, with GTK, you can also select GDK rendering (backend GTK deprecated in 2.0) or Cairo rendering
(backend GTKCairo).
For the rendering engines, one can also distinguish between vector or raster renderers. Vector graphics
languages issue drawing commands like “draw a line from this point to this point” and hence are scale free,
and raster backends generate a pixel representation of the line whose accuracy depends on a DPI setting.
Here is a summary of the matplotlib renderers (there is an eponymous backed for each; these are noninteractive backends, capable of writing to a file):
3.1. Introductory
67
Matplotlib, Release 2.1.2
Renderer
Filetypes
Description
AGG
png
PS
PDF
SVG
Cairo
ps eps
pdf
svg
png ps pdf svg
...
raster graphics – high quality images using the Anti-Grain Geometry
engine
vector graphics – Postscript output
vector graphics – Portable Document Format
vector graphics – Scalable Vector Graphics
vector graphics – Cairo graphics
And here are the user interfaces and renderer combinations supported; these are interactive backends, capable of displaying to the screen and of using appropriate renderers from the table above to write to a file:
Backend
Description
Qt5Agg Agg rendering in a Qt5 canvas (requires PyQt5). This backend can be activated in IPython with
%matplotlib qt5.
ipympl Agg rendering embedded in a Jupyter widget. (requires ipympl) This can be enabled in a
Jupyter notebook with %matplotlib ipympl
GTK3AggAgg rendering to a GTK 3.x canvas (requires PyGObject and pycairo or cairocffi) This backend
can be activated in IPython with %matplotlib gtk3.
maAgg rendering into a Cocoa canvas in OSX. This backend can be activated in IPython with
cosx
%matplotlib osx.
TkAgg rendering to a Tk canvas (requires TkInter). This backend can be activated in IPython with
Agg
%matplotlib tk.
nbAgg Embed an interactive figure in a Jupyter classic notebook. This backend can be enabled in
Jupyter notebooks via %matplotlib notebook.
WeOn show() will start a tornado server with an interactive figure.
bAgg
GTK3Cairo
Cairo rendering to a GTK 3.x canvas (requires PyGObject and pycairo or cairocffi)
Qt4Agg Agg rendering to a Qt4 canvas (requires PyQt4 or pyside). This backend can be activated in
IPython with %matplotlib qt4.
GTKAgg rendering to a GTK 2.x canvas (requires PyGTK and pycairo or cairocffi; Python2 only)
Agg
This backend can be activated in IPython with %matplotlib gtk.
GTKCairo rendering to a GTK 2.x canvas (requires PyGTK and pycairo or cairocffi; Python2 only)
Cairo
WXAgg rendering to a wxWidgets canvas (requires wxPython. v4.0 (in beta) is required for
Agg
python3). This backend can be activated in IPython with %matplotlib wx.
ipympl
The Jupyter widget ecosystem is moving too fast to support directly in Matplotlib. To install ipympl
pip install ipympl
jupyter nbextension enable --py --sys-prefix ipympl
68
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
or
conda install ipympl -c conda-forge
See jupyter-matplotlib for more details.
GTK and Cairo
Both GTK2 and GTK3 have implicit dependencies on PyCairo regardless of the specific Matplotlib backend
used. Unfortunatly the latest release of PyCairo for Python3 does not implement the Python wrappers
needed for the GTK3Agg backend. Cairocffi can be used as a replacement which implements the correct
wrapper.
How do I select PyQt4 or PySide?
You can choose either PyQt4 or PySide when using the qt4 backend by setting the appropriate value for
backend.qt4 in your matplotlibrc file. The default value is PyQt4.
The setting in your matplotlibrc file can be overridden by setting the QT_API environment variable to
either pyqt or pyside to use PyQt4 or PySide, respectively.
Since the default value for the bindings to be used is PyQt4, matplotlib first tries to import it, if the import
fails, it tries to import PySide.
What is interactive mode?
Use of an interactive backend (see What is a backend?) permits–but does not by itself require or ensure–plotting to the screen. Whether and when plotting to the screen occurs, and whether a script or shell
session continues after a plot is drawn on the screen, depends on the functions and methods that are called,
and on a state variable that determines whether matplotlib is in “interactive mode”. The default Boolean
value is set by the matplotlibrc file, and may be customized like any other configuration parameter (see
Customizing matplotlib). It may also be set via matplotlib.interactive(), and its value may be queried
via matplotlib.is_interactive(). Turning interactive mode on and off in the middle of a stream of
plotting commands, whether in a script or in a shell, is rarely needed and potentially confusing, so in the
following we will assume all plotting is done with interactive mode either on or off.
Note: Major changes related to interactivity, and in particular the role and behavior of show(), were made
in the transition to matplotlib version 1.0, and bugs were fixed in 1.0.1. Here we describe the version 1.0.1
behavior for the primary interactive backends, with the partial exception of macosx.
Interactive mode may also be turned on via matplotlib.pyplot.ion(), and turned off via matplotlib.
pyplot.ioff().
Note: Interactive mode works with suitable backends in ipython and in the ordinary python shell, but it
does not work in the IDLE IDE. If the default backend does not support interactivity, an interactive backend
3.1. Introductory
69
Matplotlib, Release 2.1.2
can be explicitly activated using any of the methods discussed in What is a backend?.
Interactive example
From an ordinary python prompt, or after invoking ipython with no options, try this:
import matplotlib.pyplot as plt
plt.ion()
plt.plot([1.6, 2.7])
Assuming you are running version 1.0.1 or higher, and you have an interactive backend installed and selected
by default, you should see a plot, and your terminal prompt should also be active; you can type additional
commands such as:
plt.title("interactive test")
plt.xlabel("index")
and you will see the plot being updated after each line. Since version 1.5, modifying the plot by other means
should also automatically update the display on most backends. Get a reference to the Axes instance, and
call a method of that instance:
ax = plt.gca()
ax.plot([3.1, 2.2])
If you are using certain backends (like macosx), or an older version of matplotlib, you may not see the new
line added to the plot immediately. In this case, you need to explicitly call draw() in order to update the
plot:
plt.draw()
Non-interactive example
Start a fresh session as in the previous example, but now turn interactive mode off:
import matplotlib.pyplot as plt
plt.ioff()
plt.plot([1.6, 2.7])
Nothing happened–or at least nothing has shown up on the screen (unless you are using macosx backend,
which is anomalous). To make the plot appear, you need to do this:
plt.show()
Now you see the plot, but your terminal command line is unresponsive; the show() command blocks the
input of additional commands until you manually kill the plot window.
What good is this–being forced to use a blocking function? Suppose you need a script that plots the contents
of a file to the screen. You want to look at that plot, and then end the script. Without some blocking
70
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
command such as show(), the script would flash up the plot and then end immediately, leaving nothing on
the screen.
In addition, non-interactive mode delays all drawing until show() is called; this is more efficient than redrawing the plot each time a line in the script adds a new feature.
Prior to version 1.0, show() generally could not be called more than once in a single script (although sometimes one could get away with it); for version 1.0.1 and above, this restriction is lifted, so one can write a
script like this:
import numpy as np
import matplotlib.pyplot as plt
plt.ioff()
for i in range(3):
plt.plot(np.random.rand(10))
plt.show()
which makes three plots, one at a time.
Summary
In interactive mode, pyplot functions automatically draw to the screen.
3.1. Introductory
71
Matplotlib, Release 2.1.2
When plotting interactively, if using object method calls in addition to pyplot functions, then call draw()
whenever you want to refresh the plot.
Use non-interactive mode in scripts in which you want to generate one or more figures and display them
before ending or generating a new set of figures. In that case, use show() to display the figure(s) and to
block execution until you have manually destroyed them.
Performance
Whether exploring data in interactive mode or programatically saving lots of plots, rendering performance
can be a painful bottleneck in your pipeline. Matplotlib provides a couple ways to greatly reduce rendering
time at the cost of a slight change (to a settable tolerance) in your plot’s appearance. The methods available
to reduce rendering time depend on the type of plot that is being created.
Line segment simplification
For plots that have line segments (e.g. typical line plots, outlines of polygons, etc.), rendering performance can be controlled by the path.simplify and path.simplify_threshold parameters in your
matplotlibrc file (see Customizing matplotlib for more information about the matplotlibrc file). The
path.simplify parameter is a boolean indicating whether or not line segments are simplified at all. The
path.simplify_threshold parameter controls how much line segments are simplified; higher thresholds
result in quicker rendering.
The following script will first display the data without any simplification, and then display the same data
with simplification. Try interacting with both of them:
import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl
# Setup, and create the data to plot
y = np.random.rand(100000)
y[50000:] *= 2
y[np.logspace(1, np.log10(50000), 400).astype(int)] = -1
mpl.rcParams['path.simplify'] = True
mpl.rcParams['path.simplify_threshold'] = 0.0
plt.plot(y)
plt.show()
mpl.rcParams['path.simplify_threshold'] = 1.0
plt.plot(y)
plt.show()
Matplotlib currently defaults to a conservative simplification threshold of 1/9. If you want to change your
default settings to use a different value, you can change your matplotlibrc file. Alternatively, you could
create a new style for interactive plotting (with maximal simplification) and another style for publication
quality plotting (with minimal simplification) and activate them as necessary. See Customizing matplotlib
for instructions on how to perform these actions.
72
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
The simplification works by iteratively merging line segments into a single vector until the next line segment’s perpendicular distance to the vector (measured in display-coordinate space) is greater than the path.
simplify_threshold parameter.
Note: Changes related to how line segments are simplified were made in version 2.1. Rendering time will
still be improved by these parameters prior to 2.1, but rendering time for some kinds of data will be vastly
improved in versions 2.1 and greater.
Marker simplification
Markers can also be simplified, albeit less robustly than line segments. Marker simplification is only
available to Line2D objects (through the markevery property). Wherever Line2D construction parameter are passed through, such as matplotlib.pyplot.plot() and matplotlib.axes.Axes.plot(), the
markevery parameter can be used:
plt.plot(x, y, markevery=10)
The markevery argument allows for naive subsampling, or an attempt at evenly spaced (along the x axis)
sampling. See the sphx_glr_gallery_lines_bars_and_markers_markevery_demo.py for more information.
Splitting lines into smaller chunks
If you are using the Agg backend (see What is a backend?), then you can make use of the agg.path.
chunksize rc parameter. This allows you to specify a chunk size, and any lines with greater than that many
vertices will be split into multiple lines, each of which have no more than agg.path.chunksize many
vertices. (Unless agg.path.chunksize is zero, in which case there is no chunking.) For some kind of
data, chunking the line up into reasonable sizes can greatly decrease rendering time.
The following script will first display the data without any chunk size restriction, and then display the same
data with a chunk size of 10,000. The difference can best be seen when the figures are large, try maximizing
the GUI and then interacting with them:
import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl
mpl.rcParams['path.simplify_threshold'] = 1.0
# Setup, and create the data to plot
y = np.random.rand(100000)
y[50000:] *= 2
y[np.logspace(1,np.log10(50000), 400).astype(int)] = -1
mpl.rcParams['path.simplify'] = True
mpl.rcParams['agg.path.chunksize'] = 0
plt.plot(y)
plt.show()
3.1. Introductory
73
Matplotlib, Release 2.1.2
mpl.rcParams['agg.path.chunksize'] = 10000
plt.plot(y)
plt.show()
Using the fast style
The fast style can be used to automatically set simplification and chunking parameters to reasonable settings
to speed up plotting large amounts of data. It can be used simply by running:
import matplotlib.style as mplstyle
mplstyle.use('fast')
It is very light weight, so it plays nicely with other styles, just make sure the fast style is applied last so that
other styles do not overwrite the settings:
mplstyle.use(['dark_background', 'ggplot', 'fast'])
Total running time of the script: ( 0 minutes 0.192 seconds)
3.1.6 Pyplot tutorial
An introduction to the pyplot interface.
Intro to pyplot
matplotlib.pyplot is a collection of command style functions that make matplotlib work like MATLAB.
Each pyplot function makes some change to a figure: e.g., creates a figure, creates a plotting area in a figure,
plots some lines in a plotting area, decorates the plot with labels, etc.
In matplotlib.pyplot various states are preserved across function calls, so that it keeps track of things
like the current figure and plotting area, and the plotting functions are directed to the current axes (please
note that “axes” here and in most places in the documentation refers to the axes part of a figure and not the
strict mathematical term for more than one axis).
Note: the pyplot API is generally less-flexible than the object-oriented API. Most of the function calls you
see here can also be called as methods from an Axes object. We recommend browsing the tutorials and
examples to see how this works.
Generating visualizations with pyplot is very quick:
import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()
74
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
You may be wondering why the x-axis ranges from 0-3 and the y-axis from 1-4. If you provide a single
list or array to the plot() command, matplotlib assumes it is a sequence of y values, and automatically
generates the x values for you. Since python ranges start with 0, the default x vector has the same length as
y but starts with 0. Hence the x data are [0,1,2,3].
plot() is a versatile command, and will take an arbitrary number of arguments. For example, to plot x
versus y, you can issue the command:
plt.plot([1, 2, 3, 4], [1, 4, 9, 16])
3.1. Introductory
75
Matplotlib, Release 2.1.2
Formatting the style of your plot
For every x, y pair of arguments, there is an optional third argument which is the format string that indicates
the color and line type of the plot. The letters and symbols of the format string are from MATLAB, and you
concatenate a color string with a line style string. The default format string is ‘b-‘, which is a solid blue line.
For example, to plot the above with red circles, you would issue
plt.plot([1, 2, 3, 4], [1, 4, 9, 16], 'ro')
plt.axis([0, 6, 0, 20])
plt.show()
76
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
See the plot() documentation for a complete list of line styles and format strings. The axis() command
in the example above takes a list of [xmin, xmax, ymin, ymax] and specifies the viewport of the axes.
If matplotlib were limited to working with lists, it would be fairly useless for numeric processing. Generally,
you will use numpy arrays. In fact, all sequences are converted to numpy arrays internally. The example
below illustrates a plotting several lines with different format styles in one command using arrays.
import numpy as np
# evenly sampled time at 200ms intervals
t = np.arange(0., 5., 0.2)
# red dashes, blue squares and green triangles
plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
plt.show()
3.1. Introductory
77
Matplotlib, Release 2.1.2
Plotting with keyword strings
There are some instances where you have data in a format that lets you access particular variables with
strings. For example, with numpy.recarray or pandas.DataFrame.
Matplotlib allows you provide such an object with the data keyword argument. If provided, then you may
generate plots with the strings corresponding to these variables.
data = {'a': np.arange(50),
'c': np.random.randint(0, 50, 50),
'd': np.random.randn(50)}
data['b'] = data['a'] + 10 * np.random.randn(50)
data['d'] = np.abs(data['d']) * 100
plt.scatter('a', 'b', c='c', s='d', data=data)
plt.xlabel('entry a')
plt.ylabel('entry b')
plt.show()
78
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Plotting with categorical variables
It is also possible to create a plot using categorical variables. Matplotlib allows you to pass categorical
variables directly to many plotting functions. For example:
names = ['group_a', 'group_b', 'group_c']
values = [1, 10, 100]
plt.figure(1, figsize=(9, 3))
plt.subplot(131)
plt.bar(names, values)
plt.subplot(132)
plt.scatter(names, values)
plt.subplot(133)
plt.plot(names, values)
plt.suptitle('Categorical Plotting')
plt.show()
3.1. Introductory
79
Matplotlib, Release 2.1.2
Controlling line properties
Lines have many attributes that you can set: linewidth, dash style, antialiased, etc; see matplotlib.lines.
Line2D. There are several ways to set line properties
• Use keyword args:
plt.plot(x, y, linewidth=2.0)
• Use the setter methods of a Line2D instance. plot returns a list of Line2D objects; e.g., line1,
line2 = plot(x1, y1, x2, y2). In the code below we will suppose that we have only one line
so that the list returned is of length 1. We use tuple unpacking with line, to get the first element of
that list:
line, = plt.plot(x, y, '-')
line.set_antialiased(False) # turn off antialising
• Use the setp() command. The example below uses a MATLAB-style command to set multiple
properties on a list of lines. setp works transparently with a list of objects or a single object. You can
either use python keyword arguments or MATLAB-style string/value pairs:
lines = plt.plot(x1, y1, x2, y2)
# use keyword args
plt.setp(lines, color='r', linewidth=2.0)
# or MATLAB style string value pairs
plt.setp(lines, 'color', 'r', 'linewidth', 2.0)
Here are the available Line2D properties.
Property
Value Type
alpha
animated
antialiased or aa
clip_box
clip_on
float
[True | False]
[True | False]
a matplotlib.transform.Bbox instance
[True | False]
Continued on next page
80
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Property
Table 3.1 – continued from previous page
Value Type
clip_path
color or c
contains
dash_capstyle
dash_joinstyle
dashes
data
figure
label
linestyle or ls
linewidth or lw
lod
marker
markeredgecolor or mec
markeredgewidth or mew
markerfacecolor or mfc
markersize or ms
markevery
picker
pickradius
solid_capstyle
solid_joinstyle
transform
visible
xdata
ydata
zorder
a Path instance and a Transform instance, a Patch
any matplotlib color
the hit testing function
['butt' | 'round' | 'projecting']
['miter' | 'round' | 'bevel']
sequence of on/off ink in points
(np.array xdata, np.array ydata)
a matplotlib.figure.Figure instance
any string
[ '-' | '--' | '-.' | ':' | 'steps' | . . . ]
float value in points
[True | False]
[ '+' | ',' | '.' | '1' | '2' | '3' | '4' ]
any matplotlib color
float value in points
any matplotlib color
float
[ None | integer | (startind, stride) ]
used in interactive line selection
the line pick selection radius
['butt' | 'round' | 'projecting']
['miter' | 'round' | 'bevel']
a matplotlib.transforms.Transform instance
[True | False]
np.array
np.array
any number
To get a list of settable line properties, call the setp() function with a line or lines as argument
In [69]: lines = plt.plot([1, 2, 3])
In [70]: plt.setp(lines)
alpha: float
animated: [True | False]
antialiased or aa: [True | False]
...snip
Working with multiple figures and axes
MATLAB, and pyplot, have the concept of the current figure and the current axes. All plotting commands apply to the current axes. The function gca() returns the current axes (a matplotlib.axes.Axes
instance), and gcf() returns the current figure (matplotlib.figure.Figure instance). Normally, you
don’t have to worry about this, because it is all taken care of behind the scenes. Below is a script to create
two subplots.
3.1. Introductory
81
Matplotlib, Release 2.1.2
def f(t):
return np.exp(-t) * np.cos(2*np.pi*t)
t1 = np.arange(0.0, 5.0, 0.1)
t2 = np.arange(0.0, 5.0, 0.02)
plt.figure(1)
plt.subplot(211)
plt.plot(t1, f(t1), 'bo', t2, f(t2), 'k')
plt.subplot(212)
plt.plot(t2, np.cos(2*np.pi*t2), 'r--')
plt.show()
The figure() command here is optional because figure(1) will be created by default, just as a
subplot(111) will be created by default if you don’t manually specify any axes. The subplot() command
specifies numrows, numcols, plot_number where plot_number ranges from 1 to numrows*numcols.
The commas in the subplot command are optional if numrows*numcols<10. So subplot(211) is identical to subplot(2, 1, 1).
You can create an arbitrary number of subplots and axes. If you want to place an axes manually,
i.e., not on a rectangular grid, use the axes() command, which allows you to specify the location as
axes([left, bottom, width, height]) where all values are in fractional (0 to 1) coordinates. See
82
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
sphx_glr_gallery_subplots_axes_and_figures_axes_demo.py for an example of placing axes manually and
sphx_glr_gallery_subplots_axes_and_figures_subplot_demo.py for an example with lots of subplots.
You can create multiple figures by using multiple figure() calls with an increasing figure number. Of
course, each figure can contain as many axes and subplots as your heart desires:
import matplotlib.pyplot as plt
plt.figure(1)
# the first figure
plt.subplot(211)
# the first subplot in the first figure
plt.plot([1, 2, 3])
plt.subplot(212)
# the second subplot in the first figure
plt.plot([4, 5, 6])
plt.figure(2)
plt.plot([4, 5, 6])
# a second figure
# creates a subplot(111) by default
plt.figure(1)
# figure 1 current; subplot(212) still current
plt.subplot(211)
# make subplot(211) in figure1 current
plt.title('Easy as 1, 2, 3') # subplot 211 title
You can clear the current figure with clf() and the current axes with cla(). If you find it annoying that
states (specifically the current image, figure and axes) are being maintained for you behind the scenes, don’t
despair: this is just a thin stateful wrapper around an object oriented API, which you can use instead (see
Artist tutorial)
If you are making lots of figures, you need to be aware of one more thing: the memory required for a figure
is not completely released until the figure is explicitly closed with close(). Deleting all references to the
figure, and/or using the window manager to kill the window in which the figure appears on the screen, is not
enough, because pyplot maintains internal references until close() is called.
Working with text
The text() command can be used to add text in an arbitrary location, and the xlabel(), ylabel() and
title() are used to add text in the indicated locations (see Text introduction for a more detailed example)
mu, sigma = 100, 15
x = mu + sigma * np.random.randn(10000)
# the histogram of the data
n, bins, patches = plt.hist(x, 50, normed=1, facecolor='g', alpha=0.75)
plt.xlabel('Smarts')
plt.ylabel('Probability')
plt.title('Histogram of IQ')
plt.text(60, .025, r'$\mu=100,\ \sigma=15$')
plt.axis([40, 160, 0, 0.03])
plt.grid(True)
plt.show()
3.1. Introductory
83
Matplotlib, Release 2.1.2
All of the text() commands return an matplotlib.text.Text instance. Just as with with lines above,
you can customize the properties by passing keyword arguments into the text functions or using setp():
t = plt.xlabel('my data', fontsize=14, color='red')
These properties are covered in more detail in Text properties and layout.
Using mathematical expressions in text
matplotlib accepts TeX equation expressions in any text expression. For example to write the expression
σi = 15 in the title, you can write a TeX expression surrounded by dollar signs:
plt.title(r'$\sigma_i=15$')
The r preceding the title string is important – it signifies that the string is a raw string and not to treat
backslashes as python escapes. matplotlib has a built-in TeX expression parser and layout engine, and ships
its own math fonts – for details see Writing mathematical expressions. Thus you can use mathematical text
across platforms without requiring a TeX installation. For those who have LaTeX and dvipng installed, you
can also use LaTeX to format your text and incorporate the output directly into your display figures or saved
postscript – see Text rendering With LaTeX.
84
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Annotating text
The uses of the basic text() command above place text at an arbitrary position on the Axes. A common use
for text is to annotate some feature of the plot, and the annotate() method provides helper functionality
to make annotations easy. In an annotation, there are two points to consider: the location being annotated
represented by the argument xy and the location of the text xytext. Both of these arguments are (x,y)
tuples.
ax = plt.subplot(111)
t = np.arange(0.0, 5.0, 0.01)
s = np.cos(2*np.pi*t)
line, = plt.plot(t, s, lw=2)
plt.annotate('local max', xy=(2, 1), xytext=(3, 1.5),
arrowprops=dict(facecolor='black', shrink=0.05),
)
plt.ylim(-2, 2)
plt.show()
In this basic example, both the xy (arrow tip) and xytext locations (text location) are in
data coordinates.
There are a variety of other coordinate systems one can choose – see
3.1. Introductory
85
Matplotlib, Release 2.1.2
Basic annotation and Advanced Annotation for details.
More examples can be found in
sphx_glr_gallery_text_labels_and_annotations_annotation_demo.py.
Logarithmic and other nonlinear axes
matplotlib.pyplot supports not only linear axis scales, but also logarithmic and logit scales. This is
commonly used if data spans many orders of magnitude. Changing the scale of an axis is easy:
plt.xscale(‘log’)
An example of four plots with the same data and different scales for the y axis is shown below.
from matplotlib.ticker import NullFormatter
# useful for `logit` scale
# Fixing random state for reproducibility
np.random.seed(19680801)
# make up some data in the interval ]0, 1[
y = np.random.normal(loc=0.5, scale=0.4, size=1000)
y = y[(y > 0) & (y < 1)]
y.sort()
x = np.arange(len(y))
# plot with various axes scales
plt.figure(1)
# linear
plt.subplot(221)
plt.plot(x, y)
plt.yscale('linear')
plt.title('linear')
plt.grid(True)
# log
plt.subplot(222)
plt.plot(x, y)
plt.yscale('log')
plt.title('log')
plt.grid(True)
# symmetric log
plt.subplot(223)
plt.plot(x, y - y.mean())
plt.yscale('symlog', linthreshy=0.01)
plt.title('symlog')
plt.grid(True)
# logit
plt.subplot(224)
plt.plot(x, y)
plt.yscale('logit')
86
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
plt.title('logit')
plt.grid(True)
# Format the minor tick labels of the y-axis into empty strings with
# `NullFormatter`, to avoid cumbering the axis with too many labels.
plt.gca().yaxis.set_minor_formatter(NullFormatter())
# Adjust the subplot layout, because the logit one may take more space
# than usual, due to y-tick labels like "1 - 10^{-3}"
plt.subplots_adjust(top=0.92, bottom=0.08, left=0.10, right=0.95, hspace=0.25,
wspace=0.35)
plt.show()
It is also possible to add your own scale, see Developer’s guide for creating scales and transformations for
details.
Total running time of the script: ( 0 minutes 0.479 seconds)
3.1.7 The Lifecycle of a Plot
This tutorial aims to show the beginning, middle, and end of a single visualization using Matplotlib. We’ll
begin with some raw data and end by saving a figure of a customized visualization. Along the way we’ll try
to highlight some neat features and best-practices using Matplotlib.
3.1. Introductory
87
Matplotlib, Release 2.1.2
Note: This tutorial is based off of this excellent blog post by Chris Moffitt. It was transformed into this
tutorial by Chris Holdgraf.
A note on the Object-Oriented API vs Pyplot
Matplotlib has two interfaces. The first is an object-oriented (OO) interface. In this case, we utilize an
instance of axes.Axes in order to render visualizations on an instance of figure.Figure.
The second is based on MATLAB and uses a state-based interface. This is encapsulated in the pyplot
module. See the pyplot tutorials for a more in-depth look at the pyplot interface.
Most of the terms are straightforward but the main thing to remember is that:
• The Figure is the final image that may contain 1 or more Axes.
• The Axes represent an individual plot (don’t confuse this with the word “axis”, which refers to the x/y
axis of a plot).
We call methods that do the plotting directly from the Axes, which gives us much more flexibility and power
in customizing our plot. See the object-oriented examples for many examples of how this approach is used.
Note: In general, try to use the object-oriented interface over the pyplot interface.
Our data
We’ll use the data from the post from which this tutorial was derived. It contains sales information for a
number of companies.
# sphinx_gallery_thumbnail_number = 10
import numpy as np
import matplotlib.pyplot as plt
from matplotlib.ticker import FuncFormatter
data = {'Barton LLC': 109438.50,
'Frami, Hills and Schmidt': 103569.59,
'Fritsch, Russel and Anderson': 112214.71,
'Jerde-Hilpert': 112591.43,
'Keeling LLC': 100934.30,
'Koepp Ltd': 103660.54,
'Kulas Inc': 137351.96,
'Trantow-Barrows': 123381.38,
'White-Trantow': 135841.99,
'Will LLC': 104437.60}
group_data = list(data.values())
group_names = list(data.keys())
group_mean = np.mean(group_data)
88
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Getting started
This data is naturally visualized as a barplot, with one bar per group. To do this with the object-oriented
approach, we’ll first generate an instance of figure.Figure and axes.Axes. The Figure is like a canvas,
and the Axes is a part of that canvas on which we will make a particular visualization.
Note: Figures can have multiple axes on them. For information on how to do this, see the Tight Layout
tutorial.
fig, ax = plt.subplots()
Now that we have an Axes instance, we can plot on top of it.
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
3.1. Introductory
89
Matplotlib, Release 2.1.2
Controlling the style
There are many styles available in Matplotlib in order to let you tailor your visualization to your needs. To
see a list of styles, we can use pyplot.style.
print(plt.style.available)
Out:
['seaborn-ticks', 'ggplot', 'dark_background', 'bmh', 'seaborn-poster', 'seaborn-notebook
,→', 'fast', 'seaborn', 'classic', 'Solarize_Light2', 'seaborn-dark', 'seaborn-pastel',
,→'seaborn-muted', '_classic_test', 'seaborn-paper', 'seaborn-colorblind', 'seaborn,→bright', 'seaborn-talk', 'seaborn-dark-palette', 'seaborn-darkgrid', 'seaborn-whitegrid
,→', 'fivethirtyeight', 'grayscale', 'seaborn-white', 'seaborn-deep']
You can activate a style with the following:
plt.style.use('fivethirtyeight')
Now let’s remake the above plot to see how it looks:
90
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
The style controls many things, such as color, linewidths, backgrounds, etc.
Customizing the plot
Now we’ve got a plot with the general look that we want, so let’s fine-tune it so that it’s ready for print. First
let’s rotate the labels on the x-axis so that they show up more clearly. We can gain access to these labels
with the axes.Axes.get_xticklabels() method:
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
3.1. Introductory
91
Matplotlib, Release 2.1.2
If we’d like to set the property of many items at once, it’s useful to use the pyplot.setp() function. This
will take a list (or many lists) of Matplotlib objects, and attempt to set some style element of each one.
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
92
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
It looks like this cut off some of the labels on the bottom. We can tell Matplotlib to automatically make room
for elements in the figures that we create. To do this we’ll set the autolayout value of our rcParams. For
more information on controlling the style, layout, and other features of plots with rcParams, see Customizing
matplotlib.
plt.rcParams.update({'figure.autolayout': True})
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
3.1. Introductory
93
Matplotlib, Release 2.1.2
Next, we’ll add labels to the plot. To do this with the OO interface, we can use the axes.Axes.set()
method to set properties of this Axes object.
fig, ax = plt.subplots()
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
ax.set(xlim=[-10000, 140000], xlabel='Total Revenue', ylabel='Company',
title='Company Revenue')
94
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
We can also adjust the size of this plot using the pyplot.subplots() function. We can do this with the
figsize kwarg.
Note: While indexing in NumPy follows the form (row, column), the figsize kwarg follows the form
(width, height). This follows conventions in visualization, which unfortunately are different from those of
linear algebra.
fig, ax = plt.subplots(figsize=(8, 4))
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
ax.set(xlim=[-10000, 140000], xlabel='Total Revenue', ylabel='Company',
title='Company Revenue')
3.1. Introductory
95
Matplotlib, Release 2.1.2
For labels, we can specify custom formatting guidelines in the form of functions by using the ticker.
FuncFormatter class. Below we’ll define a function that takes an integer as input, and returns a string as
an output.
def currency(x, pos):
"""The two args are the value and tick position"""
if x >= 1e6:
s = '${:1.1f}M'.format(x*1e-6)
else:
s = '${:1.0f}K'.format(x*1e-3)
return s
formatter = FuncFormatter(currency)
We can then apply this formatter to the labels on our plot. To do this, we’ll use the xaxis attribute of our
axis. This lets you perform actions on a specific axis on our plot.
fig, ax = plt.subplots(figsize=(6, 8))
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
ax.set(xlim=[-10000, 140000], xlabel='Total Revenue', ylabel='Company',
title='Company Revenue')
ax.xaxis.set_major_formatter(formatter)
96
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
3.1. Introductory
97
Matplotlib, Release 2.1.2
Combining multiple visualizations
It is possible to draw multiple plot elements on the same instance of axes.Axes. To do this we simply need
to call another one of the plot methods on that axes object.
fig, ax = plt.subplots(figsize=(8, 8))
ax.barh(group_names, group_data)
labels = ax.get_xticklabels()
plt.setp(labels, rotation=45, horizontalalignment='right')
# Add a vertical line, here we set the style in the function call
ax.axvline(group_mean, ls='--', color='r')
# Annotate new companies
for group in [3, 5, 8]:
ax.text(145000, group, "New Company", fontsize=10,
verticalalignment="center")
# Now we'll move our title up since it's getting a little cramped
ax.title.set(y=1.05)
ax.set(xlim=[-10000, 140000], xlabel='Total Revenue', ylabel='Company',
title='Company Revenue')
ax.xaxis.set_major_formatter(formatter)
ax.set_xticks([0, 25e3, 50e3, 75e3, 100e3, 125e3])
fig.subplots_adjust(right=.1)
plt.show()
98
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Saving our plot
Now that we’re happy with the outcome of our plot, we want to save it to disk. There are many file formats
we can save to in Matplotlib. To see a list of available options, use:
print(fig.canvas.get_supported_filetypes())
Out:
{'ps': 'Postscript', 'eps': 'Encapsulated Postscript', 'pdf': 'Portable Document Format',
,→ 'pgf': 'PGF code for LaTeX', 'png': 'Portable Network Graphics', 'raw': 'Raw RGBA␣
,→bitmap', 'rgba': 'Raw RGBA bitmap', 'svg': 'Scalable Vector Graphics', 'svgz':
,→'Scalable Vector Graphics', 'jpg': 'Joint Photographic Experts Group', 'jpeg': 'Joint␣
,→Photographic Experts Group', 'tif': 'Tagged Image File Format', 'tiff': 'Tagged Image␣
,→File Format'}
3.1.
Introductory
99
Matplotlib, Release 2.1.2
We can then use the figure.Figure.savefig() in order to save the figure to disk. Note that there are
several useful flags we’ll show below:
• transparent=True makes the background of the saved figure transparent if the format supports it.
• dpi=80 controls the resolution (dots per square inch) of the output.
• bbox_inches="tight" fits the bounds of the figure to our plot.
# Uncomment this line to save the figure.
# fig.savefig('sales.png', transparent=False, dpi=80, bbox_inches="tight")
Total running time of the script: ( 0 minutes 0.667 seconds)
3.2 Intermediate
These tutorials cover some of the more complicated classes and functions in Matplotlib. They can be useful
for particular custom and complex visualizations.
3.2.1 Styling with cycler
Demo of custom property-cycle settings to control colors and other style properties for multi-line plots.
Note: More complete documentation of the cycler API can be found here.
This example demonstrates two different APIs:
1. Setting the default rc parameter specifying the property cycle. This affects all subsequent axes (but
not axes already created).
2. Setting the property cycle for a single pair of axes.
from cycler import cycler
import numpy as np
import matplotlib.pyplot as plt
First we’ll generate some sample data, in this case, four offset sine curves.
x = np.linspace(0, 2 * np.pi, 50)
offsets = np.linspace(0, 2 * np.pi, 4, endpoint=False)
yy = np.transpose([np.sin(x + phi) for phi in offsets])
Now yy has shape
print(yy.shape)
Out:
100
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
(50, 4)
So yy[:, i] will give you the i-th offset sine curve. Let’s set the default prop_cycle using matplotlib.
pyplot.rc(). We’ll combine a color cycler and a linestyle cycler by adding (+) two cycler’s together.
See the bottom of this tutorial for more information about combining different cyclers.
default_cycler = cycler('color', ['r', 'g', 'b', 'y']) \
+ cycler('linestyle', ['-', '--', ':', '-.'])
plt.rc('lines', linewidth=4)
plt.rc('axes', prop_cycle=default_cycler)
Now we’ll generate a figure with two axes, one on top of the other. On the first axis, we’ll plot
with the default cycler. On the second axis, we’ll set the prop_cycler using matplotlib.axes.Axes.
set_prop_cycle() which will only set the prop_cycle for this matplotlib.axes.Axes instance. We’ll
use a second cycler that combines a color cycler and a linewidth cycler.
custom_cycler = cycler('color', ['c', 'm', 'y', 'k']) \
+ cycler('lw', [1, 2, 3, 4])
fig, (ax0, ax1) = plt.subplots(nrows=2)
ax0.plot(yy)
ax0.set_title('Set default color cycle to rgby')
ax1.set_prop_cycle(custom_cycler)
ax1.plot(yy)
ax1.set_title('Set axes color cycle to cmyk')
# Add a bit more space between the two plots.
fig.subplots_adjust(hspace=0.3)
plt.show()
3.2. Intermediate
101
Matplotlib, Release 2.1.2
Setting prop_cycler in the matplotlibrc file or style files
Remember, if you want to set a custom prop_cycler in your .matplotlibrc file or a style file (style.
mplstyle), you can set the axes.prop_cycle property:
..code-block:: python
axes.prop_cycle : cycler(‘color’, ‘bgrcmyk’)
Cycling through multiple properties
You can add cyclers:
from cycler import cycler
cc = (cycler(color=list('rgb')) +
cycler(linestyle=['-', '--', '-.']))
for d in cc:
print(d)
Results in:
102
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
{'color': 'r', 'linestyle': '-'}
{'color': 'g', 'linestyle': '--'}
{'color': 'b', 'linestyle': '-.'}
You can multiply cyclers:
from cycler import cycler
cc = (cycler(color=list('rgb')) *
cycler(linestyle=['-', '--', '-.']))
for d in cc:
print(d)
Results in:
{'color':
{'color':
{'color':
{'color':
{'color':
{'color':
{'color':
{'color':
{'color':
'r',
'r',
'r',
'g',
'g',
'g',
'b',
'b',
'b',
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'linestyle':
'-'}
'--'}
'-.'}
'-'}
'--'}
'-.'}
'-'}
'--'}
'-.'}
Total running time of the script: ( 0 minutes 0.102 seconds)
3.2.2 Legend guide
Generating legends flexibly in Matplotlib.
This legend guide is an extension of the documentation available at legend() - please ensure you are
familiar with contents of that documentation before proceeding with this guide.
This guide makes use of some common terms, which are documented here for clarity:
legend entry A legend is made up of one or more legend entries. An entry is made up of exactly one key
and one label.
legend key The colored/patterned marker to the left of each legend label.
legend label
The text which describes the handle represented by the key.
legend handle The original object which is used to generate an appropriate entry in the legend.
Controlling the legend entries
Calling legend() with no arguments automatically fetches the legend handles and their associated labels.
This functionality is equivalent to:
handles, labels = ax.get_legend_handles_labels()
ax.legend(handles, labels)
3.2. Intermediate
103
Matplotlib, Release 2.1.2
The get_legend_handles_labels() function returns a list of handles/artists which exist on the Axes
which can be used to generate entries for the resulting legend - it is worth noting however that not all artists
can be added to a legend, at which point a “proxy” will have to be created (see Creating artists specifically
for adding to the legend (aka. Proxy artists) for further details).
# For full control of what is being added to the legend, it is common to pass # the appropriate handles
directly to legend()
line_up, = plt.plot([1,2,3], label=’Line 2’) line_down, = plt.plot([3,2,1], label=’Line 1’)
plt.legend(handles=[line_up, line_down])
In some cases, it is not possible to set the label of the handle, so it is possible to pass through the list of
labels to legend():
line_up, = plt.plot([1,2,3], label='Line 2')
line_down, = plt.plot([3,2,1], label='Line 1')
plt.legend([line_up, line_down], ['Line Up', 'Line Down'])
Creating artists specifically for adding to the legend (aka. Proxy artists)
Not all handles can be turned into legend entries automatically, so it is often necessary to create an artist
which can. Legend handles don’t have to exists on the Figure or Axes in order to be used.
Suppose we wanted to create a legend which has an entry for some data which is represented by a red color:
import matplotlib.patches as mpatches
import matplotlib.pyplot as plt
red_patch = mpatches.Patch(color='red', label='The red data')
plt.legend(handles=[red_patch])
plt.show()
104
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
There are many supported legend handles, instead of creating a patch of color we could have created a line
with a marker:
import matplotlib.lines as mlines
blue_line = mlines.Line2D([], [], color='blue', marker='*',
markersize=15, label='Blue stars')
plt.legend(handles=[blue_line])
plt.show()
3.2. Intermediate
105
Matplotlib, Release 2.1.2
Legend location
The location of the legend can be specified by the keyword argument loc. Please see the documentation at
legend() for more details.
The bbox_to_anchor keyword gives a great degree of control for manual legend placement. For example,
if you want your axes legend located at the figure’s top right-hand corner instead of the axes’ corner, simply
specify the corner’s location, and the coordinate system of that location:
plt.legend(bbox_to_anchor=(1, 1),
bbox_transform=plt.gcf().transFigure)
More examples of custom legend placement:
plt.subplot(211)
plt.plot([1, 2, 3], label="test1")
plt.plot([3, 2, 1], label="test2")
# Place a legend above this subplot, expanding itself to
# fully use the given bounding box.
plt.legend(bbox_to_anchor=(0., 1.02, 1., .102), loc=3,
ncol=2, mode="expand", borderaxespad=0.)
106
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
plt.subplot(223)
plt.plot([1, 2, 3], label="test1")
plt.plot([3, 2, 1], label="test2")
# Place a legend to the right of this smaller subplot.
plt.legend(bbox_to_anchor=(1.05, 1), loc=2, borderaxespad=0.)
plt.show()
Multiple legends on the same Axes
Sometimes it is more clear to split legend entries across multiple legends. Whilst the instinctive approach
to doing this might be to call the legend() function multiple times, you will find that only one legend ever
exists on the Axes. This has been done so that it is possible to call legend() repeatedly to update the legend
to the latest handles on the Axes, so to persist old legend instances, we must add them manually to the Axes:
line1, = plt.plot([1, 2, 3], label="Line 1", linestyle='--')
line2, = plt.plot([3, 2, 1], label="Line 2", linewidth=4)
# Create a legend for the first line.
first_legend = plt.legend(handles=[line1], loc=1)
3.2. Intermediate
107
Matplotlib, Release 2.1.2
# Add the legend manually to the current Axes.
ax = plt.gca().add_artist(first_legend)
# Create another legend for the second line.
plt.legend(handles=[line2], loc=4)
plt.show()
Legend Handlers
In order to create legend entries, handles are given as an argument to an appropriate HandlerBase subclass.
The choice of handler subclass is determined by the following rules:
1. Update get_legend_handler_map() with the value in the handler_map keyword.
2. Check if the handle is in the newly created handler_map.
3. Check if the type of handle is in the newly created handler_map.
4. Check if any of the types in the handle’s mro is in the newly created handler_map.
For completeness, this logic is mostly implemented in get_legend_handler().
108
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
All of this flexibility means that we have the necessary hooks to implement custom handlers for our own
type of legend key.
The simplest example of using custom handlers is to instantiate one of the existing HandlerBase subclasses.
For the sake of simplicity, let’s choose matplotlib.legend_handler.HandlerLine2D which accepts a
numpoints argument (note numpoints is a keyword on the legend() function for convenience). We can
then pass the mapping of instance to Handler as a keyword to legend.
from matplotlib.legend_handler import HandlerLine2D
line1, = plt.plot([3, 2, 1], marker='o', label='Line 1')
line2, = plt.plot([1, 2, 3], marker='o', label='Line 2')
plt.legend(handler_map={line1: HandlerLine2D(numpoints=4)})
As you can see, “Line 1” now has 4 marker points, where “Line 2” has 2 (the default). Try the above code,
only change the map’s key from line1 to type(line1). Notice how now both Line2D instances get 4
markers.
Along with handlers for complex plot types such as errorbars, stem plots and histograms, the default
handler_map has a special tuple handler (HandlerTuple) which simply plots the handles on top of
one another for each item in the given tuple. The following example demonstrates combining two legend
keys on top of one another:
3.2. Intermediate
109
Matplotlib, Release 2.1.2
from numpy.random import randn
z = randn(10)
red_dot, = plt.plot(z, "ro", markersize=15)
# Put a white cross over some of the data.
white_cross, = plt.plot(z[:5], "w+", markeredgewidth=3, markersize=15)
plt.legend([red_dot, (red_dot, white_cross)], ["Attr A", "Attr A+B"])
The HandlerTuple class can also be used to assign several legend keys to the same entry:
from matplotlib.legend_handler import HandlerLine2D, HandlerTuple
p1, = plt.plot([1, 2.5, 3], 'r-d')
p2, = plt.plot([3, 2, 1], 'k-o')
l = plt.legend([(p1, p2)], ['Two keys'], numpoints=1,
handler_map={tuple: HandlerTuple(ndivide=None)})
110
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Implementing a custom legend handler
A custom handler can be implemented to turn any handle into a legend key (handles don’t necessarily need
to be matplotlib artists). The handler must implement a “legend_artist” method which returns a single artist
for the legend to use. Signature details about the “legend_artist” are documented at legend_artist().
import matplotlib.patches as mpatches
class AnyObject(object):
pass
class AnyObjectHandler(object):
def legend_artist(self, legend, orig_handle, fontsize, handlebox):
x0, y0 = handlebox.xdescent, handlebox.ydescent
width, height = handlebox.width, handlebox.height
patch = mpatches.Rectangle([x0, y0], width, height, facecolor='red',
edgecolor='black', hatch='xx', lw=3,
transform=handlebox.get_transform())
handlebox.add_artist(patch)
return patch
3.2. Intermediate
111
Matplotlib, Release 2.1.2
plt.legend([AnyObject()], ['My first handler'],
handler_map={AnyObject: AnyObjectHandler()})
Alternatively, had we wanted to globally accept AnyObject instances without needing to manually set the
handler_map keyword all the time, we could have registered the new handler with:
from matplotlib.legend import Legend
Legend.update_default_handler_map({AnyObject: AnyObjectHandler()})
Whilst the power here is clear, remember that there are already many handlers implemented and what you
want to achieve may already be easily possible with existing classes. For example, to produce elliptical
legend keys, rather than rectangular ones:
from matplotlib.legend_handler import HandlerPatch
class HandlerEllipse(HandlerPatch):
def create_artists(self, legend, orig_handle,
xdescent, ydescent, width, height, fontsize, trans):
center = 0.5 * width - 0.5 * xdescent, 0.5 * height - 0.5 * ydescent
p = mpatches.Ellipse(xy=center, width=width + xdescent,
112
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
height=height + ydescent)
self.update_prop(p, orig_handle, legend)
p.set_transform(trans)
return [p]
c = mpatches.Circle((0.5, 0.5), 0.25, facecolor="green",
edgecolor="red", linewidth=3)
plt.gca().add_patch(c)
plt.legend([c], ["An ellipse, not a rectangle"],
handler_map={mpatches.Circle: HandlerEllipse()})
Total running time of the script: ( 0 minutes 0.363 seconds)
3.2.3 Customizing Location of Subplot Using GridSpec
How to create grid-shaped combinations of axes.
GridSpec specifies the geometry of the grid that a subplot will be placed in. The number of
rows and number of columns of the grid need to be set. Optionally, the subplot layout
parameters (e.g., left, right, etc.) can be tuned.
3.2. Intermediate
113
Matplotlib, Release 2.1.2
SubplotSpec specifies the location of the subplot in the given GridSpec.
subplot2grid() a helper function that is similar to subplot() but uses 0-based indexing
and let subplot to occupy multiple cells.
import matplotlib.pyplot as plt
import matplotlib.gridspec as gridspec
Basic Example of using subplot2grid
# To use :func:`~matplotlib.pyplot.subplot2grid`, you provide geometry of
# the grid and the location of the subplot in the grid. For a simple
# single-cell subplot
fig = plt.figure()
ax = plt.subplot2grid((2, 2), (0, 0))
# is identical to
fig = plt.figure()
ax = plt.subplot(2, 2, 1)
•
•
Note that, unlike Matplotlib’s subplot, the index starts from 0 in GridSpec.
114
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
To create a subplot that spans multiple cells:
fig = plt.figure()
ax2 = plt.subplot2grid((3, 3), (1, 0), colspan=2)
ax3 = plt.subplot2grid((3, 3), (1, 2), rowspan=2)
For example, see the output of the following commands:
ax1
ax2
ax3
ax4
ax5
=
=
=
=
=
plt.subplot2grid((3,
plt.subplot2grid((3,
plt.subplot2grid((3,
plt.subplot2grid((3,
plt.subplot2grid((3,
3.2. Intermediate
3),
3),
3),
3),
3),
(0,
(1,
(1,
(2,
(2,
0), colspan=3)
0), colspan=2)
2), rowspan=2)
0))
1))
115
Matplotlib, Release 2.1.2
GridSpec and SubplotSpec
You can create GridSpec explicitly and use them to create a subplot.
For example:
fig = plt.figure()
ax = plt.subplot2grid((2, 2), (0, 0))
# is equal to:
fig = plt.figure()
gs = gridspec.GridSpec(2, 2)
ax = plt.subplot(gs[0, 0])
# A GridSpec instance provides array-like (2d or 1d) indexing that
# returns the SubplotSpec instance. For a SubplotSpec that spans multiple
# cells, use slice.
ax2 = plt.subplot(gs[1, :-1])
ax3 = plt.subplot(gs[1:, -1])
116
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
•
•
The above example becomes
fig = plt.figure()
gs = gridspec.GridSpec(3, 3)
ax1 = plt.subplot(gs[0, :])
ax2 = plt.subplot(gs[1, :-1])
ax3 = plt.subplot(gs[1:, -1])
ax4 = plt.subplot(gs[-1, 0])
ax5 = plt.subplot(gs[-1, -2])
3.2. Intermediate
117
Matplotlib, Release 2.1.2
Adjust GridSpec layout
When a GridSpec is explicitly used, you can adjust the layout parameters of subplots that are created from
the GridSpec.
fig = plt.figure()
gs1 = gridspec.GridSpec(3, 3)
gs1.update(left=0.05, right=0.48, wspace=0.05)
118
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
This is similar to subplots_adjust(), but it only affects the subplots that are created from the given
GridSpec.
For example, see this code and the resulting figure:
fig = plt.figure()
gs1 = gridspec.GridSpec(3, 3)
gs1.update(left=0.05, right=0.48, wspace=0.05)
ax1 = plt.subplot(gs1[:-1, :])
ax2 = plt.subplot(gs1[-1, :-1])
ax3 = plt.subplot(gs1[-1, -1])
fig = plt.figure()
gs2 = gridspec.GridSpec(3, 3)
gs2.update(left=0.55, right=0.98, hspace=0.05)
ax4 = plt.subplot(gs2[:, :-1])
ax5 = plt.subplot(gs2[:-1, -1])
ax6 = plt.subplot(gs2[-1, -1])
3.2. Intermediate
119
Matplotlib, Release 2.1.2
•
•
GridSpec using SubplotSpec
You can create GridSpec from the SubplotSpec, in which case its layout parameters are set to that of the
location of the given SubplotSpec.
fig = plt.figure()
gs0 = gridspec.GridSpec(1, 2)
gs00 = gridspec.GridSpecFromSubplotSpec(3, 3, subplot_spec=gs0[0])
gs01 = gridspec.GridSpecFromSubplotSpec(3, 3, subplot_spec=gs0[1])
120
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
A Complex Nested GridSpec using SubplotSpec
Here’s a more sophisticated example of nested GridSpec where we put a box around each cell of the outer
4x4 grid, by hiding appropriate spines in each of the inner 3x3 grids.
import numpy as np
from itertools import product
def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
return np.sin(i*a)*np.cos(i*b), np.sin(i*c)*np.cos(i*d)
fig = plt.figure(figsize=(8, 8))
# gridspec inside gridspec
outer_grid = gridspec.GridSpec(4, 4, wspace=0.0, hspace=0.0)
for i in range(16):
inner_grid = gridspec.GridSpecFromSubplotSpec(
3, 3, subplot_spec=outer_grid[i], wspace=0.0, hspace=0.0)
a, b = int(i/4)+1, i % 4+1
for j, (c, d) in enumerate(product(range(1, 4), repeat=2)):
3.2. Intermediate
121
Matplotlib, Release 2.1.2
ax = plt.Subplot(fig, inner_grid[j])
ax.plot(*squiggle_xy(a, b, c, d))
ax.set_xticks([])
ax.set_yticks([])
fig.add_subplot(ax)
all_axes = fig.get_axes()
# show only the outside spines
for ax in all_axes:
for sp in ax.spines.values():
sp.set_visible(False)
if ax.is_first_row():
ax.spines['top'].set_visible(True)
if ax.is_last_row():
ax.spines['bottom'].set_visible(True)
if ax.is_first_col():
ax.spines['left'].set_visible(True)
if ax.is_last_col():
ax.spines['right'].set_visible(True)
plt.show()
#
#
#
#
#
#
GridSpec with Varying Cell Sizes
================================
By default, GridSpec creates cells of equal sizes. You can adjust
relative heights and widths of rows and columns. Note that absolute
values are meaningless, only their relative ratios matter.
fig = plt.figure()
gs = gridspec.GridSpec(2, 2,
width_ratios=[1, 2],
height_ratios=[4, 1]
)
ax1
ax2
ax3
ax4
122
=
=
=
=
plt.subplot(gs[0])
plt.subplot(gs[1])
plt.subplot(gs[2])
plt.subplot(gs[3])
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
•
•
Total running time of the script: ( 0 minutes 6.655 seconds)
3.2.4 Artist tutorial
Using Artist objects to render on the canvas.
There are three layers to the matplotlib API.
• the matplotlib.backend_bases.FigureCanvas is the area onto which the figure is drawn
• the matplotlib.backend_bases.Renderer is the object which knows how to draw on the
FigureCanvas
• and the matplotlib.artist.Artist is the object that knows how to use a renderer to paint onto
the canvas.
3.2. Intermediate
123
Matplotlib, Release 2.1.2
The FigureCanvas and Renderer handle all the details of talking to user interface toolkits like wxPython
or drawing languages like PostScript®, and the Artist handles all the high level constructs like representing and laying out the figure, text, and lines. The typical user will spend 95% of their time working with the
Artists.
There are two types of Artists: primitives and containers. The primitives represent the standard graphical
objects we want to paint onto our canvas: Line2D, Rectangle, Text, AxesImage, etc., and the containers
are places to put them (Axis, Axes and Figure). The standard use is to create a Figure instance, use
the Figure to create one or more Axes or Subplot instances, and use the Axes instance helper methods
to create the primitives. In the example below, we create a Figure instance using matplotlib.pyplot.
figure(), which is a convenience method for instantiating Figure instances and connecting them with
your user interface or drawing toolkit FigureCanvas. As we will discuss below, this is not necessary –
you can work directly with PostScript, PDF Gtk+, or wxPython FigureCanvas instances, instantiate your
Figures directly and connect them yourselves – but since we are focusing here on the Artist API we’ll
let pyplot handle some of those details for us:
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(2,1,1) # two rows, one column, first plot
The Axes is probably the most important class in the matplotlib API, and the one you will be working with
most of the time. This is because the Axes is the plotting area into which most of the objects go, and the
Axes has many special helper methods (plot(), text(), hist(), imshow()) to create the most common
graphics primitives (Line2D, Text, Rectangle, Image, respectively). These helper methods will take your
data (e.g., numpy arrays and strings) and create primitive Artist instances as needed (e.g., Line2D), add
them to the relevant containers, and draw them when requested. Most of you are probably familiar with the
Subplot, which is just a special case of an Axes that lives on a regular rows by columns grid of Subplot
instances. If you want to create an Axes at an arbitrary location, simply use the add_axes() method which
takes a list of [left, bottom, width, height] values in 0-1 relative figure coordinates:
fig2 = plt.figure()
ax2 = fig2.add_axes([0.15, 0.1, 0.7, 0.3])
Continuing with our example:
import numpy as np
t = np.arange(0.0, 1.0, 0.01)
s = np.sin(2*np.pi*t)
line, = ax.plot(t, s, color='blue', lw=2)
In this example, ax is the Axes instance created by the fig.add_subplot call above (remember Subplot
is just a subclass of Axes) and when you call ax.plot, it creates a Line2D instance and adds it to the
Axes.lines list. In the interactive ipython session below, you can see that the Axes.lines list is length
one and contains the same line that was returned by the line, = ax.plot... call:
In [101]: ax.lines[0]
Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>
In [102]: line
Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>
124
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
If you make subsequent calls to ax.plot (and the hold state is “on” which is the default) then additional
lines will be added to the list. You can remove lines later simply by calling the list methods; either of these
will work:
del ax.lines[0]
ax.lines.remove(line)
# one or the other, not both!
The Axes also has helper methods to configure and decorate the x-axis and y-axis tick, tick labels and axis
labels:
xtext = ax.set_xlabel('my xdata') # returns a Text instance
ytext = ax.set_ylabel('my ydata')
When you call ax.set_xlabel, it passes the information on the Text instance of the XAxis. Each Axes
instance contains an XAxis and a YAxis instance, which handle the layout and drawing of the ticks, tick
labels and axis labels.
Try creating the figure below.
import numpy as np
import matplotlib.pyplot as plt
fig = plt.figure()
fig.subplots_adjust(top=0.8)
ax1 = fig.add_subplot(211)
ax1.set_ylabel('volts')
ax1.set_title('a sine wave')
t = np.arange(0.0, 1.0, 0.01)
s = np.sin(2*np.pi*t)
line, = ax1.plot(t, s, color='blue', lw=2)
# Fixing random state for reproducibility
np.random.seed(19680801)
ax2 = fig.add_axes([0.15, 0.1, 0.7, 0.3])
n, bins, patches = ax2.hist(np.random.randn(1000), 50,
facecolor='yellow', edgecolor='yellow')
ax2.set_xlabel('time (s)')
plt.show()
3.2. Intermediate
125
Matplotlib, Release 2.1.2
Customizing your objects
Every element in the figure is represented by a matplotlib Artist, and each has an extensive list of properties to configure its appearance. The figure itself contains a Rectangle exactly the size of the figure, which
you can use to set the background color and transparency of the figures. Likewise, each Axes bounding
box (the standard white box with black edges in the typical matplotlib plot, has a Rectangle instance that
determines the color, transparency, and other properties of the Axes. These instances are stored as member variables Figure.patch and Axes.patch (“Patch” is a name inherited from MATLAB, and is a 2D
“patch” of color on the figure, e.g., rectangles, circles and polygons). Every matplotlib Artist has the
following properties
126
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Property
Description
alpha
animated
axes
clip_box
clip_on
clip_path
contains
figure
label
picker
transform
visible
zorder
rasterized
The transparency - a scalar from 0-1
A boolean that is used to facilitate animated drawing
The axes that the Artist lives in, possibly None
The bounding box that clips the Artist
Whether clipping is enabled
The path the artist is clipped to
A picking function to test whether the artist contains the pick point
The figure instance the artist lives in, possibly None
A text label (e.g., for auto-labeling)
A python object that controls object picking
The transformation
A boolean whether the artist should be drawn
A number which determines the drawing order
Boolean; Turns vectors into rastergraphics: (for compression & eps transparency)
Each of the properties is accessed with an old-fashioned setter or getter (yes we know this irritates Pythonistas and we plan to support direct access via properties or traits but it hasn’t been done yet). For example,
to multiply the current alpha by a half:
a = o.get_alpha()
o.set_alpha(0.5*a)
If you want to set a number of properties at once, you can also use the set method with keyword arguments.
For example:
o.set(alpha=0.5, zorder=2)
If you are working interactively at the python shell, a handy way to inspect the Artist properties is to use
the matplotlib.artist.getp() function (simply getp() in pylab), which lists the properties and their
values. This works for classes derived from Artist as well, e.g., Figure and Rectangle. Here are the
Figure rectangle properties mentioned above:
In [149]: matplotlib.artist.getp(fig.patch)
alpha = 1.0
animated = False
antialiased or aa = True
axes = None
clip_box = None
clip_on = False
clip_path = None
contains = None
edgecolor or ec = w
facecolor or fc = 0.75
figure = Figure(8.125x6.125)
fill = 1
hatch = None
height = 1
label =
3.2. Intermediate
127
Matplotlib, Release 2.1.2
linewidth or lw = 1.0
picker = None
transform = <Affine object at 0x134cca84>
verts = ((0, 0), (0, 1), (1, 1), (1, 0))
visible = True
width = 1
window_extent = <Bbox object at 0x134acbcc>
x = 0
y = 0
zorder = 1
The docstrings for all of the classes also contain the Artist properties, so you can consult the interactive
“help” or the artist Module for a listing of properties for a given object.
Object containers
Now that we know how to inspect and set the properties of a given object we want to configure, we need to
know how to get at that object. As mentioned in the introduction, there are two kinds of objects: primitives
and containers. The primitives are usually the things you want to configure (the font of a Text instance,
the width of a Line2D) although the containers also have some properties as well – for example the Axes
Artist is a container that contains many of the primitives in your plot, but it also has properties like the
xscale to control whether the xaxis is ‘linear’ or ‘log’. In this section we’ll review where the various
container objects store the Artists that you want to get at.
Figure container
The top level container Artist is the matplotlib.figure.Figure, and it contains everything in the
figure. The background of the figure is a Rectangle which is stored in Figure.patch. As you add
subplots (add_subplot()) and axes (add_axes()) to the figure these will be appended to the Figure.
axes. These are also returned by the methods that create them:
In [156]: fig = plt.figure()
In [157]: ax1 = fig.add_subplot(211)
In [158]: ax2 = fig.add_axes([0.1, 0.1, 0.7, 0.3])
In [159]: ax1
Out[159]: <matplotlib.axes.Subplot instance at 0xd54b26c>
In [160]: print fig.axes
[<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at␣
,→0xd3f0b2c>]
Because the figure maintains the concept of the “current axes” (see Figure.gca and Figure.sca) to
support the pylab/pyplot state machine, you should not insert or remove axes directly from the axes list, but
rather use the add_subplot() and add_axes() methods to insert, and the delaxes() method to delete.
128
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
You are free however, to iterate over the list of axes or index into it to get access to Axes instances you want
to customize. Here is an example which turns all the axes grids on:
for ax in fig.axes:
ax.grid(True)
The figure also has its own text, lines, patches and images, which you can use to add primitives directly. The
default coordinate system for the Figure will simply be in pixels (which is not usually what you want) but
you can control this by setting the transform property of the Artist you are adding to the figure.
More useful is “figure coordinates” where (0, 0) is the bottom-left of the figure and (1, 1) is the top-right of
the figure which you can obtain by setting the Artist transform to fig.transFigure:
import matplotlib.lines as lines
fig = plt.figure()
l1 = lines.Line2D([0, 1], [0, 1], transform=fig.transFigure, figure=fig)
l2 = lines.Line2D([0, 1], [1, 0], transform=fig.transFigure, figure=fig)
fig.lines.extend([l1, l2])
plt.show()
Here is a summary of the Artists the figure contains
3.2. Intermediate
129
Matplotlib, Release 2.1.2
Figure attribute
Description
axes
patch
images
legends
lines
patches
texts
A list of Axes instances (includes Subplot)
The Rectangle background
A list of FigureImages patches - useful for raw pixel display
A list of Figure Legend instances (different from Axes.legends)
A list of Figure Line2D instances (rarely used, see Axes.lines)
A list of Figure patches (rarely used, see Axes.patches)
A list Figure Text instances
Axes container
The matplotlib.axes.Axes is the center of the matplotlib universe – it contains the vast majority of all
the Artists used in a figure with many helper methods to create and add these Artists to itself, as well
as helper methods to access and customize the Artists it contains. Like the Figure, it contains a Patch
patch which is a Rectangle for Cartesian coordinates and a Circle for polar coordinates; this patch
determines the shape, background and border of the plotting region:
ax = fig.add_subplot(111)
rect = ax.patch # a Rectangle instance
rect.set_facecolor('green')
When you call a plotting method, e.g., the canonical plot() and pass in arrays or lists of values, the method
will create a matplotlib.lines.Line2D() instance, update the line with all the Line2D properties passed
as keyword arguments, add the line to the Axes.lines container, and returns it to you:
In [213]: x, y = np.random.rand(2, 100)
In [214]: line, = ax.plot(x, y, '-', color='blue', linewidth=2)
plot returns a list of lines because you can pass in multiple x, y pairs to plot, and we are unpacking the first
element of the length one list into the line variable. The line has been added to the Axes.lines list:
In [229]: print ax.lines
[<matplotlib.lines.Line2D instance at 0xd378b0c>]
Similarly, methods that create patches, like bar() creates a list of rectangles, will add the patches to the
Axes.patches list:
In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor='yellow')
In [234]: rectangles
Out[234]: <a list of 50 Patch objects>
In [235]: print len(ax.patches)
You should not add objects directly to the Axes.lines or Axes.patches lists unless you know exactly
what you are doing, because the Axes needs to do a few things when it creates and adds an object. It sets the
figure and axes property of the Artist, as well as the default Axes transformation (unless a transformation is
130
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
set). It also inspects the data contained in the Artist to update the data structures controlling auto-scaling,
so that the view limits can be adjusted to contain the plotted data. You can, nonetheless, create objects
yourself and add them directly to the Axes using helper methods like add_line() and add_patch().
Here is an annotated interactive session illustrating what is going on:
In [261]: fig = plt.figure()
In [262]: ax = fig.add_subplot(111)
# create a rectangle instance
In [263]: rect = matplotlib.patches.Rectangle( (1,1), width=5, height=12)
# by default the axes instance is None
In [264]: print rect.get_axes()
None
# and the transformation instance is set to the "identity transform"
In [265]: print rect.get_transform()
<Affine object at 0x13695544>
# now we add the Rectangle to the Axes
In [266]: ax.add_patch(rect)
# and notice that the ax.add_patch method has set the axes
# instance
In [267]: print rect.get_axes()
Axes(0.125,0.1;0.775x0.8)
# and the transformation has been set too
In [268]: print rect.get_transform()
<Affine object at 0x15009ca4>
# the default axes transformation is ax.transData
In [269]: print ax.transData
<Affine object at 0x15009ca4>
# notice that the xlimits of the Axes have not been changed
In [270]: print ax.get_xlim()
(0.0, 1.0)
# but the data limits have been updated to encompass the rectangle
In [271]: print ax.dataLim.bounds
(1.0, 1.0, 5.0, 12.0)
# we can manually invoke the auto-scaling machinery
In [272]: ax.autoscale_view()
# and now the xlim are updated to encompass the rectangle
In [273]: print ax.get_xlim()
(1.0, 6.0)
# we have to manually force a figure draw
In [274]: ax.figure.canvas.draw()
3.2. Intermediate
131
Matplotlib, Release 2.1.2
There are many, many Axes helper methods for creating primitive Artists and adding them to their respective containers. The table below summarizes a small sampling of them, the kinds of Artist they create,
and where they store them
Helper method
Artist
Container
ax.annotate - text annotations
ax.bar - bar charts
ax.errorbar - error bar plots
ax.fill - shared area
ax.hist - histograms
ax.imshow - image data
ax.legend - axes legends
ax.plot - xy plots
ax.scatter - scatter charts
ax.text - text
Annotate
Rectangle
Line2D and Rectangle
Polygon
Rectangle
AxesImage
Legend
Line2D
PolygonCollection
Text
ax.texts
ax.patches
ax.lines and ax.patches
ax.patches
ax.patches
ax.images
ax.legends
ax.lines
ax.collections
ax.texts
In addition to all of these Artists, the Axes contains two important Artist containers: the XAxis and
YAxis, which handle the drawing of the ticks and labels. These are stored as instance variables xaxis and
yaxis. The XAxis and YAxis containers will be detailed below, but note that the Axes contains many
helper methods which forward calls on to the Axis instances so you often do not need to work with them
directly unless you want to. For example, you can set the font color of the XAxis ticklabels using the Axes
helper method:
for label in ax.get_xticklabels():
label.set_color('orange')
Below is a summary of the Artists that the Axes contains
Axes attribute
Description
artists
patch
collections
images
legends
lines
patches
texts
xaxis
yaxis
A list of Artist instances
Rectangle instance for Axes background
A list of Collection instances
A list of AxesImage
A list of Legend instances
A list of Line2D instances
A list of Patch instances
A list of Text instances
matplotlib.axis.XAxis instance
matplotlib.axis.YAxis instance
Axis containers
The matplotlib.axis.Axis instances handle the drawing of the tick lines, the grid lines, the tick labels
and the axis label. You can configure the left and right ticks separately for the y-axis, and the upper and
lower ticks separately for the x-axis. The Axis also stores the data and view intervals used in auto-scaling,
132
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
panning and zooming, as well as the Locator and Formatter instances which control where the ticks are
placed and how they are represented as strings.
Each Axis object contains a label attribute (this is what pylab modifies in calls to xlabel() and
ylabel()) as well as a list of major and minor ticks. The ticks are XTick and YTick instances, which
contain the actual line and text primitives that render the ticks and ticklabels. Because the ticks are dynamically created as needed (e.g., when panning and zooming), you should access the lists of major and minor
ticks through their accessor methods get_major_ticks() and get_minor_ticks(). Although the ticks
contain all the primitives and will be covered below, Axis instances have accessor methods that return the
tick lines, tick labels, tick locations etc.:
fig, ax = plt.subplots()
axis = ax.xaxis
axis.get_ticklocs()
axis.get_ticklabels()
note there are twice as many ticklines as labels because by default there are tick lines at the top and bottom but only tick labels below the xaxis; this can be customized
axis.get_ticklines()
by default you get the major ticks back
3.2. Intermediate
133
Matplotlib, Release 2.1.2
axis.get_ticklines()
but you can also ask for the minor ticks
axis.get_ticklines(minor=True)
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Here is a summary of some of the useful accessor methods of the ``Axis``
(these have corresponding setters where useful, such as
set_major_formatter)
======================
Accessor method
======================
get_scale
get_view_interval
get_data_interval
get_gridlines
get_label
get_ticklabels
get_ticklines
get_ticklocs
get_major_locator
get_major_formatter
get_minor_locator
get_minor_formatter
get_major_ticks
get_minor_ticks
grid
======================
=========================================================
Description
=========================================================
The scale of the axis, e.g., 'log' or 'linear'
The interval instance of the axis view limits
The interval instance of the axis data limits
A list of grid lines for the Axis
The axis label - a Text instance
A list of Text instances - keyword minor=True|False
A list of Line2D instances - keyword minor=True|False
A list of Tick locations - keyword minor=True|False
The matplotlib.ticker.Locator instance for major ticks
The matplotlib.ticker.Formatter instance for major ticks
The matplotlib.ticker.Locator instance for minor ticks
The matplotlib.ticker.Formatter instance for minor ticks
A list of Tick instances for major ticks
A list of Tick instances for minor ticks
Turn the grid on or off for the major or minor ticks
=========================================================
Here is an example, not recommended for its beauty, which customizes
the axes and tick properties
# plt.figure creates a matplotlib.figure.Figure instance
fig = plt.figure()
rect = fig.patch # a rectangle instance
rect.set_facecolor('lightgoldenrodyellow')
ax1 = fig.add_axes([0.1, 0.3, 0.4, 0.4])
rect = ax1.patch
rect.set_facecolor('lightslategray')
for label in ax1.xaxis.get_ticklabels():
# label is a Text instance
label.set_color('red')
label.set_rotation(45)
label.set_fontsize(16)
for line in ax1.yaxis.get_ticklines():
# line is a Line2D instance
line.set_color('green')
line.set_markersize(25)
134
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
line.set_markeredgewidth(3)
plt.show()
Tick containers
The matplotlib.axis.Tick is the final container object in our descent from the Figure to the Axes to
the Axis to the Tick. The Tick contains the tick and grid line instances, as well as the label instances for
the upper and lower ticks. Each of these is accessible directly as an attribute of the Tick. In addition, there
are boolean variables that determine whether the upper labels and ticks are on for the x-axis and whether the
right labels and ticks are on for the y-axis.
3.2. Intermediate
135
Matplotlib, Release 2.1.2
Tick attribute
Description
tick1line
tick2line
gridline
label1
label2
gridOn
tick1On
tick2On
label1On
label2On
Line2D instance
Line2D instance
Line2D instance
Text instance
Text instance
boolean which determines whether to draw the gridline
boolean which determines whether to draw the 1st tickline
boolean which determines whether to draw the 2nd tickline
boolean which determines whether to draw the 1st tick label
boolean which determines whether to draw the 2nd tick label
Here is an example which sets the formatter for the right side ticks with dollar signs and colors them green
on the right side of the yaxis
import matplotlib.ticker as ticker
# Fixing random state for reproducibility
np.random.seed(19680801)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(100*np.random.rand(20))
formatter = ticker.FormatStrFormatter('$%1.2f ')
ax.yaxis.set_major_formatter(formatter)
for tick in ax.yaxis.get_major_ticks():
tick.label1On = False
tick.label2On = True
tick.label2.set_color('green')
plt.show()
136
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.218 seconds)
3.2.5 Tight Layout guide
How to use tight-layout to fit plots within your figure cleanly.
tight_layout automatically adjusts subplot params so that the subplot(s) fits in to the figure area. This is an
experimental feature and may not work for some cases. It only checks the extents of ticklabels, axis labels,
and titles.
Simple Example
In matplotlib, the location of axes (including subplots) are specified in normalized figure coordinates. It can
happen that your axis labels or titles (or sometimes even ticklabels) go outside the figure area, and are thus
clipped.
import matplotlib.pyplot as plt
import numpy as np
plt.rcParams['savefig.facecolor'] = "0.8"
3.2. Intermediate
137
Matplotlib, Release 2.1.2
def example_plot(ax, fontsize=12):
ax.plot([1, 2])
ax.locator_params(nbins=3)
ax.set_xlabel('x-label', fontsize=fontsize)
ax.set_ylabel('y-label', fontsize=fontsize)
ax.set_title('Title', fontsize=fontsize)
plt.close('all')
fig, ax = plt.subplots()
example_plot(ax, fontsize=24)
To prevent this, the location of axes needs to be adjusted. For subplots, this can be done by adjusting the
subplot params (Move the edge of an axes to make room for tick labels). Matplotlib v1.1 introduces a new
command tight_layout() that does this automatically for you.
fig, ax = plt.subplots()
example_plot(ax, fontsize=24)
plt.tight_layout()
138
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Note that matplotlib.pyplot.tight_layout() will only adjust the subplot params when it is
called. In order to perform this adjustment each time the figure is redrawn, you can call fig.
set_tight_layout(True), or, equivalently, set the figure.autolayout rcParam to True.
When you have multiple subplots, often you see labels of different axes overlapping each other.
plt.close('all')
fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(nrows=2, ncols=2)
example_plot(ax1)
example_plot(ax2)
example_plot(ax3)
example_plot(ax4)
3.2. Intermediate
139
Matplotlib, Release 2.1.2
tight_layout() will also adjust spacing between subplots to minimize the overlaps.
fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(nrows=2, ncols=2)
example_plot(ax1)
example_plot(ax2)
example_plot(ax3)
example_plot(ax4)
plt.tight_layout()
140
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
tight_layout() can take keyword arguments of pad, w_pad and h_pad. These control the extra padding
around the figure border and between subplots. The pads are specified in fraction of fontsize.
fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(nrows=2, ncols=2)
example_plot(ax1)
example_plot(ax2)
example_plot(ax3)
example_plot(ax4)
plt.tight_layout(pad=0.4, w_pad=0.5, h_pad=1.0)
3.2. Intermediate
141
Matplotlib, Release 2.1.2
tight_layout() will work even if the sizes of subplots are different as far as their grid specification is
compatible. In the example below, ax1 and ax2 are subplots of a 2x2 grid, while ax3 is of a 1x2 grid.
plt.close('all')
fig = plt.figure()
ax1 = plt.subplot(221)
ax2 = plt.subplot(223)
ax3 = plt.subplot(122)
example_plot(ax1)
example_plot(ax2)
example_plot(ax3)
plt.tight_layout()
142
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
It works with subplots created with subplot2grid(). In general, subplots created from the gridspec (Customizing Location of Subplot Using GridSpec) will work.
plt.close('all')
fig = plt.figure()
ax1
ax2
ax3
ax4
=
=
=
=
plt.subplot2grid((3,
plt.subplot2grid((3,
plt.subplot2grid((3,
plt.subplot2grid((3,
3),
3),
3),
3),
(0,
(0,
(1,
(1,
0))
1), colspan=2)
0), colspan=2, rowspan=2)
2), rowspan=2)
example_plot(ax1)
example_plot(ax2)
example_plot(ax3)
example_plot(ax4)
plt.tight_layout()
3.2. Intermediate
143
Matplotlib, Release 2.1.2
Although not thoroughly tested, it seems to work for subplots with aspect != “auto” (e.g., axes with images).
arr = np.arange(100).reshape((10, 10))
plt.close('all')
fig = plt.figure(figsize=(5, 4))
ax = plt.subplot(111)
im = ax.imshow(arr, interpolation="none")
plt.tight_layout()
144
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Caveats
• tight_layout() only considers ticklabels, axis labels, and titles. Thus, other artists may be clipped
and also may overlap.
• It assumes that the extra space needed for ticklabels, axis labels, and titles is independent of original
location of axes. This is often true, but there are rare cases where it is not.
• pad=0 clips some of the texts by a few pixels. This may be a bug or a limitation of the current
algorithm and it is not clear why it happens. Meanwhile, use of pad at least larger than 0.3 is recommended.
Use with GridSpec
GridSpec has its own tight_layout() method (the pyplot api tight_layout() also works).
import matplotlib.gridspec as gridspec
plt.close('all')
fig = plt.figure()
gs1 = gridspec.GridSpec(2, 1)
ax1 = fig.add_subplot(gs1[0])
ax2 = fig.add_subplot(gs1[1])
example_plot(ax1)
3.2. Intermediate
145
Matplotlib, Release 2.1.2
example_plot(ax2)
gs1.tight_layout(fig)
You may provide an optional rect parameter, which specifies the bounding box that the subplots will be fit
inside. The coordinates must be in normalized figure coordinates and the default is (0, 0, 1, 1).
fig = plt.figure()
gs1 = gridspec.GridSpec(2, 1)
ax1 = fig.add_subplot(gs1[0])
ax2 = fig.add_subplot(gs1[1])
example_plot(ax1)
example_plot(ax2)
gs1.tight_layout(fig, rect=[0, 0, 0.5, 1])
146
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
For example, this can be used for a figure with multiple gridspecs.
fig = plt.figure()
gs1 = gridspec.GridSpec(2, 1)
ax1 = fig.add_subplot(gs1[0])
ax2 = fig.add_subplot(gs1[1])
example_plot(ax1)
example_plot(ax2)
gs1.tight_layout(fig, rect=[0, 0, 0.5, 1])
gs2 = gridspec.GridSpec(3, 1)
for ss in gs2:
ax = fig.add_subplot(ss)
example_plot(ax)
ax.set_title("")
ax.set_xlabel("")
ax.set_xlabel("x-label", fontsize=12)
gs2.tight_layout(fig, rect=[0.5, 0, 1, 1], h_pad=0.5)
3.2. Intermediate
147
Matplotlib, Release 2.1.2
# We may try to match the top and bottom of two grids ::
top = min(gs1.top, gs2.top)
bottom = max(gs1.bottom, gs2.bottom)
gs1.update(top=top, bottom=bottom)
gs2.update(top=top, bottom=bottom)
plt.show()
While this should be mostly good enough, adjusting top and bottom may require adjustment of hspace also.
To update hspace & vspace, we call tight_layout() again with updated rect argument. Note that the rect
argument specifies the area including the ticklabels, etc. Thus, we will increase the bottom (which is 0 for
the normal case) by the difference between the bottom from above and the bottom of each gridspec. Same
thing for the top.
fig = plt.gcf()
gs1 = gridspec.GridSpec(2, 1)
ax1 = fig.add_subplot(gs1[0])
ax2 = fig.add_subplot(gs1[1])
example_plot(ax1)
example_plot(ax2)
148
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
gs1.tight_layout(fig, rect=[0, 0, 0.5, 1])
gs2 = gridspec.GridSpec(3, 1)
for ss in gs2:
ax = fig.add_subplot(ss)
example_plot(ax)
ax.set_title("")
ax.set_xlabel("")
ax.set_xlabel("x-label", fontsize=12)
gs2.tight_layout(fig, rect=[0.5, 0, 1, 1], h_pad=0.5)
top = min(gs1.top, gs2.top)
bottom = max(gs1.bottom, gs2.bottom)
gs1.update(top=top, bottom=bottom)
gs2.update(top=top, bottom=bottom)
top = min(gs1.top, gs2.top)
bottom = max(gs1.bottom, gs2.bottom)
gs1.tight_layout(fig, rect=[None, 0 + (bottom-gs1.bottom),
0.5, 1 - (gs1.top-top)])
gs2.tight_layout(fig, rect=[0.5, 0 + (bottom-gs2.bottom),
None, 1 - (gs2.top-top)],
h_pad=0.5)
3.2. Intermediate
149
Matplotlib, Release 2.1.2
Use with AxesGrid1
While limited, the axes_grid1 toolkit is also supported.
from mpl_toolkits.axes_grid1 import Grid
plt.close('all')
fig = plt.figure()
grid = Grid(fig, rect=111, nrows_ncols=(2, 2),
axes_pad=0.25, label_mode='L',
)
for ax in grid:
example_plot(ax)
ax.title.set_visible(False)
plt.tight_layout()
150
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Colorbar
If you create a colorbar with the colorbar() command, the created colorbar is an instance of Axes, not
Subplot, so tight_layout does not work. With Matplotlib v1.1, you may create a colorbar as a subplot using
the gridspec.
plt.close('all')
arr = np.arange(100).reshape((10, 10))
fig = plt.figure(figsize=(4, 4))
im = plt.imshow(arr, interpolation="none")
plt.colorbar(im, use_gridspec=True)
plt.tight_layout()
3.2. Intermediate
151
Matplotlib, Release 2.1.2
Another option is to use AxesGrid1 toolkit to explicitly create an axes for colorbar.
from mpl_toolkits.axes_grid1 import make_axes_locatable
plt.close('all')
arr = np.arange(100).reshape((10, 10))
fig = plt.figure(figsize=(4, 4))
im = plt.imshow(arr, interpolation="none")
divider = make_axes_locatable(plt.gca())
cax = divider.append_axes("right", "5%", pad="3%")
plt.colorbar(im, cax=cax)
plt.tight_layout()
152
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 1.843 seconds)
3.3 Advanced
These tutorials cover advanced topics for experienced Matplotlib users and developers.
3.3.1 Path effects guide
Defining paths that objects follow on a canvas.
Matplotlib’s patheffects module provides functionality to apply a multiple draw stage to any Artist which
can be rendered via a Path .
Artists which can have a path effect applied to them include Patch , Line2D, Collection and even Text.
Each artist’s path effects can be controlled via the set_path_effects method (set_path_effects),
which takes an iterable of AbstractPathEffect instances.
The simplest path effect is the Normal effect, which simply draws the artist without any effect:
import matplotlib.pyplot as plt
import matplotlib.patheffects as path_effects
fig = plt.figure(figsize=(5, 1.5))
text = fig.text(0.5, 0.5, 'Hello path effects world!\nThis is the normal '
'path effect.\nPretty dull, huh?',
ha='center', va='center', size=20)
3.3. Advanced
153
Matplotlib, Release 2.1.2
text.set_path_effects([path_effects.Normal()])
plt.show()
Whilst the plot doesn’t look any different to what you would expect without any path effects, the drawing of
the text now been changed to use the path effects framework, opening up the possibilities for more interesting
examples.
Adding a shadow
A far more interesting path effect than Normal is the drop-shadow, which we can apply to any of our path
based artists. The classes SimplePatchShadow and SimpleLineShadow do precisely this by drawing
either a filled patch or a line patch below the original artist:
import matplotlib.patheffects as path_effects
text = plt.text(0.5, 0.5, 'Hello path effects world!',
path_effects=[path_effects.withSimplePatchShadow()])
plt.plot([0, 3, 2, 5], linewidth=5, color='blue',
path_effects=[path_effects.SimpleLineShadow(),
path_effects.Normal()])
plt.show()
154
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Notice the two approaches to setting the path effects in this example. The first uses the with* classes to include the desired functionality automatically followed with the “normal” effect, whereas the latter explicitly
defines the two path effects to draw.
Making an artist stand out
One nice way of making artists visually stand out is to draw an outline in a bold color below the actual artist.
The Stroke path effect makes this a relatively simple task:
fig = plt.figure(figsize=(7, 1))
text = fig.text(0.5, 0.5, 'This text stands out because of\n'
'its black border.', color='white',
ha='center', va='center', size=30)
text.set_path_effects([path_effects.Stroke(linewidth=3, foreground='black'),
path_effects.Normal()])
plt.show()
3.3. Advanced
155
Matplotlib, Release 2.1.2
It is important to note that this effect only works because we have drawn the text path twice; once with a
thick black line, and then once with the original text path on top.
You may have noticed that the keywords to Stroke and SimplePatchShadow and SimpleLineShadow
are not the usual Artist keywords (such as facecolor and edgecolor etc.). This is because with these path
effects we are operating at lower level of matplotlib. In fact, the keywords which are accepted are those for
a matplotlib.backend_bases.GraphicsContextBase instance, which have been designed for making
it easy to create new backends - and not for its user interface.
Greater control of the path effect artist
As already mentioned, some of the path effects operate at a lower level than most users will be used to,
meaning that setting keywords such as facecolor and edgecolor raise an AttributeError. Luckily there
is a generic PathPatchEffect path effect which creates a PathPatch class with the original path. The
keywords to this effect are identical to those of PathPatch :
fig = plt.figure(figsize=(8, 1))
t = fig.text(0.02, 0.5, 'Hatch shadow', fontsize=75, weight=1000, va='center')
t.set_path_effects([path_effects.PathPatchEffect(offset=(4, -4), hatch='xxxx',
facecolor='gray'),
path_effects.PathPatchEffect(edgecolor='white', linewidth=1.1,
facecolor='black')])
plt.show()
Total running time of the script: ( 0 minutes 0.026 seconds)
3.3.2 Path Tutorial
Defining paths in your Matplotlib visualization.
The object underlying all of the matplotlib.patch objects is the Path , which supports the standard set of
moveto, lineto, curveto commands to draw simple and compound outlines consisting of line segments and
splines. The Path is instantiated with a (N,2) array of (x,y) vertices, and a N-length array of path codes. For
example to draw the unit rectangle from (0,0) to (1,1), we could use this code
import matplotlib.pyplot as plt
from matplotlib.path import Path
import matplotlib.patches as patches
verts =
(0.,
(0.,
(1.,
(1.,
(0.,
156
[
0.),
1.),
1.),
0.),
0.),
#
#
#
#
#
left, bottom
left, top
right, top
right, bottom
ignored
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
]
codes = [
Path.MOVETO,
Path.LINETO,
Path.LINETO,
Path.LINETO,
Path.CLOSEPOLY,
]
path = Path(verts, codes)
fig = plt.figure()
ax = fig.add_subplot(111)
patch = patches.PathPatch(path, facecolor='orange', lw=2)
ax.add_patch(patch)
ax.set_xlim(-2, 2)
ax.set_ylim(-2, 2)
plt.show()
The following path codes are recognized
3.3. Advanced
157
Matplotlib, Release 2.1.2
Code
Vertices
Description
STOP
1 (ignored)
A marker for the end of the entire path (currently not required and ignored)
Pick up the pen and move to the given vertex.
Draw a line from the current position to the given vertex.
Draw a quadratic Bézier curve from the current position, with the given
control point, to the given end point.
Draw a cubic Bézier curve from the current position, with the given
control points, to the given end point.
Draw a line segment to the start point of the current polyline.
MOVETO
LINETO
CURVE3
1
1
2 (1 control point, 1
endpoint)
CURVE4 3 (2 control points,
1 endpoint)
CLOSEPOLY1 (point itself is ignored)
Bézier example
Some of the path components require multiple vertices to specify them: for example CURVE 3 is a bézier
curve with one control point and one end point, and CURVE4 has three vertices for the two control points
and the end point. The example below shows a CURVE4 Bézier spline – the bézier curve will be contained
in the convex hull of the start point, the two control points, and the end point
verts = [
(0., 0.),
(0.2, 1.),
(1., 0.8),
(0.8, 0.),
]
#
#
#
#
P0
P1
P2
P3
codes = [
Path.MOVETO,
Path.CURVE4,
Path.CURVE4,
Path.CURVE4,
]
path = Path(verts, codes)
fig = plt.figure()
ax = fig.add_subplot(111)
patch = patches.PathPatch(path, facecolor='none', lw=2)
ax.add_patch(patch)
xs, ys = zip(*verts)
ax.plot(xs, ys, 'x--', lw=2, color='black', ms=10)
ax.text(-0.05, -0.05, 'P0')
ax.text(0.15, 1.05, 'P1')
ax.text(1.05, 0.85, 'P2')
ax.text(0.85, -0.05, 'P3')
ax.set_xlim(-0.1, 1.1)
158
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ax.set_ylim(-0.1, 1.1)
plt.show()
Compound paths
All of the simple patch primitives in matplotlib, Rectangle, Circle, Polygon, etc, are implemented with
simple path. Plotting functions like hist() and bar(), which create a number of primitives, e.g., a bunch
of Rectangles, can usually be implemented more efficiently using a compound path. The reason bar creates
a list of rectangles and not a compound path is largely historical: the Path code is comparatively new and
bar predates it. While we could change it now, it would break old code, so here we will cover how to create
compound paths, replacing the functionality in bar, in case you need to do so in your own code for efficiency
reasons, e.g., you are creating an animated bar plot.
We will make the histogram chart by creating a series of rectangles for each histogram bar: the rectangle
width is the bin width and the rectangle height is the number of datapoints in that bin. First we’ll create
some random normally distributed data and compute the histogram. Because numpy returns the bin edges
and not centers, the length of bins is 1 greater than the length of n in the example below:
# histogram our data with numpy
data = np.random.randn(1000)
n, bins = np.histogram(data, 100)
3.3. Advanced
159
Matplotlib, Release 2.1.2
We’ll now extract the corners of the rectangles. Each of the left, bottom, etc, arrays below is len(n),
where n is the array of counts for each histogram bar:
# get the corners of the rectangles for the histogram
left = np.array(bins[:-1])
right = np.array(bins[1:])
bottom = np.zeros(len(left))
top = bottom + n
Now we have to construct our compound path, which will consist of a series of MOVETO, LINETO and
CLOSEPOLY for each rectangle. For each rectangle, we need 5 vertices: 1 for the MOVETO, 3 for the LINETO,
and 1 for the CLOSEPOLY. As indicated in the table above, the vertex for the closepoly is ignored but we still
need it to keep the codes aligned with the vertices:
nverts = nrects*(1+3+1)
verts = np.zeros((nverts, 2))
codes = np.ones(nverts, int) * path.Path.LINETO
codes[0::5] = path.Path.MOVETO
codes[4::5] = path.Path.CLOSEPOLY
verts[0::5,0] = left
verts[0::5,1] = bottom
verts[1::5,0] = left
verts[1::5,1] = top
verts[2::5,0] = right
verts[2::5,1] = top
verts[3::5,0] = right
verts[3::5,1] = bottom
All that remains is to create the path, attach it to a PathPatch, and add it to our axes:
barpath = path.Path(verts, codes)
patch = patches.PathPatch(barpath, facecolor='green',
edgecolor='yellow', alpha=0.5)
ax.add_patch(patch)
import numpy as np
import matplotlib.patches as patches
import matplotlib.path as path
fig = plt.figure()
ax = fig.add_subplot(111)
# Fixing random state for reproducibility
np.random.seed(19680801)
# histogram our data with numpy
data = np.random.randn(1000)
n, bins = np.histogram(data, 100)
# get the corners of the rectangles for the histogram
left = np.array(bins[:-1])
right = np.array(bins[1:])
bottom = np.zeros(len(left))
160
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
top = bottom + n
nrects = len(left)
nverts = nrects*(1+3+1)
verts = np.zeros((nverts, 2))
codes = np.ones(nverts, int) * path.Path.LINETO
codes[0::5] = path.Path.MOVETO
codes[4::5] = path.Path.CLOSEPOLY
verts[0::5, 0] = left
verts[0::5, 1] = bottom
verts[1::5, 0] = left
verts[1::5, 1] = top
verts[2::5, 0] = right
verts[2::5, 1] = top
verts[3::5, 0] = right
verts[3::5, 1] = bottom
barpath = path.Path(verts, codes)
patch = patches.PathPatch(barpath, facecolor='green',
edgecolor='yellow', alpha=0.5)
ax.add_patch(patch)
ax.set_xlim(left[0], right[-1])
ax.set_ylim(bottom.min(), top.max())
plt.show()
3.3. Advanced
161
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.059 seconds)
3.3.3 Transformations Tutorial
Like any graphics packages, Matplotlib is built on top of a transformation framework to easily move between coordinate systems, the userland data coordinate system, the axes coordinate system, the figure
coordinate system, and the display coordinate system. In 95% of your plotting, you won’t need to think
about this, as it happens under the hood, but as you push the limits of custom figure generation, it helps to
have an understanding of these objects so you can reuse the existing transformations Matplotlib makes available to you, or create your own (see matplotlib.transforms). The table below summarizes the some
useful coordinate systems, the transformation object you should use to work in that coordinate system, and
the description of that system. In the Transformation Object column, ax is a Axes instance, and fig is
a Figure instance.
162
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Coordinates
“data”
Transformation object
Description
ax.transData
“axes”
ax.transAxes
“figure”
“display”
fig.transFigure
The coordinate system for the data, controlled by xlim and
ylim.
The coordinate system of the Axes; (0, 0) is bottom left of the
axes, and (1, 1) is top right of the axes.
The coordinate system of the Figure; (0, 0) is bottom left of
the figure, and (1, 1) is top right of the figure.
The pixel coordinate system of the display; (0, 0) is bottom
left of the display, and (width, height) is top right of the display in pixels.
Blended coordinate systems; use data coordinates on one of
the axis and axes coordinates on the other.
None,
IdentityTransform()
or
“xaxis”, ax.
“yaxis” get_xaxis_transform(),
ax.
get_yaxis_transform()
All of the transformation objects in the table above take inputs in their coordinate system, and transform
the input to the display coordinate system. That is why the display coordinate system has None for the
Transformation Object column – it already is in display coordinates. The transformations also know
how to invert themselves, to go from display back to the native coordinate system. This is particularly
useful when processing events from the user interface, which typically occur in display space, and you want
to know where the mouse click or key-press occurred in your data coordinate system.
Data coordinates
Let’s start with the most commonly used coordinate, the data coordinate system. Whenever you add data to
the axes, Matplotlib updates the datalimits, most commonly updated with the set_xlim() and set_ylim()
methods. For example, in the figure below, the data limits stretch from 0 to 10 on the x-axis, and -1 to 1 on
the y-axis.
import numpy as np
import matplotlib.pyplot as plt
x = np.arange(0, 10, 0.005)
y = np.exp(-x/2.) * np.sin(2*np.pi*x)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(x, y)
ax.set_xlim(0, 10)
ax.set_ylim(-1, 1)
plt.show()
3.3. Advanced
163
Matplotlib, Release 2.1.2
You can use the ax.transData instance to transform from your data to your display coordinate system,
either a single point or a sequence of points as shown below:
In [14]: type(ax.transData)
Out[14]: <class 'matplotlib.transforms.CompositeGenericTransform'>
In [15]: ax.transData.transform((5, 0))
Out[15]: array([ 335.175, 247.
])
In [16]: ax.transData.transform([(5, 0), (1, 2)])
Out[16]:
array([[ 335.175, 247.
],
[ 132.435, 642.2 ]])
You can use the inverted() method to create a transform which will take you from display to data coordinates:
In [41]: inv = ax.transData.inverted()
In [42]: type(inv)
Out[42]: <class 'matplotlib.transforms.CompositeGenericTransform'>
In [43]: inv.transform((335.175,
Out[43]: array([ 5., 0.])
164
247.))
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
If your are typing along with this tutorial, the exact values of the display coordinates may differ if you have
a different window size or dpi setting. Likewise, in the figure below, the display labeled points are probably
not the same as in the ipython session because the documentation figure size defaults are different.
x = np.arange(0, 10, 0.005)
y = np.exp(-x/2.) * np.sin(2*np.pi*x)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(x, y)
ax.set_xlim(0, 10)
ax.set_ylim(-1, 1)
xdata, ydata = 5, 0
xdisplay, ydisplay = ax.transData.transform_point((xdata, ydata))
bbox = dict(boxstyle="round", fc="0.8")
arrowprops = dict(
arrowstyle="->",
connectionstyle="angle,angleA=0,angleB=90,rad=10")
offset = 72
ax.annotate('data = (%.1f , %.1f )' % (xdata, ydata),
(xdata, ydata), xytext=(-2*offset, offset), textcoords='offset points',
bbox=bbox, arrowprops=arrowprops)
disp = ax.annotate('display = (%.1f , %.1f )' % (xdisplay, ydisplay),
(xdisplay, ydisplay), xytext=(0.5*offset, -offset),
xycoords='figure pixels',
textcoords='offset points',
bbox=bbox, arrowprops=arrowprops)
plt.show()
3.3. Advanced
165
Matplotlib, Release 2.1.2
Note: If you run the source code in the example above in a GUI backend, you may also find that the two
arrows for the data and display annotations do not point to exactly the same point. This is because the
display point was computed before the figure was displayed, and the GUI backend may slightly resize the
figure when it is created. The effect is more pronounced if you resize the figure yourself. This is one good
reason why you rarely want to work in display space, but you can connect to the 'on_draw' Event to
update figure coordinates on figure draws; see Event handling and picking.
When you change the x or y limits of your axes, the data limits are updated so the transformation yields a
new display point. Note that when we just change the ylim, only the y-display coordinate is altered, and
when we change the xlim too, both are altered. More on this later when we talk about the Bbox.
In [54]: ax.transData.transform((5, 0))
Out[54]: array([ 335.175, 247.
])
In [55]: ax.set_ylim(-1, 2)
Out[55]: (-1, 2)
In [56]: ax.transData.transform((5, 0))
Out[56]: array([ 335.175
, 181.13333333])
In [57]: ax.set_xlim(10, 20)
166
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Out[57]: (10, 20)
In [58]: ax.transData.transform((5, 0))
Out[58]: array([-171.675
, 181.13333333])
Axes coordinates
After the data coordinate system, axes is probably the second most useful coordinate system. Here the
point (0, 0) is the bottom left of your axes or subplot, (0.5, 0.5) is the center, and (1.0, 1.0) is the top
right. You can also refer to points outside the range, so (-0.1, 1.1) is to the left and above your axes. This
coordinate system is extremely useful when placing text in your axes, because you often want a text bubble
in a fixed, location, e.g., the upper left of the axes pane, and have that location remain fixed when you pan
or zoom. Here is a simple example that creates four panels and labels them ‘A’, ‘B’, ‘C’, ‘D’ as you often
see in journals.
fig = plt.figure()
for i, label in enumerate(('A', 'B', 'C', 'D')):
ax = fig.add_subplot(2, 2, i+1)
ax.text(0.05, 0.95, label, transform=ax.transAxes,
fontsize=16, fontweight='bold', va='top')
plt.show()
3.3. Advanced
167
Matplotlib, Release 2.1.2
You can also make lines or patches in the axes coordinate system, but this is less useful in my experience
than using ax.transAxes for placing text. Nonetheless, here is a silly example which plots some random
dots in data space, and overlays a semi-transparent Circle centered in the middle of the axes with a radius
one quarter of the axes – if your axes does not preserve aspect ratio (see set_aspect()), this will look like
an ellipse. Use the pan/zoom tool to move around, or manually change the data xlim and ylim, and you
will see the data move, but the circle will remain fixed because it is not in data coordinates and will always
remain at the center of the axes.
import matplotlib.patches as patches
fig = plt.figure()
ax = fig.add_subplot(111)
x, y = 10*np.random.rand(2, 1000)
ax.plot(x, y, 'go') # plot some data in data coordinates
circ = patches.Circle((0.5, 0.5), 0.25, transform=ax.transAxes,
facecolor='yellow', alpha=0.5)
ax.add_patch(circ)
plt.show()
168
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Blended transformations
Drawing in blended coordinate spaces which mix axes with data coordinates is extremely useful, for
example to create a horizontal span which highlights some region of the y-data but spans across the x-axis
regardless of the data limits, pan or zoom level, etc. In fact these blended lines and spans are so useful, we
have built in functions to make them easy to plot (see axhline(), axvline(), axhspan(), axvspan())
but for didactic purposes we will implement the horizontal span here using a blended transformation. This
trick only works for separable transformations, like you see in normal Cartesian coordinate systems, but not
on inseparable transformations like the PolarTransform.
import matplotlib.transforms as transforms
fig = plt.figure()
ax = fig.add_subplot(111)
x = np.random.randn(1000)
ax.hist(x, 30)
ax.set_title(r'$\sigma=1 \/ \dots \/ \sigma=2$', fontsize=16)
# the x coords of this transformation are data, and the
# y coord are axes
3.3. Advanced
169
Matplotlib, Release 2.1.2
trans = transforms.blended_transform_factory(
ax.transData, ax.transAxes)
# highlight the 1..2 stddev region with a
# We want x to be in data coordinates and
# span from 0..1 in axes coords
rect = patches.Rectangle((1, 0), width=1,
transform=trans,
alpha=0.5)
span.
y to
height=1,
color='yellow',
ax.add_patch(rect)
plt.show()
Note: The blended transformations where x is in data coords and y in axes coordinates is so useful
that we have helper methods to return the versions mpl uses internally for drawing ticks, ticklabels, etc.
The methods are matplotlib.axes.Axes.get_xaxis_transform() and matplotlib.axes.Axes.
get_yaxis_transform(). So in the example above, the call to blended_transform_factory() can
be replaced by get_xaxis_transform:
trans = ax.get_xaxis_transform()
170
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Using offset transforms to create a shadow effect
One use of transformations is to create a new transformation that is offset from another transformation, e.g.,
to place one object shifted a bit relative to another object. Typically you want the shift to be in some physical
dimension, like points or inches rather than in data coordinates, so that the shift effect is constant at different
zoom levels and dpi settings.
One use for an offset is to create a shadow effect, where you draw one object identical to the first just to the
right of it, and just below it, adjusting the zorder to make sure the shadow is drawn first and then the object
it is shadowing above it. The transforms module has a helper transformation ScaledTranslation. It is
instantiated with:
trans = ScaledTranslation(xt, yt, scale_trans)
where xt and yt are the translation offsets, and scale_trans is a transformation which scales xt and
yt at transformation time before applying the offsets. A typical use case is to use the figure fig.
dpi_scale_trans transformation for the scale_trans argument, to first scale xt and yt specified in
points to display space before doing the final offset. The dpi and inches offset is a common-enough use
case that we have a special helper function to create it in matplotlib.transforms.offset_copy(),
which returns a new transform with an added offset. But in the example below, we’ll create the offset
transform ourselves. Note the use of the plus operator in:
offset = transforms.ScaledTranslation(dx, dy,
fig.dpi_scale_trans)
shadow_transform = ax.transData + offset
showing that can chain transformations using the addition operator. This code says: first apply the data
transformation ax.transData and then translate the data by dx and dy points. In typography, a‘point
<https://en.wikipedia.org/wiki/Point_%28typography%29>‘_ is 1/72 inches, and by specifying your offsets
in points, your figure will look the same regardless of the dpi resolution it is saved in.
fig = plt.figure()
ax = fig.add_subplot(111)
# make a simple sine wave
x = np.arange(0., 2., 0.01)
y = np.sin(2*np.pi*x)
line, = ax.plot(x, y, lw=3, color='blue')
# shift the object over 2 points, and down 2 points
dx, dy = 2/72., -2/72.
offset = transforms.ScaledTranslation(dx, dy, fig.dpi_scale_trans)
shadow_transform = ax.transData + offset
# now plot the same data with our offset transform;
# use the zorder to make sure we are below the line
ax.plot(x, y, lw=3, color='gray',
transform=shadow_transform,
zorder=0.5*line.get_zorder())
3.3. Advanced
171
Matplotlib, Release 2.1.2
ax.set_title('creating a shadow effect with an offset transform')
plt.show()
The transformation pipeline
The ax.transData transform we have been working with in this tutorial is a composite of three different
transformations that comprise the transformation pipeline from data -> display coordinates. Michael
Droettboom implemented the transformations framework, taking care to provide a clean API that segregated the nonlinear projections and scales that happen in polar and logarithmic plots, from the linear affine
transformations that happen when you pan and zoom. There is an efficiency here, because you can pan and
zoom in your axes which affects the affine transformation, but you may not need to compute the potentially
expensive nonlinear scales or projections on simple navigation events. It is also possible to multiply affine
transformation matrices together, and then apply them to coordinates in one step. This is not true of all
possible transformations.
Here is how the ax.transData instance is defined in the basic separable axis Axes class:
self.transData = self.transScale + (self.transLimits + self.transAxes)
We’ve been introduced to the transAxes instance above in Axes coordinates, which maps the (0, 0), (1, 1)
172
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
corners of the axes or subplot bounding box to display space, so let’s look at these other two pieces.
self.transLimits is the transformation that takes you from data to axes coordinates; i.e., it maps your
view xlim and ylim to the unit space of the axes (and transAxes then takes that unit space to display space).
We can see this in action here
In [80]: ax = subplot(111)
In [81]: ax.set_xlim(0, 10)
Out[81]: (0, 10)
In [82]: ax.set_ylim(-1, 1)
Out[82]: (-1, 1)
In [84]: ax.transLimits.transform((0, -1))
Out[84]: array([ 0., 0.])
In [85]: ax.transLimits.transform((10, -1))
Out[85]: array([ 1., 0.])
In [86]: ax.transLimits.transform((10, 1))
Out[86]: array([ 1., 1.])
In [87]: ax.transLimits.transform((5, 0))
Out[87]: array([ 0.5, 0.5])
and we can use this same inverted transformation to go from the unit axes coordinates back to data coordinates.
In [90]: inv.transform((0.25, 0.25))
Out[90]: array([ 2.5, -0.5])
The final piece is the self.transScale attribute, which is responsible for the optional non-linear scaling
of the data, e.g., for logarithmic axes. When an Axes is initially setup, this is just set to the identity transform, since the basic Matplotlib axes has linear scale, but when you call a logarithmic scaling function like
semilogx() or explicitly set the scale to logarithmic with set_xscale(), then the ax.transScale attribute is set to handle the nonlinear projection. The scales transforms are properties of the respective xaxis
and yaxis Axis instances. For example, when you call ax.set_xscale('log'), the xaxis updates its
scale to a matplotlib.scale.LogScale instance.
For non-separable axes the PolarAxes, there is one more piece to consider, the projection transformation.
The transData matplotlib.projections.polar.PolarAxes is similar to that for the typical separable
matplotlib Axes, with one additional piece transProjection:
self.transData = self.transScale + self.transProjection + \
(self.transProjectionAffine + self.transAxes)
transProjection handles the projection from the space, e.g., latitude and longitude for map data, or
radius and theta for polar data, to a separable Cartesian coordinate system. There are several projection
examples in the matplotlib.projections package, and the best way to learn more is to open the source
for those packages and see how to make your own, since Matplotlib supports extensible axes and projections. Michael Droettboom has provided a nice tutorial example of creating a Hammer projection axes; see
3.3. Advanced
173
Matplotlib, Release 2.1.2
sphx_glr_gallery_api_custom_projection_example.py.
Total running time of the script: ( 0 minutes 0.293 seconds)
3.4 Colors
Matplotlib has support for visualizing information with a wide array of colors and colormaps. These tutorials
cover the basics of how these colormaps look, how you can create your own, and how you can customize
colormaps for your use case.
For even more information see the examples page.
3.4.1 Specifying Colors
Matplotlib recognizes the following formats to specify a color:
• an RGB or RGBA tuple of float values in [0, 1] (e.g., (0.1, 0.2, 0.5) or (0.1, 0.2, 0.5,
0.3));
• a hex RGB or RGBA string (e.g., '#0F0F0F' or '#0F0F0F0F');
• a string representation of a float value in [0, 1] inclusive for gray level (e.g., '0.5');
• one of {'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'};
• a X11/CSS4 color name;
• a name from the xkcd color survey; prefixed with 'xkcd:' (e.g., 'xkcd:sky blue');
• one
of
{'tab:blue', 'tab:orange', 'tab:green', 'tab:red', 'tab:purple',
'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'} which are the
Tableau Colors from the ‘T10’ categorical palette (which is the default color cycle);
• a “CN” color spec, i.e. 'C' followed by a single digit, which is an index into the default property
cycle (matplotlib.rcParams['axes.prop_cycle']); the indexing occurs at artist creation time
and defaults to black if the cycle does not include color.
All string specifications of color, other than “CN”, are case-insensitive.
“CN” color selection
“CN” colors are converted to RGBA as soon as the artist is created. For example,
import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl
th = np.linspace(0, 2*np.pi, 128)
def demo(sty):
174
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
mpl.style.use(sty)
fig, ax = plt.subplots(figsize=(3, 3))
ax.set_title('style: {!r}'.format(sty), color='C0')
ax.plot(th, np.cos(th), 'C1', label='C1')
ax.plot(th, np.sin(th), 'C2', label='C2')
ax.legend()
demo('default')
demo('seaborn')
•
•
will use the first color for the title and then plot using the second and third colors of each style’s mpl.
rcParams['axes.prop_cycle'].
xkcd v X11/CSS4
The xkcd colors are derived from a user survey conducted by the webcomic xkcd. Details of the survey are
available on the xkcd blog.
Out of 148 colors in the CSS color list, there are 95 name collisions between the X11/CSS4 names and the
xkcd names, all but 3 of which have different hex values. For example 'blue' maps to '#0000FF' where
as 'xkcd:blue' maps to '#0343DF'. Due to these name collisions all of the xkcd colors have 'xkcd:'
prefixed. As noted in the blog post, while it might be interesting to re-define the X11/CSS4 names based on
such a survey, we do not do so unilaterally.
The name collisions are shown in the table below; the color names where the hex values agree are shown in
bold.
import matplotlib._color_data as mcd
import matplotlib.patches as mpatch
overlap = {name for name in mcd.CSS4_COLORS
3.4. Colors
175
Matplotlib, Release 2.1.2
if "xkcd:" + name in mcd.XKCD_COLORS}
fig = plt.figure(figsize=[4.8, 16])
ax = fig.add_axes([0, 0, 1, 1])
for j, n in enumerate(sorted(overlap, reverse=True)):
weight = None
cn = mcd.CSS4_COLORS[n]
xkcd = mcd.XKCD_COLORS["xkcd:" + n].upper()
if cn == xkcd:
weight = 'bold'
r1 = mpatch.Rectangle((0, j), 1, 1, color=cn)
r2 = mpatch.Rectangle((1, j), 1, 1, color=xkcd)
txt = ax.text(2, j+.5, ' ' + n, va='center', fontsize=10,
weight=weight)
ax.add_patch(r1)
ax.add_patch(r2)
ax.axhline(j, color='k')
ax.text(.5, j + 1.5, 'X11', ha='center', va='center')
ax.text(1.5, j + 1.5, 'xkcd', ha='center', va='center')
ax.set_xlim(0, 3)
ax.set_ylim(0, j + 2)
ax.axis('off')
176
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
3.4. Colors
177
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.144 seconds)
3.4.2 Customized Colorbars Tutorial
This tutorial shows how to build colorbars without an attached plot.
Customized Colorbars
ColorbarBase derives from ScalarMappable and puts a colorbar in a specified axes, so it has everything
needed for a standalone colorbar. It can be used as is to make a colorbar for a given colormap and does not
need a mappable object like an image. In this tutorial we will explore what can be done with standalone
colorbar.
Basic continuous colorbar
Set the colormap and norm to correspond to the data for which the colorbar will be used. Then create the
colorbar by calling ColorbarBase and specify axis, colormap, norm and orientation as parameters. Here
we create a basic continuous colorbar with ticks and labels. More information on colorbar api can be found
here.
import matplotlib.pyplot as plt
import matplotlib as mpl
fig, ax = plt.subplots()
cmap = mpl.cm.cool
norm = mpl.colors.Normalize(vmin=5, vmax=10)
cb1 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
norm=norm,
orientation='horizontal')
cb1.set_label('Some Units')
fig.show()
178
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Discrete intervals colorbar
The second example illustrates the use of a ListedColormap which generates a colormap from a set of
listed colors, colors.BoundaryNorm() which generates a colormap index based on discrete intervals and
extended ends to show the “over” and “under” value colors. Over and under are used to display data outside
of the normalized [0,1] range. Here we pass colors as gray shades as a string encoding a float in the 0-1
range.
If a ListedColormap is used, the length of the bounds array must be one greater than the length of the
color list. The bounds must be monotonically increasing.
This time we pass some more arguments in addition to previous arguments to ColorbarBase. For the outof-range values to display on the colorbar, we have to use the extend keyword argument. To use extend, you
must specify two extra boundaries. Finally spacing argument ensures that intervals are shown on colorbar
proportionally.
fig, ax = plt.subplots()
cmap = mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])
cmap.set_over('0.25')
cmap.set_under('0.75')
3.4. Colors
179
Matplotlib, Release 2.1.2
bounds = [1, 2, 4, 7, 8]
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
cb2 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
norm=norm,
boundaries=[0] + bounds + [13],
extend='both',
ticks=bounds,
spacing='proportional',
orientation='horizontal')
cb2.set_label('Discrete intervals, some other units')
fig.show()
Colorbar with custom extension lengths
Here we illustrate the use of custom length colorbar extensions, used on a colorbar with discrete intervals.
To make the length of each extension same as the length of the interior colors, use extendfrac='auto'.
fig, ax = plt.subplots()
cmap = mpl.colors.ListedColormap(['royalblue', 'cyan',
'yellow', 'orange'])
180
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
cmap.set_over('red')
cmap.set_under('blue')
bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
cb3 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
norm=norm,
boundaries=[-10] + bounds + [10],
extend='both',
extendfrac='auto',
ticks=bounds,
spacing='uniform',
orientation='horizontal')
cb3.set_label('Custom extension lengths, some other units')
fig.show()
Total running time of the script: ( 0 minutes 0.064 seconds)
3.4.3 Colormap Normalization
Objects that use colormaps by default linearly map the colors in the colormap from data values vmin to
vmax. For example:
3.4. Colors
181
Matplotlib, Release 2.1.2
pcm = ax.pcolormesh(x, y, Z, vmin=-1., vmax=1., cmap='RdBu_r')
will map the data in Z linearly from -1 to +1, so Z=0 will give a color at the center of the colormap RdBu_r
(white in this case).
Matplotlib does this mapping in two steps, with a normalization from [0,1] occurring first, and then mapping
onto the indices in the colormap. Normalizations are classes defined in the matplotlib.colors() module.
The default, linear normalization is matplotlib.colors.Normalize().
Artists that map data to color pass the arguments vmin and vmax to construct a matplotlib.colors.
Normalize() instance, then call it:
In [1]: import matplotlib as mpl
In [2]: norm = mpl.colors.Normalize(vmin=-1.,vmax=1.)
In [3]: norm(0.)
Out[3]: 0.5
However, there are sometimes cases where it is useful to map data to colormaps in a non-linear fashion.
Logarithmic
One of the most common transformations is to plot data by taking its logarithm (to the base-10). This
transformation is useful to display changes across disparate scales. Using colors.LogNorm() normalizes
the data via log10 . In the example below, there are two bumps, one much smaller than the other. Using
colors.LogNorm(), the shape and location of each bump can clearly be seen:
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.colors as colors
from matplotlib.mlab import bivariate_normal
N = 100
X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
# A low hump with a spike coming out of the top right. Needs to have
# z/colour axis on a log scale so we see both hump and spike. linear
# scale only shows the spike.
Z1 = bivariate_normal(X, Y, 0.1, 0.2, 1.0, 1.0) + \
0.1 * bivariate_normal(X, Y, 1.0, 1.0, 0.0, 0.0)
fig, ax = plt.subplots(2, 1)
pcm = ax[0].pcolor(X, Y, Z1,
norm=colors.LogNorm(vmin=Z1.min(), vmax=Z1.max()),
cmap='PuBu_r')
fig.colorbar(pcm, ax=ax[0], extend='max')
pcm = ax[1].pcolor(X, Y, Z1, cmap='PuBu_r')
182
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
fig.colorbar(pcm, ax=ax[1], extend='max')
fig.show()
Symmetric logarithmic
Similarly, it sometimes happens that there is data that is positive and negative, but we would still like a
logarithmic scaling applied to both. In this case, the negative numbers are also scaled logarithmically, and
mapped to smaller numbers; e.g., if vmin=-vmax, then they the negative numbers are mapped from 0 to 0.5
and the positive from 0.5 to 1.
Since the logarithm of values close to zero tends toward infinity, a small range around zero needs to be
mapped linearly. The parameter linthresh allows the user to specify the size of this range (-linthresh,
linthresh). The size of this range in the colormap is set by linscale. When linscale == 1.0 (the default),
the space used for the positive and negative halves of the linear range will be equal to one decade in the
logarithmic range.
N = 100
X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
Z1 = (bivariate_normal(X, Y, 1., 1., 1.0, 1.0))**2 \
- 0.4 * (bivariate_normal(X, Y, 1.0, 1.0, -1.0, 0.0))**2
Z1 = Z1/0.03
3.4. Colors
183
Matplotlib, Release 2.1.2
fig, ax = plt.subplots(2, 1)
pcm = ax[0].pcolormesh(X, Y, Z1,
norm=colors.SymLogNorm(linthresh=0.03, linscale=0.03,
vmin=-1.0, vmax=1.0),
cmap='RdBu_r')
fig.colorbar(pcm, ax=ax[0], extend='both')
pcm = ax[1].pcolormesh(X, Y, Z1, cmap='RdBu_r', vmin=-np.max(Z1))
fig.colorbar(pcm, ax=ax[1], extend='both')
fig.show()
Power-law
Sometimes it is useful to remap the colors onto a power-law relationship (i.e. y = xγ , where γ is the power).
For this we use the colors.PowerNorm(). It takes as an argument gamma (gamma == 1.0 will just yield
the default linear normalization):
Note: There should probably be a good reason for plotting the data using this type of transformation.
Technical viewers are used to linear and logarithmic axes and data transformations. Power laws are less
184
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
common, and viewers should explicitly be made aware that they have been used.
N = 100
X, Y = np.mgrid[0:3:complex(0, N), 0:2:complex(0, N)]
Z1 = (1 + np.sin(Y * 10.)) * X**(2.)
fig, ax = plt.subplots(2, 1)
pcm = ax[0].pcolormesh(X, Y, Z1, norm=colors.PowerNorm(gamma=1./2.),
cmap='PuBu_r')
fig.colorbar(pcm, ax=ax[0], extend='max')
pcm = ax[1].pcolormesh(X, Y, Z1, cmap='PuBu_r')
fig.colorbar(pcm, ax=ax[1], extend='max')
fig.show()
Discrete bounds
Another normaization that comes with matplolib is colors.BoundaryNorm(). In addition to vmin and
vmax, this takes as arguments boundaries between which data is to be mapped. The colors are then linearly
distributed between these “bounds”. For instance:
3.4. Colors
185
Matplotlib, Release 2.1.2
In [4]: import matplotlib.colors as colors
In [5]: bounds = np.array([-0.25, -0.125, 0, 0.5, 1])
In [6]: norm = colors.BoundaryNorm(boundaries=bounds, ncolors=4)
In [7]: print(norm([-0.2,-0.15,-0.02, 0.3, 0.8, 0.99]))
[0 0 1 2 3 3]
Note unlike the other norms, this norm returns values from 0 to ncolors-1.
N = 100
X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
Z1 = (bivariate_normal(X, Y, 1., 1., 1.0, 1.0))**2 \
- 0.4 * (bivariate_normal(X, Y, 1.0, 1.0, -1.0, 0.0))**2
Z1 = Z1/0.03
fig, ax = plt.subplots(3, 1, figsize=(8, 8))
ax = ax.flatten()
# even bounds gives a contour-like effect
bounds = np.linspace(-1, 1, 10)
norm = colors.BoundaryNorm(boundaries=bounds, ncolors=256)
pcm = ax[0].pcolormesh(X, Y, Z1,
norm=norm,
cmap='RdBu_r')
fig.colorbar(pcm, ax=ax[0], extend='both', orientation='vertical')
# uneven bounds changes the colormapping:
bounds = np.array([-0.25, -0.125, 0, 0.5, 1])
norm = colors.BoundaryNorm(boundaries=bounds, ncolors=256)
pcm = ax[1].pcolormesh(X, Y, Z1, norm=norm, cmap='RdBu_r')
fig.colorbar(pcm, ax=ax[1], extend='both', orientation='vertical')
pcm = ax[2].pcolormesh(X, Y, Z1, cmap='RdBu_r', vmin=-np.max(Z1))
fig.colorbar(pcm, ax=ax[2], extend='both', orientation='vertical')
fig.show()
186
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Custom normalization: Two linear ranges
It is possible to define your own normalization.
In the following example, we modify
colors:SymLogNorm() to use different linear maps for the negative data values and the positive. (Note
that this example is simple, and does not validate inputs or account for complex cases such as masked data)
Note: This may appear soon as colors.OffsetNorm().
As above, non-symmetric mapping of data to color is non-standard practice for quantitative data, and should
only be used advisedly. A practical example is having an ocean/land colormap where the land and ocean
3.4. Colors
187
Matplotlib, Release 2.1.2
data span different ranges.
N = 100
X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
Z1 = (bivariate_normal(X, Y, 1., 1., 1.0, 1.0))**2 \
- 0.4 * (bivariate_normal(X, Y, 1.0, 1.0, -1.0, 0.0))**2
Z1 = Z1/0.03
class MidpointNormalize(colors.Normalize):
def __init__(self, vmin=None, vmax=None, midpoint=None, clip=False):
self.midpoint = midpoint
colors.Normalize.__init__(self, vmin, vmax, clip)
def __call__(self, value, clip=None):
# I'm ignoring masked values and all kinds of edge cases to make a
# simple example...
x, y = [self.vmin, self.midpoint, self.vmax], [0, 0.5, 1]
return np.ma.masked_array(np.interp(value, x, y))
fig, ax = plt.subplots(2, 1)
pcm = ax[0].pcolormesh(X, Y, Z1,
norm=MidpointNormalize(midpoint=0.),
cmap='RdBu_r')
fig.colorbar(pcm, ax=ax[0], extend='both')
pcm = ax[1].pcolormesh(X, Y, Z1, cmap='RdBu_r', vmin=-np.max(Z1))
fig.colorbar(pcm, ax=ax[1], extend='both')
fig.show()
188
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.813 seconds)
3.4.4 Colormaps in Matplotlib
How (and why) to choose a particular colormap.
Overview
The idea behind choosing a good colormap is to find a good representation in 3D colorspace for your data
set. The best colormap for any given data set depends on many things including:
• Whether representing form or metric data ([Ware])
• Your knowledge of the data set (e.g., is there a critical value from which the other values deviate?)
• If there is an intuitive color scheme for the parameter you are plotting
• If there is a standard in the field the audience may be expecting
For many applications, a perceptually uniform colormap is the best choice — one in which equal steps in
data are perceived as equal steps in the color space. Researchers have found that the human brain perceives
changes in the lightness parameter as changes in the data much better than, for example, changes in hue.
3.4. Colors
189
Matplotlib, Release 2.1.2
Therefore, colormaps which have monotonically increasing lightness through the colormap will be better
interpreted by the viewer. A wonderful example of perceptually uniform colormaps is [colorcet].
Color can be represented in 3D space in various ways. One way to represent color is using CIELAB. In
CIELAB, color space is represented by lightness, L* ; red-green, a* ; and yellow-blue, b* . The lightness
parameter L* can then be used to learn more about how the matplotlib colormaps will be perceived by
viewers.
An excellent starting resource for learning about human perception of colormaps is from [IBM].
Classes of colormaps
Colormaps are often split into several categories based on their function (see, e.g., [Moreland]):
1. Sequential: change in lightness and often saturation of color incrementally, often using a single hue;
should be used for representing information that has ordering.
2. Diverging: change in lightness and possibly saturation of two different colors that meet in the middle
at an unsaturated color; should be used when the information being plotted has a critical middle value,
such as topography or when the data deviates around zero.
3. Qualitative: often are miscellaneous colors; should be used to represent information which does not
have ordering or relationships.
# sphinx_gallery_thumbnail_number = 2
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
from matplotlib import cm
from colorspacious import cspace_converter
from collections import OrderedDict
cmaps = OrderedDict()
Sequential
For the Sequential plots, the lightness value increases monotonically through the colormaps. This is good.
Some of the L* values in the colormaps span from 0 to 100 (binary and the other grayscale), and others start
around L* = 20. Those that have a smaller range of L* will accordingly have a smaller perceptual range.
Note also that the L* function varies amongst the colormaps: some are approximately linear in L* and others
are more curved.
cmaps['Perceptually Uniform Sequential'] = ['viridis', 'plasma',
'inferno', 'magma']
cmaps['Sequential'] = [
'Greys', 'Purples', 'Blues', 'Greens', 'Oranges', 'Reds',
'YlOrBr', 'YlOrRd', 'OrRd', 'PuRd', 'RdPu', 'BuPu',
'GnBu', 'PuBu', 'YlGnBu', 'PuBuGn', 'BuGn', 'YlGn']
190
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Sequential2
Many of the L* values from the Sequential2 plots are monotonically increasing, but some (autumn, cool,
spring, and winter) plateau or even go both up and down in L* space. Others (afmhot, copper, gist_heat,
and hot) have kinks in the L* functions. Data that is being represented in a region of the colormap that is
at a plateau or kink will lead to a perception of banding of the data in those values in the colormap (see
[mycarta-banding] for an excellent example of this).
cmaps['Sequential (2)'] = [
'binary', 'gist_yarg', 'gist_gray', 'gray', 'bone', 'pink',
'spring', 'summer', 'autumn', 'winter', 'cool', 'Wistia',
'hot', 'afmhot', 'gist_heat', 'copper']
Diverging
For the Diverging maps, we want to have monotonically increasing L* values up to a maximum, which
should be close to L* = 100, followed by monotonically decreasing L* values. We are looking for approximately equal minimum L* values at opposite ends of the colormap. By these measures, BrBG and RdBu
are good options. coolwarm is a good option, but it doesn’t span a wide range of L* values (see grayscale
section below).
cmaps['Diverging'] = [
'PiYG', 'PRGn', 'BrBG', 'PuOr', 'RdGy', 'RdBu',
'RdYlBu', 'RdYlGn', 'Spectral', 'coolwarm', 'bwr', 'seismic']
Qualitative
Qualitative colormaps are not aimed at being perceptual maps, but looking at the lightness parameter can
verify that for us. The L* values move all over the place throughout the colormap, and are clearly not
monotonically increasing. These would not be good options for use as perceptual colormaps.
cmaps['Qualitative'] = ['Pastel1', 'Pastel2', 'Paired', 'Accent',
'Dark2', 'Set1', 'Set2', 'Set3',
'tab10', 'tab20', 'tab20b', 'tab20c']
Miscellaneous
Some of the miscellaneous colormaps have particular uses for which they have been created. For example,
gist_earth, ocean, and terrain all seem to be created for plotting topography (green/brown) and water depths
(blue) together. We would expect to see a divergence in these colormaps, then, but multiple kinks may not
be ideal, such as in gist_earth and terrain. CMRmap was created to convert well to grayscale, though it does
appear to have some small kinks in L* . cubehelix was created to vary smoothly in both lightness and hue,
but appears to have a small hump in the green hue area.
3.4. Colors
191
Matplotlib, Release 2.1.2
The often-used jet colormap is included in this set of colormaps. We can see that the L* values vary widely
throughout the colormap, making it a poor choice for representing data for viewers to see perceptually. See
an extension on this idea at [mycarta-jet].
cmaps['Miscellaneous'] = [
'flag', 'prism', 'ocean', 'gist_earth', 'terrain', 'gist_stern',
'gnuplot', 'gnuplot2', 'CMRmap', 'cubehelix', 'brg', 'hsv',
'gist_rainbow', 'rainbow', 'jet', 'nipy_spectral', 'gist_ncar']
First, we’ll show the range of each colormap. Note that some seem to change more “quickly” than others.
nrows = max(len(cmap_list) for cmap_category, cmap_list in cmaps.items())
gradient = np.linspace(0, 1, 256)
gradient = np.vstack((gradient, gradient))
def plot_color_gradients(cmap_category, cmap_list, nrows):
fig, axes = plt.subplots(nrows=nrows)
fig.subplots_adjust(top=0.95, bottom=0.01, left=0.2, right=0.99)
axes[0].set_title(cmap_category + ' colormaps', fontsize=14)
for ax, name in zip(axes, cmap_list):
ax.imshow(gradient, aspect='auto', cmap=plt.get_cmap(name))
pos = list(ax.get_position().bounds)
x_text = pos[0] - 0.01
y_text = pos[1] + pos[3]/2.
fig.text(x_text, y_text, name, va='center', ha='right', fontsize=10)
# Turn off *all* ticks & spines, not just the ones with colormaps.
for ax in axes:
ax.set_axis_off()
for cmap_category, cmap_list in cmaps.items():
plot_color_gradients(cmap_category, cmap_list, nrows)
plt.show()
•
192
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
•
•
•
3.4. Colors
193
Matplotlib, Release 2.1.2
•
•
Lightness of matplotlib colormaps
Here we examine the lightness values of the matplotlib colormaps. Note that some documentation on the
colormaps is available ([list-colormaps]).
mpl.rcParams.update({'font.size': 12})
# Number of colormap per subplot for particular cmap categories
_DSUBS = {'Perceptually Uniform Sequential': 4, 'Sequential': 6,
'Sequential (2)': 6, 'Diverging': 6, 'Qualitative': 4,
'Miscellaneous': 6}
# Spacing between the colormaps of a subplot
_DC = {'Perceptually Uniform Sequential': 1.4, 'Sequential': 0.7,
'Sequential (2)': 1.4, 'Diverging': 1.4, 'Qualitative': 1.4,
'Miscellaneous': 1.4}
# Indices to step through colormap
x = np.linspace(0.0, 1.0, 100)
# Do plot
for cmap_category, cmap_list in cmaps.items():
194
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
# Do subplots so that colormaps have enough space.
# Default is 6 colormaps per subplot.
dsub = _DSUBS.get(cmap_category, 6)
nsubplots = int(np.ceil(len(cmap_list) / float(dsub)))
# squeeze=False to handle similarly the case of a single subplot
fig, axes = plt.subplots(nrows=nsubplots, squeeze=False,
figsize=(7, 2.6*nsubplots))
for i, ax in enumerate(axes.flat):
locs = []
# locations for text labels
for j, cmap in enumerate(cmap_list[i*dsub:(i+1)*dsub]):
# Get RGB values for colormap and convert the colormap in
# CAM02-UCS colorspace. lab[0, :, 0] is the lightness.
rgb = cm.get_cmap(cmap)(x)[np.newaxis, :, :3]
lab = cspace_converter("sRGB1", "CAM02-UCS")(rgb)
# Plot colormap L values. Do separately for each category
# so each plot can be pretty. To make scatter markers change
# color along plot:
# http://stackoverflow.com/questions/8202605/matplotlib-scatterplot-colour,→as-a-function-of-a-third-variable
if cmap_category == 'Sequential':
# These colormaps all start at high lightness but we want them
# reversed to look nice in the plot, so reverse the order.
y_ = lab[0, ::-1, 0]
c_ = x[::-1]
else:
y_ = lab[0, :, 0]
c_ = x
dc = _DC.get(cmap_category, 1.4) # cmaps horizontal spacing
ax.scatter(x + j*dc, y_, c=c_, cmap=cmap, s=300, linewidths=0.0)
# Store locations for colormap labels
if cmap_category in ('Perceptually Uniform Sequential',
'Sequential'):
locs.append(x[-1] + j*dc)
elif cmap_category in ('Diverging', 'Qualitative',
'Miscellaneous', 'Sequential (2)'):
locs.append(x[int(x.size/2.)] + j*dc)
# Set up the axis limits:
#
* the 1st subplot is used as a reference for the x-axis limits
#
* lightness values goes from 0 to 100 (y-axis limits)
ax.set_xlim(axes[0, 0].get_xlim())
ax.set_ylim(0.0, 100.0)
# Set up labels for colormaps
3.4. Colors
195
Matplotlib, Release 2.1.2
ax.xaxis.set_ticks_position('top')
ticker = mpl.ticker.FixedLocator(locs)
ax.xaxis.set_major_locator(ticker)
formatter = mpl.ticker.FixedFormatter(cmap_list[i*dsub:(i+1)*dsub])
ax.xaxis.set_major_formatter(formatter)
ax.xaxis.set_tick_params(rotation=50)
ax.set_xlabel(cmap_category + ' colormaps', fontsize=14)
fig.text(0.0, 0.55, 'Lightness $L^*$', fontsize=12,
transform=fig.transFigure, rotation=90)
fig.tight_layout(h_pad=0.0, pad=1.5)
plt.show()
•
•
196
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
•
•
3.4. Colors
197
Matplotlib, Release 2.1.2
•
•
Grayscale conversion
It is important to pay attention to conversion to grayscale for color plots, since they may be printed on black
and white printers. If not carefully considered, your readers may end up with indecipherable plots because
the grayscale changes unpredictably through the colormap.
Conversion to grayscale is done in many different ways [bw]. Some of the better ones use a linear combi198
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
nation of the rgb values of a pixel, but weighted according to how we perceive color intensity. A nonlinear
method of conversion to grayscale is to use the L* values of the pixels. In general, similar principles apply
for this question as they do for presenting one’s information perceptually; that is, if a colormap is chosen
that is monotonically increasing in L* values, it will print in a reasonable manner to grayscale.
With this in mind, we see that the Sequential colormaps have reasonable representations in grayscale. Some
of the Sequential2 colormaps have decent enough grayscale representations, though some (autumn, spring,
summer, winter) have very little grayscale change. If a colormap like this was used in a plot and then
the plot was printed to grayscale, a lot of the information may map to the same gray values. The Diverging
colormaps mostly vary from darker gray on the outer edges to white in the middle. Some (PuOr and seismic)
have noticably darker gray on one side than the other and therefore are not very symmetric. coolwarm has
little range of gray scale and would print to a more uniform plot, losing a lot of detail. Note that overlaid,
labeled contours could help differentiate between one side of the colormap vs. the other since color cannot
be used once a plot is printed to grayscale. Many of the Qualitative and Miscellaneous colormaps, such as
Accent, hsv, and jet, change from darker to lighter and back to darker gray throughout the colormap. This
would make it impossible for a viewer to interpret the information in a plot once it is printed in grayscale.
mpl.rcParams.update({'font.size': 14})
# Indices to step through colormap.
x = np.linspace(0.0, 1.0, 100)
gradient = np.linspace(0, 1, 256)
gradient = np.vstack((gradient, gradient))
def plot_color_gradients(cmap_category, cmap_list):
fig, axes = plt.subplots(nrows=len(cmap_list), ncols=2)
fig.subplots_adjust(top=0.95, bottom=0.01, left=0.2, right=0.99,
wspace=0.05)
fig.suptitle(cmap_category + ' colormaps', fontsize=14, y=1.0, x=0.6)
for ax, name in zip(axes, cmap_list):
# Get RGB values for colormap.
rgb = cm.get_cmap(plt.get_cmap(name))(x)[np.newaxis, :, :3]
# Get colormap in CAM02-UCS colorspace. We want the lightness.
lab = cspace_converter("sRGB1", "CAM02-UCS")(rgb)
L = lab[0, :, 0]
L = np.float32(np.vstack((L, L, L)))
ax[0].imshow(gradient, aspect='auto', cmap=plt.get_cmap(name))
ax[1].imshow(L, aspect='auto', cmap='binary_r', vmin=0., vmax=100.)
pos = list(ax[0].get_position().bounds)
x_text = pos[0] - 0.01
y_text = pos[1] + pos[3]/2.
fig.text(x_text, y_text, name, va='center', ha='right', fontsize=10)
# Turn off *all* ticks & spines, not just the ones with colormaps.
for ax in axes.flat:
ax.set_axis_off()
3.4. Colors
199
Matplotlib, Release 2.1.2
plt.show()
for cmap_category, cmap_list in cmaps.items():
plot_color_gradients(cmap_category, cmap_list)
•
•
•
200
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
•
•
•
Color vision deficiencies
There is a lot of information available about color blindness (e.g., [colorblindness]). Additionally, there
are tools available to convert images to how they look for different types of color vision deficiencies (e.g.,
[vischeck]).
The most common form of color vision deficiency involves differentiating between red and green. Thus,
avoiding colormaps with both red and green will avoid many problems in general.
3.4. Colors
201
Matplotlib, Release 2.1.2
References
Total running time of the script: ( 0 minutes 5.873 seconds)
3.5 Text
matplotlib has extensive text support, including support for mathematical expressions, truetype support for
raster and vector outputs, newline separated text with arbitrary rotations, and unicode support. These tutorials cover the basics of working with text in Matplotlib.
3.5.1 Annotations
Annotating text with Matplotlib.
Table of Contents
• Annotations
• Basic annotation
• Advanced Annotation
– Annotating with Text with Box
– Annotating with Arrow
– Placing Artist at the anchored location of the Axes
– Using Complex Coordinates with Annotations
– Using ConnectorPatch
* Advanced Topics
– Zoom effect between Axes
– Define Custom BoxStyle
3.5.2 Basic annotation
The uses of the basic text() will place text at an arbitrary position on the Axes. A common use case of text
is to annotate some feature of the plot, and the annotate() method provides helper functionality to make
annotations easy. In an annotation, there are two points to consider: the location being annotated represented
by the argument xy and the location of the text xytext. Both of these arguments are (x,y) tuples.
In this example, both the xy (arrow tip) and xytext locations (text location) are in data coordinates. There
are a variety of other coordinate systems one can choose – you can specify the coordinate system of xy and
xytext with one of the following strings for xycoords and textcoords (default is ‘data’)
202
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.23: Annotation Basic
argument
coordinate system
‘figure points’
‘figure pixels’
‘figure fraction’
‘axes points’
‘axes pixels’
‘axes fraction’
‘data’
points from the lower left corner of the figure
pixels from the lower left corner of the figure
0,0 is lower left of figure and 1,1 is upper right
points from lower left corner of axes
pixels from lower left corner of axes
0,0 is lower left of axes and 1,1 is upper right
use the axes data coordinate system
For example to place the text coordinates in fractional axes coordinates, one could do:
ax.annotate('local max', xy=(3, 1), xycoords='data',
xytext=(0.8, 0.95), textcoords='axes fraction',
arrowprops=dict(facecolor='black', shrink=0.05),
horizontalalignment='right', verticalalignment='top',
)
For physical coordinate systems (points or pixels) the origin is the bottom-left of the figure or axes.
Optionally, you can enable drawing of an arrow from the text to the annotated point by giving a dictionary
of arrow properties in the optional keyword argument arrowprops.
arrowprops key
width
frac
headwidth
shrink
**kwargs
description
the width of the arrow in points
the fraction of the arrow length occupied by the head
the width of the base of the arrow head in points
move the tip and base some percent away from the annotated point and text
any key for matplotlib.patches.Polygon, e.g., facecolor
In the example below, the xy point is in native coordinates (xycoords defaults to ‘data’). For a polar
axes, this is in (theta, radius) space. The text in this example is placed in the fractional figure coordinate
3.5. Text
203
Matplotlib, Release 2.1.2
system. matplotlib.text.Text keyword args like horizontalalignment, verticalalignment and
fontsize are passed from annotate to the Text instance.
Fig. 3.24: Annotation Polar
For more on all the wild and wonderful things you can do with annotations, including fancy arrows, see
Advanced Annotation and sphx_glr_gallery_text_labels_and_annotations_annotation_demo.py.
Do not proceed unless you have already read Basic annotation, text() and annotate()!
3.5.3 Advanced Annotation
Annotating with Text with Box
Let’s start with a simple example.
Fig. 3.25: Annotate Text Arrow
The text() function in the pyplot module (or text method of the Axes class) takes bbox keyword argument,
and when given, a box around the text is drawn.
204
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
bbox_props = dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2)
t = ax.text(0, 0, "Direction", ha="center", va="center", rotation=45,
size=15,
bbox=bbox_props)
The patch object associated with the text can be accessed by:
bb = t.get_bbox_patch()
The return value is an instance of FancyBboxPatch and the patch properties like facecolor, edgewidth, etc.
can be accessed and modified as usual. To change the shape of the box, use the set_boxstyle method.
bb.set_boxstyle("rarrow", pad=0.6)
The arguments are the name of the box style with its attributes as keyword arguments. Currently, following
box styles are implemented.
Class
Name
Attrs
Circle
DArrow
LArrow
RArrow
Round
Round4
Roundtooth
Sawtooth
Square
circle
darrow
larrow
rarrow
round
round4
roundtooth
sawtooth
square
pad=0.3
pad=0.3
pad=0.3
pad=0.3
pad=0.3,rounding_size=None
pad=0.3,rounding_size=None
pad=0.3,tooth_size=None
pad=0.3,tooth_size=None
pad=0.3
Note that the attribute arguments can be specified within the style name with separating comma (this form
can be used as “boxstyle” value of bbox argument when initializing the text instance)
bb.set_boxstyle("rarrow,pad=0.6")
Annotating with Arrow
The annotate() function in the pyplot module (or annotate method of the Axes class) is used to draw an
arrow connecting two points on the plot.
ax.annotate("Annotation",
xy=(x1, y1), xycoords='data',
xytext=(x2, y2), textcoords='offset points',
)
This annotates a point at xy in the given coordinate (xycoords) with the text at xytext given in
textcoords. Often, the annotated point is specified in the data coordinate and the annotating text in offset
points. See annotate() for available coordinate systems.
3.5. Text
205
Matplotlib, Release 2.1.2
Fig. 3.26: Fancybox Demo
An arrow connecting two points (xy & xytext) can be optionally drawn by specifying the arrowprops
argument. To draw only an arrow, use empty string as the first argument.
ax.annotate("",
xy=(0.2, 0.2), xycoords='data',
xytext=(0.8, 0.8), textcoords='data',
arrowprops=dict(arrowstyle="->",
connectionstyle="arc3"),
)
Fig. 3.27: Annotate Simple01
The arrow drawing takes a few steps.
1. a connecting path between two points are created. This is controlled by connectionstyle key value.
2. If patch object is given (patchA & patchB), the path is clipped to avoid the patch.
206
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
3. The path is further shrunk by given amount of pixels (shrinkA & shrinkB)
4. The path is transmuted to arrow patch, which is controlled by the arrowstyle key value.
Fig. 3.28: Annotate Explain
The creation of the connecting path between two points is controlled by connectionstyle key and the
following styles are available.
Name
Attrs
angle
angle3
arc
arc3
bar
angleA=90,angleB=0,rad=0.0
angleA=90,angleB=0
angleA=0,angleB=0,armA=None,armB=None,rad=0.0
rad=0.0
armA=0.0,armB=0.0,fraction=0.3,angle=None
Note that “3” in angle3 and arc3 is meant to indicate that the resulting path is a quadratic spline segment
(three control points). As will be discussed below, some arrow style options can only be used when the
connecting path is a quadratic spline.
The behavior of each connection style is (limitedly) demonstrated in the example below. (Warning : The
behavior of the bar style is currently not well defined, it may be changed in the future).
The connecting path (after clipping and shrinking) is then mutated to an arrow patch, according to the given
arrowstyle.
3.5. Text
207
Matplotlib, Release 2.1.2
Fig. 3.29: Connectionstyle Demo
Name
Attrs
->
-[
|-|
-|>
<<->
<|<|-|>
fancy
simple
wedge
None
head_length=0.4,head_width=0.2
widthB=1.0,lengthB=0.2,angleB=None
widthA=1.0,widthB=1.0
head_length=0.4,head_width=0.2
head_length=0.4,head_width=0.2
head_length=0.4,head_width=0.2
head_length=0.4,head_width=0.2
head_length=0.4,head_width=0.2
head_length=0.4,head_width=0.4,tail_width=0.4
head_length=0.5,head_width=0.5,tail_width=0.2
tail_width=0.3,shrink_factor=0.5
Fig. 3.30: Fancyarrow Demo
208
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Some arrowstyles only work with connection styles that generate a quadratic-spline segment. They are
fancy, simple, and wedge. For these arrow styles, you must use the “angle3” or “arc3” connection style.
If the annotation string is given, the patchA is set to the bbox patch of the text by default.
Fig. 3.31: Annotate Simple02
As in the text command, a box around the text can be drawn using the bbox argument.
Fig. 3.32: Annotate Simple03
By default, the starting point is set to the center of the text extent. This can be adjusted with relpos key
value. The values are normalized to the extent of the text. For example, (0,0) means lower-left corner and
(1,1) means top-right.
Fig. 3.33: Annotate Simple04
Placing Artist at the anchored location of the Axes
There are classes of artists that can be placed at an anchored location in the Axes. A common example is
the legend. This type of artist can be created by using the OffsetBox class. A few predefined classes are
available in mpl_toolkits.axes_grid1.anchored_artists others in matplotlib.offsetbox
3.5. Text
209
Matplotlib, Release 2.1.2
from matplotlib.offsetbox import AnchoredText
at = AnchoredText("Figure 1a",
prop=dict(size=8), frameon=True,
loc=2,
)
at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
ax.add_artist(at)
Fig. 3.34: Anchored Box01
The loc keyword has same meaning as in the legend command.
A simple application is when the size of the artist (or collection of artists) is known in pixel size during the
time of creation. For example, If you want to draw a circle with fixed size of 20 pixel x 20 pixel (radius = 10
pixel), you can utilize AnchoredDrawingArea. The instance is created with a size of the drawing area (in
pixels), and arbitrary artists can added to the drawing area. Note that the extents of the artists that are added
to the drawing area are not related to the placement of the drawing area itself. Only the initial size matters.
from mpl_toolkits.axes_grid1.anchored_artists import AnchoredDrawingArea
ada = AnchoredDrawingArea(20, 20, 0, 0,
loc=1, pad=0., frameon=False)
p1 = Circle((10, 10), 10)
ada.drawing_area.add_artist(p1)
p2 = Circle((30, 10), 5, fc="r")
ada.drawing_area.add_artist(p2)
The artists that are added to the drawing area should not have a transform set (it will be overridden) and
the dimensions of those artists are interpreted as a pixel coordinate, i.e., the radius of the circles in above
example are 10 pixels and 5 pixels, respectively.
Sometimes, you want your artists to scale with the data coordinate (or coordinates other than canvas pixels).
You can use AnchoredAuxTransformBox class. This is similar to AnchoredDrawingArea except that the
extent of the artist is determined during the drawing time respecting the specified transform.
from mpl_toolkits.axes_grid1.anchored_artists import AnchoredAuxTransformBox
box = AnchoredAuxTransformBox(ax.transData, loc=2)
el = Ellipse((0,0), width=0.1, height=0.4, angle=30)
box.drawing_area.add_artist(el)
# in data coordinates!
The ellipse in the above example will have width and height corresponding to 0.1 and 0.4 in data coordi210
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.35: Anchored Box02
nateing and will be automatically scaled when the view limits of the axes change.
Fig. 3.36: Anchored Box03
As in the legend, the bbox_to_anchor argument can be set. Using the HPacker and VPacker, you can have
an arrangement(?) of artist as in the legend (as a matter of fact, this is how the legend is created).
Fig. 3.37: Anchored Box04
Note that unlike the legend, the bbox_transform is set to IdentityTransform by default.
Using Complex Coordinates with Annotations
The Annotation in matplotlib supports several types of coordinates as described in Basic annotation. For an
advanced user who wants more control, it supports a few other options.
1. Transform instance. For example,
3.5. Text
211
Matplotlib, Release 2.1.2
ax.annotate("Test", xy=(0.5, 0.5), xycoords=ax.transAxes)
is identical to
ax.annotate("Test", xy=(0.5, 0.5), xycoords="axes fraction")
With this, you can annotate a point in other axes.
ax1, ax2 = subplot(121), subplot(122)
ax2.annotate("Test", xy=(0.5, 0.5), xycoords=ax1.transData,
xytext=(0.5, 0.5), textcoords=ax2.transData,
arrowprops=dict(arrowstyle="->"))
2. Artist instance. The xy value (or xytext) is interpreted as a fractional coordinate of the bbox (return
value of get_window_extent) of the artist.
an1 = ax.annotate("Test 1", xy=(0.5, 0.5), xycoords="data",
va="center", ha="center",
bbox=dict(boxstyle="round", fc="w"))
an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1, # (1,0.5) of the an1's bbox
xytext=(30,0), textcoords="offset points",
va="center", ha="left",
bbox=dict(boxstyle="round", fc="w"),
arrowprops=dict(arrowstyle="->"))
Fig. 3.38: Annotation with Simple Coordinates
Note that it is your responsibility that the extent of the coordinate artist (an1 in above example) is
determined before an2 gets drawn. In most cases, it means that an2 needs to be drawn later than an1.
3. A callable object that returns an instance of either BboxBase or Transform. If a transform is returned,
it is the same as 1 and if a bbox is returned, it is the same as 2. The callable object should take a single
argument of the renderer instance. For example, the following two commands give identical results
an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1,
xytext=(30,0), textcoords="offset points")
an2 = ax.annotate("Test 2", xy=(1, 0.5), xycoords=an1.get_window_extent,
xytext=(30,0), textcoords="offset points")
4. A tuple of two coordinate specifications. The first item is for the x-coordinate and the second is for
the y-coordinate. For example,
annotate("Test", xy=(0.5, 1), xycoords=("data", "axes fraction"))
212
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
0.5 is in data coordinates, and 1 is in normalized axes coordinates. You may use an artist or transform
as with a tuple. For example,
Fig. 3.39: Annotation with Simple Coordinates 2
5. Sometimes, you want your annotation with some “offset points”, not from the annotated point but
from some other point. OffsetFrom is a helper class for such cases.
Fig. 3.40: Annotation with Simple Coordinates 3
You may take a look at this example sphx_glr_gallery_text_labels_and_annotations_annotation_demo.py.
Using ConnectorPatch
The ConnectorPatch is like an annotation without text. While the annotate function is recommended in most
situations, the ConnectorPatch is useful when you want to connect points in different axes.
from matplotlib.patches import ConnectionPatch
xy = (0.2, 0.2)
con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data",
axesA=ax1, axesB=ax2)
ax2.add_artist(con)
The above code connects point xy in the data coordinates of ax1 to point xy in the data coordinates of ax2.
Here is a simple example.
Fig. 3.41: Connect Simple01
3.5. Text
213
Matplotlib, Release 2.1.2
While the ConnectorPatch instance can be added to any axes, you may want to add it to the axes that is latest
in drawing order to prevent overlap by other axes.
Advanced Topics
Zoom effect between Axes
mpl_toolkits.axes_grid1.inset_locator defines some patch classes useful for interconnecting two
axes. Understanding the code requires some knowledge of how mpl’s transform works. But, utilizing it will
be straight forward.
Fig. 3.42: Axes Zoom Effect
Define Custom BoxStyle
You can use a custom box style. The value for the boxstyle can be a callable object in the following forms.:
def __call__(self, x0, y0, width, height, mutation_size,
aspect_ratio=1.):
'''
Given the location and size of the box, return the path of
the box around it.
- *x0*, *y0*, *width*, *height* : location and size of the box
- *mutation_size* : a reference scale for the mutation.
- *aspect_ratio* : aspect-ratio for the mutation.
'''
path = ...
return path
Here is a complete example.
However, it is recommended that you derive from the matplotlib.patches.BoxStyle._Base as demonstrated
below.
214
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.43: Custom Boxstyle01
Fig. 3.44: Custom Boxstyle02
Similarly, you can define a custom ConnectionStyle and a custom ArrowStyle. See the source code of
lib/matplotlib/patches.py and check how each style class is defined.
Total running time of the script: ( 0 minutes 0.000 seconds)
3.5.4 Text rendering With LaTeX
Rendering text with LaTeX in Matplotlib.
Matplotlib has the option to use LaTeX to manage all text layout. This option is available with the following
backends:
• Agg
• PS
• PDF
The LaTeX option is activated by setting text.usetex : True in your rc settings. Text handling with
matplotlib’s LaTeX support is slower than matplotlib’s very capable mathtext, but is more flexible, since
different LaTeX packages (font packages, math packages, etc.) can be used. The results can be striking,
especially when you take care to use the same fonts in your figures as in the main document.
Matplotlib’s LaTeX support requires a working LaTeX installation, dvipng (which may be included with
your LaTeX installation), and Ghostscript (GPL Ghostscript 8.60 or later is recommended). The executables
for these external dependencies must all be located on your PATH.
There are a couple of options to mention, which can be changed using rc settings. Here is an example
matplotlibrc file:
3.5. Text
215
Matplotlib, Release 2.1.2
font.family
font.serif
,→Roman
font.sans-serif
font.cursive
font.monospace
: serif
: Times, Palatino, New Century Schoolbook, Bookman, Computer Modern␣
text.usetex
: true
: Helvetica, Avant Garde, Computer Modern Sans serif
: Zapf Chancery
: Courier, Computer Modern Typewriter
The first valid font in each family is the one that will be loaded. If the fonts are not specified, the Computer
Modern fonts are used by default. All of the other fonts are Adobe fonts. Times and Palatino each have their
own accompanying math fonts, while the other Adobe serif fonts make use of the Computer Modern math
fonts. See the PSNFSS documentation for more details.
To use LaTeX and select Helvetica as the default font, without editing matplotlibrc use:
from matplotlib import rc
rc('font',**{'family':'sans-serif','sans-serif':['Helvetica']})
## for Palatino and other serif fonts use:
#rc('font',**{'family':'serif','serif':['Palatino']})
rc('text', usetex=True)
Here is the standard example, tex_demo.py:
Fig. 3.45: TeX Demo
Note that display math mode ($$ e=mc^2 $$) is not supported, but adding the command \displaystyle,
as in tex_demo.py, will produce the same results.
Note: Certain characters require special escaping in TeX, such as:
# $ % & ~ _ ^ \ { } \( \) \[ \]
Therefore, these characters will behave differently depending on the rcParam text.usetex flag.
216
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
usetex with unicode
It is also possible to use unicode strings with the LaTeX text manager, here is an example taken from
tex_demo.py. The axis labels include Unicode text:
Fig. 3.46: TeX Unicode Demo
Postscript options
In order to produce encapsulated postscript files that can be embedded in a new LaTeX document, the default
behavior of matplotlib is to distill the output, which removes some postscript operators used by LaTeX that
are illegal in an eps file. This step produces results which may be unacceptable to some users, because
the text is coarsely rasterized and converted to bitmaps, which are not scalable like standard postscript,
and the text is not searchable. One workaround is to set ps.distiller.res to a higher value (perhaps
6000) in your rc settings, which will produce larger files but may look better and scale reasonably. A better
workaround, which requires Poppler or Xpdf, can be activated by changing the ps.usedistiller rc setting
to xpdf. This alternative produces postscript without rasterizing text, so it scales properly, can be edited in
Adobe Illustrator, and searched text in pdf documents.
Possible hangups
• On Windows, the PATH environment variable may need to be modified to include the directories
containing the latex, dvipng and ghostscript executables. See Environment Variables and Setting
environment variables in windows for details.
• Using MiKTeX with Computer Modern fonts, if you get odd *Agg and PNG results, go to MiKTeX/Options and update your format files
• On Ubuntu and Gentoo, the base texlive install does not ship with the type1cm package. You may
need to install some of the extra packages to get all the goodies that come bundled with other latex
distributions.
• Some progress has been made so matplotlib uses the dvi files directly for text layout. This allows
latex to be used for text layout with the pdf and svg backends, as well as the *Agg and PS backends.
In the future, a latex installation may be the only external dependency.
3.5. Text
217
Matplotlib, Release 2.1.2
Troubleshooting
• Try deleting your .matplotlib/tex.cache directory. If you don’t know where to find .
matplotlib, see matplotlib configuration and cache directory locations.
• Make sure LaTeX, dvipng and ghostscript are each working and on your PATH.
• Make sure what you are trying to do is possible in a LaTeX document, that your LaTeX syntax is valid
and that you are using raw strings if necessary to avoid unintended escape sequences.
• Most problems reported on the mailing list have been cleared up by upgrading Ghostscript. If possible,
please try upgrading to the latest release before reporting problems to the list.
• The text.latex.preamble rc setting is not officially supported. This option provides lots of flexibility, and lots of ways to cause problems. Please disable this option before reporting problems to the
mailing list.
• If you still need help, please see Getting help
Total running time of the script: ( 0 minutes 0.000 seconds)
3.5.5 Typesetting With XeLaTeX/LuaLaTeX
How to typeset text with the pgf backend in Matplotlib.
Using the pgf backend, matplotlib can export figures as pgf drawing commands that can be processed with
pdflatex, xelatex or lualatex. XeLaTeX and LuaLaTeX have full unicode support and can use any font that
is installed in the operating system, making use of advanced typographic features of OpenType, AAT and
Graphite. Pgf pictures created by plt.savefig('figure.pgf') can be embedded as raw commands in
LaTeX documents. Figures can also be directly compiled and saved to PDF with plt.savefig('figure.
pdf') by either switching to the backend
matplotlib.use('pgf')
or registering it for handling pdf output
from matplotlib.backends.backend_pgf import FigureCanvasPgf
matplotlib.backend_bases.register_backend('pdf', FigureCanvasPgf)
The second method allows you to keep using regular interactive backends and to save xelatex, lualatex or
pdflatex compiled PDF files from the graphical user interface.
Matplotlib’s pgf support requires a recent LaTeX installation that includes the TikZ/PGF packages (such as
TeXLive), preferably with XeLaTeX or LuaLaTeX installed. If either pdftocairo or ghostscript is present on
your system, figures can optionally be saved to PNG images as well. The executables for all applications
must be located on your PATH.
Rc parameters that control the behavior of the pgf backend:
218
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Parameter
Documentation
pgf.preamble
pgf.rcfonts
pgf.texsystem
Lines to be included in the LaTeX preamble
Setup fonts from rc params using the fontspec package
Either “xelatex” (default), “lualatex” or “pdflatex”
Note: TeX defines a set of special characters, such as:
# $ % & ~ _ ^ \ { }
Generally, these characters must be escaped correctly. For convenience, some characters (_,^,%) are automatically escaped outside of math environments.
Font specification
The fonts used for obtaining the size of text elements or when compiling figures to PDF are usually defined
in the matplotlib rc parameters. You can also use the LaTeX default Computer Modern fonts by clearing
the lists for font.serif, font.sans-serif or font.monospace. Please note that the glyph coverage of
these fonts is very limited. If you want to keep the Computer Modern font face but require extended unicode
support, consider installing the Computer Modern Unicode fonts CMU Serif, CMU Sans Serif, etc.
When saving to .pgf, the font configuration matplotlib used for the layout of the figure is included in the
header of the text file.
"""
=========
Pgf Fonts
=========
"""
# -*- coding: utf-8 -*import matplotlib as mpl
mpl.use("pgf")
pgf_with_rc_fonts = {
"font.family": "serif",
"font.serif": [],
"font.sans-serif": ["DejaVu Sans"],
}
mpl.rcParams.update(pgf_with_rc_fonts)
# use latex default serif font
# use a specific sans-serif font
import matplotlib.pyplot as plt
plt.figure(figsize=(4.5, 2.5))
plt.plot(range(5))
plt.text(0.5, 3., "serif")
plt.text(0.5, 2., "monospace", family="monospace")
plt.text(2.5, 2., "sans-serif", family="sans-serif")
plt.text(2.5, 1., "comic sans", family="Comic Sans MS")
plt.xlabel(u"µ is not $\\mu$")
3.5. Text
219
Matplotlib, Release 2.1.2
plt.tight_layout(.5)
Custom preamble
Full customization is possible by adding your own commands to the preamble. Use the pgf.preamble parameter if you want to configure the math fonts, using unicode-math for example, or for loading additional
packages. Also, if you want to do the font configuration yourself instead of using the fonts specified in the
rc parameters, make sure to disable pgf.rcfonts.
"""
============
Pgf Preamble
============
"""
# -*- coding: utf-8 -*from __future__ import (absolute_import, division, print_function,
unicode_literals)
import six
import matplotlib as mpl
mpl.use("pgf")
pgf_with_custom_preamble = {
"font.family": "serif", # use serif/main font for text elements
"text.usetex": True,
# use inline math for ticks
"pgf.rcfonts": False,
# don't setup fonts from rc parameters
"pgf.preamble": [
"\\usepackage{units}",
# load additional packages
"\\usepackage{metalogo}",
"\\usepackage{unicode-math}",
# unicode math setup
r"\setmathfont{xits-math.otf}",
r"\setmainfont{DejaVu Serif}", # serif font via preamble
]
}
mpl.rcParams.update(pgf_with_custom_preamble)
Choosing the TeX system
The TeX system to be used by matplotlib is chosen by the pgf.texsystem parameter. Possible values are
'xelatex' (default), 'lualatex' and 'pdflatex'. Please note that when selecting pdflatex the fonts and
unicode handling must be configured in the preamble.
"""
=============
Pgf Texsystem
=============
220
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
"""
# -*- coding: utf-8 -*import matplotlib as mpl
mpl.use("pgf")
pgf_with_pdflatex = {
"pgf.texsystem": "pdflatex",
"pgf.preamble": [
r"\usepackage[utf8x]{inputenc}",
r"\usepackage[T1]{fontenc}",
r"\usepackage{cmbright}",
]
}
mpl.rcParams.update(pgf_with_pdflatex)
import matplotlib.pyplot as plt
plt.figure(figsize=(4.5, 2.5))
plt.plot(range(5))
plt.text(0.5, 3., "serif", family="serif")
plt.text(0.5, 2., "monospace", family="monospace")
plt.text(2.5, 2., "sans-serif", family="sans-serif")
plt.xlabel(u"µ is not $\\mu$")
plt.tight_layout(.5)
Troubleshooting
• Please note that the TeX packages found in some Linux distributions and MiKTeX installations are
dramatically outdated. Make sure to update your package catalog and upgrade or install a recent TeX
distribution.
• On Windows, the PATH environment variable may need to be modified to include the directories
containing the latex, dvipng and ghostscript executables. See Environment Variables and Setting
environment variables in windows for details.
• A limitation on Windows causes the backend to keep file handles that have been opened by your application open. As a result, it may not be possible to delete the corresponding files until the application
closes (see #1324).
• Sometimes the font rendering in figures that are saved to png images is very bad. This happens when
the pdftocairo tool is not available and ghostscript is used for the pdf to png conversion.
• Make sure what you are trying to do is possible in a LaTeX document, that your LaTeX syntax is valid
and that you are using raw strings if necessary to avoid unintended escape sequences.
• The pgf.preamble rc setting provides lots of flexibility, and lots of ways to cause problems. When
experiencing problems, try to minimalize or disable the custom preamble.
• Configuring an unicode-math environment can be a bit tricky. The TeXLive distribution for example provides a set of math fonts which are usually not installed system-wide. XeTeX, unlike LuaLatex, cannot find these fonts by their name, which is why you might have to specify
3.5. Text
221
Matplotlib, Release 2.1.2
\setmathfont{xits-math.otf} instead of \setmathfont{XITS Math} or alternatively make
the fonts available to your OS. See this tex.stackexchange.com question for more details.
• If the font configuration used by matplotlib differs from the font setting in yout LaTeX document, the
alignment of text elements in imported figures may be off. Check the header of your .pgf file if you
are unsure about the fonts matplotlib used for the layout.
• Vector images and hence .pgf files can become bloated if there are a lot of objects in the graph. This
can be the case for image processing or very big scatter graphs. In an extreme case this can cause TeX
to run out of memory: “TeX capacity exceeded, sorry” You can configure latex to increase the amount
of memory available to generate the .pdf image as discussed on tex.stackexchange.com. Another
way would be to “rasterize” parts of the graph causing problems using either the rasterized=True
keyword, or .set_rasterized(True) as per this example.
• If you still need help, please see Getting help
Total running time of the script: ( 0 minutes 0.000 seconds)
3.5.6 Writing mathematical expressions
An introduction to writing mathematical expressions in Matplotlib.
You can use a subset TeX markup in any matplotlib text string by placing it inside a pair of dollar signs ($).
Note that you do not need to have TeX installed, since matplotlib ships its own TeX expression parser, layout
engine and fonts. The layout engine is a fairly direct adaptation of the layout algorithms in Donald Knuth’s
TeX, so the quality is quite good (matplotlib also provides a usetex option for those who do want to call
out to TeX to generate their text (see Text rendering With LaTeX).
Any text element can use math text. You should use raw strings (precede the quotes with an 'r'), and
surround the math text with dollar signs ($), as in TeX. Regular text and mathtext can be interleaved within
the same string. Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts (from
(La)TeX), STIX fonts (with are designed to blend well with Times), or a Unicode font that you provide.
The mathtext font can be selected with the customization variable mathtext.fontset (see Customizing
matplotlib)
Note: On “narrow” builds of Python, if you use the STIX fonts you should also set ps.fonttype and
pdf.fonttype to 3 (the default), not 42. Otherwise some characters will not be visible.
Here is a simple example:
# plain text
plt.title('alpha > beta')
produces “alpha > beta”.
Whereas this:
# math text
plt.title(r'$\alpha > \beta$')
222
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
produces “α > β”.
Note: Mathtext should be placed between a pair of dollar signs ($). To make it easy to display monetary
values, e.g., “$100.00”, if a single dollar sign is present in the entire string, it will be displayed verbatim as
a dollar sign. This is a small change from regular TeX, where the dollar sign in non-math text would have
to be escaped (‘\$’).
Note: While the syntax inside the pair of dollar signs ($) aims to be TeX-like, the text outside does not. In
particular, characters such as:
# $ % & ~ _ ^ \ { } \( \) \[ \]
have special meaning outside of math mode in TeX. Therefore, these characters will behave differently
depending on the rcParam text.usetex flag. See the usetex tutorial for more information.
Subscripts and superscripts
To make subscripts and superscripts, use the '_' and '^' symbols:
r'$\alpha_i > \beta_i$'
αi > βi
(3.1)
Some symbols automatically put their sub/superscripts under and over the operator. For example, to write
the sum of xi from 0 to ∞, you could do:
r'$\sum_{i=0}^\infty x_i$'
∞
∑︁
xi
(3.2)
i=0
Fractions, binomials and stacked numbers
Fractions, binomials and stacked numbers can be created with the \frac{}{}, \binom{}{} and
\stackrel{}{} commands, respectively:
r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$'
produces
(︃ )︃
3 3 3
4
4 4
(3.3)
Fractions can be arbitrarily nested:
r'$\frac{5 - \frac{1}{x}}{4}$'
3.5. Text
223
Matplotlib, Release 2.1.2
produces
5 − 1x
(3.4)
4
Note that special care needs to be taken to place parentheses and brackets around fractions. Doing things
the obvious way produces brackets that are too small:
r'$(\frac{5 - \frac{1}{x}}{4})$'
5 − 1x
(
)
(3.5)
4
The solution is to precede the bracket with \left and \right to inform the parser that those brackets
encompass the entire object.:
r'$\left(\frac{5 - \frac{1}{x}}{4}\right)$'
⎛
⎜⎜⎜ 5 −
⎜⎜⎝
4
1⎟
x⎟
⎟⎟
⎞
(3.6)
⎟⎠
Radicals
Radicals can be produced with the \sqrt[]{} command. For example:
r'$\sqrt{2}$'
√
2
(3.7)
Any base can (optionally) be provided inside square brackets. Note that the base must be a simple expression, and can not contain layout commands such as fractions or sub/superscripts:
r'$\sqrt[3]{x}$'
√3
(3.8)
x
Fonts
The default font is italics for mathematical symbols.
Note: This default can be changed using the mathtext.default rcParam. This is useful, for example, to
use the same font as regular non-math text for math text, by setting it to regular.
To change fonts, e.g., to write “sin” in a Roman font, enclose the text in a font command:
r'$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$'
s(t) = sin(2ωt)
(3.9)
More conveniently, many commonly used function names that are typeset in a Roman font have shortcuts.
So the expression above could be written as follows:
224
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
r'$s(t) = \mathcal{A}\sin(2 \omega t)$'
s(t) =  sin(2ωt)
(3.10)
Here “s” and “t” are variable in italics font (default), “sin” is in Roman font, and the amplitude “A” is in
calligraphy font. Note in the example above the caligraphy A is squished into the sin. You can use a spacing
command to add a little whitespace between them:
s(t) = \mathcal{A}\/\sin(2 \omega t)
s(t) =  sin(2ωt)
(3.11)
The choices available with all fonts are:
Command
Result
\mathrm{Roman}
\mathit{Italic}
\mathtt{Typewriter}
\mathcal{CALLIGRAPHY}
Roman
Italic
Typewriter
ℒℒℐℛℋ
When using the STIX fonts, you also have the choice of:
Command
Result
\mathbb{blackboard}
\mathrm{\mathbb{blackboard}}
\mathfrak{Fraktur}
\mathsf{sansserif}
\mathrm{\mathsf{sansserif}}
lakoar
lakoar
Fraktur
sansserif
sansserif
There are also three global “font sets” to choose from, which are selected using the mathtext.fontset
parameter in matplotlibrc.
cm: Computer Modern (TeX)
stix: STIX (designed to blend well with Times)
stixsans: STIX sans-serif
3.5. Text
225
Matplotlib, Release 2.1.2
Additionally, you can use \mathdefault{...} or its alias \mathregular{...} to use the font used for
regular text outside of mathtext. There are a number of limitations to this approach, most notably that far
fewer symbols will be available, but it can be useful to make math expressions blend well with other text in
the plot.
Custom fonts
mathtext also provides a way to use custom fonts for math. This method is fairly tricky to use, and should
be considered an experimental feature for patient users only. By setting the rcParam mathtext.fontset
to custom, you can then set the following parameters, which control which font file to use for a particular
set of math characters.
Parameter
Corresponds to
mathtext.it
mathtext.rm
mathtext.tt
mathtext.bf
mathtext.cal
mathtext.sf
\mathit{} or default italic
\mathrm{} Roman (upright)
\mathtt{} Typewriter (monospace)
\mathbf{} bold italic
\mathcal{} calligraphic
\mathsf{} sans-serif
Each parameter should be set to a fontconfig font descriptor (as defined in the yet-to-be-written font chapter).
The fonts used should have a Unicode mapping in order to find any non-Latin characters, such as Greek.
If you want to use a math symbol that is not contained in your custom fonts, you can set the rcParam
mathtext.fallback_to_cm to True which will cause the mathtext system to use characters from the
default Computer Modern fonts whenever a particular character can not be found in the custom font.
Note that the math glyphs specified in Unicode have evolved over time, and many fonts may not have glyphs
in the correct place for mathtext.
Accents
An accent command may precede any symbol to add an accent above it. There are long and short forms for
some of them.
226
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Command
Result
\acute a or \'a
\bar a
\breve a
\ddot a or \''a
\dot a or \.a
\grave a or \`a
\hat a or \^a
\tilde a or \~a
\vec a
\overline{abc}
á
ā
ă
ä
ȧ
à
â
ã
~a
abc
In addition, there are two special accents that automatically adjust to the width of the symbols below:
Command
Result
\widehat{xyz}
\widetilde{xyz}
̂︁
xyz
̃︁
xyz
Care should be taken when putting accents on lower-case i’s and j’s. Note that in the following \imath is
used to avoid the extra dot over the i:
r"$\hat i\ \ \hat \imath$"
î ı̂
(3.12)
Symbols
You can also use a large number of the TeX symbols, as in \infty, \leftarrow, \sum, \int.
Lower-case Greek
α \alpha
\epsilon
λ \lambda
π \pi
θ \theta
$ \varpi
ζ \zeta
β \beta
η \eta
µ \mu
ψ \psi
υ \upsilon
% \varrho
χ \chi
γ \gamma
ν \nu
ρ \rho
ε \varepsilon
ς \varsigma
δ \delta
ι \iota
ω \omega
σ \sigma
κ \varkappa
ϑ \vartheta
z \digamma
κ \kappa
φ \phi
τ \tau
ϕ \varphi
ξ \xi
Upper-case Greek
∆ \Delta
Ψ \Psi
∇ \nabla
3.5. Text
Γ \Gamma
Σ \Sigma
Λ \Lambda
Θ \Theta
Ω \Omega
Υ \Upsilon
Φ \Phi
Ξ \Xi
Π \Pi
f \mho
227
Matplotlib, Release 2.1.2
Hebrew
ℵ \aleph
i \beth
k \daleth
‫\ ג‬gimel
Delimiters
//
[[
↓
\downarrow
⟩ \rangle
⟨
\langle
⌉ \rceil
| \vert
{ \{
⇓
\Downarrow
⌈ \lceil
⇑ \Uparrow
‖ \Vert
⌊ \lfloor
⌋ \rfloor
p
\ulcorner
} \}
x
\llcorner
↑ \uparrow
‖ \|
∖
\backslash
y \lrcorner
q \urcorner
||
]]
Big symbols
⋂︀
\bigcap
⨄︀
∮︀ \biguplus
\oint
⋃︀
\bigcup
⋁︀
\bigvee
∏︀
\prod
⨀︀
\bigodot
⋀︀
\bigwedge
∑︀
\sum
⨁︀
\bigoplus
∐︀
\coprod
⨂︀
∫︀ \bigotimes
\int
Standard function names
Pr \Pr
arg \arg
coth \coth
dim \dim
inf \inf
lim inf \liminf
max \max
sinh \sinh
arccos \arccos
cos \cos
csc \csc
exp \exp
ker \ker
lim sup \limsup
min \min
sup \sup
arcsin \arcsin
cosh \cosh
deg \deg
gcd \gcd
lg \lg
ln \ln
sec \sec
tan \tan
arctan \arctan
cot \cot
det \det
hom \hom
lim \lim
log \log
sin \sin
tanh \tanh
Binary operation and relation symbols
228
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
m \Bumpeq
+ \Doteq
c \Supset
≈ \approx
≍ \asymp
w \backsimeq
G \between
△ \bigtriangleup
⊥ \bot
\boxminus
∙ \bullet
· \cdot
D \coloneq
2 \curlyeqprec
f \curlywedge
‡ \ddag
> \divideontimes
u \dotplus
E \eqcolon
0 \eqslantless
e \Cap
Z \Join
\Vdash
u \approxeq
 \backepsilon
Z \barwedge
○ \bigcirc
J \blacktriangleleft
./ \bowtie
\boxplus
l \bumpeq
∘ \circ
\cong
3 \curlyeqsucc
† \dag
◇ \diamond
\doteq
[ \doublebarwedge
h \eqsim
≡ \equiv
_ \frown
> \geqslant
\gnapprox
' \gtrapprox
T \gtreqqless
∈ \in
≤ \leq
/ \lessapprox
S \lesseqqgtr
≪ \ll
\lneqq
| \mid
3 \nVDash
\ncong
, \neq
≯ \ngtr
≮ \nless
∦ \nparallel
1 \nsubset
2 \nsupset
3.5. Text
≥ \geq
≫ \gg
\gneqq
m \gtrdot
≷ \gtrless
| \intercal
5 \leqq
l \lessdot
≶ \lessgtr
≪ \lll
\lnsim
|= \models
1 \nVdash
, \ne
. \nequiv
∋ \ni
- \nmid
⊀ \nprec
* \nsubseteq
+ \nsupseteq
d \Cup
b \Subset
\Vvdash
* \ast
v \backsim
∵ \because
▽ \bigtriangledown
I \blacktriangleright
\boxdot
\boxtimes
∩ \cap
$ \circeq
∪ \cup
g \curlyvee
⊣ \dashv
÷ \div
+ \doteqdot
P \eqcirc
1 \eqslantgtr
; \fallingdotseq
= \geqq
≫ \ggg
\gnsim
R \gtreqless
& \gtrsim
h \leftthreetimes
6 \leqslant
Q \lesseqgtr
. \lesssim
\lnapprox
n \ltimes
∓ \mp
0 \napprox
, \neq
\ngeq
\nleq
< \notin
/ \nsim
\nsucc
6 \ntriangleleft
229
Matplotlib, Release 2.1.2
5 \ntrianglelefteq
2 \nvDash
⊖ \ominus
⊗ \otimes
t \pitchfork
v \precapprox
\precnapprox
∝ \propto
o \rtimes
/ \slash
⊔ \sqcup
⊑ \sqsubseteq
⊒ \sqsupseteq
⊆ \subseteq
$ \subsetneqq
< \succcurlyeq
\succnsim
⊇ \supseteq
% \supsetneqq
⊤ \top
7 \ntriangleright
0 \nvdash
⊕ \oplus
‖ \parallel
± \pm
4 \preccurlyeq
\precnsim
i \rightthreetimes
∼ \sim
^ \smile
@ \sqsubset
A \sqsupset
? \star
j \subseteqq
≻ \succ
⪰ \succeq
% \succsim
k \supseteqq
∴ \therefore
/ \triangleleft
4 \ntrianglerighteq
⊙ \odot
⊘ \oslash
⊥ \perp
≺ \prec
⪯ \preceq
- \precsim
: \risingdotseq
≃ \simeq
⊓ \sqcap
@ \sqsubset
A \sqsupset
⊂ \subset
( \subsetneq
w \succapprox
\succnapprox
⊃ \supset
) \supsetneq
× \times
E \trianglelefteq
, \triangleq
⊎ \uplus
C \vartriangleleft
∨ \vee
≀ \wr
. \triangleright
\vDash
B \vartriangleright
Y \veebar
D \trianglerighteq
∝ \varpropto
⊢ \vdash
∧ \wedge
Arrow symbols
230
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
⇓ \Downarrow
⇔ \Leftrightarrow
⇐= \Longleftarrow
=⇒ \Longrightarrow
t \Nearrow
⇒ \Rightarrow
\Rsh
w \Swarrow
⇕ \Updownarrow
\circlearrowright
y \curvearrowright
d \dashrightarrow
\downdownarrows
\downharpoonright
,→ \hookrightarrow
← \leftarrow
) \leftharpoondown
⇔ \leftleftarrows
\leftrightarrows
! \leftrightsquigarrow
←− \longleftarrow
↦−→ \longmapsto
" \looparrowleft
↦→ \mapsto
: \nLeftarrow
; \nRightarrow
8 \nleftarrow
9 \nrightarrow
→ \rightarrow
+ \rightharpoondown
\rightleftarrows
\rightleftharpoons
⇒ \rightrightarrows
\rightsquigarrow
↘ \swarrow
\twoheadleftarrow
↑ \uparrow
↕ \updownarrow
\upharpoonright
⇐ \Leftarrow
W \Lleftarrow
⇐⇒ \Longleftrightarrow
\Lsh
v \Nwarrow
V \Rrightarrow
u \Searrow
⇑ \Uparrow
\circlearrowleft
x \curvearrowleft
c \dashleftarrow
↓ \downarrow
\downharpoonleft
←- \hookleftarrow
{ \leadsto
\leftarrowtail
( \leftharpoonup
↔ \leftrightarrow
\leftrightharpoons
f \leftsquigarrow
←→ \longleftrightarrow
−→ \longrightarrow
# \looparrowright
( \multimap
< \nLeftrightarrow
↗ \nearrow
= \nleftrightarrow
↖ \nwarrow
\rightarrowtail
* \rightharpoonup
\rightleftarrows
\rightleftharpoons
⇒ \rightrightarrows
↘ \searrow
→ \to
\twoheadrightarrow
↕ \updownarrow
\upharpoonleft
\upuparrows
Miscellaneous symbols
3.5. Text
231
Matplotlib, Release 2.1.2
$ \$
a \Game
ℜ \Re
8 \backprime
N \blacktriangle
X \checkmark
♣ \clubsuit
..
. \ddots
Å \AA
ℑ \Im
S \S
F \bigstar
H \blacktriangledown
r \circledR
{ \complement
` \Finv
¶ \P
∠ \angle
\blacksquare
· · · \cdots
s \circledS
© \copyright
∅ \emptyset
[ \flat
♡
! \heartsuit
\iint
∞ \infty
] \measuredangle
@ \nexists
′ \prime
^ \sphericalangle
♢ \diamondsuit
ð \eth
∀ \forall
}!\hslash
\iint
 \jmath
\)\natural
\oiiint
] \sharp
\ss
∅ \varnothing
℘ \wp
M \vartriangle
U \yen
` \ell
∃ \exists
~#\hbar
\iiint
ı \imath
. . . \ldots
¬ \neg
∂ \partial
♠ \spadesuit
O \triangledown
..
. \vdots
If a particular symbol does not have a name (as is true of many of the more obscure symbols in the STIX
fonts), Unicode characters can also be used:
ur'$\u23ce$'
Example
Here is an example illustrating many of these features in context.
Fig. 3.47: Pyplot Mathtext
232
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.000 seconds)
3.5.7 Text introduction
Introduction to plotting and working with text in Matplotlib.
Matplotlib has extensive text support, including support for mathematical expressions, truetype support for
raster and vector outputs, newline separated text with arbitrary rotations, and unicode support.
Because it embeds fonts directly in output documents, e.g., for postscript or PDF, what you see on the screen
is what you get in the hardcopy. FreeType support produces very nice, antialiased fonts, that look good even
at small raster sizes. matplotlib includes its own matplotlib.font_manager (thanks to Paul Barrett),
which implements a cross platform, W3C compliant font finding algorithm.
The user has a great deal of control over text properties (font size, font weight, text location and color,
etc.) with sensible defaults set in the rc file. And significantly, for those interested in mathematical or
scientific figures, matplotlib implements a large number of TeX math symbols and commands, supporting
mathematical expressions anywhere in your figure.
3.5.8 Basic text commands
The following commands are used to create text in the pyplot interface
• text() - add text at an arbitrary location to the Axes; matplotlib.axes.Axes.text() in the API.
• xlabel() - add a label to the x-axis; matplotlib.axes.Axes.set_xlabel() in the API.
• ylabel() - add a label to the y-axis; matplotlib.axes.Axes.set_ylabel() in the API.
• title() - add a title to the Axes; matplotlib.axes.Axes.set_title() in the API.
• figtext() - add text at an arbitrary location to the Figure; matplotlib.figure.Figure.text()
in the API.
• suptitle() - add a title to the Figure; matplotlib.figure.Figure.suptitle() in the API.
• annotate() - add an annotation, with optional arrow, to the Axes ; matplotlib.axes.Axes.
annotate() in the API.
All of these functions create and return a matplotlib.text.Text() instance, which can be configured
with a variety of font and other properties. The example below shows all of these commands in action.
3.5. Text
233
Matplotlib, Release 2.1.2
import matplotlib.pyplot as plt
fig = plt.figure()
fig.suptitle('bold figure suptitle', fontsize=14, fontweight='bold')
ax = fig.add_subplot(111)
fig.subplots_adjust(top=0.85)
ax.set_title('axes title')
ax.set_xlabel('xlabel')
ax.set_ylabel('ylabel')
ax.text(3, 8, 'boxed italics text in data coords', style='italic',
bbox={'facecolor': 'red', 'alpha': 0.5, 'pad': 10})
ax.text(2, 6, r'an equation: $E=mc^2$', fontsize=15)
ax.text(3, 2, u'unicode: Institut f\374r Festk\366rperphysik')
ax.text(0.95, 0.01, 'colored text in axes coords',
verticalalignment='bottom', horizontalalignment='right',
transform=ax.transAxes,
color='green', fontsize=15)
234
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ax.plot([2], [1], 'o')
ax.annotate('annotate', xy=(2, 1), xytext=(3, 4),
arrowprops=dict(facecolor='black', shrink=0.05))
ax.axis([0, 10, 0, 10])
plt.show()
Total running time of the script: ( 0 minutes 0.019 seconds)
3.5.9 Text properties and layout
Controlling properties of text and its layout with Matplotlib.
The matplotlib.text.Text instances have a variety of properties which can be configured via keyword
arguments to the text commands (e.g., title(), xlabel() and text()).
3.5. Text
235
Matplotlib, Release 2.1.2
Property
Value Type
alpha
backgroundcolor
bbox
clip_box
clip_on
clip_path
color
family
fontproperties
horizontalalignment or
ha
label
linespacing
multialignment
name or fontname
picker
position
rotation
size or fontsize
style or fontstyle
text
transform
variant
verticalalignment or va
visible
weight or fontweight
float
any matplotlib color
Rectangle prop dict plus key 'pad' which is a pad in points
a matplotlib.transform.Bbox instance
[True | False]
a Path instance and a Transform instance, a Patch
any matplotlib color
[ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
a FontProperties instance
[ 'center' | 'right' | 'left' ]
x
y
zorder
any string
float
['left' | 'right' | 'center' ]
string e.g., ['Sans' | 'Courier' | 'Helvetica' . . . ]
[None|float|boolean|callable]
(x, y)
[ angle in degrees | 'vertical' | 'horizontal' ]
[ size in points | relative size, e.g., 'smaller', 'x-large' ]
[ 'normal' | 'italic' | 'oblique' ]
string or anything printable with ‘%s’ conversion
a Transform instance
[ 'normal' | 'small-caps' ]
[ 'center' | 'top' | 'bottom' | 'baseline' ]
[True | False]
[ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' |
'ultralight']
float
float
any number
You can lay out text with the alignment arguments horizontalalignment, verticalalignment, and
multialignment. horizontalalignment controls whether the x positional argument for the text indicates the left, center or right side of the text bounding box. verticalalignment controls whether
the y positional argument for the text indicates the bottom, center or top side of the text bounding box.
multialignment, for newline separated strings only, controls whether the different lines are left, center or
right justified. Here is an example which uses the text() command to show the various alignment possibilities. The use of transform=ax.transAxes throughout the code indicates that the coordinates are given
relative to the axes bounding box, with 0,0 being the lower left of the axes and 1,1 the upper right.
import matplotlib.pyplot as plt
import matplotlib.patches as patches
# build a rectangle in axes coords
left, width = .25, .5
bottom, height = .25, .5
236
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
right = left + width
top = bottom + height
fig = plt.figure()
ax = fig.add_axes([0, 0, 1, 1])
# axes coordinates are 0,0 is bottom left and 1,1 is upper right
p = patches.Rectangle(
(left, bottom), width, height,
fill=False, transform=ax.transAxes, clip_on=False
)
ax.add_patch(p)
ax.text(left, bottom, 'left top',
horizontalalignment='left',
verticalalignment='top',
transform=ax.transAxes)
ax.text(left, bottom, 'left bottom',
horizontalalignment='left',
verticalalignment='bottom',
transform=ax.transAxes)
ax.text(right, top, 'right bottom',
horizontalalignment='right',
verticalalignment='bottom',
transform=ax.transAxes)
ax.text(right, top, 'right top',
horizontalalignment='right',
verticalalignment='top',
transform=ax.transAxes)
ax.text(right, bottom, 'center top',
horizontalalignment='center',
verticalalignment='top',
transform=ax.transAxes)
ax.text(left, 0.5*(bottom+top), 'right center',
horizontalalignment='right',
verticalalignment='center',
rotation='vertical',
transform=ax.transAxes)
ax.text(left, 0.5*(bottom+top), 'left center',
horizontalalignment='left',
verticalalignment='center',
rotation='vertical',
transform=ax.transAxes)
ax.text(0.5*(left+right), 0.5*(bottom+top), 'middle',
horizontalalignment='center',
3.5. Text
237
Matplotlib, Release 2.1.2
verticalalignment='center',
fontsize=20, color='red',
transform=ax.transAxes)
ax.text(right, 0.5*(bottom+top), 'centered',
horizontalalignment='center',
verticalalignment='center',
rotation='vertical',
transform=ax.transAxes)
ax.text(left, top, 'rotated\nwith newlines',
horizontalalignment='center',
verticalalignment='center',
rotation=45,
transform=ax.transAxes)
ax.set_axis_off()
plt.show()
238
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
3.5.10 Default Font
The base default font is controlled by a set of rcParams. To set the font for mathematical expressions, use
the rcParams beginning with mathtext (see mathtext).
rcParam
usage
'font.
family'
'font.
style'
'font.
variant'
'font.
stretch'
'font.
weight'
'font.
size'
List of either names of font or {'cursive', 'fantasy', 'monospace', 'sans',
'sans serif', 'sans-serif', 'serif'}.
The default style, ex 'normal', 'italic'.
Default variant, ex 'normal', 'small-caps' (untested)
Default stretch, ex 'normal', 'condensed' (incomplete)
Default weight. Either string or integer
Default font size in points. Relative font sizes ('large', 'x-small') are computed
against this size.
The mapping between the family aliases ({'cursive', 'fantasy', 'monospace', 'sans', 'sans
serif', 'sans-serif', 'serif'}) and actual font names is controlled by the following rcParams:
family alias
rcParam with mappings
'serif'
'monospace'
'fantasy'
'cursive'
{'sans', 'sans serif', 'sans-serif'}
'font.serif'
'font.monospace'
'font.fantasy'
'font.cursive'
'font.sans-serif'
which are lists of font names.
Text with non-latin glyphs
As of v2.0 the default font contains glyphs for many western alphabets, but still does not cover all of the
glyphs that may be required by mpl users. For example, DejaVu has no coverage of Chinese, Korean, or
Japanese.
To set the default font to be one that supports the code points you need, prepend the font name to 'font.
family' or the desired alias lists
matplotlib.rcParams['font.sans-serif'] = ['Source Han Sans TW', 'sans-serif']
or set it in your .matplotlibrc file:
font.sans-serif: Source Han Sans TW, Arial, sans-serif
3.5. Text
239
Matplotlib, Release 2.1.2
To control the font used on per-artist basis use the 'name', 'fontname' or 'fontproperties' kwargs
documented above.
On linux, fc-list can be a useful tool to discover the font name; for example
$ fc-list :lang=zh family
Noto to Sans Mono CJK TC,Noto Sans Mono CJK TC Bold
Noto Sans CJK TC,Noto Sans CJK TC Medium
Noto Sans CJK TC,Noto Sans CJK TC DemiLight
Noto Sans CJK KR,Noto Sans CJK KR Black
Noto Sans CJK TC,Noto Sans CJK TC Black
Noto Sans Mono CJK TC,Noto Sans Mono CJK TC Regular
Noto Sans CJK SC,Noto Sans CJK SC Light
lists all of the fonts that support Chinese.
Total running time of the script: ( 0 minutes 0.019 seconds)
3.6 Toolkits
These tutorials cover toolkits designed to extend the functionality of Matplotlib in order to accomplish
specific goals.
3.6.1 The mplot3d Toolkit
Generating 3D plots using the mplot3d toolkit.
Contents
• The mplot3d Toolkit
– Getting started
* Line plots
* Scatter plots
* Wireframe plots
* Surface plots
* Tri-Surface plots
* Contour plots
* Filled contour plots
* Polygon plots
* Bar plots
* Quiver
240
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
* 2D plots in 3D
* Text
* Subplotting
Getting started
An Axes3D object is created just like any other axes using the projection=‘3d’ keyword. Create a new
matplotlib.figure.Figure and add a new axes to it of type Axes3D:
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
New in version 1.0.0: This approach is the preferred method of creating a 3D axes.
Note: Prior to version 1.0.0, the method of creating a 3D axes was different. For those using older versions
of matplotlib, change ax = fig.add_subplot(111, projection='3d') to ax = Axes3D(fig).
See the mplot3d FAQ for more information about the mplot3d toolkit.
Line plots
Axes3D.plot(xs, ys, *args, **kwargs)
Plot 2D or 3D data.
Argument
Description
xs, ys
zs
zdir
x, y coordinates of vertices
z value(s), either one for all points or one for each point.
Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.
Other arguments are passed on to plot()
Scatter plots
Axes3D.scatter(xs, ys, zs=0, zdir=’z’, s=20, c=None, depthshade=True, *args, **kwargs)
Create a scatter plot.
3.6. Toolkits
241
Matplotlib, Release 2.1.2
Fig. 3.48: Lines3d
Ar- Description
gument
xs,
ys
zs
Positions of data points.
Either an array of the same length as xs and ys or a single value to place all points in the
same plane. Default is 0.
zdir Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.
s
Size in points^2. It is a scalar or an array of the same length as x and y.
c
A color. c can be a single color format string, or a sequence of color specifications of length
N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified
via kwargs (see below). Note that c should not be a single numeric RGB or RGBA sequence
because that is indistinguishable from an array of values to be colormapped. c can be a 2-D
array in which the rows are RGB or RGBA, however, including the case of a single row to
specify the same color for all points.
depthshade
Whether or not to shade the scatter markers to give the appearance of depth. Default is True.
Keyword arguments are passed on to scatter().
Returns a Patch3DCollection
Wireframe plots
Axes3D.plot_wireframe(X, Y, Z, *args, **kwargs)
Plot a 3D wireframe.
Note: The rcount and ccount kwargs, which both default to 50, determine the maximum number of
samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these
numbers of points.
242
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.49: Scatter3d
Parameters X, Y, Z : 2d arrays
Data values.
rcount, ccount : int
Maximum number of samples used in each direction. If the input data is
larger, it will be downsampled (by slicing) to these numbers of points. Setting a count to zero causes the data to be not sampled in the corresponding
direction, producing a 3D line plot rather than a wireframe plot. Defaults to
50.
New in version 2.0.
rstride, cstride : int
Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other
defaults to 1. Setting a stride to zero causes the data to be not sampled in
the corresponding direction, producing a 3D line plot rather than a wireframe
plot.
‘classic’ mode uses a default of rstride = cstride = 1 instead of the
new default of rcount = ccount = 50.
**kwargs :
Other arguments are forwarded to Line3DCollection.
Surface plots
Axes3D.plot_surface(X, Y, Z, *args, **kwargs)
Create a surface plot.
3.6. Toolkits
243
Matplotlib, Release 2.1.2
Fig. 3.50: Wire3d
By default it will be colored in shades of a solid color, but it also supports color mapping by supplying
the cmap argument.
Note: The rcount and ccount kwargs, which both default to 50, determine the maximum number of
samples used in each direction. If the input data is larger, it will be downsampled (by slicing) to these
numbers of points.
Parameters X, Y, Z : 2d arrays
Data values.
rcount, ccount : int
Maximum number of samples used in each direction. If the input data is
larger, it will be downsampled (by slicing) to these numbers of points. Defaults to 50.
New in version 2.0.
rstride, cstride : int
Downsampling stride in each direction. These arguments are mutually exclusive with rcount and ccount. If only one of rstride or cstride is set, the other
defaults to 10.
‘classic’ mode uses a default of rstride = cstride = 10 instead of the
new default of rcount = ccount = 50.
color : color-like
Color of the surface patches.
cmap : Colormap
Colormap of the surface patches.
244
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
facecolors : array-like of colors.
Colors of each individual patch.
norm : Normalize
Normalization for the colormap.
vmin, vmax : float
Bounds for the normalization.
shade : bool
Whether to shade the face colors.
**kwargs :
Other arguments are forwarded to Poly3DCollection.
Fig. 3.51: Surface3d
Surface3d 2
Surface3d 3
Tri-Surface plots
Axes3D.plot_trisurf(*args, **kwargs)
3.6. Toolkits
Argument
Description
X, Y, Z
color
cmap
norm
vmin
vmax
shade
Data values as 1D arrays
Color of the surface patches
A colormap for the surface patches.
An instance of Normalize to map values to colors
Minimum value to map
Maximum value to map
Whether to shade the facecolors
245
Matplotlib, Release 2.1.2
The (optional) triangulation can be specified in one of two ways; either:
plot_trisurf(triangulation, ...)
where triangulation is a Triangulation object, or:
plot_trisurf(X, Y, ...)
plot_trisurf(X, Y, triangles, ...)
plot_trisurf(X, Y, triangles=triangles, ...)
in which case a Triangulation object will be created. See Triangulation for a explanation of these
possibilities.
The remaining arguments are:
plot_trisurf(..., Z)
where Z is the array of values to contour, one per point in the triangulation.
Other arguments are passed on to Poly3DCollection
Examples:
0.4
0.2
0.0
0.2
0.4
1.000.75
0.500.25
0.000.25
0.500.75
1.00
1.00
0.75
0.50
0.25
0.00
0.25
0.50
0.75
1.00
New in version 1.2.0: This plotting function was added for the v1.2.0 release.
246
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
1.0
0.5
0.5
0.0
0.0
0.5
0.5
1.0
1.0 0.5
0.0 0.5
1.0
1.0
0.5
0.0
0.5
1.0
1.0
0.5
1.0
0.0
0.5
0.5
0.0
0.5
1.0 1.0
Fig. 3.52: Trisurf3d
3.6. Toolkits
247
Matplotlib, Release 2.1.2
Contour plots
Axes3D.contour(X, Y, Z, *args, **kwargs)
Create a 3D contour plot.
Argument
Description
X, Y,
Z
extend3d
stride
zdir
offset
Data values as numpy.arrays
Whether to extend contour in 3D (default: False)
Stride (step size) for extending contour
The direction to use: x, y or z (default)
If specified plot a projection of the contour lines on this position in plane normal to
zdir
The positional and other keyword arguments are passed on to contour()
Returns a contour
Fig. 3.53: Contour3d
Contour3d 2
Contour3d 3
Filled contour plots
Axes3D.contourf(X, Y, Z, *args, **kwargs)
Create a 3D contourf plot.
248
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Argument
Description
X, Y,
Z
zdir
offset
Data values as numpy.arrays
The direction to use: x, y or z (default)
If specified plot a projection of the filled contour on this position in plane normal to
zdir
The positional and keyword arguments are passed on to contourf()
Returns a contourf
Changed in version 1.1.0: The zdir and offset kwargs were added.
Fig. 3.54: Contourf3d
Contourf3d 2
New in version 1.1.0: The feature demoed in the second contourf3d example was enabled as a result of a
bugfix for version 1.1.0.
Polygon plots
Axes3D.add_collection3d(col, zs=0, zdir=’z’)
Add a 3D collection object to the plot.
2D collection types are converted to a 3D version by modifying the object and adding z coordinate
information.
Supported are:
• PolyCollection
• LineCollection
• PatchCollection
3.6. Toolkits
249
Matplotlib, Release 2.1.2
Fig. 3.55: Polys3d
Bar plots
Axes3D.bar(left, height, zs=0, zdir=’z’, *args, **kwargs)
Add 2D bar(s).
Argument
Description
left
height
zs
zdir
The x coordinates of the left sides of the bars.
The height of the bars.
Z coordinate of bars, if one value is specified they will all be placed at the same z.
Which direction to use as z (‘x’, ‘y’ or ‘z’) when plotting a 2D set.
Keyword arguments are passed onto bar().
Returns a Patch3DCollection
Fig. 3.56: Bars3d
250
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Quiver
Axes3D.quiver(*args, **kwargs)
Plot a 3D field of arrows.
call signatures:
quiver(X, Y, Z, U, V, W, **kwargs)
Arguments:
X, Y, Z: The x, y and z coordinates of the arrow locations (default is tail of arrow; see
pivot kwarg)
U, V, W: The x, y and z components of the arrow vectors
The arguments could be array-like or scalars, so long as they they can be broadcast together. The arguments can also be masked arrays. If an element in any of argument is masked, then that corresponding
quiver element will not be plotted.
Keyword arguments:
length: [1.0 | float] The length of each quiver, default to 1.0, the unit is the same with the
axes
arrow_length_ratio: [0.3 | float] The ratio of the arrow head with respect to the quiver,
default to 0.3
pivot: [ ‘tail’ | ‘middle’ | ‘tip’ ] The part of the arrow that is at the grid point; the arrow
rotates about this point, hence the name pivot. Default is ‘tail’
normalize: [False | True] When True, all of the arrows will be the same length. This
defaults to False, where the arrows will be different lengths depending on the values
of u,v,w.
Any additional keyword arguments are delegated to LineCollection
Fig. 3.57: Quiver3d
3.6. Toolkits
251
Matplotlib, Release 2.1.2
2D plots in 3D
Fig. 3.58: 2dcollections3d
Text
Axes3D.text(x, y, z, s, zdir=None, **kwargs)
Add text to the plot. kwargs will be passed on to Axes.text, except for the zdir keyword, which sets
the direction to be used as the z direction.
Fig. 3.59: Text3d
Subplotting
Having multiple 3D plots in a single figure is the same as it is for 2D plots. Also, you can have both 2D and
3D plots in the same figure.
New in version 1.0.0: Subplotting 3D plots was added in v1.0.0. Earlier version can not do this.
252
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.60: Subplot3d
Mixed Subplots
Total running time of the script: ( 0 minutes 0.000 seconds)
3.6.2 Overview of axisartist toolkit
The axisartist toolkit tutorial.
Warning: axisartist uses a custom Axes class (derived from the mpl’s original Axes class). As a side
effect, some commands (mostly tick-related) do not work.
The axisartist contains a custom Axes class that is meant to support curvilinear grids (e.g., the world coordinate system in astronomy). Unlike mpl’s original Axes class which uses Axes.xaxis and Axes.yaxis to
draw ticks, ticklines, etc., axisartist uses a special artist (AxisArtist) that can handle ticks, ticklines, etc. for
curved coordinate systems.
Since it uses special artists, some Matplotlib commands that work on Axes.xaxis and Axes.yaxis may not
work.
axisartist
The axisartist module provides a custom (and very experimental) Axes class, where each axis (left, right,
top, and bottom) have a separate associated artist which is responsible for drawing the axis-line, ticks,
ticklabels, and labels. You can also create your own axis, which can pass through a fixed position in the axes
coordinate, or a fixed position in the data coordinate (i.e., the axis floats around when viewlimit changes).
The axes class, by default, has its xaxis and yaxis invisible, and has 4 additional artists which are responsible
for drawing the 4 axis spines in “left”, “right”, “bottom”, and “top”. They are accessed as ax.axis[“left”],
ax.axis[“right”], and so on, i.e., ax.axis is a dictionary that contains artists (note that ax.axis is still a callable
method and it behaves as an original Axes.axis method in Matplotlib).
3.6. Toolkits
253
Matplotlib, Release 2.1.2
Fig. 3.61: Demo Floating Axis
To create an axes,
import mpl_toolkits.axisartist as AA
fig = plt.figure(1)
ax = AA.Axes(fig, [0.1, 0.1, 0.8, 0.8])
fig.add_axes(ax)
or to create a subplot
ax = AA.Subplot(fig, 111)
fig.add_subplot(ax)
For example, you can hide the right and top spines using:
ax.axis["right"].set_visible(False)
ax.axis["top"].set_visible(False)
Fig. 3.62: Simple Axisline3
It is also possible to add a horizontal axis. For example, you may have an horizontal axis at y=0 (in data
coordinate).
ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0)
254
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.63: Simple Axisartist1
Or a fixed axis with some offset
# make new (right-side) yaxis, but wth some offset
ax.axis["right2"] = ax.new_fixed_axis(loc="right",
offset=(20, 0))
axisartist with ParasiteAxes
Most commands in the axes_grid1 toolkit can take an axes_class keyword argument, and the commands
create an axes of the given class. For example, to create a host subplot with axisartist.Axes,
import mpl_toolkits.axisartist as AA
from mpl_toolkits.axes_grid1 import host_subplot
host = host_subplot(111, axes_class=AA.Axes)
Here is an example that uses parasiteAxes.
Curvilinear Grid
The motivation behind the AxisArtist module is to support a curvilinear grid and ticks.
Floating Axes
AxisArtist also supports a Floating Axes whose outer axes are defined as floating axis.
3.6. Toolkits
255
Matplotlib, Release 2.1.2
Fig. 3.64: Demo Parasite Axes2
Fig. 3.65: Demo Curvelinear Grid
Fig. 3.66: Demo Floating Axes
256
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
axisartist namespace
The axisartist namespace includes a derived Axes implementation. The biggest difference is that the artists
responsible to draw axis line, ticks, ticklabel and axis labels are separated out from the mpl’s Axis class,
which are much more than artists in the original mpl. This change was strongly motivated to support curvilinear grid. Here are a few things that mpl_tootlkits.axisartist.Axes is different from original Axes from
mpl.
• Axis elements (axis line(spine), ticks, ticklabel and axis labels) are drawn by a AxisArtist instance.
Unlike Axis, left, right, top and bottom axis are drawn by separate artists. And each of them may have
different tick location and different tick labels.
• gridlines are drawn by a Gridlines instance. The change was motivated that in curvilinear coordinate,
a gridline may not cross axis-lines (i.e., no associated ticks). In the original Axes class, gridlines are
tied to ticks.
• ticklines can be rotated if necessary (i.e, along the gridlines)
In summary, all these changes was to support
• a curvilinear grid.
• a floating axis
Fig. 3.67: Demo Floating Axis
mpl_toolkits.axisartist.Axes class defines a axis attribute, which is a dictionary of AxisArtist instances. By
default, the dictionary has 4 AxisArtist instances, responsible for drawing of left, right, bottom and top axis.
xaxis and yaxis attributes are still available, however they are set to not visible. As separate artists are used
for rendering axis, some axis-related method in mpl may have no effect. In addition to AxisArtist instances,
the mpl_toolkits.axisartist.Axes will have gridlines attribute (Gridlines), which obviously draws grid lines.
In both AxisArtist and Gridlines, the calculation of tick and grid location is delegated to an instance of
GridHelper class. mpl_toolkits.axisartist.Axes class uses GridHelperRectlinear as a grid helper. The GridHelperRectlinear class is a wrapper around the xaxis and yaxis of mpl’s original Axes, and it was meant to
work as the way how mpl’s original axes works. For example, tick location changes using set_ticks method
3.6. Toolkits
257
Matplotlib, Release 2.1.2
and etc. should work as expected. But change in artist properties (e.g., color) will not work in general,
although some effort has been made so that some often-change attributes (color, etc.) are respected.
AxisArtist
AxisArtist can be considered as a container artist with following attributes which will draw ticks, labels, etc.
• line
• major_ticks, major_ticklabels
• minor_ticks, minor_ticklabels
• offsetText
• label
line
Derived from Line2d class. Responsible for drawing a spinal(?) line.
major_ticks, minor_ticks
Derived from Line2d class. Note that ticks are markers.
major_ticklabels, minor_ticklabels
Derived from Text. Note that it is not a list of Text artist, but a single artist (similar to a collection).
axislabel
Derived from Text.
Default AxisArtists
By default, following for axis artists are defined.:
ax.axis["left"], ax.axis["bottom"], ax.axis["right"], ax.axis["top"]
The ticklabels and axislabel of the top and the right axis are set to not visible.
For example, if you want to change the color attributes of major_ticklabels of the bottom x-axis
ax.axis["bottom"].major_ticklabels.set_color("b")
Similarly, to make ticklabels invisible
258
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ax.axis["bottom"].major_ticklabels.set_visible(False)
AxisAritst provides a helper method to control the visibility of ticks, ticklabels, and label. To make ticklabel
invisible,
ax.axis["bottom"].toggle(ticklabels=False)
To make all of ticks, ticklabels, and (axis) label invisible
ax.axis["bottom"].toggle(all=False)
To turn all off but ticks on
ax.axis["bottom"].toggle(all=False, ticks=True)
To turn all on but (axis) label off
ax.axis["bottom"].toggle(all=True, label=False))
ax.axis’s __getitem__ method can take multiple axis names. For example, to turn ticklabels of “top” and
“right” axis on,
ax.axis["top","right"].toggle(ticklabels=True))
Note that ‘ax.axis[“top”,”right”]’ returns a simple proxy object that translate above code to something like
below.
for n in ["top","right"]:
ax.axis[n].toggle(ticklabels=True))
So, any return values in the for loop are ignored. And you should not use it anything more than a simple
method.
Like the list indexing “:” means all items, i.e.,
ax.axis[:].major_ticks.set_color("r")
changes tick color in all axis.
HowTo
1. Changing tick locations and label.
Same as the original mpl’s axes.:
ax.set_xticks([1,2,3])
2. Changing axis properties like color, etc.
Change the properties of appropriate artists. For example, to change the color of the ticklabels:
3.6. Toolkits
259
Matplotlib, Release 2.1.2
ax.axis["left"].major_ticklabels.set_color("r")
3. To change the attributes of multiple axis:
ax.axis["left","bottom"].major_ticklabels.set_color("r")
or to change the attributes of all axis:
ax.axis[:].major_ticklabels.set_color("r")
4. To change the tick size (length), you need to use axis.major_ticks.set_ticksize method. To change
the direction of the ticks (ticks are in opposite direction of ticklabels by default), use
axis.major_ticks.set_tick_out method.
To change the pad between ticks and ticklabels, use axis.major_ticklabels.set_pad method.
To change the pad between ticklabels and axis label, axis.label.set_pad method.
Rotation and Alignment of TickLabels
This is also quite different from the original mpl and can be confusing. When you want to rotate the
ticklabels, first consider using “set_axis_direction” method.
ax1.axis["left"].major_ticklabels.set_axis_direction("top")
ax1.axis["right"].label.set_axis_direction("left")
Fig. 3.68: Simple Axis Direction01
The parameter for set_axis_direction is one of [“left”, “right”, “bottom”, “top”].
You must understand some underlying concept of directions.
1. There is a reference direction which is defined as the direction of the axis line with increasing coordinate. For example, the reference direction of the left x-axis is from bottom
to top.
The direction, text angle, and alignments of the ticks, ticklabels and axis-label is
determined with respect to the reference direction
2. ticklabel_direction is either the right-hand side (+) of the reference direction or the lefthand side (-).
3. same for the label_direction
260
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.69: Axis Direction Demo - Step 01
Fig. 3.70: Axis Direction Demo - Step 02
Fig. 3.71: Axis Direction Demo - Step 03
3.6. Toolkits
261
Matplotlib, Release 2.1.2
4. ticks are by default drawn toward the opposite direction of the ticklabels.
5. text rotation of ticklabels and label is determined in reference to the ticklabel_direction or
label_direction, respectively. The rotation of ticklabels and label is anchored.
Fig. 3.72: Axis Direction Demo - Step 04
On the other hand, there is a concept of “axis_direction”. This is a default setting of above properties for
each, “bottom”, “left”, “top”, and “right” axis.
?
axislabel
axislabel
axislabel
axislabel
ticklabel
ticklabels
ticklabel
ticklabel
?
direction
rotation
va
ha
direction
rotation
ha
va
left
‘-‘
180
center
right
‘-‘
90
right
center
bottom
‘+’
0
top
center
‘+’
0
center
baseline
right
‘+’
0
center
right
‘+’
-90
right
center
top
‘-‘
180
bottom
center
‘-‘
180
center
baseline
And, ‘set_axis_direction(“top”)’ means to adjust the text rotation etc, for settings suitable for “top” axis.
The concept of axis direction can be more clear with curved axis.
Fig. 3.73: Demo Axis Direction
The axis_direction can be adjusted in the AxisArtist level, or in the level of its child arists, i.e., ticks,
ticklabels, and axis-label.
262
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ax1.axis["left"].set_axis_direction("top")
changes axis_direction of all the associated artist with the “left” axis, while
ax1.axis["left"].major_ticklabels.set_axis_direction("top")
changes the axis_direction of only the major_ticklabels. Note that set_axis_direction in the AxisArtist level
changes the ticklabel_direction and label_direction, while changing the axis_direction of ticks, ticklabels,
and axis-label does not affect them.
If you want to make ticks outward and ticklabels inside the axes, use invert_ticklabel_direction method.
ax.axis[:].invert_ticklabel_direction()
A related method is “set_tick_out”. It makes ticks outward (as a matter of fact, it makes ticks toward the
opposite direction of the default direction).
ax.axis[:].major_ticks.set_tick_out(True)
Fig. 3.74: Simple Axis Direction03
So, in summary,
• AxisArtist’s methods
– set_axis_direction : “left”, “right”, “bottom”, or “top”
– set_ticklabel_direction : “+” or “-“
– set_axislabel_direction : “+” or “-“
– invert_ticklabel_direction
• Ticks’ methods (major_ticks and minor_ticks)
– set_tick_out : True or False
– set_ticksize : size in points
• TickLabels’ methods (major_ticklabels and minor_ticklabels)
– set_axis_direction : “left”, “right”, “bottom”, or “top”
– set_rotation : angle with respect to the reference direction
– set_ha and set_va : see below
• AxisLabels’ methods (label)
3.6. Toolkits
263
Matplotlib, Release 2.1.2
– set_axis_direction : “left”, “right”, “bottom”, or “top”
– set_rotation : angle with respect to the reference direction
– set_ha and set_va
Adjusting ticklabels alignment
Alignment of TickLabels are treated specially. See below
Fig. 3.75: Demo Ticklabel Alignment
Adjusting pad
To change the pad between ticks and ticklabels
ax.axis["left"].major_ticklabels.set_pad(10)
Or ticklabels and axis-label
ax.axis["left"].label.set_pad(10)
Fig. 3.76: Simple Axis Pad
264
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
GridHelper
To actually define a curvilinear coordinate, you have to use your own grid helper. A generalised version
of grid helper class is supplied and this class should suffice in most of cases. A user may provide two
functions which defines a transformation (and its inverse pair) from the curved coordinate to (rectilinear)
image coordinate. Note that while ticks and grids are drawn for curved coordinate, the data transform of the
axes itself (ax.transData) is still rectilinear (image) coordinate.
from mpl_toolkits.axisartist.grid_helper_curvelinear
,→GridHelperCurveLinear
from mpl_toolkits.axisartist import Subplot
import␣
# from curved coordinate to rectlinear coordinate.
def tr(x, y):
x, y = np.asarray(x), np.asarray(y)
return x, y-x
# from rectlinear coordinate to curved coordinate.
def inv_tr(x,y):
x, y = np.asarray(x), np.asarray(y)
return x, y+x
grid_helper = GridHelperCurveLinear((tr, inv_tr))
ax1 = Subplot(fig, 1, 1, 1, grid_helper=grid_helper)
fig.add_subplot(ax1)
You may use matplotlib’s Transform instance instead (but a inverse transformation must be defined). Often,
coordinate range in a curved coordinate system may have a limited range, or may have cycles. In those
cases, a more customized version of grid helper is required.
import
mpl_toolkits.axisartist.angle_helper as angle_helper
# PolarAxes.PolarTransform takes radian. However, we want our coordinate
# system in degree
tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
# extreme finder : find a range of coordinate.
# 20, 20 : number of sampling points along x, y direction
# The first coordinate (longitude, but theta in polar)
#
has a cycle of 360 degree.
# The second coordinate (latitude, but radius in polar) has a minimum of 0
extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
lon_cycle = 360,
lat_cycle = None,
lon_minmax = None,
lat_minmax = (0, np.inf),
)
# Find a grid values appropriate for the coordinate (degree,
3.6. Toolkits
265
Matplotlib, Release 2.1.2
# minute, second). The argument is a approximate number of grids.
grid_locator1 = angle_helper.LocatorDMS(12)
# And also uses an appropriate formatter. Note that,the
# acceptable Locator and Formatter class is a bit different than
# that of mpl's, and you cannot directly use mpl's Locator and
# Formatter here (but may be possible in the future).
tick_formatter1 = angle_helper.FormatterDMS()
grid_helper = GridHelperCurveLinear(tr,
extreme_finder=extreme_finder,
grid_locator1=grid_locator1,
tick_formatter1=tick_formatter1
)
Again, the transData of the axes is still a rectilinear coordinate (image coordinate). You may manually do
conversion between two coordinates, or you may use Parasite Axes for convenience.:
ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)
# A parasite axes with given transform
ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
# note that ax2.transData == tr + ax1.transData
# Anthing you draw in ax2 will match the ticks and grids of ax1.
ax1.parasites.append(ax2)
Fig. 3.77: Demo Curvelinear Grid
FloatingAxis
A floating axis is an axis one of whose data coordinate is fixed, i.e, its location is not fixed in Axes coordinate
but changes as axes data limits changes. A floating axis can be created using new_floating_axis method.
However, it is your responsibility that the resulting AxisArtist is properly added to the axes. A recommended
way is to add it as an item of Axes’s axis attribute.:
# floating axis whose first (index starts from 0) coordinate
# (theta) is fixed at 60
266
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
axis.label.set_text(r"$
heta = 60^{\circ}$")
axis.label.set_visible(True)
See the first example of this page.
Current Limitations and TODO’s
The code need more refinement. Here is a incomplete list of issues and TODO’s
• No easy way to support a user customized tick location (for curvilinear grid). A new Locator class
needs to be created.
• FloatingAxis may have coordinate limits, e.g., a floating axis of x = 0, but y only spans from 0 to 1.
• The location of axislabel of FloatingAxis needs to be optionally given as a coordinate value. ex, a
floating axis of x=0 with label at y=1
Total running time of the script: ( 0 minutes 0.000 seconds)
3.6.3 Overview of axes_grid1 toolkit
Controlling the layout of plots with the axes_grid toolkit.
What is axes_grid1 toolkit?
axes_grid1 is a collection of helper classes to ease displaying (multiple) images with matplotlib. In matplotlib, the axes location (and size) is specified in the normalized figure coordinates, which may not be ideal
for displaying images that needs to have a given aspect ratio. For example, it helps if you have a colorbar
whose height always matches that of the image. ImageGrid, RGB Axes and AxesDivider are helper classes
that deals with adjusting the location of (multiple) Axes. They provides a framework to adjust the position
of multiple axes at the drawing time. ParasiteAxes provides twinx(or twiny)-like features so that you can
plot different data (e.g., different y-scale) in a same Axes. AnchoredArtists includes custom artists which are
placed at some anchored position, like the legend.
Fig. 3.78: Demo Axes Grid
3.6. Toolkits
267
Matplotlib, Release 2.1.2
axes_grid1
ImageGrid
A class that creates a grid of Axes. In matplotlib, the axes location (and size) is specified in the normalized
figure coordinates. This may not be ideal for images that needs to be displayed with a given aspect ratio. For
example, displaying images of a same size with some fixed padding between them cannot be easily done in
matplotlib. ImageGrid is used in such case.
Fig. 3.79: Simple Axesgrid
• The position of each axes is determined at the drawing time (see AxesDivider), so that the size of the
entire grid fits in the given rectangle (like the aspect of axes). Note that in this example, the paddings
between axes are fixed even if you changes the figure size.
• axes in the same column has a same axes width (in figure coordinate), and similarly, axes in the same
row has a same height. The widths (height) of the axes in the same row (column) are scaled according
to their view limits (xlim or ylim).
Fig. 3.80: Simple Axes Grid
• xaxis are shared among axes in a same column. Similarly, yaxis are shared among axes in a same row.
Therefore, changing axis properties (view limits, tick location, etc. either by plot commands or using
your mouse in interactive backends) of one axes will affect all other shared axes.
When initialized, ImageGrid creates given number (ngrids or ncols * nrows if ngrids is None) of Axes
instances. A sequence-like interface is provided to access the individual Axes instances (e.g., grid[0] is the
first Axes in the grid. See below for the order of axes).
268
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
ImageGrid takes following arguments,
Name
Default
Description
fig
rect
nrows_ncols
number of rows and cols. e.g., (2,2)
ngrids
None number of grids. nrows x ncols if None
direc“row” increasing direction of axes number. [row|column]
tion
axes_pad 0.02 pad between axes in inches
add_all True Add axes to figures if True
share_all False xaxis & yaxis of all axes are shared if True
aspect
True aspect of axes
la“L” location of tick labels thaw will be displayed. “1” (only the lower left
bel_mode
axes), “L” (left most and bottom most axes), or “all”.
cbar_modeNone [None|single|each]
cbar_location
“right” [right|top]
cbar_pad None pad between image axes and colorbar axes
cbar_size “5%” size of the colorbar
axes_class None
rect specifies the location of the grid. You can either specify coordinates of the rectangle to be
used (e.g., (0.1, 0.1, 0.8, 0.8) as in the Axes), or the subplot-like position (e.g., “121”).
direction means the increasing direction of the axes number.
aspect By default (False), widths and heights of axes in the grid are scaled independently. If
True, they are scaled according to their data limits (similar to aspect parameter in mpl).
share_all if True, xaxis and yaxis of all axes are shared.
direction direction of increasing axes number. For “row”,
grid[0]
grid[2]
grid[1]
grid[3]
grid[0]
grid[1]
grid[2]
grid[3]
For “column”,
You can also create a colorbar (or colorbars). You can have colorbar for each axes (cbar_mode=”each”), or
you can have a single colorbar for the grid (cbar_mode=”single”). The colorbar can be placed on your right,
or top. The axes for each colorbar is stored as a cbar_axes attribute.
The examples below show what you can do with ImageGrid.
3.6. Toolkits
269
Matplotlib, Release 2.1.2
Fig. 3.81: Demo Axes Grid
AxesDivider Class
Behind the scene, the ImageGrid class and the RGBAxes class utilize the AxesDivider class, whose role
is to calculate the location of the axes at drawing time. While a more about the AxesDivider is (will be)
explained in (yet to be written) AxesDividerGuide, direct use of the AxesDivider class will not be necessary
for most users. The axes_divider module provides a helper function make_axes_locatable, which can be
useful. It takes a existing axes instance and create a divider for it.
ax = subplot(1,1,1)
divider = make_axes_locatable(ax)
make_axes_locatable returns an instance of the AxesLocator class, derived from the Locator. It provides
append_axes method that creates a new axes on the given side of (“top”, “right”, “bottom” and “left”) of the
original axes.
colorbar whose height (or width) in sync with the master axes
Fig. 3.82: Simple Colorbar
scatter_hist.py with AxesDivider
The “scatter_hist.py” example in mpl can be rewritten using make_axes_locatable.
270
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
axScatter = subplot(111)
axScatter.scatter(x, y)
axScatter.set_aspect(1.)
# create new axes on the right and on the top of the current axes.
divider = make_axes_locatable(axScatter)
axHistx = divider.append_axes("top", size=1.2, pad=0.1, sharex=axScatter)
axHisty = divider.append_axes("right", size=1.2, pad=0.1, sharey=axScatter)
# the scatter plot:
# histograms
bins = np.arange(-lim, lim + binwidth, binwidth)
axHistx.hist(x, bins=bins)
axHisty.hist(y, bins=bins, orientation='horizontal')
See the full source code below.
Fig. 3.83: Scatter Hist
The scatter_hist using the AxesDivider has some advantage over the original scatter_hist.py in mpl. For
example, you can set the aspect ratio of the scatter plot, even with the x-axis or y-axis is shared accordingly.
ParasiteAxes
The ParasiteAxes is an axes whose location is identical to its host axes. The location is adjusted in the
drawing time, thus it works even if the host change its location (e.g., images).
In most cases, you first create a host axes, which provides a few method that can be used to create parasite
axes. They are twinx, twiny (which are similar to twinx and twiny in the matplotlib) and twin. twin takes
an arbitrary transformation that maps between the data coordinates of the host axes and the parasite axes.
draw method of the parasite axes are never called. Instead, host axes collects artists in parasite axes and
draw them as if they belong to the host axes, i.e., artists in parasite axes are merged to those of the host axes
and then drawn according to their zorder. The host and parasite axes modifies some of the axes behavior.
3.6. Toolkits
271
Matplotlib, Release 2.1.2
For example, color cycle for plot lines are shared between host and parasites. Also, the legend command in
host, creates a legend that includes lines in the parasite axes. To create a host axes, you may use host_suplot
or host_axes command.
Example 1. twinx
Fig. 3.84: Parasite Simple
Example 2. twin
twin without a transform argument assumes that the parasite axes has the same data transform as the host.
This can be useful when you want the top(or right)-axis to have different tick-locations, tick-labels, or tickformatter for bottom(or left)-axis.
ax2 = ax.twin() # now, ax2 is responsible for "top" axis and "right" axis
ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi])
ax2.set_xticklabels(["0", r"$ rac{1}{2}\pi$",
r"$\pi$", r"$ rac{3}{2}\pi$", r"$2\pi$"])
A more sophisticated example using twin. Note that if you change the x-limit in the host axes, the x-limit of
the parasite axes will change accordingly.
AnchoredArtists
It’s a collection of artists whose location is anchored to the (axes) bbox, like the legend. It is derived from
OffsetBox in mpl, and artist need to be drawn in the canvas coordinate. But, there is a limited support for
an arbitrary transform. For example, the ellipse in the example below will have width and height in the data
coordinate.
272
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.85: Simple Axisline4
Fig. 3.86: Parasite Simple2
Fig. 3.87: Simple Anchored Artists
3.6. Toolkits
273
Matplotlib, Release 2.1.2
InsetLocator
mpl_toolkits.axes_grid1.inset_locator provides helper classes and functions to place your (inset)
axes at the anchored position of the parent axes, similarly to AnchoredArtist.
Using mpl_toolkits.axes_grid1.inset_locator.inset_axes(), you can have inset axes whose
size is either fixed, or a fixed proportion of the parent axes. For example,:
inset_axes = inset_axes(parent_axes,
width="30%", # width = 30% of parent_bbox
height=1., # height : 1 inch
loc=3)
creates an inset axes whose width is 30% of the parent axes and whose height is fixed at 1 inch.
You may creates your inset whose size is determined so that the data scale of the inset axes to be that of the
parent axes multiplied by some factor. For example,
inset_axes = zoomed_inset_axes(ax,
0.5, # zoom = 0.5
loc=1)
creates an inset axes whose data scale is half of the parent axes. Here is complete examples.
Fig. 3.88: Inset Locator Demo
For example, zoomed_inset_axes() can be used when you want the inset represents the zoom-up of
the small portion in the parent axes. And mpl_toolkits/axes_grid/inset_locator provides a helper
function mark_inset() to mark the location of the area represented by the inset axes.
RGB Axes
RGBAxes is a helper class to conveniently show RGB composite images. Like ImageGrid, the location of
axes are adjusted so that the area occupied by them fits in a given rectangle. Also, the xaxis and yaxis of
each axes are shared.
from mpl_toolkits.axes_grid1.axes_rgb import RGBAxes
fig = plt.figure(1)
ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8])
274
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.89: Inset Locator Demo2
r, g, b = get_rgb() # r,g,b are 2-d images
ax.imshow_rgb(r, g, b,
origin="lower", interpolation="nearest")
Fig. 3.90: Simple Rgb
AxesDivider
The axes_divider module provides helper classes to adjust the axes positions of a set of images at drawing
time.
• axes_size provides a class of units that are used to determine the size of each axes. For example,
you can specify a fixed size.
• Divider is the class that calculates the axes position. It divides the given rectangular area into several
areas. The divider is initialized by setting the lists of horizontal and vertical sizes on which the division
will be based. Then use new_locator(), which returns a callable object that can be used to set the
axes_locator of the axes.
First, initialize the divider by specifying its grids, i.e., horizontal and vertical.
3.6. Toolkits
275
Matplotlib, Release 2.1.2
for example,:
rect = [0.2, 0.2, 0.6, 0.6]
horiz=[h0, h1, h2, h3]
vert=[v0, v1, v2]
divider = Divider(fig, rect, horiz, vert)
where, rect is a bounds of the box that will be divided and h0,..h3, v0,..v2 need to be an instance of classes
in the axes_size. They have get_size method that returns a tuple of two floats. The first float is the relative
size, and the second float is the absolute size. Consider a following grid.
v0
v1
h0,v2
h1
h2
h3
• v0 => 0, 2
• v1 => 2, 0
• v2 => 3, 0
The height of the bottom row is always 2 (axes_divider internally assumes that the unit is inches). The first
and the second rows have a height ratio of 2:3. For example, if the total height of the grid is 6, then the
first and second row will each occupy 2/(2+3) and 3/(2+3) of (6-1) inches. The widths of the horizontal
columns will be similarly determined. When the aspect ratio is set, the total height (or width) will be
adjusted accordingly.
The mpl_toolkits.axes_grid1.axes_size contains several classes that can be used to set the horizontal
and vertical configurations. For example, for vertical configuration one could use:
from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled
vert = [Fixed(2), Scaled(2), Scaled(3)]
After you set up the divider object, then you create a locator instance that will be given to the axes object.:
locator = divider.new_locator(nx=0, ny=1)
ax.set_axes_locator(locator)
The return value of the new_locator method is an instance of the AxesLocator class. It is a callable object
that returns the location and size of the cell at the first column and the second row. You may create a locator
that spans over multiple cells.:
locator = divider.new_locator(nx=0, nx=2, ny=1)
The above locator, when called, will return the position and size of the cells spanning the first and second
column and the first row. In this example, it will return [0:2, 1].
See the example,
You can adjust the size of each axes according to its x or y data limits (AxesX and AxesY).
Total running time of the script: ( 0 minutes 0.000 seconds)
276
Chapter 3. Tutorials
Matplotlib, Release 2.1.2
Fig. 3.91: Simple Axes Divider2
Fig. 3.92: Simple Axes Divider3
3.6. Toolkits
277
Matplotlib, Release 2.1.2
278
Chapter 3. Tutorials
CHAPTER
FOUR
INTERACTIVE PLOTS
4.1 Interactive navigation
All figure windows come with a navigation toolbar, which can be used to navigate through the data set. Here
is a description of each of the buttons at the bottom of the toolbar
The Home, Forward and Back buttons These are akin to a web browser’s home, forward and back controls. Forward and Back are used to navigate back and forth between previously defined views. They
have no meaning unless you have already navigated somewhere else using the pan and zoom buttons.
This is analogous to trying to click Back on your web browser before visiting a new page or Forward
before you have gone back to a page – nothing happens. Home always takes you to the first, default
view of your data. Again, all of these buttons should feel very familiar to any user of a web browser.
279
Matplotlib, Release 2.1.2
The Pan/Zoom button This button has two modes: pan and zoom. Click the toolbar button to activate
panning and zooming, then put your mouse somewhere over an axes. Press the left mouse button
and hold it to pan the figure, dragging it to a new position. When you release it, the data under the
point where you pressed will be moved to the point where you released. If you press ‘x’ or ‘y’ while
panning the motion will be constrained to the x or y axis, respectively. Press the right mouse button
to zoom, dragging it to a new position. The x axis will be zoomed in proportionately to the rightward
movement and zoomed out proportionately to the leftward movement. The same is true for the y axis
and up/down motions. The point under your mouse when you begin the zoom remains stationary,
allowing you to zoom in or out around that point as much as you wish. You can use the modifier
keys ‘x’, ‘y’ or ‘CONTROL’ to constrain the zoom to the x axis, the y axis, or aspect ratio preserve,
respectively.
With polar plots, the pan and zoom functionality behaves differently. The radius axis labels can be
dragged using the left mouse button. The radius scale can be zoomed in and out using the right mouse
button.
The Zoom-to-rectangle button Click this toolbar button to activate this mode. Put your mouse somewhere over an axes and press a mouse button. Define a rectangular region by dragging the mouse
while holding the button to a new location. When using the left mouse button, the axes view limits
will be zoomed to the defined region. When using the right mouse button, the axes view limits will be
zoomed out, placing the original axes in the defined region.
The Subplot-configuration button Use this tool to configure the appearance of the subplot: you can
stretch or compress the left, right, top, or bottom side of the subplot, or the space between the rows or
space between the columns.
280
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
The Save button Click this button to launch a file save dialog. You can save files with the following
extensions: png, ps, eps, svg and pdf.
4.1.1 Navigation Keyboard Shortcuts
The following table holds all the default keys, which can be overwritten by use of your matplotlibrc
(#keymap.*).
Command
Keyboard Shortcut(s)
Home/Reset
Back
Forward
Pan/Zoom
Zoom-to-rect
Save
Toggle fullscreen
Close plot
Close all plots
Constrain pan/zoom to x axis
Constrain pan/zoom to y axis
Preserve aspect ratio
Toggle major grids
Toggle minor grids
Toggle x axis scale (log/linear)
Toggle y axis scale (log/linear)
h or r or home
c or left arrow or backspace
v or right arrow
p
o
ctrl + s
f or ctrl + f
ctrl + w
shift + w
hold x when panning/zooming with mouse
hold y when panning/zooming with mouse
hold CONTROL when panning/zooming with mouse
g when mouse is over an axes
G when mouse is over an axes
L or k when mouse is over an axes
l when mouse is over an axes
If you are using matplotlib.pyplot the toolbar will be created automatically for every figure. If you are
writing your own user interface code, you can add the toolbar as a widget. The exact syntax depends on
your UI, but we have examples for every supported UI in the matplotlib/examples/user_interfaces
directory. Here is some example code for GTK:
import gtk
from matplotlib.figure import Figure
from matplotlib.backends.backend_gtkagg import FigureCanvasGTKAgg as FigureCanvas
from matplotlib.backends.backend_gtkagg import NavigationToolbar2GTKAgg as␣
,→NavigationToolbar
win = gtk.Window()
win.connect("destroy", lambda x: gtk.main_quit())
win.set_default_size(400,300)
win.set_title("Embedding in GTK")
vbox = gtk.VBox()
win.add(vbox)
fig = Figure(figsize=(5,4), dpi=100)
ax = fig.add_subplot(111)
4.1. Interactive navigation
281
Matplotlib, Release 2.1.2
ax.plot([1,2,3])
canvas = FigureCanvas(fig) # a gtk.DrawingArea
vbox.pack_start(canvas)
toolbar = NavigationToolbar(canvas, win)
vbox.pack_start(toolbar, False, False)
win.show_all()
gtk.main()
4.2 Using matplotlib in a python shell
Warning: This page is significantly out of date
By default, matplotlib defers drawing until the end of the script because drawing can be an expensive operation, and you may not want to update the plot every time a single property is changed, only once after all
the properties have changed.
But when working from the python shell, you usually do want to update the plot with every command, e.g.,
after changing the xlabel(), or the marker style of a line. While this is simple in concept, in practice it
can be tricky, because matplotlib is a graphical user interface application under the hood, and there are some
tricks to make the applications work right in a python shell.
4.2.1 IPython to the rescue
Note: The mode described here still exists for historical reasons, but it is highly advised not to use. It
pollutes namespaces with functions that will shadow python built-in and can lead to hard to track bugs.
To get IPython integration without imports the use of the %matplotlib magic is preferred. See ipython
documentation .
Fortunately, ipython, an enhanced interactive python shell, has figured out all of these tricks, and is matplotlib aware, so when you start ipython in the pylab mode.
johnh@flag:~> ipython
Python 2.4.5 (#4, Apr 12 2008, 09:09:16)
IPython 0.9.0 -- An enhanced Interactive Python.
In [1]: %pylab
Welcome to pylab, a matplotlib-based Python environment.
For more information, type 'help(pylab)'.
In [2]: x = randn(10000)
282
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
In [3]: hist(x, 100)
it sets everything up for you so interactive plotting works as you would expect it to. Call figure() and a
figure window pops up, call plot() and your data appears in the figure window.
Note in the example above that we did not import any matplotlib names because in pylab mode, ipython will
import them automatically. ipython also turns on interactive mode for you, which causes every pyplot command to trigger a figure update, and also provides a matplotlib aware run command to run matplotlib scripts
efficiently. ipython will turn off interactive mode during a run command, and then restore the interactive
state at the end of the run so you can continue tweaking the figure manually.
There has been a lot of recent work to embed ipython, with pylab support, into various GUI applications, so
check on the ipython mailing list for the latest status.
4.2.2 Other python interpreters
If you can’t use ipython, and still want to use matplotlib/pylab from an interactive python shell, e.g., the
plain-ole standard python interactive interpreter, you are going to need to understand what a matplotlib
backend is What is a backend?.
With the TkAgg backend, which uses the Tkinter user interface toolkit, you can use matplotlib from an
arbitrary non-gui python shell. Just set your backend : TkAgg and interactive : True in your
matplotlibrc file (see Customizing matplotlib) and fire up python. Then:
>>> from pylab import *
>>> plot([1,2,3])
>>> xlabel('hi mom')
should work out of the box. This is also likely to work with recent versions of the qt4agg and gtkagg
backends, and with the macosx backend on the Macintosh. Note, in batch mode, i.e. when making figures
from scripts, interactive mode can be slow since it redraws the figure with each command. So you may want
to think carefully before making this the default behavior via the matplotlibrc file instead of using the
functions listed in the next section.
Gui shells are at best problematic, because they have to run a mainloop, but interactive plotting also involves
a mainloop. Ipython has sorted all this out for the primary matplotlib backends. There may be other shells
and IDEs that also work with matplotlib in interactive mode, but one obvious candidate does not: the python
IDLE IDE is a Tkinter gui app that does not support pylab interactive mode, regardless of backend.
4.2.3 Controlling interactive updating
The interactive property of the pyplot interface controls whether a figure canvas is drawn on every pyplot
command. If interactive is False, then the figure state is updated on every plot command, but will only be
drawn on explicit calls to draw(). When interactive is True, then every pyplot command triggers a draw.
The pyplot interface provides 4 commands that are useful for interactive control.
isinteractive() returns the interactive setting True|False
4.2. Using matplotlib in a python shell
283
Matplotlib, Release 2.1.2
ion() turns interactive mode on
ioff() turns interactive mode off
draw() forces a figure redraw
When working with a big figure in which drawing is expensive, you may want to turn matplotlib’s interactive
setting off temporarily to avoid the performance hit:
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
#create big-expensive-figure
ioff()
# turn updates off
title('now how much would you pay?')
xticklabels(fontsize=20, color='green')
draw()
# force a draw
savefig('alldone', dpi=300)
close()
ion()
# turn updating back on
plot(rand(20), mfc='g', mec='r', ms=40, mew=4, ls='--', lw=3)
4.3 Event handling and picking
matplotlib works with a number of user interface toolkits (wxpython, tkinter, qt4, gtk, and macosx) and in
order to support features like interactive panning and zooming of figures, it is helpful to the developers to
have an API for interacting with the figure via key presses and mouse movements that is “GUI neutral”
so we don’t have to repeat a lot of code across the different user interfaces. Although the event handling
API is GUI neutral, it is based on the GTK model, which was the first user interface matplotlib supported.
The events that are triggered are also a bit richer vis-a-vis matplotlib than standard GUI events, including
information like which matplotlib.axes.Axes the event occurred in. The events also understand the
matplotlib coordinate system, and report event locations in both pixel and data coordinates.
4.3.1 Event connections
To receive events, you need to write a callback function and then connect your function to the event manager,
which is part of the FigureCanvasBase. Here is a simple example that prints the location of the mouse
click and which button was pressed:
fig, ax = plt.subplots()
ax.plot(np.random.rand(10))
def onclick(event):
print('%s click: button=%d, x=%d, y=%d, xdata=%f , ydata=%f ' %
('double' if event.dblclick else 'single', event.button,
event.x, event.y, event.xdata, event.ydata))
cid = fig.canvas.mpl_connect('button_press_event', onclick)
The FigureCanvas method mpl_connect() returns a connection id which is simply an integer. When you
want to disconnect the callback, just call:
284
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
fig.canvas.mpl_disconnect(cid)
Note: The canvas retains only weak references to the callbacks. Therefore if a callback is a method of
a class instance, you need to retain a reference to that instance. Otherwise the instance will be garbagecollected and the callback will vanish.
Here are the events that you can connect to, the class instances that are sent back to you when the event
occurs, and the event descriptions
Event name
Class and description
‘button_press_event’
‘button_release_event’
‘draw_event’
‘key_press_event’
‘key_release_event’
‘motion_notify_event’
‘pick_event’
‘resize_event’
‘scroll_event’
‘figure_enter_event’
‘figure_leave_event’
‘axes_enter_event’
‘axes_leave_event’
MouseEvent - mouse button is pressed
MouseEvent - mouse button is released
DrawEvent - canvas draw (but before screen update)
KeyEvent - key is pressed
KeyEvent - key is released
MouseEvent - mouse motion
PickEvent - an object in the canvas is selected
ResizeEvent - figure canvas is resized
MouseEvent - mouse scroll wheel is rolled
LocationEvent - mouse enters a new figure
LocationEvent - mouse leaves a figure
LocationEvent - mouse enters a new axes
LocationEvent - mouse leaves an axes
4.3.2 Event attributes
All matplotlib events inherit from the base class matplotlib.backend_bases.Event, which store the
attributes:
name the event name
canvas the FigureCanvas instance generating the event
guiEvent the GUI event that triggered the matplotlib event
The most common events that are the bread and butter of event handling are key press/release events and
mouse press/release and movement events. The KeyEvent and MouseEvent classes that handle these events
are both derived from the LocationEvent, which has the following attributes
x x position - pixels from left of canvas
y y position - pixels from bottom of canvas
inaxes the Axes instance if mouse is over axes
xdata x coord of mouse in data coords
ydata y coord of mouse in data coords
4.3. Event handling and picking
285
Matplotlib, Release 2.1.2
Let’s look a simple example of a canvas, where a simple line segment is created every time a mouse is
pressed:
from matplotlib import pyplot as plt
class LineBuilder:
def __init__(self, line):
self.line = line
self.xs = list(line.get_xdata())
self.ys = list(line.get_ydata())
self.cid = line.figure.canvas.mpl_connect('button_press_event', self)
def __call__(self, event):
print('click', event)
if event.inaxes!=self.line.axes: return
self.xs.append(event.xdata)
self.ys.append(event.ydata)
self.line.set_data(self.xs, self.ys)
self.line.figure.canvas.draw()
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click to build line segments')
line, = ax.plot([0], [0]) # empty line
linebuilder = LineBuilder(line)
plt.show()
The MouseEvent that we just used is a LocationEvent, so we have access to the data and pixel coordinates
in event.x and event.xdata. In addition to the LocationEvent attributes, it has
button button pressed None, 1, 2, 3, ‘up’, ‘down’ (up and down are used for scroll events)
key the key pressed: None, any character, ‘shift’, ‘win’, or ‘control’
Draggable rectangle exercise
Write draggable rectangle class that is initialized with a Rectangle instance but will move its x,y location
when dragged. Hint: you will need to store the original xy location of the rectangle which is stored as
rect.xy and connect to the press, motion and release mouse events. When the mouse is pressed, check to
see if the click occurs over your rectangle (see matplotlib.patches.Rectangle.contains()) and if it
does, store the rectangle xy and the location of the mouse click in data coords. In the motion event callback,
compute the deltax and deltay of the mouse movement, and add those deltas to the origin of the rectangle
you stored. The redraw the figure. On the button release event, just reset all the button press data you stored
as None.
Here is the solution:
import numpy as np
import matplotlib.pyplot as plt
class DraggableRectangle:
286
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
def __init__(self, rect):
self.rect = rect
self.press = None
def connect(self):
'connect to all the events we need'
self.cidpress = self.rect.figure.canvas.mpl_connect(
'button_press_event', self.on_press)
self.cidrelease = self.rect.figure.canvas.mpl_connect(
'button_release_event', self.on_release)
self.cidmotion = self.rect.figure.canvas.mpl_connect(
'motion_notify_event', self.on_motion)
def on_press(self, event):
'on button press we will see if the mouse is over us and store some data'
if event.inaxes != self.rect.axes: return
contains, attrd = self.rect.contains(event)
if not contains: return
print('event contains', self.rect.xy)
x0, y0 = self.rect.xy
self.press = x0, y0, event.xdata, event.ydata
def on_motion(self, event):
'on motion we will move the rect if the mouse is over us'
if self.press is None: return
if event.inaxes != self.rect.axes: return
x0, y0, xpress, ypress = self.press
dx = event.xdata - xpress
dy = event.ydata - ypress
#print('x0=%f, xpress=%f, event.xdata=%f, dx=%f, x0+dx=%f' %
#
(x0, xpress, event.xdata, dx, x0+dx))
self.rect.set_x(x0+dx)
self.rect.set_y(y0+dy)
self.rect.figure.canvas.draw()
def on_release(self, event):
'on release we reset the press data'
self.press = None
self.rect.figure.canvas.draw()
def disconnect(self):
'disconnect all the stored connection ids'
self.rect.figure.canvas.mpl_disconnect(self.cidpress)
self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
fig = plt.figure()
ax = fig.add_subplot(111)
rects = ax.bar(range(10), 20*np.random.rand(10))
drs = []
4.3. Event handling and picking
287
Matplotlib, Release 2.1.2
for rect in rects:
dr = DraggableRectangle(rect)
dr.connect()
drs.append(dr)
plt.show()
Extra credit: use the animation blit techniques discussed in the animations recipe to make the animated
drawing faster and smoother.
Extra credit solution:
# draggable rectangle with the animation blit techniques; see
# http://www.scipy.org/Cookbook/Matplotlib/Animations
import numpy as np
import matplotlib.pyplot as plt
class DraggableRectangle:
lock = None # only one can be animated at a time
def __init__(self, rect):
self.rect = rect
self.press = None
self.background = None
def connect(self):
'connect to all the events we need'
self.cidpress = self.rect.figure.canvas.mpl_connect(
'button_press_event', self.on_press)
self.cidrelease = self.rect.figure.canvas.mpl_connect(
'button_release_event', self.on_release)
self.cidmotion = self.rect.figure.canvas.mpl_connect(
'motion_notify_event', self.on_motion)
def on_press(self, event):
'on button press we will see if the mouse is over us and store some data'
if event.inaxes != self.rect.axes: return
if DraggableRectangle.lock is not None: return
contains, attrd = self.rect.contains(event)
if not contains: return
print('event contains', self.rect.xy)
x0, y0 = self.rect.xy
self.press = x0, y0, event.xdata, event.ydata
DraggableRectangle.lock = self
# draw everything but the selected rectangle and store the pixel buffer
canvas = self.rect.figure.canvas
axes = self.rect.axes
self.rect.set_animated(True)
canvas.draw()
self.background = canvas.copy_from_bbox(self.rect.axes.bbox)
# now redraw just the rectangle
axes.draw_artist(self.rect)
288
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
# and blit just the redrawn area
canvas.blit(axes.bbox)
def on_motion(self, event):
'on motion we will move the rect if the mouse is over us'
if DraggableRectangle.lock is not self:
return
if event.inaxes != self.rect.axes: return
x0, y0, xpress, ypress = self.press
dx = event.xdata - xpress
dy = event.ydata - ypress
self.rect.set_x(x0+dx)
self.rect.set_y(y0+dy)
canvas = self.rect.figure.canvas
axes = self.rect.axes
# restore the background region
canvas.restore_region(self.background)
# redraw just the current rectangle
axes.draw_artist(self.rect)
# blit just the redrawn area
canvas.blit(axes.bbox)
def on_release(self, event):
'on release we reset the press data'
if DraggableRectangle.lock is not self:
return
self.press = None
DraggableRectangle.lock = None
# turn off the rect animation property and reset the background
self.rect.set_animated(False)
self.background = None
# redraw the full figure
self.rect.figure.canvas.draw()
def disconnect(self):
'disconnect all the stored connection ids'
self.rect.figure.canvas.mpl_disconnect(self.cidpress)
self.rect.figure.canvas.mpl_disconnect(self.cidrelease)
self.rect.figure.canvas.mpl_disconnect(self.cidmotion)
fig = plt.figure()
ax = fig.add_subplot(111)
rects = ax.bar(range(10), 20*np.random.rand(10))
drs = []
for rect in rects:
dr = DraggableRectangle(rect)
4.3. Event handling and picking
289
Matplotlib, Release 2.1.2
dr.connect()
drs.append(dr)
plt.show()
4.3.3 Mouse enter and leave
If you want to be notified when the mouse enters or leaves a figure or axes, you can connect to the figure/axes
enter/leave events. Here is a simple example that changes the colors of the axes and figure background that
the mouse is over:
"""
Illustrate the figure and axes enter and leave events by changing the
frame colors on enter and leave
"""
import matplotlib.pyplot as plt
def enter_axes(event):
print('enter_axes', event.inaxes)
event.inaxes.patch.set_facecolor('yellow')
event.canvas.draw()
def leave_axes(event):
print('leave_axes', event.inaxes)
event.inaxes.patch.set_facecolor('white')
event.canvas.draw()
def enter_figure(event):
print('enter_figure', event.canvas.figure)
event.canvas.figure.patch.set_facecolor('red')
event.canvas.draw()
def leave_figure(event):
print('leave_figure', event.canvas.figure)
event.canvas.figure.patch.set_facecolor('grey')
event.canvas.draw()
fig1 = plt.figure()
fig1.suptitle('mouse hover over figure or axes to trigger events')
ax1 = fig1.add_subplot(211)
ax2 = fig1.add_subplot(212)
fig1.canvas.mpl_connect('figure_enter_event', enter_figure)
fig1.canvas.mpl_connect('figure_leave_event', leave_figure)
fig1.canvas.mpl_connect('axes_enter_event', enter_axes)
fig1.canvas.mpl_connect('axes_leave_event', leave_axes)
fig2 = plt.figure()
fig2.suptitle('mouse hover over figure or axes to trigger events')
ax1 = fig2.add_subplot(211)
ax2 = fig2.add_subplot(212)
290
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
fig2.canvas.mpl_connect('figure_enter_event', enter_figure)
fig2.canvas.mpl_connect('figure_leave_event', leave_figure)
fig2.canvas.mpl_connect('axes_enter_event', enter_axes)
fig2.canvas.mpl_connect('axes_leave_event', leave_axes)
plt.show()
4.3.4 Object picking
You can enable picking by setting the picker property of an Artist (e.g., a matplotlib Line2D, Text,
Patch , Polygon, AxesImage, etc. . . )
There are a variety of meanings of the picker property:
None picking is disabled for this artist (default)
boolean if True then picking will be enabled and the artist will fire a pick event if the mouse
event is over the artist
float if picker is a number it is interpreted as an epsilon tolerance in points and the artist
will fire off an event if its data is within epsilon of the mouse event. For some artists like
lines and patch collections, the artist may provide additional data to the pick event that is
generated, e.g., the indices of the data within epsilon of the pick event.
function if picker is callable, it is a user supplied function which determines whether the
artist is hit by the mouse event. The signature is hit, props = picker(artist,
mouseevent) to determine the hit test. If the mouse event is over the artist, return
hit=True and props is a dictionary of properties you want added to the PickEvent attributes
After you have enabled an artist for picking by setting the picker property, you need to connect to the figure
canvas pick_event to get pick callbacks on mouse press events. e.g.:
def pick_handler(event):
mouseevent = event.mouseevent
artist = event.artist
# now do something with this...
The PickEvent which is passed to your callback is always fired with two attributes:
mouseevent the mouse event that generate the pick event. The mouse event in turn has attributes like x and y (the coords in display space, e.g., pixels from left, bottom) and xdata,
ydata (the coords in data space). Additionally, you can get information about which buttons were pressed, which keys were pressed, which Axes the mouse is over, etc. See
matplotlib.backend_bases.MouseEvent for details.
artist the Artist that generated the pick event.
Additionally, certain artists like Line2D and PatchCollection may attach additional meta data like the
indices into the data that meet the picker criteria (e.g., all the points in the line that are within the specified
epsilon tolerance)
4.3. Event handling and picking
291
Matplotlib, Release 2.1.2
Simple picking example
In the example below, we set the line picker property to a scalar, so it represents a tolerance in points (72
points per inch). The onpick callback function will be called when the pick event it within the tolerance
distance from the line, and has the indices of the data vertices that are within the pick distance tolerance.
Our onpick callback function simply prints the data that are under the pick location. Different matplotlib
Artists can attach different data to the PickEvent. For example, Line2D attaches the ind property, which are
the indices into the line data under the pick point. See pick() for details on the PickEvent properties of
the line. Here is the code:
import numpy as np
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click on points')
line, = ax.plot(np.random.rand(100), 'o', picker=5)
# 5 points tolerance
def onpick(event):
thisline = event.artist
xdata = thisline.get_xdata()
ydata = thisline.get_ydata()
ind = event.ind
points = tuple(zip(xdata[ind], ydata[ind]))
print('onpick points:', points)
fig.canvas.mpl_connect('pick_event', onpick)
plt.show()
Picking exercise
Create a data set of 100 arrays of 1000 Gaussian random numbers and compute the sample mean and
standard deviation of each of them (hint: numpy arrays have a mean and std method) and make a xy marker
plot of the 100 means vs the 100 standard deviations. Connect the line created by the plot command to the
pick event, and plot the original time series of the data that generated the clicked on points. If more than one
point is within the tolerance of the clicked on point, you can use multiple subplots to plot the multiple time
series.
Exercise solution:
"""
compute the mean and stddev of 100 data sets and plot mean vs stddev.
When you click on one of the mu, sigma points, plot the raw data from
the dataset that generated the mean and stddev
"""
import numpy as np
import matplotlib.pyplot as plt
X = np.random.rand(100, 1000)
292
Chapter 4. Interactive plots
Matplotlib, Release 2.1.2
xs = np.mean(X, axis=1)
ys = np.std(X, axis=1)
fig = plt.figure()
ax = fig.add_subplot(111)
ax.set_title('click on point to plot time series')
line, = ax.plot(xs, ys, 'o', picker=5) # 5 points tolerance
def onpick(event):
if event.artist!=line: return True
N = len(event.ind)
if not N: return True
figi = plt.figure()
for subplotnum, dataind in enumerate(event.ind):
ax = figi.add_subplot(N,1,subplotnum+1)
ax.plot(X[dataind])
ax.text(0.05, 0.9, 'mu=%1.3f \nsigma=%1.3f '%(xs[dataind], ys[dataind]),
transform=ax.transAxes, va='top')
ax.set_ylim(-0.5, 1.5)
figi.show()
return True
fig.canvas.mpl_connect('pick_event', onpick)
plt.show()
4.3. Event handling and picking
293
Matplotlib, Release 2.1.2
294
Chapter 4. Interactive plots
CHAPTER
FIVE
WHAT’S NEW IN MATPLOTLIB
For a list of all of the issues and pull requests since the last revision, see the GitHub Stats.
Table of Contents
• What’s new in Matplotlib
– New in Matplotlib 2.1
* Documentation
* New features
· String categorical values
· Interactive JS widgets for animation
· Enhancements to polar plot
· Figure class now has subplots method
· Metadata savefig keyword argument
· Busy Cursor
· PolygonSelector
· Added matplotlib.ticker.PercentFormatter
· Reproducible PS, PDF and SVG output
· Orthographic projection for mplot3d
· voxels function for mplot3d
* Improvements
· CheckButtons widget get_status function
· Add fill_bar argument to AnchoredSizeBar
· Annotation can use a default arrow style
· Barbs and Quiver Support Dates
· Hexbin default line color
295
Matplotlib, Release 2.1.2
· Figure.legend() can be called without arguments
· Multiple legend keys for legend entries
· New parameter clear for figure()
· Specify minimum value to format as scalar for LogFormatterMathtext
· New quiverkey angle keyword argument
· Colormap reversed method
· Artist.setp (and pyplot.setp) accept a file argument
· streamplot streamline generation more configurable
· Axis.set_tick_params now responds to rotation
· Shading in 3D bar plots
· New which Parameter for autofmt_xdate
· New Figure Parameter for subplot2grid
· Interpolation in fill_betweenx
· New keyword argument sep for EngFormatter
· Extend MATPLOTLIBRC behavior
· density kwarg to hist
* Internals
· New TransformedPatchPath caching object
· Abstract base class for movie writers
· Stricter validation of line style rcParams
· pytest
* Performance
· Path simplification updates
· Implement intersects_bbox in c++
– Previous Whats New
5.1 New in Matplotlib 2.1
5.1.1 Documentation
The examples have been migrated to use sphinx gallery. This allows better mixing of prose and code in
the examples, provides links to download the examples as both a Python script and a Jupyter notebook, and
improves the thumbnail galleries. The examples have been re-organized into Tutorials and a gallery.
296
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Many docstrings and examples have been clarified and improved.
5.1.2 New features
String categorical values
All plotting functions now support string categorical values as input. For example:
data = {'apples': 10, 'oranges': 15, 'lemons': 5, 'limes': 20}
fig, ax = plt.subplots()
ax.bar(data.keys(), data.values(), color='lightgray')
20.0
17.5
15.0
12.5
10.0
7.5
5.0
2.5
0.0
apples
lemons
limes
oranges
Interactive JS widgets for animation
Jake Vanderplas’ JSAnimation package has been merged into Matplotlib. This adds to Matplotlib the
HTMLWriter class for generating a JavaScript HTML animation, suitable for the IPython notebook. This
can be activated by default by setting the animation.html rc parameter to jshtml. One can also call the
to_jshtml method to manually convert an animation. This can be displayed using IPython’s HTML display
class:
5.1. New in Matplotlib 2.1
297
Matplotlib, Release 2.1.2
from IPython.display import HTML
HTML(animation.to_jshtml())
The HTMLWriter class can also be used to generate an HTML file by asking for the html writer.
Enhancements to polar plot
The polar axes transforms have been greatly re-factored to allow for more customization of view limits and
tick labelling. Additional options for view limits allow for creating an annulus, a sector, or some combination
of the two.
The set_rorigin() method may be used to provide an offset to the minimum plotting radius, producing
an annulus.
The set_theta_zero_location() method now has an optional offset argument. This argument may
be used to further specify the zero location based on the given anchor point.
Fig. 5.1: Polar Offset Demo
The set_thetamin() and set_thetamax() methods may be used to limit the range of angles plotted,
producing sectors of a circle.
Previous releases allowed plots containing negative radii for which the negative values are simply used as
labels, and the real radius is shifted by the configured minimum. This release also allows negative radii to
be used for grids and ticks, which were previously silently ignored.
Radial ticks have been modified to be parallel to the circular grid line, and angular ticks have been modified
to be parallel to the grid line. It may also be useful to rotate tick labels to match the boundary. Calling
ax.tick_params(rotation='auto') will enable the new behavior: radial tick labels will be parallel
to the circular grid line, and angular tick labels will be perpendicular to the grid line (i.e., parallel to the
298
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fig. 5.2: Polar Sector Demo
outer boundary). Additionally, tick labels now obey the padding settings that previously only worked on
Cartesian plots. Consequently, the frac argument to PolarAxes.set_thetagrids is no longer applied.
Tick padding can be modified with the pad argument to Axes.tick_params or Axis.set_tick_params.
Figure class now has subplots method
The Figure class now has a subplots() method which behaves the same as pyplot.subplots() but on
an existing figure.
Metadata savefig keyword argument
savefig() now accepts metadata as a keyword argument. It can be used to store key/value pairs in the
image metadata.
• ‘png’ with Agg backend
• ‘pdf’ with PDF backend (see writeInfoDict() for a list of supported keywords)
• ‘eps’ and ‘ps’ with PS backend (only ‘Creator’ key is accepted)
plt.savefig('test.png', metadata={'Software': 'My awesome software'})
Busy Cursor
The interactive GUI backends will now change the cursor to busy when Matplotlib is rendering the canvas.
5.1. New in Matplotlib 2.1
299
Matplotlib, Release 2.1.2
PolygonSelector
A
PolygonSelector
class
has
been
added
to
sphx_glr_gallery_widgets_polygon_selector_demo.py for details.
matplotlib.widgets.
See
Added matplotlib.ticker.PercentFormatter
The new PercentFormatter formatter has some nice features like being able to convert from arbitrary data
scales to percents, a customizable percent symbol and either automatic or manual control over the decimal
points.
Reproducible PS, PDF and SVG output
The SOURCE_DATE_EPOCH environment variable can now be used to set the timestamp value in the PS and
PDF outputs. See source date epoch.
Alternatively, calling savefig with metadata={'creationDate':
together for the PDF backend.
None} will omit the timestamp al-
The reproducibility of the output from the PS and PDF backends has so far been tested using various plot
elements but only default values of options such as {ps,pdf}.fonttype that can affect the output at a
low level, and not with the mathtext or usetex features. When Matplotlib calls external tools (such as PS
distillers or LaTeX) their versions need to be kept constant for reproducibility, and they may add sources of
nondeterminism outside the control of Matplotlib.
For SVG output, the svg.hashsalt rc parameter has been added in an earlier release. This parameter
changes some random identifiers in the SVG file to be deterministic. The downside of this setting is that
if more than one file is generated using deterministic identifiers and they end up as parts of one larger
document, the identifiers can collide and cause the different parts to affect each other.
These features are now enabled in the tests for the PDF and SVG backends, so most test output files (but not
all of them) are now deterministic.
Orthographic projection for mplot3d
Axes3D now accepts proj_type keyword argument and has a method set_proj_type(). The default
option is 'persp' as before, and supplying 'ortho' enables orthographic view.
Compare the z-axis which is vertical in orthographic view, but slightly skewed in the perspective view.
import numpy as np
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
fig = plt.figure(figsize=(4, 6))
ax1 = fig.add_subplot(2, 1, 1, projection='3d')
ax1.set_proj_type('persp')
ax1.set_title('Perspective (default)')
300
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
ax2 = fig.add_subplot(2, 1, 2, projection='3d')
ax2.set_proj_type('ortho')
ax2.set_title('Orthographic')
plt.show()
Perspective (default)
1.0
0.8
0.6
0.4
0.2
0.0
1.0
0.8
0.0 0.2
0.40.6
0.4 0.6
0.8 1.0 0.00.2
Orthographic
0.0 0.2
0.4 0.6
0.8 1.0
1.0
0.8
0.6
0.4
0.2
0.0
0.81.0
0.6
0.4
0.00.2
voxels function for mplot3d
Axes3D now has a voxels method, for visualizing boolean 3D data. Uses could include plotting a sparse
3D heat map, or visualizing a volumetric model.
5.1.3 Improvements
5.1. New in Matplotlib 2.1
301
Matplotlib, Release 2.1.2
Fig. 5.3: Voxel Demo
CheckButtons widget get_status function
A get_status() method has been added to the matplotlib.widgets.CheckButtons class. This
get_status method allows user to query the status (True/False) of all of the buttons in the CheckButtons
object.
Add fill_bar argument to AnchoredSizeBar
The mpl_toolkits class AnchoredSizeBar now has an additional fill_bar argument, which makes
the size bar a solid rectangle instead of just drawing the border of the rectangle. The default is None, and
whether or not the bar will be filled by default depends on the value of size_vertical. If size_vertical
is nonzero, fill_bar will be set to True. If size_vertical is zero then fill_bar will be set to False.
If you wish to override this default behavior, set fill_bar to True or False to unconditionally always or
never use a filled patch rectangle for the size bar.
import matplotlib.pyplot as plt
from mpl_toolkits.axes_grid1.anchored_artists import AnchoredSizeBar
fig, ax = plt.subplots(figsize=(3, 3))
bar0 = AnchoredSizeBar(ax.transData, 0.3, 'unfilled', loc=3, frameon=False,
size_vertical=0.05, fill_bar=False)
ax.add_artist(bar0)
bar1 = AnchoredSizeBar(ax.transData, 0.3, 'filled', loc=4, frameon=False,
size_vertical=0.05, fill_bar=True)
ax.add_artist(bar1)
302
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
plt.show()
1.0
0.8
0.6
0.4
0.2
0.0 unfilled
0.0 0.2 0.4
0.6
filled
0.8 1.0
Annotation can use a default arrow style
Annotations now use the default arrow style when setting arrowprops={}, rather than no arrow (the new
behavior actually matches the documentation).
Barbs and Quiver Support Dates
When using the quiver() and barbs() plotting methods, it is now possible to pass dates, just like for other
methods like plot(). This also allows these functions to handle values that need unit-conversion applied.
Hexbin default line color
The default linecolor keyword argument for hexbin() is now 'face', and supplying 'none' now prevents lines from being drawn around the hexagons.
Figure.legend() can be called without arguments
Calling Figure.legend() can now be done with no arguments. In this case a legend will be created that
contains all the artists on all the axes contained within the figure.
Multiple legend keys for legend entries
A legend entry can now contain more than one legend key. The extended HandlerTuple class now accepts
two parameters: ndivide divides the legend area in the specified number of sections; pad changes the
padding between the legend keys.
5.1. New in Matplotlib 2.1
303
Matplotlib, Release 2.1.2
Fig. 5.4: Multiple Legend Keys
New parameter clear for figure()
When the pyplot’s function figure() is called with a num parameter, a new window is only created if no
existing window with the same value exists. A new bool parameter clear was added for explicitly clearing
its existing contents. This is particularly useful when utilized in interactive sessions. Since subplots()
also accepts keyword arguments from figure(), it can also be used there:
import matplotlib.pyplot as plt
fig0 = plt.figure(num=1)
fig0.suptitle("A fancy plot")
print("fig0.texts: ", [t.get_text() for t in fig0.texts])
fig1 = plt.figure(num=1, clear=False) # do not clear contents of window
fig1.text(0.5, 0.5, "Really fancy!")
print("fig0 is fig1: ", fig0 is fig1)
print("fig1.texts: ", [t.get_text() for t in fig1.texts])
fig2, ax2 = plt.subplots(2, 1, num=1, clear=True) # clear contents
print("fig0 is fig2: ", fig0 is fig2)
print("fig2.texts: ", [t.get_text() for t in fig2.texts])
#
#
#
#
#
#
The output:
fig0.texts: ['A fancy plot']
fig0 is fig1: True
fig1.texts: ['A fancy plot', 'Really fancy!']
fig0 is fig2: True
fig2.texts: []
304
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Specify minimum value to format as scalar for LogFormatterMathtext
LogFormatterMathtext now includes the option to specify a minimum value exponent to format as a
scalar (i.e., 0.001 instead of 10-3 ).
New quiverkey angle keyword argument
Plotting a quiverkey() now admits the angle keyword argument, which sets the angle at which to draw
the key arrow.
Colormap reversed method
The methods matplotlib.colors.LinearSegmentedColormap.reversed() and matplotlib.
colors.ListedColormap.reversed() return a reversed instance of the Colormap. This implements
a way for any Colormap to be reversed.
Artist.setp (and pyplot.setp) accept a file argument
The argument is keyword-only. It allows an output file other than sys.stdout to be specified. It works
exactly like the file argument to print.
streamplot streamline generation more configurable
The starting point, direction, and length of the stream lines can now be configured. This allows to follow the
vector field for a longer time and can enhance the visibility of the flow pattern in some use cases.
Axis.set_tick_params now responds to rotation
Bulk setting of tick label rotation is now possible via set_tick_params() using the rotation keyword.
ax.xaxis.set_tick_params(which='both', rotation=90)
Shading in 3D bar plots
A new shade parameter has been added the 3D bar plotting method. The default behavior remains to shade
the bars, but now users have the option of setting shade to False.
import numpy as np
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
x = np.arange(2)
y = np.arange(3)
x2d, y2d = np.meshgrid(x, y)
5.1. New in Matplotlib 2.1
305
Matplotlib, Release 2.1.2
x, y = x2d.ravel(), y2d.ravel()
z = np.zeros_like(x)
dz = x + y
fig = plt.figure(figsize=(4, 6))
ax1 = fig.add_subplot(2, 1, 1, projection='3d')
ax1.bar3d(x, y, z, 1, 1, dz, shade=True)
ax1.set_title('Shading On')
ax2 = fig.add_subplot(2, 1, 2, projection='3d')
ax2.bar3d(x, y, z, 1, 1, dz, shade=False)
ax2.set_title('Shading Off')
plt.show()
Shading On
0.0 0.5
1.0 1.5
2.0
3.0
2.5
2.0
1.5
1.0
0.5
0.0
2.53.0
2.0
1.01.5
0.5
0.0
Shading Off
0.0 0.5
1.0 1.5
2.0
306
3.0
2.5
2.0
1.5
1.0
0.5
0.0
2.53.0
2.0
1.01.5
0.5
0.0
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
New which Parameter for autofmt_xdate
A which parameter now exists for the method autofmt_xdate(). This allows a user to format major,
minor or both tick labels selectively. The default behavior will rotate and align the major tick labels.
fig.autofmt_xdate(bottom=0.2, rotation=30, ha='right', which='minor')
New Figure Parameter for subplot2grid
A fig parameter now exists for the function subplot2grid(). This allows a user to specify the figure
where the subplots will be created. If fig is None (default) then the method will use the current figure
retrieved by gcf().
subplot2grid(shape, loc, rowspan=1, colspan=1, fig=myfig)
Interpolation in fill_betweenx
The interpolate parameter now exists for the method fill_betweenx(). This allows a user to interpolate the data and fill the areas in the crossover points, similarly to fill_between().
New keyword argument sep for EngFormatter
A new sep keyword argument has been added to EngFormatter and provides a means to define the string
that will be used between the value and its unit. The default string is " ", which preserves the former
behavior. Additionally, the separator is now present between the value and its unit even in the absence of
SI prefix. There was formerly a bug that was causing strings like "3.14V" to be returned instead of the
expected "3.14 V" (with the default behavior).
Extend MATPLOTLIBRC behavior
The environmental variable can now specify the full file path or the path to a directory containing a
matplotlibrc file.
density kwarg to hist
The hist() method now prefers density to normed to control if the histogram should be normalized,
following a change upstream to NumPy. This will reduce confusion as the behavior has always been that
the integral of the histogram is 1 (rather than sum or maximum value).
5.1.4 Internals
5.1. New in Matplotlib 2.1
307
Matplotlib, Release 2.1.2
New TransformedPatchPath caching object
A newly added TransformedPatchPath provides a means to transform a Patch into a Path via a
Transform while caching the resulting path. If neither the patch nor the transform have changed, a cached
copy of the path is returned.
This class differs from the older TransformedPath in that it is able to refresh itself based on the underlying
patch while the older class uses an immutable path.
Abstract base class for movie writers
The new AbstractMovieWriter class defines the API required by a class that is to be used as the writer in
the matplotlib.animation.Animation.save() method. The existing MovieWriter class now derives
from the new abstract base class.
Stricter validation of line style rcParams
The validation of rcParams that are related to line styles (lines.linestyle, boxplot.*.linestyle,
grid.linestyle and contour.negative_linestyle) now effectively checks that the values are valid
line styles. Strings like 'dashed' or '--' are accepted, as well as even-length sequences of on-off ink like
[1, 1.65]. In this latter case, the offset value is handled internally and should not be provided by the user.
The new validation scheme replaces the former one used for the contour.negative_linestyle rcParams, that was limited to 'solid' and 'dashed' line styles.
The validation is case-insensitive. The following are now valid:
grid.linestyle
: (1, 3)
contour.negative_linestyle : dashdot
# loosely dotted grid lines
# previously only solid or dashed
pytest
The automated tests have been switched from nose to pytest.
5.1.5 Performance
Path simplification updates
Line simplification controlled by the path.simplify and path.simplify_threshold parameters has
been improved. You should notice better rendering performance when plotting large amounts of data (as
long as the above parameters are set accordingly). Only the line segment portion of paths will be simplified –
if you are also drawing markers and experiencing problems with rendering speed, you should consider using
the markevery option to plot. See the Performance section in the usage tutorial for more information.
The simplification works by iteratively merging line segments into a single vector until the next line segment’s perpendicular distance to the vector (measured in display-coordinate space) is greater than the path.
simplify_threshold parameter. Thus, higher values of path.simplify_threshold result in quicker
308
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
rendering times. If you are plotting just to explore data and not for publication quality, pixel perfect plots,
then a value of 1.0 can be safely used. If you want to make sure your plot reflects your data exactly, then
you should set path.simplify to false and/or path.simplify_threshold to 0. Matplotlib currently
defaults to a conservative value of 1/9, smaller values are unlikely to cause any visible differences in your
plots.
Implement intersects_bbox in c++
intersects_bbox() has been implemented in c++ which improves the performance of automatically
placing the legend.
5.2 Previous Whats New
5.2.1 List of changes to Matplotlib prior to 2015
This is a list of the changes made to Matplotlib from 2003 to 2015. For more recent changes, please refer to
the what’s new or the API changes.
2015-11-16 Levels passed to contour(f) and tricontour(f) must be in increasing order.
2015-10-21 Added TextBox widget
2015-10-21 Added get_ticks_direction()
2015-02-27 Added the rcParam ‘image.composite_image’ to permit users to decide whether they want
the vector graphics backends to combine all images within a set of axes into a single composite image.
(If images do not get combined, users can open vector graphics files in Adobe Illustrator or Inkscape
and edit each image individually.)
2015-02-19 Rewrite of C++ code that calculates contours to add support for corner masking. This is
controlled by the ‘corner_mask’ keyword in plotting commands ‘contour’ and ‘contourf’. - IMT
2015-01-23 Text bounding boxes are now computed with advance width rather than ink area.
may result in slightly different placement of text.
2014-10-27 Allowed selection of the backend using the MPLBACKEND environment variable.
documentation on backend selection methods.
This
Added
2014-09-27 Overhauled colors.LightSource. Added LightSource.hillshade to allow the independent generation of illumination maps. Added new types of blending for creating more visually
appealing shaded relief plots (e.g. blend_mode="overlay", etc, in addition to the legacy “hsv”
mode).
2014-06-10 Added Colorbar.remove()
2014-06-07 Fixed bug so radial plots can be saved as ps in py3k.
2014-06-01 Changed the fmt kwarg of errorbar to support the the mpl convention that “none” means
“don’t draw it”, and to default to the empty string, so that plotting of data points is done with the
plot() function defaults. Deprecated use of the None object in place “none”.
5.2. Previous Whats New
309
Matplotlib, Release 2.1.2
2014-05-22 Allow the linscale keyword parameter of symlog scale to be smaller than one.
2014-05-20 Added logic to in FontManager to invalidate font-cache if if font-family rcparams have
changed.
2014-05-16 Fixed the positioning of multi-line text in the PGF backend.
2014-05-14 Added Axes.add_image() as the standard way to add AxesImage instances to Axes. This
improves the consistency with add_artist(), add_collection(), add_container(), add_line(),
add_patch(), and add_table().
2014-05-02 Added colorblind-friendly colormap, named ‘Wistia’.
2014-04-27 Improved input clean up in Axes.{h|v}lines Coerce input into a 1D ndarrays (after dealing
with units).
2014-04-27 removed un-needed cast to float in stem
2014-04-23 Updated references to “ipython -pylab” The preferred method for invoking pylab is now using the “%pylab” magic. -Chris G.
2014-04-22 Added (re-)generate a simple automatic legend to “Figure Options” dialog of the Qt4Agg
backend.
2014-04-22 Added an example showing the difference between interpolation = ‘none’ and interpolation
= ‘nearest’ in imshow() when saving vector graphics files.
2014-04-22 Added violin plotting functions. See Axes.violinplot, Axes.violin,
violin_stats and mlab.GaussianKDE for details.
cbook.
2014-04-10 Fixed the triangular marker rendering error. The “Up” triangle was rendered instead of
“Right” triangle and vice-versa.
2014-04-08 Fixed a bug in parasite_axes.py by making a list out of a generator at line 263.
2014-04-02 Added clipon=False to patch creation of wedges and shadows in pie.
2014-02-25 In backend_qt4agg changed from using update -> repaint under windows. See comment
in source near self._priv_update for longer explaination.
2014-03-27 Added tests for pie ccw parameter. Removed pdf and svg images from
linewidth parameter.
tests
for
pie
2014-03-24 Changed the behaviour of axes to not ignore leading or trailing patches of height 0 (or
width 0) while calculating the x and y axis limits. Patches having both height == 0 and width ==
0 are ignored.
2014-03-24 Added bool kwarg (manage_xticks) to boxplot to enable/disable the managemnet of the
xlimits and ticks when making a boxplot. Default in True which maintains current behavior by default.
2014-03-23 Fixed a bug in projections/polar.py by making sure that the theta value being calculated
when given the mouse coordinates stays within the range of 0 and 2 * pi.
2014-03-22 Added the keyword arguments wedgeprops and textprops to pie. Users can control the
wedge and text properties of the pie in more detail, if they choose.
2014-03-17 Bug was fixed in append_axes from the AxesDivider class would not append axes in the
right location with respect to the reference locator axes
310
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2014-03-13 Add parameter ‘clockwise’ to function pie, True by default.
2014-02-28 Added ‘origin’ kwarg to spy
2014-02-27 Implemented separate horizontal/vertical axes padding to the ImageGrid in the AxesGrid
toolkit
2014-02-27 Allowed markevery property of matplotlib.lines.Line2D to be, an int numpy fancy index,
slice object, or float. The float behaviour turns on markers at approximately equal display-coordinatedistances along the line.
2014-02-25 In backend_qt4agg changed from using update -> repaint under windows. See comment
in source near self._priv_update for longer explaination.
2014-01-02 triplot now returns the artist it adds and support of line and marker kwargs has been
improved. GBY
2013-12-30 Made streamplot grid size consistent for different types of density argument.
grid is now used for both density=1 and density=(1, 1).
A 30x30
2013-12-03 Added a pure boxplot-drawing method that allow a more complete customization of boxplots. It takes a list of dicts contains stats. Also created a function (cbook.boxplot_stats) that
generates the stats needed.
2013-11-28 Added qhull extension module to perform Delaunay triangulation more robustly than before. It is used by tri.Triangulation (and hence all pyplot.tri* methods) and mlab.griddata. Deprecated
matplotlib.delaunay module. - IMT
2013-11-05 Add power-law normalization method. This is useful for, e.g., showing small populations
in a “hist2d” histogram.
2013-10-27 Added get_rlabel_position and set_rlabel_position methods to PolarAxes to control angular position of radial tick labels.
2013-10-06 Add stride-based functions to mlab for easy creation of 2D arrays with less memory.
2013-10-06 Improve window and detrend functions in mlab, particulart support for 2D arrays.
2013-10-06 Improve performance of all spectrum-related mlab functions and plots.
2013-10-06 Added support for magnitude, phase, and angle spectrums to axes.specgram, and support
for magnitude, phase, angle, and complex spectrums to mlab-specgram.
2013-10-06 Added magnitude_spectrum, angle_spectrum, and phase_spectrum plots, as well as
magnitude_spectrum, angle_spectrum, phase_spectrum, and complex_spectrum functions to mlab
2013-07-12 Added support for datetime axes to 2d plots. Axis values are passed through
Axes.convert_xunits/Axes.convert_yunits before being used by contour/contourf, pcolormesh
and pcolor.
2013-07-12 Allowed matplotlib.dates.date2num, matplotlib.dates.num2date, and
matplotlib.dates.datestr2num to accept n-d inputs. Also factored in support for n-d arrays to matplotlib.dates.DateConverter and matplotlib.units.Registry.
2013-06-26 Refactored the axes module: the axes module is now a folder,
containing the following submodule:
5.2. Previous Whats New
311
Matplotlib, Release 2.1.2
• _subplots.py, containing all the subplots helper methods
• _base.py, containing several private methods and a new _AxesBase class. This _AxesBase
class contains all the methods that are not directly linked to plots of the “old” Axes
• _axes.py contains the Axes class. This class now inherits from _AxesBase: it contains all
“plotting” methods and labelling methods.
This refactoring should not affect the API. Only private methods are not importable from the axes
module anymore.
2013-05-18 Added support for arbitrary rasterization resolutions to the SVG backend. Previously the
resolution was hard coded to 72 dpi. Now the backend class takes a image_dpi argument for its
constructor, adjusts the image bounding box accordingly and forwards a magnification factor to the
image renderer. The code and results now resemble those of the PDF backend. - MW
2013-05-08 Changed behavior of hist when given stacked=True and normed=True. Histograms are
now stacked first, then the sum is normalized. Previously, each histogram was normalized, then they
were stacked.
2013-04-25 Changed all instances of:
from matplotlib import MatplotlibDeprecationWarning as mplDeprecation to:
from cbook import mplDeprecation
and removed the import into the matplotlib namespace in __init__.py Thomas Caswell
2013-04-15 Added ‘axes.xmargin’ and ‘axes.ymargin’ to rpParams to set default margins on autoscaleing. - TAC
2013-04-16 Added patheffect support for Line2D objects. -JJL
2013-03-31 Added support for arbitrary unstructured user-specified triangulations
Axes3D.tricontour[f] - Damon McDougall
to
2013-03-19 Added support for passing linestyle kwarg to step so all plot kwargs are passed to the
underlying plot call. -TAC
2013-02-25 Added classes CubicTriInterpolator, UniformTriRefiner, TriAnalyzer to
module. - GBy
matplotlib.tri
2013-01-23 Add ‘savefig.directory’ to rcParams to remember and fill in the last directory saved to for
figure save dialogs - Martin Spacek
2013-01-13 Add eventplot method to axes and pyplot and EventCollection class to collections.
2013-01-08 Added two extra titles to axes which are flush with the left and right edges of the plot respectively. Andrew Dawson
2013-01-07 Add framealpha keyword argument to legend - PO
2013-01-16 Till Stensitzki added a baseline feature to stackplot
2012-12-22 Added classes for interpolation within triangular grids (LinearTriInterpolator) and to find
the triangles in which points lie (TrapezoidMapTriFinder) to matplotlib.tri module. - IMT
312
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2012-12-05 Added MatplotlibDeprecationWarning class for signaling deprecation. Matplotlib developers can use this class as follows:
from matplotlib import MatplotlibDeprecationWarning as mplDeprecation
In light of the fact that Python builtin DeprecationWarnings are ignored by default as of Python 2.7,
this class was put in to allow for the signaling of deprecation, but via UserWarnings which are not
ignored by default. - PI
2012-11-27 Added the mtext parameter for supplying matplotlib.text.Text instances
to
RendererBase.draw_tex and RendererBase.draw_text. This allows backends to utilize additional
text attributes, like the alignment of text elements. - pwuertz
2012-11-26 deprecate matplotlib/mpl.py, which was used only in pylab.py and is now replaced by the
more suitable import matplotlib as mpl. - PI
2012-11-25 Make rc_context available via pyplot interface - PI
2012-11-16 plt.set_cmap no longer throws errors if there is not already an active colorable artist, such
as an image, and just sets up the colormap to use from that point forward. - PI
2012-11-16 Added the funcction _get_rbga_face, which is identical to _get_rbg_face except it return a
(r,g,b,a) tuble, to line2D. Modified Line2D.draw to use _get_rbga_face to get the markerface color so
that any alpha set by markerfacecolor will respected. - Thomas Caswell
2012-11-13 Add a symmetric log normalization class to colors.py. Also added some tests for the normalization class. Till Stensitzki
2012-11-12 Make axes.stem take at least one argument. Uses a default range(n) when the first arg not
provided. Damon McDougall
2012-11-09 Make plt.subplot() without arguments act as subplot(111) - PI
2012-11-08 Replaced plt.figure and plt.subplot calls by the newer, more convenient
plt.subplots() in the documentation examples - PI
single
call
to
2012-10-05 Add support for saving animations as animated GIFs. - JVDP
2012-08-11 Fix path-closing bug in patches.Polygon, so that regardless of whether the path is the initial one or was subsequently set by set_xy(), get_xy() will return a closed path if and only if
get_closed() is True. Thanks to Jacob Vanderplas. - EF
2012-08-05 When a norm is passed to contourf, either or both of the vmin, vmax attributes of that
norm are now respected. Formerly they were respected only if both were specified. In addition,
vmin and/or vmax can now be passed to contourf directly as kwargs. - EF
2012-07-24 Contourf handles the extend kwarg by mapping the extended ranges outside the normed
0-1 range so that they are handled by colormap colors determined by the set_under and set_over
methods. Previously the extended ranges were mapped to 0 or 1 so that the “under” and “over” colormap colors were ignored. This change also increases slightly the color contrast for a given set of
contour levels. - EF
2012-06-24 Make use of mathtext in tick labels configurable - DSD
2012-06-05 Images loaded through PIL are now ordered correctly - CG
2012-06-02 Add new Axes method and pyplot function, hist2d. - PO
5.2. Previous Whats New
313
Matplotlib, Release 2.1.2
2012-05-31 Remove support for ‘cairo.<format>’ style of backend specification. Deprecate
‘cairo.format’ and ‘savefig.extension’ rcParams and replace with ‘savefig.format’. - Martin
Spacek
2012-05-29 pcolormesh now obeys the passed in “edgecolor” kwarg. To support this, the “shading” argument to pcolormesh now only takes “flat” or “gouraud”. To achieve the old “faceted” behavior, pass
“edgecolors=’k’”. - MGD
2012-05-22 Added radius kwarg to pie charts. - HH
2012-05-22 Collections now have a setting “offset_position” to select whether the offsets are given in
“screen” coordinates (default, following the old behavior) or “data” coordinates. This is currently
used internally to improve the performance of hexbin.
As a result, the “draw_path_collection” backend methods have grown a new argument “offset_position”. - MGD
2012-05-04 Add a new argument to pie charts - startingangle - that allows one to specify the angle offset for the first wedge of the chart. - EP
2012-05-03 symlog scale now obeys the logarithmic base. Previously, it was completely ignored and
always treated as base e. - MGD
2012-05-03 Allow linscalex/y keyword to symlog scale that allows the size of the linear portion relative
to the logarithmic portion to be adjusted. - MGD
2012-04-14 Added new plot style: stackplot. This new feature supports stacked area plots. - Damon
McDougall
2012-04-06 When path clipping changes a LINETO to a MOVETO, it also changes any CLOSEPOLY command to a LINETO to the initial point. This fixes a problem with pdf and svg where the
CLOSEPOLY would then draw a line to the latest MOVETO position instead of the intended initial
position. - JKS
2012-03-27 Add support to ImageGrid for placing colorbars only at one edge of each column/row. RMM
2012-03-07 Refactor movie writing into useful classes that make use of pipes to write image data to
ffmpeg or mencoder. Also improve settings for these and the ability to pass custom options. - RMM
2012-02-29 errorevery keyword added to errorbar to enable errorbar subsampling. fixes issue #600.
2012-02-28 Added plot_trisurf to the mplot3d toolkit. This supports plotting three dimensional surfaces on an irregular grid. - Damon McDougall
2012-01-23 The radius labels in polar plots no longer use a fixed padding, but use a different alignment
depending on the quadrant they are in. This fixes numerical problems when (rmax - rmin) gets too
small. - MGD
2012-01-08 Add axes.streamplot to plot streamlines of a velocity field. Adapted from Tom Flannaghan
streamplot implementation. -TSY
2011-12-29 ps and pdf markers are now stroked only if the line width is nonzero for consistency with
agg, fixes issue #621. - JKS
2011-12-27 Work around an EINTR bug in some versions of subprocess. - JKS
314
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2011-10-25 added support for operatorname to mathtext, including the ability to insert spaces, such as
$operatorname{arg,max}$ - PI
2011-08-18 Change api of Axes.get_tightbbox and add an optional keyword
call_axes_locator. - JJL
parameter
2011-07-29 A new rcParam “axes.formatter.use_locale” was added, that, when True, will use the current locale to format tick labels. This means that, for example, in the fr_FR locale, ‘,’ will be used as
a decimal separator. - MGD
2011-07-15 The set of markers available in the plot() and scatter() commands has been unified. In general, this gives more options to both than were previously available, however, there is one backwardincompatible change to the markers in scatter:
“d” used to mean “diamond”, it now means “narrow diamond”. “D” can be used for a
“diamond”.
-MGD
2011-07-13 Fix numerical problems in symlog scale, particularly when linthresh <= 1.0. Symlog plots
may look different if one was depending on the old broken behavior - MGD
2011-07-10 Fixed argument handling error in tripcolor/triplot/tricontour, issue #203. - IMT
2011-07-08 Many functions added to mplot3d.axes3d to bring Axes3D objects more
with regular Axes objects. Significant revisions to the documentation as well. - BVR
feature-parity
2011-07-07 Added compatibility with IPython strategy for picking a version of Qt4 support, and an rcParam for making the choice explicitly: backend.qt4. - EF
2011-07-07 Modified AutoMinorLocator to improve automatic choice of the number of minor intervals per major interval, and to allow one to specify this number via a kwarg. - EF
2011-06-28 3D versions of scatter, plot, plot_wireframe, plot_surface, bar3d, and some other functions
now support empty inputs. - BVR
2011-06-22 Add set_theta_offset, set_theta_direction and set_theta_zero_location to polar axes to control the location of 0 and directionality of theta. - MGD
2011-06-22 Add axes.labelweight parameter to set font weight to axis labels - MGD.
2011-06-20 Add pause function to pyplot. - EF
2011-06-16 Added bottom keyword parameter for the stem command. Also, implemented a legend
handler for the stem plot. - JJL
2011-06-16 Added legend.frameon rcParams. - Mike Kaufman
2011-05-31 Made backend_qt4 compatible with PySide . - Gerald Storer
2011-04-17 Disable keyboard auto-repeat in qt4 backend by ignoring key events resulting from autorepeat. This makes constrained zoom/pan work. - EF
2011-04-14 interpolation=”nearest” always interpolate images. A new mode “none” is introduced for
no interpolation - JJL
2011-04-03 Fixed broken pick interface to AsteriskCollection objects used by scatter. - EF
5.2. Previous Whats New
315
Matplotlib, Release 2.1.2
2011-04-01 The plot directive Sphinx extension now supports all of the features in the Numpy fork of
that extension. These include doctest formatting, an ‘include-source’ option, and a number of new
configuration options. - MGD
2011-03-29 Wrapped ViewVCCachedServer definition in a factory function. This class now inherits
from urllib2.HTTPSHandler in order to fetch data from github, but HTTPSHandler is not defined
if python was built without SSL support. - DSD
2011-03-10 Update pytz version to 2011c, thanks to Simon Cross. - JKS
2011-03-06 Add standalone tests.py test runner script. - JKS
2011-03-06 Set edgecolor to ‘face’ for scatter asterisk-type symbols; this fixes a bug in which these
symbols were not responding to the c kwarg. The symbols have no face area, so only the edgecolor is
visible. - EF
2011-02-27 Support libpng version 1.5.x; suggestion by Michael Albert. Changed installation specification to a minimum of libpng version 1.2. - EF
2011-02-20 clabel accepts a callable as an fmt kwarg; modified patch by Daniel Hyams. - EF
2011-02-18 scatter([], []) is now valid. Also fixed issues with empty collections - BVR
2011-02-07 Quick workaround for dviread bug #3175113 - JKS
2011-02-05 Add cbook memory monitoring for Windows, using tasklist. - EF
2011-02-05 Speed up Normalize and LogNorm by using in-place operations and by using float32 for
float32 inputs and for ints of 2 bytes or shorter; based on patch by Christoph Gohlke. - EF
2011-02-04 Changed imshow to use rgba as uint8 from start to finish, instead of going through an intermediate step as double precision; thanks to Christoph Gohlke. - EF
2011-01-13 Added zdir and offset arguments to contourf3d to bring contourf3d in feature parity with
contour3d. - BVR
2011-01-04 Tag 1.0.1 for release at r8896
2011-01-03 Added display of ticker offset to 3d plots. - BVR
2011-01-03 Turn off tick labeling on interior subplots for pyplots.subplots when sharex/sharey is True.
- JDH
2010-12-29 Implement axes_divider.HBox and VBox. -JJL
2010-11-22 Fixed error with Hammer projection. - BVR
2010-11-12 Fixed the placement and angle of axis labels in 3D plots. - BVR
2010-11-07 New rc parameters examples.download and examples.directory allow
download mechanism in get_sample_data. - JKS
bypassing
the
2010-10-04 Fix JPEG saving bug: only accept the kwargs documented by PIL for JPEG files. - JKS
2010-09-15 Remove unused _wxagg extension and numerix.h. - EF
2010-08-25 Add new framework for doing animations with examples.- RM
316
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2010-08-21 Remove unused and inappropriate methods from Tick classes: set_view_interval,
get_minpos, and get_data_interval are properly found in the Axis class and don’t need to be
duplicated in XTick and YTick. - EF
2010-08-21 Change Axis.set_view_interval() so that when updating an existing interval, it respects the
orientation of that interval, and can enlarge but not reduce the interval. This fixes a bug in which
Axis.set_ticks would change the view limits of an inverted axis. Whether set_ticks should be affecting
the viewLim at all remains an open question. - EF
2010-08-16 Handle NaN’s correctly in path analysis routines. Fixes a bug where the best location for a
legend was not calculated correctly when the line contains NaNs. - MGD
2010-08-14 Fix bug in patch alpha handling, and in bar color kwarg - EF
2010-08-12 Removed all traces of numerix module after 17 months of deprecation warnings. - EF
2010-08-05 Added keyword arguments ‘thetaunits’ and ‘runits’ for polar plots. Fixed PolarAxes so
that when it set default Formatters, it marked them as such. Fixed semilogx and semilogy to no
longer blindly reset the ticker information on the non-log axis. Axes.arrow can now accept unitized
data. - JRE
2010-08-03 Add support for MPLSETUPCFG variable for custom setup.cfg filename. Used by sage
buildbot to build an mpl w/ no gui support - JDH
2010-08-01 Create directory specified by MPLCONFIGDIR if it does not exist. - ADS
2010-07-20 Return Qt4’s default cursor when leaving the canvas - DSD
2010-07-06 Tagging for mpl 1.0 at r8502
2010-07-05 Added Ben Root’s patch to put 3D plots in arbitrary axes, allowing you to mix 3d and
2d in different axes/subplots or to have multiple 3D plots in one figure.
See examples/mplot3d/subplot3d_demo.py - JDH
2010-07-05 Preferred kwarg names in set_xlim are now ‘left’ and ‘right’; in set_ylim, ‘bottom’ and
‘top’; original kwargs are still accepted without complaint. - EF
2010-07-05 TkAgg and FltkAgg backends are now consistent with other interactive backends: when
used in scripts from the command line (not from ipython -pylab), show blocks, and can be called
more than once. - EF
2010-07-02 Modified CXX/WrapPython.h to fix “swab bug” on solaris so mpl can compile on Solaris
with CXX6 in the trunk. Closes tracker bug 3022815 - JDH
2010-06-30 Added autoscale convenience method and corresponding pyplot function for simplified
control of autoscaling; and changed axis, set_xlim, and set_ylim so that by default, they turn off
the autoscaling on the relevant axis or axes. Therefore one can call set_xlim before plotting a line, for
example, and the limits will be retained. - EF
2010-06-20 Added Axes.tick_params and corresponding pyplot function to control tick and tick label
appearance after an Axes has been created. - EF
2010-06-09 Allow Axes.grid to control minor gridlines; allow Axes.grid and Axis.grid to control major
and minor gridlines in the same method call. - EF
5.2. Previous Whats New
317
Matplotlib, Release 2.1.2
2010-06-06 Change the way we do split/dividend adjustments in finance.py to handle dividends and fix
the zero division bug reported in sf bug 2949906 and 2123566. Note that volume is not adjusted
because the Yahoo CSV does not distinguish between share split and dividend adjustments making
it near impossible to get volume adjustement right (unless we want to guess based on the size of the
adjustment or scrape the html tables, which we don’t) - JDH
2010-06-06 Updated dateutil to 1.5 and pytz to 2010h.
2010-06-02 Add error_kw kwarg to Axes.bar(). - EF
2010-06-01 Fix pcolormesh() and QuadMesh to pass on kwargs as appropriate. - RM
2010-05-18 Merge mpl_toolkits.gridspec into the main tree. - JJL
2010-05-04 Improve backend_qt4 so it displays figures with the correct size - DSD
2010-04-20 Added generic support for connecting to a timer for events. This adds
TimerBase,
TimerGTK, TimerQT, TimerWx, and TimerTk to the backends and a new_timer() method to
each backend’s canvas to allow ease of creating a new timer. - RM
2010-04-20 Added margins() Axes method and pyplot function. - EF
2010-04-18 update the axes_grid documentation. -JJL
2010-04-18 Control MaxNLocator parameters after instantiation, and
method, with corresponding pyplot function. -EF
via
Axes.locator_params
2010-04-18 Control ScalarFormatter offsets directly and via the Axes.ticklabel_format() method, and
add that to pyplot. -EF
2010-04-16 Add a close_event to the backends. -RM
2010-04-06 modify axes_grid examples to use axes_grid1 and axisartist. -JJL
2010-04-06 rebase axes_grid using axes_grid1 and axisartist modules. -JJL
2010-04-06 axes_grid toolkit is splitted into two separate modules, axes_grid1 and axisartist. -JJL
2010-04-05 Speed up import: import pytz only if and when it is needed. It is not needed if the rc timezone is UTC. - EF
2010-04-03 Added color kwarg to Axes.hist(), based on work by Jeff Klukas. - EF
2010-03-24 refactor colorbar code so that no cla() is necessary when mappable is changed. -JJL
2010-03-22 fix incorrect rubber band during the zoom mode when mouse leaves the axes. -JJL
2010-03-21 x/y key during the zoom mode only changes the x/y limits. -JJL
2010-03-20 Added pyplot.sca() function suggested by JJL. - EF
2010-03-20 Added conditional support for new Tooltip API in gtk backend. - EF
2010-03-20 Changed plt.fig_subplot() to plt.subplots() after discussion on list, and changed its API to
return axes as a numpy object array (with control of dimensions via squeeze keyword). FP.
2010-03-13 Manually brought in commits from branch:
318
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
-----------------------------------------------------------------------r8191 | leejjoon | 2010-03-13 17:27:57 -0500 (Sat, 13 Mar 2010) | 1 line
fix the bug that handles for scatter are incorrectly set when dpi!=72.
Thanks to Ray Speth for the bug report.
2010-03-03 Manually brought in commits from branch via diff/patch (svnmerge is broken):
-----------------------------------------------------------------------r8175 | leejjoon | 2010-03-03 10:03:30 -0800 (Wed, 03 Mar 2010) | 1 line
fix arguments of allow_rasterization.draw_wrapper
-----------------------------------------------------------------------r8174 | jdh2358 | 2010-03-03 09:15:58 -0800 (Wed, 03 Mar 2010) | 1 line
added support for favicon in docs build
-----------------------------------------------------------------------r8173 | jdh2358 | 2010-03-03 08:56:16 -0800 (Wed, 03 Mar 2010) | 1 line
applied Mattias get_bounds patch
-----------------------------------------------------------------------r8172 | jdh2358 | 2010-03-03 08:31:42 -0800 (Wed, 03 Mar 2010) | 1 line
fix svnmerge download instructions
-----------------------------------------------------------------------r8171 | jdh2358 | 2010-03-03 07:47:48 -0800 (Wed, 03 Mar 2010) | 1 line
2010-02-25 add annotation_demo3.py that demonstrates new functionality. -JJL
2010-02-25 refactor Annotation to support arbitrary Transform as xycoords or textcoords. Also, if a
tuple of two coordinates is provided, they are interpreted as coordinates for each x and y position.
-JJL
2010-02-24 Added pyplot.fig_subplot(), to create a figure and a group of subplots in a single call. This
offers an easier pattern than manually making figures and calling add_subplot() multiple times. FP
2010-02-17 Added Gokhan’s and Mattias’ customizable keybindings patch for the toolbar. You can
now set the keymap.* properties in the matplotlibrc file. Newbindings were added for toggling log
scaling on the x-axis. JDH
2010-02-16 Committed TJ’s filled marker patch for left|right|bottom|top|full filled markers. See examples/pylab_examples/filledmarker_demo.py. JDH
2010-02-11 Added ‘bootstrap’ option to boxplot. This allows bootstrap estimates of median confidence intervals. Based on an initial patch by Paul Hobson. - ADS
2010-02-06 Added setup.cfg “basedirlist” option to override setting in setupext.py “basedir” dictionary; added “gnu0” platform requested by Benjamin Drung. - EF
2010-02-06 Added ‘xy’ scaling option to EllipseCollection. - EF
2010-02-03 Made plot_directive use a custom PlotWarning category, so that warnings can be turned
into fatal errors easily if desired. - FP
5.2. Previous Whats New
319
Matplotlib, Release 2.1.2
2010-01-29 Added draggable method to Legend to allow mouse drag placement.
Fraser. JDH
Thanks Adam
2010-01-25 Fixed a bug reported by Olle Engdegard, when using histograms
log=True - MM
stepfilled
with
and
2010-01-16 Upgraded CXX to 6.1.1 - JDH
2009-01-16 Don’t create minor ticks on top of existing major ticks. Patch by Neil Crighton. -ADS
2009-01-16 Ensure three minor ticks always drawn (SF# 2924245). Patch by Neil Crighton. -ADS
2010-01-16 Applied patch by Ian Thomas to fix two contouring problems: now contourf handles interior masked regions, and the boundaries of line and filled contours coincide. - EF
2009-01-11 The color of legend patch follows the rc parameters axes.facecolor and axes.edgecolor. JJL
2009-01-11 adjustable of Axes can be “box-forced” which allow sharing axes. -JJL
2009-01-11 Add add_click and pop_click methods in BlockingContourLabeler. -JJL
2010-01-03 Added rcParams[‘axes.color_cycle’] - EF
2010-01-03 Added Pierre’s qt4 formlayout editor and toolbar button - JDH
2009-12-31 Add support for using math text as marker symbols (Thanks to tcb)
• MGD
2009-12-31 Commit a workaround for a regression in PyQt4-4.6.{0,1} - DSD
2009-12-22 Fix cmap data for gist_earth_r, etc. -JJL
2009-12-20 spines: put spines in data coordinates, add set_bounds() call. -ADS
2009-12-18 Don’t limit notch size in boxplot to q1-q3 range, as this is effectively making the data look
better than it is. - ADS
2009-12-18 mlab.prctile handles even-length data, such that the median is the mean of the two middle
values. - ADS
2009-12-15 Add raw-image (unsampled) support for the ps backend. - JJL
2009-12-14 Add patch_artist kwarg to boxplot, but keep old default. Convert boxplot_demo2.py to
use the new patch_artist. - ADS
2009-12-06 axes_grid: reimplemented AxisArtist with FloatingAxes support. Added new examples. JJL
2009-12-01 Applied Laurent Dufrechou’s patch to improve blitting with the qt4 backend - DSD
2009-11-13 The pdf backend now allows changing the contents of a pdf file’s information dictionary
via PdfPages.infodict. - JKS
2009-11-12 font_manager.py should no longer cause EINTR on Python 2.6 (but will on the 2.5 version
of subprocess). Also the fc-list command in that file was fixed so now it should actually find the list
of fontconfig fonts. - JKS
320
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2009-11-10 Single images, and all images in renderers with option_image_nocomposite (i.e. agg, macosx and the svg backend when rcParams[‘svg.image_noscale’] is True), are now drawn respecting
the zorder relative to other artists. (Note that there may now be inconsistencies across backends when
more than one image is drawn at varying zorders, but this change introduces correct behavior for the
backends in which it’s easy to do so.)
2009-10-21 Make AutoDateLocator more configurable by adding options to control the maximum and
minimum number of ticks. Also add control of the intervals to be used for ticking. This does not
change behavior but opens previously hard-coded behavior to runtime modification‘. - RMM
2009-10-19 Add “path_effects” support for Text and Patch. See examples/pylab_examples/patheffect_demo.py
-JJL
2009-10-19 Add “use_clabeltext” option to clabel. If True, clabels will be created with ClabelText
class, which recalculates rotation angle of the label during the drawing time. -JJL
2009-10-16 Make AutoDateFormatter actually use any specified timezone setting.This was only working correctly when no timezone was specified. - RMM
2009-09-27 Beginnings of a capability to test the pdf backend. - JKS
2009-09-27 Add a savefig.extension rcparam to control the default filename extension used by savefig.
- JKS
2009-09-21 Tagged for release 0.99.1
2009-09-20 Fix usetex spacing errors in pdf backend. - JKS
2009-09-20 Add Sphinx extension to highlight IPython console sessions, originally authored (I think)
by Michael Droetboom. - FP
2009-09-20 Fix off-by-one error in dviread.Tfm, and additionally protect against exceptions in case a
dvi font is missing some metrics. - JKS
2009-09-15 Implement draw_text and draw_tex method of backend_base using the textpath module.
Implement draw_tex method of the svg backend. - JJL
2009-09-15 Don’t fail on AFM files containing floating-point bounding boxes - JKS
2009-09-13 AxesGrid [add modified version of colorbar. Add colorbar] location howto. - JJL
2009-09-07 AxesGrid [implemented
axisline
examples/axes_grid/demo_axisline_style.py- JJL
style.]
Added
a
demo
2009-09-04 Make the textpath class as a separate moduel (textpath.py). Add support for mathtext and
tex.- JJL
2009-09-01 Added support for Gouraud interpolated triangles. pcolormesh
ing=’gouraud’ as an option. - MGD
now
accepts
shad-
2009-08-29 Added matplotlib.testing package, which contains a Nose plugin and a decorator that lets
tests be marked as KnownFailures - ADS
2009-08-20 Added scaled dict to AutoDateFormatter for customized scales - JDH
5.2. Previous Whats New
321
Matplotlib, Release 2.1.2
2009-08-15 Pyplot interface: the current image is now tracked at the figure and axes level, addressing
tracker item 1656374. - EF
2009-08-15 Docstrings are now manipulated with decorators defined in a new module, docstring.py,
thanks to Jason Coombs. - EF
2009-08-14 Add support for image filtering for agg back end. See the example demo_agg_filter.py. JJL
2009-08-09 AnnotationBbox added. Similar to Annotation, but works with OffsetBox instead of Text.
See the example demo_annotation_box.py. -JJL
2009-08-07 BboxImage implemented. Two examples, demo_bboximage.py and demo_ribbon_box.py
added. - JJL
2009-08-07 In an effort to simplify the backend API, all clipping rectangles and paths are now passed
in using GraphicsContext objects, even on collections and images. Therefore:
draw_path_collection(self, master_transform, cliprect, clippath, clippath_trans,
paths, all_transforms, offsets, offsetTrans, facecolors, edgecolors, linewidths,
linestyles, antialiaseds, urls)
becomes:
draw_path_collection(self, gc, master_transform, paths, all_transforms, offsets, offsetTrans, facecolors, edgecolors, linewidths, linestyles, antialiaseds, urls)
draw_quad_mesh(self, master_transform, cliprect, clippath, clippath_trans, meshWidth, meshHeight, coordinates, offsets, offsetTrans, facecolors, antialiased,
showedges)
becomes:
draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight, coordinates,
offsets, offsetTrans, facecolors, antialiased, showedges)
draw_image(self, x, y, im, bbox, clippath=None, clippath_trans=None)
becomes:
draw_image(self, gc, x, y, im)
• MGD
2009-08-06 Tagging the 0.99.0 release at svn r7397 - JDH
• fixed an alpha colormapping bug posted on sf 2832575
• fix typo in axes_divider.py. use nanmin, nanmax in angle_helper.py (patch by Christoph Gohlke)
• remove dup gui event in enter/leave events in gtk
• lots of fixes for os x binaries (Thanks Russell Owen)
• attach gtk events to mpl events – fixes sf bug 2816580
• applied sf patch 2815064 (middle button events for wx) and patch 2818092 (resize events for wx)
• fixed boilerplate.py so it doesn’t break the ReST docs.
322
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
• removed a couple of cases of mlab.load
• fixed rec2csv win32 file handle bug from sf patch 2831018
• added two examples from Josh Hemann: examples/pylab_examples/barchart_demo2.py and examples/pylab_examples/boxplot_demo2.py
• handled sf bugs 2831556 and 2830525; better bar error messages and backend driver configs
• added miktex win32 patch from sf patch 2820194
• apply sf patches 2830233 and 2823885 for osx setup and 64 bit; thanks Michiel
2009-08-04 Made cbook.get_sample_data make use of the ETag and Last-Modified headers
mod_dav_svn. - JKS
of
2009-08-03 Add PathCollection; modify contourf to use complex paths instead of simple paths with
cuts. - EF
2009-08-03 Fixed boilerplate.py so it doesn’t break the ReST docs. - JKS
2009-08-03 pylab no longer provides a load and save function. These are available in matplotlib.mlab,
or you can use numpy.loadtxt and numpy.savetxt for text files, or np.save and np.load for binary numpy
arrays. - JDH
2009-07-31 Added cbook.get_sample_data for urllib enabled fetching and cacheing of data needed for
examples. See examples/misc/sample_data_demo.py - JDH
2009-07-31 Tagging 0.99.0.rc1 at 7314 - MGD
2009-07-30 Add set_cmap and register_cmap, and improve get_cmap, to provide convenient handling
of user-generated colormaps. Reorganized _cm and cm modules. - EF
2009-07-28 Quiver speed improved, thanks to tip by Ray Speth. -EF
2009-07-27 Simplify argument handling code for plot method. -EF
2009-07-25 Allow “plot(1, 2, ‘r*’)” to work. - EF
2009-07-22 Added an ‘interp’ keyword to griddata so the faster linear interpolation method can be
chosen. Default is ‘nn’, so default behavior (using natural neighbor method) is unchanged (JSW)
2009-07-22 Improved boilerplate.py so that it generates the correct signatures for pyplot functions. JKS
2009-07-19 Fixed the docstring of Axes.step to reflect the correct meaning of the kwargs “pre” and
“post” - See SF bug https://sourceforge.net/tracker/index.php?func=detail&aid=2823304&group_id=
80706&atid=560720 - JDH
2009-07-18 Fix support for hatches without color fills to pdf and svg backends.
that to hatch_demo.py. - JKS
Add an example of
2009-07-17 Removed fossils from swig version of agg backend. - EF
2009-07-14 initial submission of the annotation guide. -JJL
2009-07-14 axes_grid [minor improvements in anchored_artists and] inset_locator. -JJL
2009-07-14 Fix a few bugs in ConnectionStyle algorithms. Add ConnectionPatch class. -JJL
5.2. Previous Whats New
323
Matplotlib, Release 2.1.2
2009-07-11 Added a fillstyle Line2D property for half filled markers –
ples/pylab_examples/fillstyle_demo.py JDH
see
exam-
2009-07-08 Attempt to improve performance of qt4 backend, do not call qApp.processEvents
processing an event. Thanks Ole Streicher for tracking this down - DSD
while
2009-06-24 Add withheader option to mlab.rec2csv and changed use_mrecords default to False in
mlab.csv2rec since this is partially broken - JDH
2009-06-24 backend_agg.draw_marker quantizes the main path (as in the draw_path). - JJL
2009-06-24 axes_grid: floating axis support added. - JJL
2009-06-14 Add new command line options to backend_driver.py to support running only some directories of tests - JKS
2009-06-13 partial cleanup of mlab and its importation in pylab - EF
2009-06-13 Introduce a rotation_mode property for the Text artist. See
examples/pylab_examples/demo_text_rotation_mode.py -JJL
2009-06-07 add support for bz2 files per sf support request 2794556 - JDH
2009-06-06 added a properties method to the artist and inspector to return a dict mapping property
name -> value; see sf feature request 2792183 - JDH
2009-06-06 added Neil’s auto minor tick patch; sf patch #2789713 - JDH
2009-06-06 do not apply alpha to rgba color conversion if input is already rgba - JDH
2009-06-03 axes_grid [Initial check-in of curvelinear
ples/axes_grid/demo_curvelinear_grid.py - JJL
grid
support.
See]
exam-
2009-06-01 Add set_color method to Patch - EF
2009-06-01 Spine is now derived from Patch - ADS
2009-06-01 use cbook.is_string_like() instead of isinstance() for spines - ADS
2009-06-01 cla() support for spines - ADS
2009-06-01 Removed support for gtk < 2.4. - EF
2009-05-29 Improved the animation_blit_qt4 example, which was a mix of the object-oriented and pylab interfaces. It is now strictly object-oriented - DSD
2009-05-28 Fix axes_grid toolkit to work with spine patch by ADS. - JJL
2009-05-28 Applied fbianco’s patch to handle scroll wheel events in the qt4 backend - DSD
2009-05-26 Add support for “axis spines” to have arbitrary location. -ADS
2009-05-20 Add an empty matplotlibrc to the tests/ directory so that running tests will use the default
set of rcparams rather than the user’s config. - RMM
2009-05-19 Axis.grid(): allow use of which=’major,minor’ to have grid on major and minor ticks. ADS
2009-05-18 Make psd(), csd(), and cohere() wrap properly for complex/two-sided versions, like specgram() (SF #2791686) - RMM
324
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2009-05-18 Fix the linespacing bug of multiline text (#1239682). See examples/pylab_examples/multiline.py
-JJL
2009-05-18 Add annotation_clip attr. for text.Annotation class. If True, annotation is only drawn when
the annotated point is inside the axes area. -JJL
2009-05-17 Fix bug(#2749174) that some properties of minor ticks are not conserved -JJL
2009-05-17 applied Michiel’s sf patch 2790638 to turn off gtk event loop
pygtk>=2.15.10 - JDH
in
setupext
for
2009-05-17 applied Michiel’s sf patch 2792742 to speed up Cairo and macosx collections; speedups
can be 20x. Also fixes some bugs in which gc got into inconsistent state
2008-05-17 Release 0.98.5.3 at r7107 from the branch - JDH
2009-05-13 An optional offset and bbox support in restore_bbox. Add animation_blit_gtk2.py. -JJL
2009-05-13 psfrag in backend_ps now uses baseline-alignment when preview.sty is used ((default is
bottom-alignment). Also, a small api imporvement in OffsetBox-JJL
2009-05-13 When the x-coordinate of a line is monotonically increasing, it is now automatically
clipped at the stage of generating the transformed path in the draw method; this greatly speeds up
zooming and panning when one is looking at a short segment of a long time series, for example. - EF
2009-05-11 aspect=1 in log-log plot gives square decades. -JJL
2009-05-08 clabel takes new kwarg, rightside_up; if False, labels will not be flipped to keep them
rightside-up. This allows the use of clabel to make streamfunction arrows, as requested by Evan
Mason. - EF
2009-05-07 ‘labelpad’ can now be passed when setting x/y labels. This allows controlling the spacing
between the label and its axis. - RMM
2009-05-06 print_ps now uses mixed-mode renderer. Axes.draw rasterize artists whose zorder smaller
than rasterization_zorder. -JJL
2009-05-06 Per-artist Rasterization, originally by Eric Bruning. -JJ
2009-05-05 Add an example that shows how to make a plot that updates using data from another process. Thanks to Robert Cimrman - RMM
2009-05-05 Add Axes.get_legend_handles_labels method. - JJL
2009-05-04 Fix bug that Text.Annotation is still drawn while set to not visible. - JJL
2009-05-04 Added TJ’s fill_betweenx patch - JDH
2009-05-02 Added options to plotfile based on question from Joseph Smidt and patch by Matthias
Michler. - EF
2009-05-01 Changed add_artist and similar Axes methods to return their argument. - EF
2009-04-30 Incorrect eps bbox for landscape mode fixed - JJL
2009-04-28 Fixed incorrect bbox of eps output when usetex=True. - JJL
5.2. Previous Whats New
325
Matplotlib, Release 2.1.2
2009-04-24 Changed use of os.open* to instead use subprocess.Popen. os.popen* are deprecated in 2.6
and are removed in 3.0. - RMM
2009-04-20 Worked on axes_grid documentation. Added axes_grid.inset_locator. - JJL
2009-04-17 Initial check-in of the axes_grid toolkit. - JJL
2009-04-17 Added a support for bbox_to_anchor in offsetbox.AnchoredOffsetbox. Improved a documentation. - JJL
2009-04-16 Fixed a offsetbox bug that multiline texts are not correctly aligned. - JJL
2009-04-16 Fixed a bug in mixed mode renderer that images produced by an rasterizing backend are
placed with incorrect size. - JJL
2009-04-14 Added Jonathan Taylor’s Reinier Heeres’ port of John Porters’ mplot3d to svn trunk.
Package in mpl_toolkits.mplot3d and demo is examples/mplot3d/demo.py. Thanks Reiner
2009-04-06 The pdf backend now escapes newlines and linefeeds in strings. Fixes sf bug #2708559;
thanks to Tiago Pereira for the report.
2009-04-06 texmanager.make_dvi now raises an error if LaTeX failed to create an output file. Thanks
to Joao Luis Silva for reporting this. - JKS
2009-04-05 _png.read_png() reads 12 bit PNGs (patch from Tobias Wood) - ADS
2009-04-04 Allow log axis scale to clip non-positive values to small positive value; this is useful for errorbars. - EF
2009-03-28 Make images handle nan in their array argument. A helper, cbook.safe_masked_invalid()
was added. - EF
2009-03-25 Make contour and contourf handle nan in their Z argument. - EF
2009-03-20 Add AuxTransformBox in offsetbox.py to support some transformation.
anchored_text.py example is enhanced and renamed (anchored_artists.py). - JJL
2009-03-20 Add “bar” connection style for annotation - JJL
2009-03-17 Fix bugs in edge color handling by contourf, found by Jae-Joon Lee. - EF
2009-03-14 Added ‘LightSource’ class to colors module for creating shaded relief maps.
ing_example.py added to illustrate usage. - JSW
shad-
2009-03-11 Ensure wx version >= 2.8; thanks to Sandro Tosi and Chris Barker. - EF
2009-03-10 Fix join style bug in pdf. - JKS
2009-03-07 Add pyplot access to figure number list - EF
2009-02-28 hashing of FontProperties accounts current rcParams - JJL
2009-02-28 Prevent double-rendering of shared axis in twinx, twiny - EF
2009-02-26 Add optional bbox_to_anchor argument for legend class - JJL
2009-02-26 Support image clipping in pdf backend. - JKS
2009-02-25 Improve tick location subset choice in FixedLocator. - EF
326
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2009-02-24 Deprecate numerix, and strip out all but the numpy part of the code. - EF
2009-02-21 Improve scatter argument handling; add an early error message, allow inputs to have
more than one dimension. - EF
2009-02-16 Move plot_directive.py to the installed source tree. Add support for inline code content MGD
2009-02-16 Move mathmpl.py to the installed source tree so it is available to other projects. - MGD
2009-02-14 Added the legend title support - JJL
2009-02-10 Fixed a bug in backend_pdf so it doesn’t break when the setting
pdf.use14corefonts=True is used. Added test case in unit/test_pdf_use14corefonts.py. - NGR
2009-02-08 Added a new imsave function to image.py and exposed it in the pyplot interface - GR
2009-02-04 Some reorgnization of the legend code. anchored_text.py added as an example. - JJL
2009-02-04 Add extent keyword arg to hexbin - ADS
2009-02-04 Fix bug in mathtext related to dots and ldots - MGD
2009-02-03 Change default joinstyle to round - MGD
2009-02-02 Reduce number of marker XObjects in pdf output - JKS
2009-02-02 Change default resolution on polar plot to 1 - MGD
2009-02-02 Avoid malloc errors in ttconv for fonts that don’t have e.g.,
Tahoma triggered this) - JKS
PostName (a version of
2009-01-30 Remove support for pyExcelerator in exceltools – use xlwt instead - JDH
2009-01-29 Document ‘resolution’ kwarg for polar plots. Support it when using pyplot.polar, not just
Figure.add_axes. - MGD
2009-01-29 Rework the nan-handling/clipping/quantizing/simplification framework so each is an independent part of a pipeline. Expose the C++-implementation of all of this so it can be used from all
Python backends. Add rcParam “path.simplify_threshold” to control the threshold of similarity below
which vertices will be removed.
2009-01-26 Improved tight bbox option of the savefig. - JJL
2009-01-26 Make curves and NaNs play nice together - MGD
2009-01-21 Changed the defaults of acorr and xcorr to use usevlines=True,
normed=True since these are the best defaults
maxlags=10
and
2009-01-19 Fix bug in quiver argument handling. - EF
2009-01-19 Fix bug in backend_gtk: don’t delete nonexistent toolbar. - EF
2009-01-16 Implement bbox_inches option for savefig. If bbox_inches is “tight”, try to determine the
tight bounding box. - JJL
2009-01-16 Fix bug in is_string_like so it doesn’t raise an unnecessary exception. - EF
2009-01-16 Fix an infinite recursion in the unit registry when searching for a converter for a sequence
of strings. Add a corresponding test. - RM
5.2. Previous Whats New
327
Matplotlib, Release 2.1.2
2009-01-16 Bugfix of C typedef of MPL_Int64 that was failing on Windows XP 64 bit, as reported by
George Goussard on numpy mailing list. - ADS
2009-01-16 Added helper function LinearSegmentedColormap.from_list to facilitate building simple
custom colomaps. See examples/pylab_examples/custom_cmap_fromlist.py - JDH
2009-01-16 Applied Michiel’s patch for macosx backend to fix rounding bug. Closed sf bug 2508440 JSW
2009-01-10 Applied Michiel’s hatch patch for macosx backend and draw_idle patch for qt. Closes sf
patched 2497785 and 2468809 - JDH
2009-01-10 Fix bug in pan/zoom with log coordinates. - EF
2009-01-06 Fix bug in setting of dashed negative contours. - EF
2009-01-06 Be fault tolerant when len(linestyles)>NLev in contour. - MM
2009-01-06 Added marginals kwarg to hexbin to plot marginal densities JDH
2009-01-06 Change user-visible multipage pdf object to PdfPages to avoid accidents with the file-like
PdfFile. - JKS
2009-01-05 Fix a bug in pdf usetex: allow using non-embedded fonts. - JKS
2009-01-05 optional use of preview.sty in usetex mode. - JJL
2009-01-02 Allow multipage pdf files. - JKS
2008-12-31 Improve pdf usetex by adding support for font effects (slanting and extending). - JKS
2008-12-29 Fix a bug in pdf usetex support, which occurred if the same Type-1 font was used with different encodings, e.g., with Minion Pro and MnSymbol. - JKS
2008-12-20 fix the dpi-dependent offset of Shadow. - JJL
2008-12-20 fix the hatch bug in the pdf backend. minor update in docs and example - JJL
2008-12-19 Add axes_locator attribute in Axes. Two examples are added.
• JJL
2008-12-19 Update Axes.legend documnetation. /api/api_changes.rst is also updated to
chages in keyword parameters. Issue a warning if old keyword parameters are used. - JJL
describe
2008-12-18 add new arrow style, a line + filled triangles. -JJL
2008-12-18 Re-Released 0.98.5.2 from v0_98_5_maint at r6679 Released
v0_98_5_maint at r6667
0.98.5.2
from
2008-12-18 Removed configobj, experimental traits and doc/mpl_data link - JDH
2008-12-18 Fix bug where a line with NULL data limits prevents subsequent data limits from calculating correctly - MGD
2008-12-17 Major documentation generator changes - MGD
2008-12-17 Applied macosx backend patch with support for path collections, quadmesh, etc. . . - JDH
328
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-12-17 fix dpi-dependent behavior of text bbox and arrow in annotate -JJL
2008-12-17 Add group id support in artist. Two examples which demostrate svg filter are added. -JJL
2008-12-16 Another attempt to fix dpi-dependent behavior of Legend. -JJL
2008-12-16 Fixed dpi-dependent behavior of Legend and fancybox in Text.
2008-12-16 Added markevery property to Line2D to support subsampling of markers - JDH
2008-12-15 Removed mpl_data symlink in docs. On platforms that do not support symlinks, these become copies, and the font files are large, so the distro becomes unneccessarily bloaded. Keeping the
mpl_examples dir because relative links are harder for the plot directive and the *.py files are not so
large. - JDH
2008-12-15 Fix $ in non-math text with usetex off. Document differences between usetex on/off MGD
2008-12-15 Fix anti-aliasing when auto-snapping - MGD
2008-12-15 Fix grid lines not moving correctly during pan and zoom - MGD
2008-12-12 Preparations to eliminate maskedarray rcParams key: its use will now generate a warning. Similarly, importing the obsolote numerix.npyma will generate a warning. - EF
2008-12-12 Added support for the numpy.histogram() weights parameter to the axes hist() method.
Docs taken from numpy - MM
2008-12-12 Fixed warning in hist() with numpy 1.2 - MM
2008-12-12 Removed external packages: configobj and enthought.traits which are only required by
the experimental traited config and are somewhat out of date. If needed, install them independently,
see:
http://code.enthought.com/projects/traits
and:
http://www.voidspace.org.uk/python/configobj.html
2008-12-12 Added support to asign labels to histograms of multiple data. - MM
2008-12-11 Released 0.98.5 at svn r6573
2008-12-11 Use subprocess.Popen instead of os.popen in dviread (Windows problem reported by Jorgen Stenarson) - JKS
2008-12-10 Added Michael’s font_manager fix and Jae-Joon’s figure/subplot fix.
number to 0.98.5 - JDH
Bumped version
2008-12-09 Released 0.98.4 at svn r6536
2008-12-08 Added mdehoon’s native macosx backend from sf patch 2179017 - JDH
2008-12-08 Removed the prints in the set_*style commands. Return the list of pprinted strings instead
- JDH
5.2. Previous Whats New
329
Matplotlib, Release 2.1.2
2008-12-08 Some of the changes Michael made to improve the output of the property tables in the rest
docs broke of made difficult to use some of the interactive doc helpers, e.g., setp and getp. Having
all the rest markup in the ipython shell also confused the docstrings. I added a new rc param docstring.harcopy, to format the docstrings differently for hardcopy and other use. Ther ArtistInspector
could use a little refactoring now since there is duplication of effort between the rest out put and the
non-rest output - JDH
2008-12-08 Updated spectral methods (psd, csd, etc.) to scale one-sided densities by a factor of 2 and,
optionally, scale all densities by the sampling frequency. This gives better MatLab compatibility. -RM
2008-12-08 Fixed alignment of ticks in colorbars. -MGD
2008-12-07 drop the deprecated “new” keyword of np.histogram() for numpy 1.2 or later. -JJL
2008-12-06 Fixed a bug in svg backend that new_figure_manager() ignores keywords arguments such
as figsize, etc. -JJL
2008-12-05 Fixed a bug that the handlelength of the new legend class set too short when numpoints=1
-JJL
2008-12-04 Added support for data with units (e.g., dates) to Axes.fill_between. -RM
2008-12-04 Added fancybox keyword to legend. Also applied some changes for better look, including
baseline adjustment of the multiline texts so that it is center aligned. -JJL
2008-12-02 The transmuter classes in the patches.py are reorganized as subclasses
classes. A few more box and arrow styles are added. -JJL
of
the
Style
2008-12-02 Fixed a bug in the new legend class that didn’t allowed a tuple of coordinate vlaues as loc.
-JJL
2008-12-02 Improve checks for external dependencies, using subprocess (instead
popen*) and distutils (for version checking) - DSD
of
deprecated
2008-11-30 Reimplementation of the legend which supports baseline alignement, multi-column, and
expand mode. - JJL
2008-12-01 Fixed histogram autoscaling bug when bins or range are given explicitly (fixes Debian
bug 503148) - MM
2008-11-25 Added rcParam axes.unicode_minus which allows plain hypen for minus when False JDH
2008-11-25 Added scatterpoints support in Legend. patch by Erik Tollerud - JJL
2008-11-24 Fix crash in log ticking. - MGD
2008-11-20 Added static helper method BrokenHBarCollection.span_where and Axes/pyplot method
fill_between. See examples/pylab/fill_between.py - JDH
2008-11-12 Add x_isdata and y_isdata attributes to Artist instances, and use them to determine
whether either or both coordinates are used when updating dataLim. This is used to fix autoscaling
problems that had been triggered by axhline, axhspan, axvline, axvspan. - EF
2008-11-11 Update the psd(), csd(), cohere(), and specgram() methods of Axes and the csd() cohere(),
and specgram() functions in mlab to be in sync with the changes to psd(). In fact, under the hood,
these all call the same core to do computations. - RM
330
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-11-11 Add ‘pad_to’ and ‘sides’ parameters to mlab.psd() to allow controlling of zero padding
and returning of negative frequency components, respecitively. These are added in a way that does
not change the API. - RM
2008-11-10 Fix handling of c kwarg by scatter; generalize is_string_like
numpy.ma string array scalars. - RM and EF
to
accept
numpy
and
2008-11-09 Fix a possible EINTR problem in dviread, which might help when saving pdf files from
the qt backend. - JKS
2008-11-05 Fix bug with zoom to rectangle and twin axes - MGD
2008-10-24 Added Jae Joon’s fancy arrow, box and annotation enhancements
ples/pylab_examples/annotation_demo2.py
–
see
exam-
2008-10-23 Autoscaling is now supported with shared axes - EF
2008-10-23 Fixed exception in dviread that happened with Minion - JKS
2008-10-21 set_xlim, ylim now return a copy of the viewlim array to avoid modify inplace surprises
2008-10-20 Added image thumbnail generating function matplotlib.image.thumbnail.
ples/misc/image_thumbnail.py - JDH
See exam-
2008-10-20 Applied scatleg patch based on ideas and work by Erik Tollerud and Jae-Joon Lee. - MM
2008-10-11 Fixed bug in pdf backend: if you pass a file object for output instead of a filename, e.g., in
a wep app, we now flush the object at the end. - JKS
2008-10-08 Add path simplification support to paths with gaps. - EF
2008-10-05 Fix problem with AFM files that don’t specify the font’s full name or family name. - JKS
2008-10-04 Added ‘scilimits’ kwarg to Axes.ticklabel_format() method, for
set_powerlimits method of the major ScalarFormatter. - EF
easy
access
to
the
2008-10-04 Experimental new kwarg borderpad to replace pad in legend, based on suggestion by JaeJoon Lee. - EF
2008-09-27 Allow spy to ignore zero values in sparse arrays, based on patch by Tony Yu. Also fixed
plot to handle empty data arrays, and fixed handling of markers in figlegend. - EF
2008-09-24 Introduce drawstyles for lines. Transparently split linestyles like ‘steps–’ into drawstyle
‘steps’ and linestyle ‘–’. Legends always use drawstyle ‘default’. - MM
2008-09-18 Fixed quiver and quiverkey bugs (failure to scale properly when resizing) and added additional methods for determining the arrow angles - EF
2008-09-18 Fix polar interpolation to handle negative values of theta - MGD
2008-09-14 Reorganized cbook and mlab methods related to numerical calculations that have little to
do with the goals of those two modules into a separate module numerical_methods.py Also, added
ability to select points and stop point selection with keyboard in ginput and manual contour labeling
code. Finally, fixed contour labeling bug. - DMK
2008-09-11 Fix backtick in Postscript output. - MGD
5.2. Previous Whats New
331
Matplotlib, Release 2.1.2
2008-09-10 [ 2089958 ] Path simplification for vector output backends Leverage the simplification
code exposed through path_to_polygons to simplify certain well-behaved paths in the vector
backends (PDF, PS and SVG). “path.simplify” must be set to True in matplotlibrc for this to work. MGD
2008-09-10 Add “filled” kwarg to Path.intersects_path and Path.intersects_bbox. - MGD
2008-09-07 Changed full arrows slightly to avoid an xpdf rendering problem reported by Friedrich
Hagedorn. - JKS
2008-09-07 Fix conversion of quadratic to cubic Bezier curves in PDF and PS backends. Patch by JaeJoon Lee. - JKS
2008-09-06 Added 5-point star marker to plot command - EF
2008-09-05 Fix hatching in PS backend - MGD
2008-09-03 Fix log with base 2 - MGD
2008-09-01 Added support for bilinear interpolation in NonUniformImage; patch by Gregory Lielens.
- EF
2008-08-28 Added support for multiple histograms with data of different length - MM
2008-08-28 Fix step plots with log scale - MGD
2008-08-28 Fix masked arrays with markers in non-Agg backends - MGD
2008-08-28 Fix clip_on kwarg so it actually works correctly - MGD
2008-08-25 Fix locale problems in SVG backend - MGD
2008-08-22 fix quiver so masked values are not plotted - JSW
2008-08-18 improve interactive pan/zoom in qt4 backend on windows - DSD
2008-08-11 Fix more bugs in NaN/inf handling. In particular, path simplification (which does not
handle NaNs or infs) will be turned off automatically when infs or NaNs are present. Also masked
arrays are now converted to arrays with NaNs for consistent handling of masks and NaNs - MGD and
EF
2008-08-03 Released 0.98.3 at svn r5947
2008-08-01 Backported memory leak fixes in _ttconv.cpp - MGD
2008-07-31 Added masked array support to griddata. - JSW
2008-07-26 Added optional C and reduce_C_function arguments to axes.hexbin(). This allows hexbin
to accumulate the values of C based on the x,y coordinates and display in hexagonal bins. - ADS
2008-07-24 Deprecated (raise NotImplementedError) all the mlab2 functions from matplotlib.mlab
out of concern that some of them were not clean room implementations. JDH
2008-07-24 Rewrite of a significant portion of the clabel code (class ContourLabeler) to improve inlining. - DMK
332
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-07-22 Added Barbs polygon collection (similar to Quiver) for plotting wind barbs. Added corresponding helpers to Axes and pyplot as well. (examples/pylab_examples/barb_demo.py shows it off.)
- RMM
2008-07-21 Added scikits.delaunay as matplotlib.delaunay. Added griddata function
in
matplotlib.mlab, with example (griddata_demo.py) in pylab_examples. griddata function will use
mpl_toolkits._natgrid if installed. - JSW
2008-07-21 Re-introduced offset_copy that works in the context of the new transforms. - MGD
2008-07-21 Committed patch by Ryan May to add get_offsets and set_offsets to Collections base class
- EF
2008-07-21 Changed the “asarray” strategy in image.py so that colormapping of masked input should
work for all image types (thanks Klaus Zimmerman) - EF
2008-07-20 Rewrote cbook.delete_masked_points and corresponding unit test to support rgb color array inputs, datetime inputs, etc. - EF
2008-07-20 Renamed unit/axes_unit.py to cbook_unit.py and modified in accord with Ryan’s move of
delete_masked_points from axes to cbook. - EF
2008-07-18 Check for nan and inf in axes.delete_masked_points(). This should help hexbin and scatter
deal with nans. - ADS
2008-07-17 Added ability to manually select contour label locations. Also added a waitforbuttonpress
function. - DMK
2008-07-17 Fix bug with NaNs at end of path (thanks, Andrew Straw for the report) - MGD
2008-07-16 Improve error handling in texmanager, thanks to Ian Henry for reporting - DSD
2008-07-12 Added support for external backends with the “module://my_backend” syntax - JDH
2008-07-11 Fix memory leak related to shared axes. Grouper should store weak references. - MGD
2008-07-10 Bugfix: crash displaying fontconfig pattern - MGD
2008-07-10 Bugfix: [ 2013963 ] update_datalim_bounds in Axes not works - MGD
2008-07-10 Bugfix: [ 2014183 ] multiple imshow() causes gray edges - MGD
2008-07-09 Fix rectangular axes patch on polar plots bug - MGD
2008-07-09 Improve mathtext radical rendering - MGD
2008-07-08 Improve mathtext superscript placement - MGD
2008-07-07 Fix custom scales in pcolormesh (thanks Matthew Turk) - MGD
2008-07-03 Implemented findobj method for artist and pyplot - see examples/pylab_examples/findobj_demo.py
- JDH
2008-06-30 Another attempt to fix TextWithDash - DSD
2008-06-30 Removed Qt4 NavigationToolbar2.destroy – it appears to have been unnecessary and
caused a bug reported by P. Raybaut - DSD
2008-06-27 Fixed tick positioning bug - MM
5.2. Previous Whats New
333
Matplotlib, Release 2.1.2
2008-06-27 Fix dashed text bug where text was at the wrong end of the dash - MGD
2008-06-26 Fix mathtext bug for expressions like $x_{leftarrow}$ - MGD
2008-06-26 Fix direction of horizontal/vertical hatches - MGD
2008-06-25 Figure.figurePatch renamed Figure.patch, Axes.axesPatch renamed
Axes.patch,
Axes.axesFrame renamed Axes.frame, Axes.get_frame, which returns Axes.patch, is deprecated.
Examples and users guide updated - JDH
2008-06-25 Fix rendering quality of pcolor - MGD
2008-06-24 Released 0.98.2 at svn r5667 - (source only for debian) JDH
2008-06-24 Added “transparent” kwarg to savefig. - MGD
2008-06-24 Applied Stefan’s patch to draw a single centered marker over a line with numpoints==1 JDH
2008-06-23 Use splines to render circles in scatter plots - MGD
2008-06-22 Released 0.98.1 at revision 5637
2008-06-22 Removed axes3d support and replaced it with a NotImplementedError for one release cycle
2008-06-21 fix marker placement bug in backend_ps - DSD
2008-06-20 [ 1978629 ] scale documentation missing/incorrect for log - MGD
2008-06-20 Added closed kwarg to PolyCollection. Fixes bug [ 1994535 ] still missing lines on graph
with svn (r 5548). - MGD
2008-06-20 Added set/get_closed method to Polygon; fixes error in hist - MM
2008-06-19 Use relative font sizes (e.g., ‘medium’ and ‘large’) in rcsetup.py and matplotlibrc.template
so that text will be scaled by default when changing rcParams[‘font.size’] - EF
2008-06-17 Add a generic PatchCollection class that can contain any kind of patch. - MGD
2008-06-13 Change pie chart label alignment to avoid having labels overwrite the pie - MGD
2008-06-12 Added some helper functions to the mathtext parser to return bitmap arrays or write pngs
to make it easier to use mathtext outside the context of an mpl figure. modified the mathpng sphinxext
to use the mathtext png save functionality - see examples/api/mathtext_asarray.py - JDH
2008-06-11 Use matplotlib.mathtext to render math expressions in online docs - MGD
2008-06-11 Move PNG loading/saving to its own extension module, and remove duplicate code in
_backend_agg.cpp and _image.cpp that does the same thing - MGD
2008-06-11 Numerous mathtext bugfixes, primarily related to dpi-independence - MGD
2008-06-10 Bar now applies the label only to the first patch only, and sets ‘_nolegend_’ for the other
patch labels. This lets autolegend work as expected for hist and bar - see https://sourceforge.net/
tracker/index.php?func=detail&aid=1986597&group_id=80706&atid=560720 JDH
334
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-06-10 Fix text baseline alignment bug. [ 1985420 ] Repair of baseline
Text._get_layout. Thanks Stan West - MGD
alignment
in
2008-06-09 Committed Gregor’s image resample patch to downsampling images with new rcparam
image.resample - JDH
2008-06-09 Don’t install Enthought.Traits along with matplotlib. For matplotlib developers convenience, it can still be installed by setting an option in setup.cfg while we figure decide if there is
a future for the traited config - DSD
2008-06-09 Added range keyword arg to hist() - MM
2008-06-07 Moved list of backends to rcsetup.py; made use of lower case for backend names consistent; use validate_backend when importing backends subpackage - EF
2008-06-06 hist() revision, applied ideas proposed by Erik Tollerud and Olle Engdegard: make histtype=’step’ unfilled by default and introduce histtype=’stepfilled’; use default color cycle; introduce
reverse cumulative histogram; new align keyword - MM
2008-06-06 Fix closed polygon patch and also provide the option to not close the polygon - MGD
2008-06-05 Fix some dpi-changing-related problems with PolyCollection, as called by Axes.scatter() MGD
2008-06-05 Fix image drawing so there is no extra space to the right or bottom - MGD
2006-06-04 Added a figure title command suptitle as a Figure method and pyplot command – see examples/figure_title.py - JDH
2008-06-02 Added support for log to hist with histtype=’step’ and fixed a bug for log-scale stacked
histograms - MM
2008-05-29 Released 0.98.0 at revision 5314
2008-05-29 matplotlib.image.imread now no longer always returns RGBA – if the image is luminance
or RGB, it will return a MxN or MxNx3 array if possible. Also uint8 is no longer always forced to
float.
2008-05-29 Implement path clipping in PS backend - JDH
2008-05-29 Fixed two bugs in texmanager.py: improved comparison of dvipng versions fixed a bug introduced when get_grey method was added - DSD
2008-05-28 Fix crashing of PDFs in xpdf and ghostscript when two-byte characters are used with Type
3 fonts - MGD
2008-05-28 Allow keyword args to configure widget properties as requested in http://sourceforge.net/
tracker/index.php?func=detail&aid=1866207&group_id=80706&atid=560722 - JDH
2008-05-28 Replaced ‘-‘ with u’u2212’ for minus sign as requested in http://sourceforge.net/tracker/
index.php?func=detail&aid=1962574&group_id=80706&atid=560720
2008-05-28 zero width/height Rectangles no longer influence the autoscaler. Useful for log histograms
with empty bins - JDH
5.2. Previous Whats New
335
Matplotlib, Release 2.1.2
2008-05-28 Fix rendering of composite glyphs in Type 3 conversion (particularly as evidenced in the
Eunjin.ttf Korean font) Thanks Jae-Joon Lee for finding this!
2008-05-27 Rewrote the cm.ScalarMappable callback infrastructure to use cbook.CallbackRegistry
rather than custom callback handling. Amy users of add_observer/notify of the cm.ScalarMappable
should uae the cm.ScalarMappable.callbacksSM CallbackRegistry instead. JDH
2008-05-27 Fix TkAgg build on Ubuntu 8.04 (and hopefully a more general solution for other platforms, too.)
2008-05-24 Added PIL support for loading images to imread (if PIL is available) - JDH
2008-05-23 Provided a function and a method for controlling the plot color cycle. - EF
2008-05-23 Major revision of hist(). Can handle 2D arrays and create stacked histogram plots; keyword ‘width’ deprecated and rwidth (relative width) introduced; align=’edge’ changed to center of
bin - MM
2008-05-22 Added support for ReST-based doumentation using Sphinx. Documents are located in
doc/, and are broken up into a users guide and an API reference. To build, run the make.py files.
Sphinx-0.4 is needed to build generate xml, which will be useful for rendering equations with mathml,
use sphinx from svn until 0.4 is released - DSD
2008-05-21 Fix segfault in TkAgg backend - MGD
2008-05-21 Fix a “local variable unreferenced” bug in plotfile - MM
2008-05-19 Fix crash when Windows can not access the registry to determine font path [Bug 1966974,
thanks Patrik Simons] - MGD
2008-05-16 removed some unneeded code w/ the python 2.4 requirement. cbook no longer provides
compatibility for reversed, enumerate, set or izip. removed lib/subprocess, mpl1, sandbox/units, and
the swig code. This stuff should remain on the maintenance branch for archival purposes. JDH
2008-05-16 Reorganized examples dir - JDH
2008-05-16 Added ‘elinewidth’ keyword arg to errorbar, based on patch by Christopher Brown - MM
2008-05-16 Added ‘cumulative’ keyword arg to hist to plot cumulative histograms. For normed hists,
this is normalized to one - MM
2008-05-15 Fix Tk backend segfault on some machines - MGD
2008-05-14 Don’t use stat on Windows (fixes font embedding problem) - MGD
2008-05-09 Fix /singlequote (‘) in Postscript backend - MGD
2008-05-08 Fix kerning in SVG when embedding character outlines - MGD
2008-05-07 Switched to future numpy histogram semantic in hist - MM
2008-05-06 Fix strange colors when blitting in QtAgg and Qt4Agg - MGD
2008-05-05 pass notify_axes_change to the figure’s add_axobserver in the qt backends, like we do for
the other backends. Thanks Glenn Jones for the report - DSD
2008-05-02 Added step histograms, based on patch by Erik Tollerud. - MM
336
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-05-02 On PyQt <= 3.14 there is no way to determine the underlying Qt version.
MGD
[1851364] -
2008-05-02 Don’t call sys.exit() when pyemf is not found [1924199] - MGD
2008-05-02 Update _subprocess.c from upstream Python 2.5.2 to get a few memory and referencecounting-related bugfixes. See bug 1949978. - MGD
2008-04-30 Added some record array editing widgets for gtk – see examples/rec_edit*.py - JDH
2008-04-29 Fix bug in mlab.sqrtm - MM
2008-04-28 Fix bug in SVG text with Mozilla-based viewers (the symbol tag is not supported) - MGD
2008-04-27 Applied patch by Michiel de Hoon to add hexbin axes method and pyplot function - EF
2008-04-25 Enforce python >= 2.4; remove subprocess build - EF
2008-04-25 Enforce the numpy requirement at build time - JDH
2008-04-24 Make numpy 1.1 and python 2.3 required when importing matplotlib - EF
2008-04-24 Fix compilation issues on VS2003 (Thanks Martin Spacek for all the help) - MGD
2008-04-24 Fix sub/superscripts when the size of the font has been changed - MGD
2008-04-22 Use “svg.embed_char_paths” consistently everywhere - MGD
2008-04-20 Add support to MaxNLocator for symmetric axis autoscaling. - EF
2008-04-20 Fix double-zoom bug. - MM
2008-04-15 Speed up color mapping. - EF
2008-04-12 Speed up zooming and panning of dense images. - EF
2008-04-11 Fix global font rcParam setting after initialization time. - MGD
2008-04-11 Revert commits 5002 and 5031, which were intended to avoid an unnecessary call to
draw(). 5002 broke saving figures before show(). 5031 fixed the problem created in 5002, but broke
interactive plotting. Unnecessary call to draw still needs resolution - DSD
2008-04-07 Improve color validation in rc handling, suggested by Lev Givon - EF
2008-04-02 Allow to use both linestyle definition arguments, ‘-‘ and ‘solid’ etc. in plots/collections MM
2008-03-27 Fix saving to Unicode filenames with Agg backend (other backends appear to already
work. . . ) (Thanks, Christopher Barker) - MGD
2008-03-26 Fix SVG backend bug that prevents copying and pasting in Inkscape
Ghose) - MGD
(thanks
Kaushik
2008-03-24 Removed an unnecessary call to draw() in the backend_qt* mouseReleaseEvent. Thanks
to Ted Drain - DSD
2008-03-23 Fix a pdf backend bug which sometimes caused the outermost gsave to not be balanced
with a grestore. - JKS
2008-03-20 Fixed a minor bug in ContourSet._process_linestyles when len(linestyles)==Nlev - MM
5.2. Previous Whats New
337
Matplotlib, Release 2.1.2
2008-03-19 Changed ma import statements to “from numpy import ma”; this should work with past
and future versions of numpy, whereas “import numpy.ma as ma” will work only with numpy >=
1.05, and “import numerix.npyma as ma” is obsolete now that maskedarray is replacing the earlier
implementation, as of numpy 1.05.
2008-03-14 Removed an apparently unnecessary call to FigureCanvasAgg.draw in backend_qt*agg.
Thanks to Ted Drain - DSD
2008-03-10 Workaround a bug in backend_qt4agg’s blitting due to a buffer width/bbox width mismatch in _backend_agg’s copy_from_bbox - DSD
2008-02-29 Fix class Wx toolbar pan and zoom functions (Thanks Jeff Peery) - MGD
2008-02-16 Added some new rec array functionality to mlab (rec_summarize,
rec2txt
rec_groupby). See examples/rec_groupby_demo.py. Thanks to Tim M for rec2txt.
and
2008-02-12 Applied Erik Tollerud’s span selector patch - JDH
2008-02-11 Update plotting() doc string to refer to getp/setp. - JKS
2008-02-10 Fixed a problem with square roots in the pdf backend with usetex. - JKS
2008-02-08 Fixed minor __str__ bugs so getp(gca()) works. - JKS
2008-02-05 Added getters for title, xlabel, ylabel, as requested by Brandon Kieth - EF
2008-02-05 Applied Gael’s ginput patch and created examples/ginput_demo.py - JDH
2008-02-03 Expose interpnames, a list of valid interpolation methods, as an AxesImage class attribute.
- EF
2008-02-03 Added BoundaryNorm, with examples in colorbar_only.py and image_masked.py. - EF
2008-02-03 Force dpi=72 in pdf backend to fix picture size bug. - JKS
2008-02-01 Fix doubly-included font problem in Postscript backend - MGD
2008-02-01 Fix reference leak in ft2font Glyph objects. - MGD
2008-01-31 Don’t use unicode strings with usetex by default - DSD
2008-01-31 Fix text spacing problems in PDF backend with some fonts, such as STIXGeneral.
2008-01-31 Fix sqrt with radical number (broken by making [ and ] work below) - MGD
2008-01-27 Applied Martin Teichmann’s patch to improve the Qt4 backend. Uses Qt’s builtin toolbars
and statusbars. See bug 1828848 - DSD
2008-01-10 Moved toolkits to mpl_toolkits, made mpl_toolkits a namespace package - JSWHIT
2008-01-10 Use setup.cfg to set the default parameters (tkagg, numpy) when building windows installers - DSD
2008-01-10 Fix bug displaying [ and ] in mathtext - MGD
2008-01-10 Fix bug when displaying a tick value offset with scientific notation. (Manifests itself as a
warning that the times symbol can not be found). - MGD
2008-01-10 Use setup.cfg to set the default parameters (tkagg, numpy) when building windows installers - DSD
338
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2008-01-06 Released 0.91.2 at revision 4802
2007-12-26 Reduce too-late use of matplotlib.use() to a warning instead of an exception, for backwards
compatibility - EF
2007-12-25 Fix bug in errorbar, identified by Noriko Minakawa - EF
2007-12-25 Changed masked array importing to work with the upcoming numpy
maskedarray branch) as well as with earlier versions. - EF
1.05
(now
the
2007-12-16 rec2csv saves doubles without losing precision. Also, it does not close filehandles passed in
open. - JDH,ADS
2007-12-13 Moved rec2gtk to matplotlib.toolkits.gtktools and rec2excel to
plotlib.toolkits.exceltools - JDH
mat-
2007-12-12 Support alpha-blended text in the Agg and Svg backends - MGD
2007-12-10 Fix SVG text rendering bug. - MGD
2007-12-10 Increase accuracy of circle and ellipse drawing by using an 8-piece bezier approximation,
rather than a 4-piece one. Fix PDF, SVG and Cairo backends so they can draw paths (meaning
ellipses as well). - MGD
2007-12-07 Issue a warning when drawing an image on a non-linear axis. - MGD
2007-12-06 let widgets.Cursor initialize to the lower x and y bounds rather than 0,0, which can cause
havoc for dates and other transforms - DSD
2007-12-06 updated references to mpl data directories for py2exe - DSD
2007-12-06 fixed a bug in rcsetup, see bug 1845057 - DSD
2007-12-05 Fix how fonts are cached to avoid loading the same one multiple times. (This was a regression since 0.90 caused by the refactoring of font_manager.py) - MGD
2007-12-05 Support arbitrary rotation of usetex text in Agg backend. - MGD
2007-12-04 Support ‘|’ as a character in mathtext - MGD
2007-11-27 Released 0.91.1 at revision 4517
2007-11-27 Released 0.91.0 at revision 4478
2007-11-13 All backends now support writing to a file-like object, not just a regular file. savefig() can
be passed a file-like object in place of a file path. - MGD
2007-11-13 Improved the default backend selection at build time: SVG -> Agg -> TkAgg -> WXAgg
-> GTK -> GTKAgg. The last usable backend in this progression will be chosen in the default config
file. If a backend is defined in setup.cfg, that will be the default backend - DSD
2007-11-13 Improved creation of default config files at build time for traited config package - DSD
5.2. Previous Whats New
339
Matplotlib, Release 2.1.2
2007-11-12 Exposed all the build options in setup.cfg. These options are read into a dict called “options” by setupext.py. Also, added “-mpl” tags to the version strings for packages provided by matplotlib. Versions provided by mpl will be identified and updated on subsequent installs - DSD
2007-11-12 Added support for STIX fonts. A new rcParam, mathtext.fontset, can be used to choose between:
‘cm’: The TeX/LaTeX Computer Modern fonts
‘stix’: The STIX fonts (see stixfonts.org)
‘stixsans’: The STIX fonts, using sans-serif glyphs by default
‘custom’: A generic Unicode font, in which case the mathtext font must be specified using mathtext.bf, mathtext.it, mathtext.sf etc.
Added a new example, stix_fonts_demo.py to show how to access different fonts and unusual symbols.
• MGD
2007-11-12 Options to disable building backend extension modules moved from setup.py to setup.cfg
- DSD
2007-11-09 Applied Martin Teichmann’s patch 1828813: a QPainter is used in paintEvent, which has
to be destroyed using the method end(). If matplotlib raises an exception before the call to end - and
it does if you feed it with bad data - this method end() is never called and Qt4 will start spitting error
messages
2007-11-09 Moved pyparsing back into matplotlib namespace. Don’t use system pyparsing, API is too
variable from one release to the next - DSD
2007-11-08 Made pylab use straight numpy instead of oldnumeric by default - EF
2007-11-08 Added additional record array utilites to mlab (rec2excel, rec2gtk,
rec_append_field, rec_drop_field) - JDH
rec_join,
2007-11-08 Updated pytz to version 2007g - DSD
2007-11-08 Updated pyparsing to version 1.4.8 - DSD
2007-11-08 Moved csv2rec to recutils and added other record array utilities - JDH
2007-11-08 If available, use existing pyparsing installation - DSD
2007-11-07 Removed old enthought.traits from lib/matplotlib, added Gael
Varoquaux’s
enthought.traits-2.6b1, which is stripped of setuptools. The package is installed to site-packages if
not already available - DSD
2007-11-05 Added easy access to minor tick properties; slight mod of patch by Pierre G-M - EF
2007-11-02 Commited Phil Thompson’s patch 1599876, fixes to Qt4Agg backend and qt4 blitting
demo - DSD
2007-11-02 Commited Phil Thompson’s patch 1599876, fixes to Qt4Agg backend and qt4 blitting
demo - DSD
2007-10-31 Made log color scale easier to use with contourf; automatic level generation now works. EF
340
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2007-10-29 TRANSFORMS REFACTORING
The primary goal of this refactoring was to make it easier to extend matplotlib to support new
kinds of projections. This is primarily an internal improvement, and the possible user-visible
changes it allows are yet to come.
The transformation framework was completely rewritten in Python (with Numpy). This will
make it easier to add news kinds of transformations without writing C/C++ code.
Transforms are composed into a ‘transform tree’, made of transforms whose value depends
on other transforms (their children). When the contents of children change, their parents are
automatically updated to reflect those changes. To do this an “invalidation” method is used:
when children change, all of their ancestors are marked as “invalid”. When the value of a
transform is accessed at a later time, its value is recomputed only if it is invalid, otherwise
a cached value may be used. This prevents unnecessary recomputations of transforms, and
contributes to better interactive performance.
The framework can be used for both affine and non-affine transformations. However, for speed,
we want use the backend renderers to perform affine transformations whenever possible. Therefore, it is possible to perform just the affine or non-affine part of a transformation on a set of
data. The affine is always assumed to occur after the non-affine. For any transform:
full transform == non-affine + affine
Much of the drawing has been refactored in terms of compound paths. Therefore, many methods
have been removed from the backend interface and replaced with a a handful to draw compound
paths. This will make updating the backends easier, since there is less to update. It also should
make the backends more consistent in terms of functionality.
User visible changes:
• POLAR PLOTS: Polar plots are now interactively zoomable, and the r-axis labels can be
interactively rotated. Straight line segments are now interpolated to follow the curve of
the r-axis.
• Non-rectangular clipping works in more backends and with more types of objects.
• Sharing an axis across figures is now done in exactly the same way as sharing an axis
between two axes in the same figure:
fig1 = figure()
fig2 = figure()
ax1 = fig1.add_subplot(111)
ax2 = fig2.add_subplot(111, sharex=ax1, sharey=ax1)
• linestyles now include steps-pre, steps-post and steps-mid. The old step still works and is
equivalent to step-pre.
• Multiple line styles may be provided to a collection.
See API_CHANGES for more low-level information about this refactoring.
2007-10-24 Added ax kwarg to Figure.colorbar and pyplot.colorbar - EF
5.2. Previous Whats New
341
Matplotlib, Release 2.1.2
2007-10-19 Removed a gsave/grestore pair surrounding _draw_ps, which was causing a loss graphics
state info (see “EPS output problem - scatter & edgecolors” on mpl-dev, 2007-10-29) - DSD
2007-10-15 Fixed a bug in patches.Ellipse that was broken for aspect=’auto’. Scale free ellipses now
work properly for equal and auto on Agg and PS, and they fall back on a polygonal approximation
for nonlinear transformations until we convince oursleves that the spline approximation holds for
nonlinear transformations. Added unit/ellipse_compare.py to compare spline with vertex approx for
both aspects. JDH
2007-10-05 remove generator expressions from texmanager and mpltraits. generator expressions are
not supported by python-2.3 - DSD
2007-10-01 Made matplotlib.use() raise an exception if called after backends has been imported. - EF
2007-09-30 Modified update* methods of Bbox and Interval so they work with reversed axes. Prior to
this, trying to set the ticks on a reversed axis failed with an uninformative error message. - EF
2007-09-30 Applied patches to axes3d to fix index error problem - EF
2007-09-24 Applied Eike Welk’s patch reported on mpl-dev on 2007-09-22 Fixes a bug with multiple
plot windows in the qt backend, ported the changes to backend_qt4 as well - DSD
2007-09-21 Changed cbook.reversed to yield the same result as the python reversed builtin - DSD
2007-09-13 The usetex support in the pdf backend is more usable now, so I am enabling it. - JKS
2007-09-12 Fixed a Axes.bar unit bug - JDH
2007-09-10 Made skiprows=1 the default on csv2rec - JDH
2007-09-09 Split out the plotting part of pylab and put it in pyplot.py; removed numerix from the remaining pylab.py, which imports everything from pyplot.py. The intention is that apart from cleanups,
the result of importing from pylab is nearly unchanged, but there is the new alternative of importing
from pyplot to get the state-engine graphics without all the numeric functions. Numpified examples;
deleted two that were obsolete; modified some to use pyplot. - EF
2007-09-08 Eliminated gd and paint backends - EF
2007-09-06 .bmp file format is now longer an alias for .raw
2007-09-07 Added clip path support to pdf backend. - JKS
2007-09-06 Fixed a bug in the embedding of Type 1 fonts in PDF. Now it doesn’t crash Preview.app. JKS
2007-09-06 Refactored image saving code so that all GUI backends can save most image types. See
FILETYPES for a matrix of backends and their supported file types. Backend canvases should no
longer write their own print_figure() method – instead they should write a print_xxx method for each
filetype they can output and add an entry to their class-scoped filetypes dictionary. - MGD
2007-09-05 Fixed Qt version reporting in setupext.py - DSD
2007-09-04 Embedding Type 1 fonts in PDF, and thus usetex support via dviread, sort of works. To
test, enable it by renaming _draw_tex to draw_tex. - JKS
2007-09-03 Added ability of errorbar show limits via caret or arrowhead ends on the bars; patch by
Manual Metz. - EF
342
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2007-09-03 Created type1font.py, added features to AFM and FT2Font (see
started work on embedding Type 1 fonts in pdf files. - JKS
API_CHANGES),
2007-09-02 Continued work on dviread.py. - JKS
2007-08-16 Added a set_extent method to AxesImage, allow data extent to be modified after initial
call to imshow - DSD
2007-08-14 Fixed a bug in pyqt4 subplots-adjust. Thanks to Xavier Gnata for the report and suggested
fix - DSD
2007-08-13 Use pickle to cache entire fontManager; change to using font_manager module-level function findfont wrapper for the fontManager.findfont method - EF
2007-08-11 Numpification and cleanup of mlab.py and some examples - EF
2007-08-06 Removed mathtext2
2007-07-31 Refactoring of distutils scripts.
• Will not fail on the entire build if an optional Python package (e.g., Tkinter) is installed but its
development headers are not (e.g., tk-devel). Instead, it will continue to build all other extensions.
• Provide an overview at the top of the output to display what dependencies and their versions
were found, and (by extension) what will be built.
• Use pkg-config, when available, to find freetype2, since this was broken on Mac OS-X when
using MacPorts in a non- standard location.
2007-07-30 Reorganized configuration code to work with traited config objects. The new config system is located in the matplotlib.config package, but it is disabled by default. To enable it,
set NEWCONFIG=True in matplotlib.__init__.py. The new configuration system will still use
the old matplotlibrc files by default. To switch to the experimental, traited configuration, set
USE_TRAITED_CONFIG=True in config.__init__.py.
2007-07-29 Changed default pcolor shading to flat; added aliases to make collection kwargs agree with
setter names, so updating works; related minor cleanups. Removed quiver_classic, scatter_classic,
pcolor_classic. - EF
2007-07-26 Major rewrite of mathtext.py, using the TeX box layout model.
There is one (known) backward incompatible change. The font commands (cal, rm, it, tt) now
behave as TeX does: they are in effect until the next font change command or the end of the
grouping. Therefore uses of $cal{R}$ should be changed to ${cal R}$. Alternatively, you may
use the new LaTeX-style font commands (mathcal, mathrm, mathit, mathtt) which do affect the
following group, e.g., $mathcal{R}$.
Other new features include:
• Math may be interspersed with non-math text. Any text with an even number of $’s (nonescaped) will be sent to the mathtext parser for layout.
• Sub/superscripts are less likely to accidentally overlap.
• Support for sub/superscripts in either order, e.g., $x^i_j$ and $x_j^i$ are equivalent.
5.2. Previous Whats New
343
Matplotlib, Release 2.1.2
• Double sub/superscripts (e.g., $x_i_j$) are considered ambiguous and raise an exception.
Use braces to disambiguate.
• $frac{x}{y}$ can be used for displaying fractions.
• $sqrt[3]{x}$ can be used to display the radical symbol with a root number and body.
• $left(frac{x}{y}right)$ may be used to create parentheses and other delimiters that automatically resize to the height of their contents.
• Spacing around operators etc. is now generally more like TeX.
• Added support (and fonts) for boldface (bf) and sans-serif (sf) symbols.
• Log-like function name shortcuts are supported. For example, $sin(x)$ may be used instead of ${rm sin}(x)$
• Limited use of kerning for the easy case (same font)
Behind the scenes, the pyparsing.py module used for doing the math parsing was updated to the
latest stable version (1.4.6). A lot of duplicate code was refactored out of the Font classes.
• MGD
2007-07-19 completed numpification of most trivial cases - NN
2007-07-19 converted non-numpy relicts throughout the code - NN
2007-07-19 replaced the Python code in numerix/ by a minimal wrapper around numpy that explicitly mentions all symbols that need to be addressed for further numpification - NN
2007-07-18 make usetex respect changes to rcParams. texmanager used to only configure itself when
it was created, now it reconfigures when rcParams are changed. Thank you Alexander Schmolck for
contributing a patch - DSD
2007-07-17 added validation to setting and changing rcParams - DSD
2007-07-17 bugfix segfault in transforms module. Thanks Ben North for the patch. - ADS
2007-07-16 clean up some code in ticker.ScalarFormatter, use unicode to render multiplication sign in
offset ticklabel - DSD
2007-07-16 fixed a formatting bug in ticker.ScalarFormatter’s scientific notation (10^0 was being rendered as 10 in some cases) - DSD
2007-07-13 Add MPL_isfinite64() and MPL_isinf64() for testing doubles in (the now misnamed)
MPL_isnan.h. - ADS
2007-07-13 The matplotlib._isnan module removed (use numpy.isnan) - ADS
2007-07-13 Some minor cleanups in _transforms.cpp - ADS
2007-07-13 Removed the rest of the numerix extension code detritus, numpified axes.py, and cleaned
up the imports in axes.py - JDH
2007-07-13 Added legend.loc as configurable option that could in future default to ‘best’. - NN
2007-07-12 Bugfixes in mlab.py to coerce inputs into numpy arrays. -ADS
2007-07-11 Added linespacing kwarg to text.Text - EF
344
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2007-07-11 Added code to store font paths in SVG files. - MGD
2007-07-10 Store subset of TTF font as a Type 3 font in PDF files. - MGD
2007-07-09 Store subset of TTF font as a Type 3 font in PS files. - MGD
2007-07-09 Applied Paul’s pick restructure pick and add pickers, sourceforge patch 1749829 - JDH
2007-07-09 Applied Allan’s draw_lines agg optimization. JDH
2007-07-08 Applied Carl Worth’s patch to fix cairo draw_arc - SC
2007-07-07 fixed bug 1712099: xpdf distiller on windows - DSD
2007-06-30 Applied patches to tkagg, gtk, and wx backends to reduce memory leakage. Patches supplied by Mike Droettboom; see tracker numbers 1745400, 1745406, 1745408. Also made
unit/memleak_gui.py more flexible with command-line options. - EF
2007-06-30 Split defaultParams into separate file rcdefaults (together with validation code). Some
heavy refactoring was necessary to do so, but the overall behavior should be the same as before.
- NN
2007-06-27 Added MPLCONFIGDIR for the default location for mpl data and configuration. useful
for some apache installs where HOME is not writable. Tried to clean up the logic in _get_config_dir
to support non-writable HOME where are writable HOME/.matplotlib already exists - JDH
2007-06-27 Fixed locale bug reported at http://sourceforge.net/tracker/index.php?func=detail&aid=
1744154&group_id=80706&atid=560720 by adding a cbook.unicode_safe function - JDH
2007-06-27 Applied Micheal’s tk savefig bugfix described at http://sourceforge.net/tracker/index.php?
func=detail&aid=1716732&group_id=80706&atid=560720 Thanks Michael!
2007-06-27 Patch for get_py2exe_datafiles() to work with new directory layout.
also Werner Bruhin.) -ADS
(Thanks Tocer and
2007-06-27 Added a scroll event to the mpl event handling system and implemented it for backends
GTK* – other backend users/developers/maintainers, please add support for your backend. - JDH
2007-06-25 Changed default to clip=False in colors.Normalize; modified ColorbarBase for easier colormap display - EF
2007-06-13 Added maskedarray option to rc, numerix - EF
2007-06-11 Python 2.5 compatibility fix for mlab.py - EF
2007-06-10 In matplotlibrc file, use ‘dashed’ | ‘solid’ instead of
tour.negative_linestyle - EF
a
pair
of
floats
for
con-
2007-06-08 Allow plot and fill fmt string to be any mpl string colorspec - EF
2007-06-08 Added gnuplot file plotfile function to pylab – see examples/plotfile_demo.py - JDH
2007-06-07 Disable build of numarray and Numeric extensions for internal MPL use and the numerix
layer. - ADS
2007-06-07 Added csv2rec to matplotlib.mlab to support automatically converting csv files to record
arrays using type introspection, and turned on native datetime support using the new units support in
matplotlib.dates. See examples/loadrec.py ! JDH
5.2. Previous Whats New
345
Matplotlib, Release 2.1.2
2007-06-07 Simplified internal code of _auto_legend_data - NN
2007-06-04 Added labeldistance arg to Axes.pie to control the raidal distance of the wedge labels JDH
2007-06-03 Turned mathtext in SVG into single <text> with multiple <tspan> objects (easier to edit
in inkscape). - NN
2007-06-02 Released 0.90.1 at revision 3352
2007-06-02 Display only meaningful labels when calling legend() without args. - NN
2007-06-02 Have errorbar follow the color cycle even if line is not plotted. Suppress plotting of errorbar caps for capsize=0. - NN
2007-06-02 Set markers to same alpha value as line. - NN
2007-06-02 Fix mathtext position in svg backend. - NN
2007-06-01 Deprecate Numeric and numarray for use as numerix. Props to Travis – job well done. ADS
2007-05-18 Added LaTeX unicode support. Enable with the ‘text.latex.unicode’ rcParam.
quires the ucs and inputenc LaTeX packages. - ADS
This re-
2007-04-23 Fixed some problems with polar – added general polygon clipping to clip the lines a nd
grids to the polar axes. Added support for set_rmax to easily change the maximum radial grid. Added
support for polar legend - JDH
2007-04-16 Added Figure.autofmt_xdate to handle adjusting the bottom and rotating the tick labels
for date plots when the ticks often overlap - JDH
2007-04-09 Beginnings of usetex support for pdf backend. -JKS
2007-04-07 Fixed legend/LineCollection bug. Added label support to collections. - EF
2007-04-06 Removed deprecated support for a float value as a gray-scale; now it must be a string, like
‘0.5’. Added alpha kwarg to ColorConverter.to_rgba_list. - EF
2007-04-06 Fixed rotation of ellipses in pdf backend (sf bug #1690559) -JKS
2007-04-04 More matshow tweaks; documentation updates; new method set_bounds() for formatters
and locators. - EF
2007-04-02 Fixed problem with imshow and matshow of integer arrays; fixed problems with changes
to color autoscaling. - EF
2007-04-01 Made image color autoscaling work correctly with a tracking colorbar; norm.autoscale
now scales unconditionally, while norm.autoscale_None changes only None-valued vmin, vmax. EF
2007-03-31 Added a qt-based subplot-adjustment dialog - DSD
2007-03-30 Fixed a bug in backend_qt4, reported on mpl-dev - DSD
2007-03-26 Removed colorbar_classic from figure.py; fixed bug in Figure.clf() in which _axobservers
was not getting cleared. Modernization and cleanups. - EF
346
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2007-03-26 Refactored some of the units support – units now live in the respective x and y Axis instances. See also API_CHANGES for some alterations to the conversion interface. JDH
2007-03-25 Fix masked array handling in quiver.py for numpy. (Numeric and numarray support for
masked arrays is broken in other ways when using quiver. I didn’t pursue that.) - ADS
2007-03-23 Made font_manager.py close opened files. - JKS
2007-03-22 Made imshow default extent match matshow - EF
2007-03-22 Some more niceties for xcorr – a maxlags option, normed now works for xcorr as well as
axorr, usevlines is supported, and a zero correlation hline is added. See examples/xcorr_demo.py.
Thanks Sameer for the patch. - JDH
2007-03-21 Axes.vlines and Axes.hlines now create and returns a LineCollection, not a list of lines.
This is much faster. The kwarg signature has changed, so consult the docs. Modified Axes.errorbar
which uses vlines and hlines. See API_CHANGES; the return signature for these three functions is
now different
2007-03-20 Refactored units support and added new examples - JDH
2007-03-19 Added Mike’s units patch - JDH
2007-03-18 Matshow as an Axes method; test version matshow1() in pylab; added ‘integer’ Boolean
kwarg to MaxNLocator initializer to force ticks at integer locations. - EF
2007-03-17 Preliminary support for clipping to paths agg - JDH
2007-03-17 Text.set_text() accepts anything convertible with ‘%s’ - EF
2007-03-14 Add masked-array support to hist. - EF
2007-03-03 Change barh to take a kwargs dict and pass it to bar. Fixes sf bug #1669506.
2007-03-02 Add rc parameter pdf.inheritcolor, which disables all color-setting operations in the pdf
backend. The idea is that you include the resulting file in another program and set the colors (both
stroke and fill color) there, so you can use the same pdf file for e.g., a paper and a presentation and
have them in the surrounding color. You will probably not want to draw figure and axis frames in that
case, since they would be filled in the same color. - JKS
2007-02-26 Prevent building _wxagg.so with broken Mac OS X wxPython. - ADS
2007-02-23 Require setuptools for Python 2.3 - ADS
2007-02-22 WXAgg accelerator updates - KM WXAgg’s C++ accelerator has been fixed to use the correct wxBitmap constructor.
The backend has been updated to use new wxPython functionality to provide fast blit() animation
without the C++ accelerator. This requires wxPython 2.8 or later. Previous versions of wxPython can
use the C++ acclerator or the old pure Python routines.
setup.py no longer builds the C++ accelerator when wxPython >= 2.8 is present.
The blit() method is now faster regardless of which agg/wxPython conversion routines are used.
2007-02-21 Applied the PDF backend patch by Nicolas Grilly. This impacts several files and directories in matplotlib:
5.2. Previous Whats New
347
Matplotlib, Release 2.1.2
• Created the directory lib/matplotlib/mpl-data/fonts/pdfcorefonts, holding AFM files for the 14
PDF core fonts. These fonts are embedded in every PDF viewing application.
• setup.py: Added the directory pdfcorefonts to package_data.
• lib/matplotlib/__init__.py: Added the default parameter ‘pdf.use14corefonts’. When True, the
PDF backend uses only the 14 PDF core fonts.
• lib/matplotlib/afm.py: Added some keywords found in recent AFM files.
workaround to handle Euro symbol.
Added a little
• lib/matplotlib/fontmanager.py: Added support for the 14 PDF core fonts. These fonts have
a dedicated cache (file pdfcorefont.cache), not the same as for other AFM files (file .afmfont.cache). Also cleaned comments to conform to CODING_GUIDE.
• lib/matplotlib/backends/backend_pdf.py: Added support for 14 PDF core fonts. Fixed some issues with incorrect character widths and encodings (works only for the most common encoding,
WinAnsiEncoding, defined by the official PDF Reference). Removed parameter ‘dpi’ because it
causes alignment issues.
-JKS (patch by Nicolas Grilly)
2007-02-17 Changed ft2font.get_charmap, and updated all the files where get_charmap is mentioned
- ES
2007-02-13 Added barcode demo- JDH
2007-02-13 Added binary colormap to cm - JDH
2007-02-13 Added twiny to pylab - JDH
2007-02-12 Moved data files into lib/matplotlib so that setuptools’ develop mode works. Re-organized
the mpl-data layout so that this source structure is maintained in the installation. (i.e., the
‘fonts’ and ‘images’ sub-directories are maintained in site-packages.) Suggest removing sitepackages/matplotlib/mpl-data and ~/.matplotlib/ttffont.cache before installing - ADS
2007-02-07 Committed Rob Hetland’s patch for qt4: remove references to text()/latin1(), plus some
improvements to the toolbar layout - DSD
2007-02-06 Released 0.90.0 at revision 3003
2007-01-22 Extended the new picker API to text, patches and patch collections. Added support for
user customizable pick hit testing and attribute tagging of the PickEvent - Details and examples in
examples/pick_event_demo.py - JDH
2007-01-16 Begun work on a new pick API using the mpl event handling frameowrk. Artists will define their own pick method with a configurable epsilon tolerance and return pick attrs. All artists that
meet the tolerance threshold will fire a PickEvent with artist dependent attrs; e.g., a Line2D can set
the indices attribute that shows the indices into the line that are within epsilon of the pick point. See
examples/pick_event_demo.py. The implementation of pick for the remaining Artists remains to be
done, but the core infrastructure at the level of event handling is in place with a proof-of-concept
implementation for Line2D - JDH
348
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2007-01-16 src/_image.cpp: update to use Py_ssize_t (for 64-bit systems). Use return value of fread()
to prevent warning messages - SC.
2007-01-15 src/_image.cpp: combine buffer_argb32() and buffer_bgra32() into a
color_conv(format) - SC
new
method
2007-01-14 backend_cairo.py: update draw_arc() so that examples/arctest.py looks correct - SC
2007-01-12 backend_cairo.py: enable clipping. Update draw_image() so that
examples/contour_demo.py looks correct - SC
2007-01-12 backend_cairo.py: fix draw_image() so that examples/image_demo.py now looks correct
- SC
2007-01-11 Added Axes.xcorr and Axes.acorr to plot the cross correlation of x vs y or the autocorrelation of x. pylab wrappers also provided. See examples/xcorr_demo.py - JDH
2007-01-10 Added “Subplot.label_outer” method. It will set the visibility of the ticklabels so that yticklabels are only visible in the first column and xticklabels are only visible in the last row - JDH
2007-01-02 Added additional kwarg documentation - JDH
2006-12-28 Improved error message for nonpositive input to log transform; added log kwarg to bar,
barh, and hist, and modified bar method to behave sensibly by default when the ordinate has a log
scale. (This only works if the log scale is set before or by the call to bar, hence the utility of the log
kwarg.) - EF
2006-12-27 backend_cairo.py: update draw_image() and _draw_mathtext() to work with numpy SC
2006-12-20 Fixed xpdf dependency check, which was failing on windows. Removed ps2eps dependency check. - DSD
2006-12-19 Added Tim Leslie’s spectral patch - JDH
2006-12-17 Added rc param ‘axes.formatter.limits’ to control the default threshold for switching to scientific notation. Added convenience method Axes.ticklabel_format() for turning scientific notation on
or off on either or both axes. - EF
2006-12-16 Added ability to turn control scientific notation in ScalarFormatter - EF
2006-12-16 Enhanced boxplot to handle more flexible inputs - EF
2006-12-13 Replaced calls to where() in colors.py with much faster clip() and putmask() calls; removed inappropriate uses of getmaskorNone (which should be needed only very rarely); all in response to profiling by David Cournapeau. Also fixed bugs in my 2-D array support from 12-09. EF
2006-12-09 Replaced spy and spy2 with the new spy that combines marker and image capabilities - EF
2006-12-09 Added support for plotting 2-D arrays with plot: columns are plotted as in Matlab - EF
2006-12-09 Added linewidth kwarg to bar and barh; fixed arg checking bugs - EF
2006-12-07 Made pcolormesh argument handling match pcolor; fixed kwarg handling problem noted
by Pierre GM - EF
2006-12-06 Made pcolor support vector X and/or Y instead of requiring 2-D arrays - EF
5.2. Previous Whats New
349
Matplotlib, Release 2.1.2
2006-12-05 Made the default Artist._transform None (rather than invoking identity_transform for
each artist only to have it overridden later). Use artist.get_transform() rather than artist._transform,
even in derived classes, so that the default transform will be created lazily as needed - JDH
2006-12-03 Added LogNorm to colors.py as illustrated by examples/pcolor_log.py, based on suggestion by Jim McDonald. Colorbar modified to handle LogNorm. Norms have additional “inverse”
method. - EF
2006-12-02 Changed class names in colors.py to match convention: normalize -> Normalize, no_norm
-> NoNorm. Old names are still available. Changed __init__.py rc defaults to match those in matplotlibrc - EF
2006-11-22 Fixed bug in set_*lim that I had introduced on 11-15 - EF
2006-11-22 Added examples/clippedline.py, which shows how to clip line data based on view limits – it
also changes the marker style when zoomed in - JDH
2006-11-21 Some spy bug-fixes and added precision arg per Robert C’s suggestion - JDH
2006-11-19 Added semi-automatic docstring generation detailing all the kwargs that functions take
using the artist introspection tools; e.g., ‘help text now details the scatter kwargs that control the
Text properties - JDH
2006-11-17 Removed obsolete scatter_classic, leaving a stub to raise NotImplementedError; same for
pcolor_classic - EF
2006-11-15 Removed obsolete pcolor_classic - EF
2006-11-15 Fixed 1588908 reported by Russel Owen; factored nonsingular method out of ticker.py, put
it into transforms.py as a function, and used it in set_xlim and set_ylim. - EF
2006-11-14 Applied patch 1591716 by Ulf Larssen to fix a bug in apply_aspect. Modified and applied
patch 1594894 by mdehoon to fix bugs and improve formatting in lines.py. Applied patch 1573008
by Greg Willden to make psd etc. plot full frequency range for complex inputs. - EF
2006-11-14 Improved the ability of the colorbar to track changes in corresponding image, pcolor, or
contourf. - EF
2006-11-11 Fixed bug that broke Numeric compatibility; added support for alpha to colorbar. The alpha information is taken from the mappable object, not specified as a kwarg. - EF
2006-11-05 Added broken_barh function for makring a sequence of horizontal bars broken by gaps –
see examples/broken_barh.py
2006-11-05 Removed lineprops and markerprops from the Annotation code and replaced them with
an arrow configurable with kwarg arrowprops. See examples/annotation_demo.py - JDH
2006-11-02 Fixed a pylab subplot bug that was causing axes to be deleted with hspace or wspace
equals zero in subplots_adjust - JDH
2006-10-31 Applied axes3d patch 1587359 http://sourceforge.net/tracker/index.php?func=detail&aid=
1587359&group_id=80706&atid=560722 JDH
2006-10-26 Released 0.87.7 at revision 2835
350
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2006-10-25 Made “tiny” kwarg in Locator.nonsingular much smaller - EF
2006-10-17 Closed sf bug 1562496 update line props dash/solid/cap/join styles - JDH
2006-10-17 Complete overhaul of the annotations API and example code - See
plotlib.text.Annotation and examples/annotation_demo.py JDH
mat-
2006-10-12 Committed Manuel Metz’s StarPolygon code and examples/scatter_star_poly.py - JDH
2006-10-11 commented out all default values in matplotlibrc.template Default values should generally
be taken from defaultParam in __init__.py - the file matplotlib should only contain those values
that the user wants to explicitly change from the default. (see thread “marker color handling” on
matplotlib-devel)
2006-10-10 Changed default comment character for load to ‘#’ - JDH
2006-10-10 deactivated rcfile-configurability of markerfacecolor and markeredgecolor. Both are now
hardcoded to the special value ‘auto’ to follow the line color. Configurability at run-time (using
function arguments) remains functional. - NN
2006-10-07 introduced dummy argument magnification=1.0 to FigImage.make_image to satisfy unit
test figimage_demo.py The argument is not yet handled correctly, which should only show up when
using non-standard DPI settings in PS backend, introduced by patch #1562394. - NN
2006-10-06 add backend-agnostic example: simple3d.py - NN
2006-09-29 fix line-breaking for SVG-inline images (purely cosmetic) - NN
2006-09-29 reworked set_linestyle and set_marker markeredgecolor and markerfacecolor now default
to a special value “auto” that keeps the color in sync with the line color further, the intelligence of
axes.plot is cleaned up, improved and simplified. Complete compatibility cannot be guaranteed, but
the new behavior should be much more predictable (see patch #1104615 for details) - NN
2006-09-29 changed implementation of clip-path in SVG to work around a limitation in inkscape NN
2006-09-29 added two options to matplotlibrc: svg.image_inline
#1533010 for details - NN
svg.image_noscale
see
patch
2006-09-29 axes.py: cleaned up kwargs checking - NN
2006-09-29 setup.py: cleaned up setup logic - NN
2006-09-29 setup.py: check for required pygtk versions, fixes bug #1460783 - SC
2006-09-27 Released 0.87.6 at revision 2783
2006-09-24 Added line pointers to the Annotation code, and a pylab interface.
See
matplotlib.text.Annotation, examples/annotation_demo.py and examples/annotation_demo_pylab.py
- JDH
2006-09-18 mathtext2.py: The SVG backend now supports the same things that the AGG backend
does. Fixed some bugs with rendering, and out of bounds errors in the AGG backend - ES. Changed
the return values of math_parse_s_ft2font_svg to support lines (fractions etc.)
5.2. Previous Whats New
351
Matplotlib, Release 2.1.2
2006-09-17 Added an Annotation class to facilitate annotating objects and an examples file examples/annotation_demo.py. I want to add dash support as in TextWithDash, but haven’t decided yet
whether inheriting from TextWithDash is the right base class or if another approach is needed - JDH
2006-09-05 Released 0.87.5 at revision 2761
2006-09-04 Added nxutils for some numeric add-on extension code – specifically a better/more efficient inside polygon tester (see unit/inside_poly_*.py) - JDH
2006-09-04 Made bitstream fonts the rc default - JDH
2006-08-31 Fixed alpha-handling bug in ColorConverter, affecting collections in general and contour/contourf in particular. - EF
2006-08-30 ft2font.cpp: Added draw_rect_filled method (now used by mathtext2 to draw the fraction
bar) to FT2Font - ES
2006-08-29 setupext.py: wrap calls to tk.getvar() with str(). On some systems,
Tcl_Obj instead of a string - DSD
getvar
returns
a
2006-08-28 mathtext2.py: Sub/superscripts can now be complex (i.e. fractions etc.). The demo is also
updated - ES
2006-08-28 font_manager.py: Added /usr/local/share/fonts to list of X11 font directories - DSD
2006-08-28 mahtext2.py: Initial support for complex fractions. Also, rendering is now completely
separated from parsing. The sub/superscripts now work better. Updated the mathtext2_demo.py ES
2006-08-27 qt backends: don’t create a QApplication when backend is imported, do it when the FigureCanvasQt is created. Simplifies applications where mpl is embedded in qt. Updated embedding_in_qt* examples - DSD
2006-08-27 mahtext2.py: Now the fonts are searched in the OS font dir and in the mpl-data dir. Also
env is not a dict anymore. - ES
2006-08-26 minor changes to __init__.py, mathtex2_demo.py. Added matplotlibrc key
text.mathtext2” (removed the key “mathtext2”) - ES
“math-
2006-08-21 mathtext2.py: Initial support for fractions Updated the mathtext2_demo.py _mathtext_data.py: removed “” from the unicode dicts mathtext.py: Minor modification (because of
_mathtext_data.py)- ES
2006-08-20 Added mathtext2.py: Replacement for mathtext.py. Supports _ ^, rm, cal etc., sin, cos
etc., unicode, recursive nestings, inline math mode. The only backend currently supported is Agg
__init__.py: added new rc params for mathtext2 added mathtext2_demo.py example - ES
2006-08-19 Added embedding_in_qt4.py example - DSD
2006-08-11 Added scale free Ellipse patch for Agg - CM
2006-08-10 Added converters to and from julian dates to matplotlib.dates (num2julian
lian2num) - JDH
and
ju-
2006-08-08 Fixed widget locking so multiple widgets could share the event handling - JDH
352
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2006-08-07 Added scale free Ellipse patch to SVG and PS - CM
2006-08-05 Re-organized imports in numerix for numpy 1.0b2 – TEO
2006-08-04 Added draw_markers to PDF backend. - JKS
2006-08-01 Fixed a bug in postscript’s rendering of dashed lines - DSD
2006-08-01 figure.py: savefig() update docstring to add support for ‘format’ argument.
end_cairo.py: print_figure() add support ‘format’ argument. - SC
back-
2006-07-31 Don’t let postscript’s xpdf distiller compress images - DSD
2006-07-31 Added shallowcopy() methods to all Transformations; removed copy_bbox_transform and
copy_bbox_transform_shallow from transforms.py; added offset_copy() function to transforms.py to
facilitate positioning artists with offsets. See examples/transoffset.py. - EF
2006-07-31 Don’t let postscript’s xpdf distiller compress images - DSD
2006-07-29 Fixed numerix polygon bug reported by Nick Fotopoulos. Added inverse_numerix_xy()
transform method. Made autoscale_view() preserve axis direction (e.g., increasing down).- EF
2006-07-28 Added shallow bbox copy routine for transforms – mainly useful for copying transforms
to apply offset to. - JDH
2006-07-28 Added resize method to FigureManager class for Qt and Gtk backend - CM
2006-07-28 Added subplots_adjust button to Qt backend - CM
2006-07-26 Use numerix more in collections. Quiver now handles masked arrays. - EF
2006-07-22 Fixed bug #1209354 - DSD
2006-07-22 make scatter() work with the kwarg “color”. Closes bug 1285750 - DSD
2006-07-20 backend_cairo.py: require pycairo 1.2.0. print_figure() update to output SVG using cairo.
2006-07-19 Added blitting for Qt4Agg - CM
2006-07-19 Added lasso widget and example examples/lasso_demo.py - JDH
2006-07-18 Added blitting for QtAgg backend - CM
2006-07-17 Fixed bug #1523585: skip nans in semilog plots - DSD
2006-07-12 Add support to render the scientific notation label over the right-side y-axis - DSD
2006-07-11 Released 0.87.4 at revision 2558
2006-07-07 Fixed a usetex bug with older versions of latex - DSD
2006-07-07 Add compatibility for NumPy 1.0 - TEO
2006-06-29 Added a Qt4Agg backend. Thank you James Amundson - DSD
2006-06-26 Fixed a usetex bug. On windows, usetex will prcess postscript output in the current directory rather than in a temp directory. This is due to the use of spaces and tildes in windows paths,
which cause problems with latex. The subprocess module is no longer used. - DSD
5.2. Previous Whats New
353
Matplotlib, Release 2.1.2
2006-06-22 Various changes to bar(), barh(), and hist(). Added ‘edgecolor’ keyword arg to bar() and
barh(). The x and y args in barh() have been renamed to width and bottom respectively, and their
order has been swapped to maintain a (position, value) order ala matlab. left, height, width and bottom args can now all be scalars or sequences. barh() now defaults to edge alignment instead of center
alignment. Added a keyword arg ‘align’ to bar(), barh() and hist() that controls between edge or center
bar alignment. Fixed ignoring the rcParams[‘patch.facecolor’] for bar color in bar() and barh(). Fixed
ignoring the rcParams[‘lines.color’] for error bar color in bar() and barh(). Fixed a bug where patches
would be cleared when error bars were plotted if rcParams[‘axes.hold’] was False. - MAS
2006-06-22 Added support for numerix 2-D arrays as alternatives to a sequence of (x,y) tuples for
specifying paths in collections, quiver, contour, pcolor, transforms. Fixed contour bug involving
setting limits for color mapping. Added numpy-style all() to numerix. - EF
2006-06-20 Added custom FigureClass hook to pylab interface - see examples/custom_figure_class.py
2006-06-16 Added colormaps from gist (gist_earth, gist_stern, gist_rainbow,
gist_heat, gist_ncar) - JW
gist_gray,
gist_yarg,
2006-06-16 Added a pointer to parent in figure canvas so you can access
the
container
with fig.canvas.manager.
Useful if you want to set the window title, e.g., in gtk
fig.canvas.manager.window.set_title, though a GUI neutral method would be preferable JDH
2006-06-16 Fixed colorbar.py to handle indexed colors (i.e., norm = no_norm()) by centering each colored region on its index. - EF
2006-06-15 Added scalex and scaley to Axes.autoscale_view to support selective autoscaling just the x
or y axis, and supported these command in plot so you can say plot(something, scaley=False) and just
the x axis will be autoscaled. Modified axvline and axhline to support this, so for example axvline
will no longer autoscale the y axis. JDH
2006-06-13 Fix so numpy updates are backward compatible - TEO
2006-06-12 Updated numerix to handle numpy restructuring of oldnumeric - TEO
2006-06-12 Updated numerix.fft to handle numpy restructuring Added
merix.linear_algebra for numpy -TEO
ImportError
to
nu-
2006-06-11 Added quiverkey command to pylab and Axes, using QuiverKey class in quiver.py.
Changed pylab and Axes to use quiver2 if possible, but drop back to the newly-renamed quiver_classic
if necessary. Modified examples/quiver_demo.py to illustrate the new quiver and quiverkey. Changed
LineCollection implementation slightly to improve compatibility with PolyCollection. - EF
2006-06-11 Fixed a usetex bug for windows, running latex on files with spaces in their names or paths
was failing - DSD
2006-06-09 Made additions to numerix, changes to quiver to make it work with all numeric flavors. EF
2006-06-09 Added quiver2 function to pylab and method to axes, with implementation via a Quiver
class in quiver.py. quiver2 will replace quiver before the next release; it is placed alongside it initially to facilitate testing and transition. See also examples/quiver2_demo.py. - EF
2006-06-08 Minor bug fix to make ticker.py draw proper minus signs with usetex - DSD
354
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2006-06-06 Released 0.87.3 at revision 2432
2006-05-30 More partial support for polygons with outline or fill, but not both. Made LineCollection
inherit from ScalarMappable. - EF
2006-05-29 Yet another revision of aspect-ratio handling. - EF
2006-05-27 Committed a patch to prevent stroking zero-width lines in the svg backend - DSD
2006-05-24 Fixed colorbar positioning bug identified by Helge Avlesen, and improved the algorithm;
added a ‘pad’ kwarg to control the spacing between colorbar and parent axes. - EF
2006-05-23 Changed color handling so that collection initializers can take any mpl color arg or sequence of args; deprecated float as grayscale, replaced by string representation of float. - EF
2006-05-19 Fixed bug: plot failed if all points were masked - EF
2006-05-19 Added custom symbol option to scatter - JDH
2006-05-18 New example, multi_image.py; colorbar fixed to show offset text when the ScalarFormatter
is used; FixedFormatter augmented to accept and display offset text. - EF
2006-05-14 New colorbar; old one is renamed to colorbar_classic. New colorbar code is in colorbar.py,
with wrappers in figure.py and pylab.py. Fixed aspect-handling bug reported by Michael Mossey.
Made backend_bases.draw_quad_mesh() run.- EF
2006-05-08 Changed handling of end ranges in contourf: replaced “clip-ends” kwarg with “extend”.
See docstring for details. -EF
2006-05-08 Added axisbelow to rc - JDH
2006-05-08 If using PyGTK require version 2.2+ - SC
2006-04-19 Added compression support to PDF backend, controlled by new pdf.compression rc setting. - JKS
2006-04-19 Added Jouni’s PDF backend
2006-04-18 Fixed a bug that caused agg to not render long lines
2006-04-16 Masked array support for pcolormesh; made pcolormesh support the same combinations
of X,Y,C dimensions as pcolor does; improved (I hope) description of grid used in pcolor, pcolormesh.
- EF
2006-04-14 Reorganized axes.py - EF
2006-04-13 Fixed a bug Ryan found using usetex with sans-serif fonts and exponential tick labels DSD
2006-04-11 Refactored backend_ps and backend_agg to prevent module-level texmanager
Now these imports only occur if text.usetex rc setting is true - DSD
imports.
2006-04-10 Committed changes required for building mpl on win32 platforms with visual studio. This
allows wxpython blitting for fast animations. - CM
2006-04-10 Fixed an off-by-one bug in Axes.change_geometry.
2006-04-10 Fixed bug in pie charts where wedge wouldn’t have label in legend. Submitted by Simon
Hildebrandt. - ADS
5.2. Previous Whats New
355
Matplotlib, Release 2.1.2
2006-05-06 Usetex makes temporary latex and dvi files in a temporary directory, rather than in the
user’s current working directory - DSD
2006-04-05 Apllied Ken’s wx deprecation warning patch closing sf patch #1465371 - JDH
2006-04-05 Added support for the new API in the postscript backend. Allows values to be masked using nan’s, and faster file creation - DSD
2006-04-05 Use python’s subprocess module for usetex calls to external programs. subprocess catches
when they exit abnormally so an error can be raised. - DSD
2006-04-03 Fixed the bug in which widgets would not respond to events. This regressed the twinx
functionality, so I also updated subplots_adjust to update axes that share an x or y with a subplot
instance. - CM
2006-04-02 Moved PBox class to transforms and deleted pbox.py; made pylab axis command a thin
wrapper for Axes.axis; more tweaks to aspect-ratio handling; fixed Axes.specgram to account for
the new imshow default of unit aspect ratio; made contour set the Axes.dataLim. - EF
2006-03-31 Fixed the Qt “Underlying C/C++ object deleted” bug. - JRE
2006-03-31 Applied Vasily Sulatskov’s Qt Navigation Toolbar enhancement. - JRE
2006-03-31 Ported Norbert’s rewriting of Halldor’s stineman_interp algorithm to make it numerix
compatible and added code to matplotlib.mlab. See examples/interp_demo.py - JDH
2006-03-30 Fixed a bug in aspect ratio handling; blocked potential crashes when panning with button
3; added axis(‘image’) support. - EF
2006-03-28 More changes to aspect ratio handling; new PBox class in new file pbox.py to facilitate resizing and repositioning axes; made PolarAxes maintain unit aspect ratio. - EF
2006-03-23 Refactored TextWithDash class to inherit from, rather than delegate to, the Text class.
Improves object inspection and closes bug # 1357969 - DSD
2006-03-22 Improved aspect ratio handling, including pylab interface. Interactive resizing, pan, zoom
of images and plots (including panels with a shared axis) should work. Additions and possible refactoring are still likely. - EF
2006-03-21 Added another colorbrewer colormap (RdYlBu) - JSWHIT
2006-03-21 Fixed tickmarks for logscale plots over very large ranges. Closes bug # 1232920 - DSD
2006-03-21 Added Rob Knight’s arrow code; see examples/arrow_demo.py - JDH
2006-03-20 Added support for masking values with nan’s, using ADS’s isnan module and the new
API. Works for *Agg backends - DSD
2006-03-20 Added contour.negative_linestyle rcParam - ADS
2006-03-20 Added _isnan extension module to test for nan with Numeric
• ADS
2006-03-17 Added Paul and Alex’s support for faceting with quadmesh in sf patch 1411223 - JDH
2006-03-17 Added Charle Twardy’s pie patch to support colors=None. Closes sf patch 1387861 JDH
356
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2006-03-17 Applied sophana’s patch to support overlapping axes with toolbar navigation by toggling
activation with the ‘a’ key. Closes sf patch 1432252 - JDH
2006-03-17 Applied Aarre’s linestyle patch for backend EMF; closes sf patch 1449279 - JDH
2006-03-17 Applied Jordan Dawe’s patch to support kwarg properties for grid lines in the grid command. Closes sf patch 1451661 - JDH
2006-03-17 Center postscript output on page when using usetex - DSD
2006-03-17 subprocess module built if Python <2.4 even if subprocess can be imported from an egg ADS
2006-03-17 Added _subprocess.c from Python upstream and hopefully enabled
breaking) on Windows, although not tested. - ADS
building
(without
2006-03-17 Updated subprocess.py to latest Python upstream and reverted name back to subprocess.py - ADS
2006-03-16 Added John Porter’s 3D handling code
2006-03-16 Released 0.87.2 at revision 2150
2006-03-15 Fixed bug in MaxNLocator revealed by daigos@infinito.it. The main change is that Locator.nonsingular now adjusts vmin and vmax if they are nearly the same, not just if they are equal. A
new kwarg, “tiny”, sets the threshold. - EF
2006-03-14 Added import of compatibility library for newer numpy linear_algebra - TEO
2006-03-12 Extended “load” function to support individual columns and moved “load” and “save”
into matplotlib.mlab so they can be used outside of pylab – see examples/load_converter.py - JDH
2006-03-12 Added AutoDateFormatter and AutoDateLocator submitted by James Evans.
load_converter.py example for a demo. - ADS
Try the
2006-03-11 Added subprocess module from python-2.4 - DSD
2006-03-11 Fixed landscape orientation support with the usetex option. The backend_ps print_figure
method was getting complicated, I added a _print_figure_tex method to maintain some degree of
sanity - DSD
2006-03-11 Added “papertype” savefig kwarg for setting postscript papersizes.
ps.papersize rc setting can also be set to “auto” to autoscale pagesizes - DSD
papertype and
2006-03-09 Apply P-J’s patch to make pstoeps work on windows patch report # 1445612 - DSD
2006-03-09 Make backend rc parameter case-insensitive - DSD
2006-03-07 Fixed bug in backend_ps related to C0-C6 papersizes, which were causing problems with
postscript viewers. Supported page sizes include letter, legal, ledger, A0-A10, and B0-B10 - DSD
2006-03-07 Released 0.87.1
2006-03-04 backend_cairo.py: fix get_rgb() bug reported by Keith Briggs. Require pycairo 1.0.2. Support saving png to file-like objects. - SC
5.2. Previous Whats New
357
Matplotlib, Release 2.1.2
2006-03-03 Fixed pcolor handling of vmin, vmax - EF
2006-03-02 improve page sizing with usetex with the latex geometry package. Closes bug # 1441629 DSD
2006-03-02 Fixed dpi problem with usetex png output. Accepted a modified
1441809 - DSD
version
of
patch
#
2006-03-01 Fixed axis(‘scaled’) to deal with case xmax < xmin - JSWHIT
2006-03-01 Added reversed colormaps (with ‘_r’ appended to name) - JSWHIT
2006-02-27 Improved eps bounding boxes with usetex - DSD
2006-02-27 Test svn commit, again!
2006-02-27 Fixed two dependency checking bugs related to usetex on Windows - DSD
2006-02-27 Made the rc deprecation warnings a little more human readable.
2006-02-26 Update the previous gtk.main_quit() bug fix to use gtk.main_level()
• SC
2006-02-24 Implemented alpha support in contour and contourf - EF
2006-02-22 Fixed gtk main quit bug when quit was called before mainloop. - JDH
2006-02-22 Small change to colors.py to workaround apparent bug in numpy masked array module JSWHIT
2006-02-22 Fixed bug in ScalarMappable.to_rgba() reported by Ray Jones, and fixed incorrect fix
found by Jeff Whitaker - EF
2006-02-22 Released 0.87
2006-02-21 Fixed portrait/landscape orientation in postscript backend - DSD
2006-02-21 Fix bug introduced in yesterday’s bug fix - SC
2006-02-20 backend_gtk.py FigureCanvasGTK.draw(): fix bug reported by David Tremouilles - SC
2006-02-20 Remove the “pygtk.require(‘2.4’)” error from examples/embedding_in_gtk2.py - SC
2006-02-18 backend_gtk.py FigureCanvasGTK.draw(): simplify to use (rather than duplicate)
expose_event() drawing code - SC
2006-02-12 Added stagger or waterfall plot capability to LineCollection; illustrated
ples/collections.py. - EF
in
the
exam-
2006-02-11 Massive cleanup of the usetex code in the postscript backend. Possibly fixed the clipping
issue users were reporting with older versions of ghostscript - DSD
2006-02-11 Added autolim kwarg to axes.add_collection. Changed collection get_verts() methods accordingly. - EF
2006-02-09 added a temporary rc parameter text.dvipnghack, to allow Mac users to get nice results
with the usetex option. - DSD
358
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2006-02-09 Fixed a bug related to setting font sizes with the usetex option. - DSD
2006-02-09 Fixed a bug related to usetex’s latex code. - DSD
2006-02-09 Modified behavior of font.size rc setting. You should define font.size in pts, which will set
the “medium” or default fontsize. Special text sizes like axis labels or tick labels can be given relative
font sizes like small, large, x-large, etc. and will scale accordingly. - DSD
2006-02-08 Added py2exe specific datapath check again. Also added new py2exe
get_py2exe_datafiles for use in py2exe setup.py scripts. - CM
helper
function
2006-02-02 Added box function to pylab
2006-02-02 Fixed a problem in setupext.py, tk library formatted in unicode caused build problems DSD
2006-02-01 Dropped TeX engine support in usetex to focus on LaTeX. - DSD
2006-01-29 Improved usetex option to respect the serif, sans-serif, monospace, and cursive rc settings.
Removed the font.latex.package rc setting, it is no longer required - DSD
2006-01-29 Fixed tex’s caching to include font.family rc information - DSD
2006-01-29 Fixed subpixel rendering bug in *Agg that was causing uneven gridlines - JDH
2006-01-28 Added fontcmd to backend_ps’s RendererPS.draw_tex, to support other font families in
eps output - DSD
2006-01-28 Added MaxNLocator to ticker.py, and changed contour.py to use it by default. - EF
2006-01-28 Added fontcmd to backend_ps’s RendererPS.draw_tex, to support other font families in
eps output - DSD
2006-01-27 Buffered reading of matplotlibrc parameters in order to allow ‘verbose’ settings to be
processed first (allows verbose.report during rc validation process) - DSD
2006-01-27 Removed setuptools support from setup.py and created a separate setupegg.py file to replace it. - CM
2006-01-26 Replaced the ugly datapath logic with a cleaner approach from http://wiki.python.org/
moin/DistutilsInstallDataScattered. Overrides the install_data command. - CM
2006-01-24 Don’t use character typecodes in cntr.c — changed to use defined typenumbers instead. TEO
2006-01-24 Fixed some bugs in usetex’s and ps.usedistiller’s dependency
2006-01-24 Added masked array support to scatter - EF
2006-01-24 Fixed some bugs in usetex’s and ps.usedistiller’s dependency checking - DSD
2006-01-24 Released 0.86.2
2006-01-20 Added a converters dict to pylab load to convert selected coloumns to float – especially
useful for files with date strings, uses a datestr2num converter - JDH
5.2. Previous Whats New
359
Matplotlib, Release 2.1.2
2006-01-20 Added datestr2num to matplotlib dates to convert a string or sequence of strings to a matplotlib datenum
2006-01-18 Added quadrilateral pcolormesh patch 1409190 by Alex Mont and Paul Kienzle – this is
*Agg only for now. See examples/quadmesh_demo.py - JDH
2006-01-18 Added Jouni’s boxplot patch - JDH
2006-01-18 Added comma delimiter for pylab save - JDH
2006-01-12 Added Ryan’s legend patch - JDH
2006-1-12 Fixed numpy / numeric to use .dtype.char to keep in SYNC with numpy SVN
2006-1-11 Released 0.86.1
2006-1-11 Fixed setup.py for win32 build and added rc template to the MANIFEST.in
2006-1-10 Added xpdf distiller option. matplotlibrc ps.usedistiller can now be none,
false,
ghostscript, or xpdf. Validation checks for dependencies. This needs testing, but the xpdf
option should produce the highest-quality output and small file sizes - DSD
2006-01-10 For the usetex option, backend_ps now does all the LaTeX work in the os’s temp directory - DSD
2006-1-10 Added checks for usetex dependencies. - DSD
2006-1-9 Released 0.86
2006-1-4 Changed to support numpy (new name for scipy_core) - TEO
2006-1-4 Added Mark’s scaled axes patch for shared axis
2005-12-28 Added Chris Barker’s build_wxagg patch - JDH
2005-12-27 Altered numerix/scipy to support new scipy package structure - TEO
2005-12-20 Fixed Jame’s Boyles date tick reversal problem - JDH
2005-12-20 Added Jouni’s rc patch to support lists of keys to set on - JDH
2005-12-12 Updated pyparsing and mathtext for some speed enhancements (Thanks Paul McGuire)
and minor fixes to scipy numerix and setuptools
2005-12-12 Matplotlib data is now installed as package_data in the matplotlib module. This gets rid of
checking the many possibilities in matplotlib._get_data_path() - CM
2005-12-11 Support for setuptools/pkg_resources to build and use matplotlib as an egg. Still allows
matplotlib to exist using a traditional distutils install. - ADS
2005-12-03 Modified setup to build matplotlibrc based on compile time findings. It will set numerix in
the order of scipy, numarray, Numeric depending on which are founds, and backend as in preference
order GTKAgg, WXAgg, TkAgg, GTK, Agg, PS
360
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-12-03 Modified scipy patch to support Numeric, scipy and numarray Some work remains to be
done because some of the scipy imports are broken if only the core is installed. e.g., apparently we
need from scipy.basic.fftpack import * rather than from scipy.fftpack import *
2005-12-03 Applied some fixes to Nicholas Young’s nonuniform image patch
2005-12-01 Applied Alex Gontmakher hatch patch - PS only for now
2005-11-30 Added Rob McMullen’s EMF patch
2005-11-30 Added Daishi’s patch for scipy
2005-11-30 Fixed out of bounds draw markers segfault in agg
2005-11-28 Got TkAgg blitting working 100% (cross fingers) correctly. - CM
2005-11-27 Multiple changes in cm.py, colors.py, figure.py, image.py, contour.py, contour_demo.py;
new _cm.py, examples/image_masked.py. 1) Separated the color table data from cm.py out into a
new file, _cm.py, to make it easier to find the actual code in cm.py and to add new colormaps. Also
added some line breaks to the color data dictionaries. Everything from _cm.py is imported by cm.py,
so the split should be transparent. 2) Enabled automatic generation of a colormap from a list of colors
in contour; see modified examples/contour_demo.py. 3) Support for imshow of a masked array, with
the ability to specify colors (or no color at all) for masked regions, and for regions that are above
or below the normally mapped region. See examples/image_masked.py. 4) In support of the above,
added two new classes, ListedColormap, and no_norm, to colors.py, and modified the Colormap
class to include common functionality. Added a clip kwarg to the normalize class. Reworked color
handling in contour.py, especially in the ContourLabeller mixin. - EF
2005-11-25 Changed text.py to ensure color is hashable. EF
2005-11-16 Released 0.85
2005-11-16 Changed the default default linewidth in rc to 1.0
2005-11-16 Replaced agg_to_gtk_drawable with pure pygtk pixbuf code in backend_gtkagg.
the equivalent is doe for blit, the agg extension code will no longer be needed
When
2005-11-16 Added a maxdict item to cbook to prevent caches from growing w/o bounds
2005-11-15 Fixed a colorup/colordown reversal bug in finance.py – Thanks Gilles
2005-11-15 Applied Jouni K Steppanen’s boxplot patch SF patch#1349997
• JDH
2005-11-09 added axisbelow attr for Axes to determine whether ticks and such are above or below the
actors
2005-11-08 Added Nicolas’ irregularly spaced image patch
2005-11-08 Deprecated HorizontalSpanSelector and replaced with SpanSelection that takes a third
arg, direction. The new SpanSelector supports horizontal and vertical span selection, and the appropriate min/max is returned. - CM
2005-11-08 Added lineprops dialog for gtk
5.2. Previous Whats New
361
Matplotlib, Release 2.1.2
2005-11-03 Added FIFOBuffer class to mlab to support real time feeds and examples/fifo_buffer.py
2005-11-01 Contributed Nickolas Young’s patch for afm mathtext to support mathtext based upon the
standard postscript Symbol font when ps.usetex = True.
2005-10-26 Added support for scatter legends - thanks John Gill
2005-10-20 Fixed image clipping bug that made some tex labels disappear. JDH
2005-10-14 Removed sqrt from dvipng 1.6 alpha channel mask.
2005-10-14 Added width kwarg to hist function
2005-10-10 Replaced all instances of os.rename with shutil.move
2005-10-05 Added Michael Brady’s ydate patch
2005-10-04 Added rkern’s texmanager patch
2005-09-25 contour.py modified to use a single ContourSet class that handles filled contours, line contours, and labels; added keyword arg (clip_ends) to contourf. Colorbar modified to work with new
ContourSet object; if the ContourSet has lines rather than polygons, the colorbar will follow suit.
Fixed a bug introduced in 0.84, in which contourf(. . . ,colors=. . . ) was broken - EF
2005-09-19 Released 0.84
2005-09-14 Added a new ‘resize_event’ which triggers a callback with a backend_bases.ResizeEvent
object - JDH
2005-09-14 font_manager.py: removed chkfontpath from x11FontDirectory() - SC
2005-09-14 Factored out auto date locator/formatter factory code into
matplotlib.date.date_ticker_factory; applies John Bryne’s quiver patch.
2005-09-13 Added Mark’s axes positions history patch #1286915
2005-09-09 Added support for auto canvas resizing with fig.set_figsize_inches(9,5,forward=True)
inches OR fig.resize(400,300) # pixels
#
2005-09-07 figure.py: update Figure.draw() to use the updated renderer.draw_image() so that examples/figimage_demo.py works again. examples/stock_demo.py: remove data_clipping (which no
longer exists) - SC
2005-09-06 Added Eric’s tick.direction patch: in or out in rc
2005-09-06 Added Martin’s rectangle selector widget
2005-09-04 Fixed a logic err in text.py that was preventing rgxsuper from matching - JDH
2005-08-29 Committed Ken’s wx blit patch #1275002
2005-08-26 colorbar modifications - now uses contourf instead of imshow so that colors used by contourf are displayed correctly. Added two new keyword args (cspacing and clabels) that are only
relevant for ContourMappable images - JSWHIT
2005-08-24 Fixed a PS image bug reported by Darren - JDH
362
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-08-23 colors.py: change hex2color() to accept unicode strings as well as normal strings.
isinstance() instead of types.IntType etc - SC
Use
2005-08-16 removed data_clipping line and rc property - JDH
2005-08-22 backend_svg.py: Remove redundant “x=0.0 y=0.0” from svg element. Increase svg version from 1.0 to 1.1. Add viewBox attribute to svg element to allow SVG documents to scale-to-fit
into an arbitrary viewport - SC
2005-08-16 Added Eric’s dot marker patch - JDH
2005-08-08 Added blitting/animation for TkAgg - CM
2005-08-05 Fixed duplicate tickline bug - JDH
2005-08-05 Fixed a GTK animation bug that cropped up when doing animations in gtk//gtkagg canvases that had widgets packed above them
2005-08-05 Added Clovis Goldemberg patch to the tk save dialog
2005-08-04 Removed origin kwarg from backend.draw_image. origin is handled entirely by the frontend now.
2005-07-03 Fixed a bug related to TeX commands in backend_ps
2005-08-03 Fixed SVG images to respect upper and lower origins.
2005-08-03 Added flipud method to image and removed it from to_str.
2005-07-29 Modified figure.figaspect to take an array or number; modified backend_svg to write utf-8
- JDH
2005-07-30 backend_svg.py: embed png image files in svg rather than linking to a separate png file,
fixes bug #1245306 (thanks to Norbert Nemec for the patch) - SC
2005-07-29 Released 0.83.2
2005-07-27 Applied SF patch 1242648: minor rounding error in IndexDateFormatter in dates.py
2005-07-27 Applied sf patch 1244732: Scale axis such that circle looks like circle - JDH
2005-07-29 Improved message reporting in texmanager and backend_ps - DSD
2005-07-28 backend_gtk.py: update FigureCanvasGTK.draw() (needed due to the recent
pose_event() change) so that examples/anim.py works in the usual way - SC
ex-
2005-07-26 Added new widgets Cursor and HorizontalSpanSelector to matplotlib.widgets. See examples/widgets/cursor.py and examples/widgets/span_selector.py - JDH
2005-07-26 added draw event to mpl event hierarchy – triggered on figure.draw
2005-07-26 backend_gtk.py: allow ‘f’ key to toggle window fullscreen mode
2005-07-26 backend_svg.py: write “<. . . />” elements all on one line and remove surplus spaces - SC
2005-07-25 backend_svg.py: simplify code by deleting GraphicsContextSVG and
RendererSVG.new_gc(),
and
moving
the
gc.get_capstyle()
code
erSVG._get_gc_props_svg() - SC
5.2. Previous Whats New
into
Render-
363
Matplotlib, Release 2.1.2
2005-07-24 backend_gtk.py: call FigureCanvasBase.motion_notify_event() on all
motion-notifyevents, not just ones where a modifier key or button has been pressed (fixes bug report from Niklas
Volbers) - SC
2005-07-24 backend_gtk.py: modify print_figure() use own pixmap, fixing problems
where
print_figure() overwrites the display pixmap. return False from all button/key etc events - to
allow the event to propagate further - SC
2005-07-23 backend_gtk.py: change expose_event from using set_back_pixmap(); clear()
draw_drawable() - SC
to
2005-07-23 backend_gtk.py: removed pygtk.require() matplotlib/__init__.py: delete ‘FROZEN’ and
‘McPLError’ which are no longer used - SC
2005-07-22 backend_gdk.py: removed pygtk.require() - SC
2005-07-21 backend_svg.py: Remove unused imports. Remove methods doc strings which just duplicate the docs from backend_bases.py. Rename draw_mathtext to _draw_mathtext. - SC
2005-07-17 examples/embedding_in_gtk3.py: new example demonstrating placing a FigureCanvas in
a gtk.ScrolledWindow - SC
2005-07-14 Fixed a Windows related bug (#1238412) in texmanager - DSD
2005-07-11 Fixed color kwarg bug, setting color=1 or 0 caused an exception - DSD
2005-07-07 Added Eric’s MA set_xdata Line2D fix - JDH
2005-07-06 Made HOME/.matplotlib the new config dir where the matplotlibrc file, the ttf.cache, and
the tex.cache live. The new default filenames in .matplotlib have no leading dot and are not hidden.
e.g., the new names are matplotlibrc tex.cache ttffont.cache. This is how ipython does it so it must be
right. If old files are found, a warning is issued and they are moved to the new location. Also fixed
texmanager to put all files, including temp files in ~/.matplotlib/tex.cache, which allows you to usetex
in non-writable dirs.
2005-07-05 Fixed bug #1231611 in subplots adjust layout. The problem was that the text cacheing
mechanism was not using the transformation affine in the key. - JDH
2005-07-05 Fixed default backend import problem when using API (SF bug #
API_CHANGES for more info - JDH
1209354
-
see
2005-07-04 backend_gtk.py: require PyGTK version 2.0.0 or higher - SC
2005-06-30 setupext.py: added numarray_inc_dirs for building against numarray when not installed
in standard location - ADS
2005-06-27 backend_svg.py: write figure width, height as int, not float. Update to fix some of the pychecker warnings - SC
2005-06-23 Updated examples/agg_test.py to demonstrate curved paths and fills - JDH
2005-06-21 Moved some texmanager and backend_agg tex caching to class level rather than instance
level - JDH
2005-06-20 setupext.py: fix problem where _nc_backend_gdk is installed to the wrong directory - SC
2005-06-19 Added 10.4 support for CocoaAgg. - CM
364
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-06-18 Move Figure.get_width_height() to FigureCanvasBase and return int instead of float. - SC
2005-06-18 Applied Ted Drain’s QtAgg patch: 1) Changed the toolbar to be a horizontal bar of push
buttons instead of a QToolbar and updated the layout algorithms in the main window accordingly.
This eliminates the ability to drag and drop the toolbar and detach it from the window. 2) Updated the
resize algorithm in the main window to show the correct size for the plot widget as requested. This
works almost correctly right now. It looks to me like the final size of the widget is off by the border
of the main window but I haven’t figured out a way to get that information yet. We could just add a
small margin to the new size but that seems a little hacky. 3) Changed the x/y location label to be in
the toolbar like the Tk backend instead of as a status line at the bottom of the widget. 4) Changed the
toolbar pixmaps to use the ppm files instead of the png files. I noticed that the Tk backend buttons
looked much nicer and it uses the ppm files so I switched them.
2005-06-17 Modified the gtk backend to not queue mouse motion events. This allows for live updates
when dragging a slider. - CM
2005-06-17 Added starter CocoaAgg backend. Only works on OS 10.3 for now and requires PyObjC.
(10.4 is high priority) - CM
2005-06-17 Upgraded pyparsing and applied Paul McGuire’s suggestions for speeding things up. This
more than doubles the speed of mathtext in my simple tests. JDH
2005-06-16 Applied David Cooke’s subplot make_key patch
2005-06-15 0.82 released
2005-06-15 Added subplot config tool to GTK* backends – note you must now import the NavigationToolbar2 from your backend of choice rather than from backend_gtk because it needs to know about
the backend specific canvas – see examples/embedding_in_gtk2.py. Ditto for wx backend – see examples/embedding_in_wxagg.py
2005-06-15 backend_cairo.py: updated to use pycairo 0.5.0 - SC
2005-06-14 Wrote some GUI neutral widgets (Button, Slider, RadioButtons, CheckButtons) in matplotlib.widgets. See examples/widgets/*.py - JDH
2005-06-14 Exposed subplot parameters as rc vars and as the fig SubplotParams instance subplotpars.
See figure.SubplotParams, figure.Figure.subplots_adjust and the pylab method subplots_adjust and
examples/subplots_adjust.py . Also added a GUI neutral widget for adjusting subplots, see examples/subplot_toolbar.py - JDH
2005-06-13 Exposed cap and join style for lines with new rc params and
line properties
lines.dash_joinstyle : miter # miter|round|bevel lines.dash_capstyle : butt # butt|round|projecting
lines.solid_joinstyle :
miter # miter|round|bevel lines.solid_capstyle :
projecting #
butt|round|projecting
2005-06-13 Added kwargs to Axes init
2005-06-13 Applied Baptiste’s tick patch - JDH
5.2. Previous Whats New
365
Matplotlib, Release 2.1.2
2005-06-13 Fixed rc alias ‘l’ bug reported by Fernando by removing aliases for mainlevel rc options. JDH
2005-06-10 Fixed bug #1217637 in ticker.py - DSD
2005-06-07 Fixed a bug in texmanager.py: .aux files not being removed - DSD
2005-06-08 Added Sean Richard’s hist binning fix – see API_CHANGES - JDH
2005-06-07 Fixed a bug in texmanager.py: .aux files not being removed
• DSD
2005-06-07 matplotlib-0.81 released
2005-06-06 Added autoscale_on prop to axes
2005-06-06 Added Nick’s picker “among” patch - JDH
2005-06-05 Fixed a TeX/LaTeX font discrepency in backend_ps. - DSD
2005-06-05 Added a ps.distill option in rc settings. If True, postscript output will be distilled using
ghostscript, which should trim the file size and allow it to load more quickly. Hopefully this will
address the issue of large ps files due to font definitions. Tested with gnu-ghostscript-8.16. - DSD
2005-06-03 Improved support for tex handling of text in backend_ps. - DSD
2005-06-03 Added rc options to render text with tex or latex, and to select the latex font package. DSD
2005-06-03 Fixed a bug in ticker.py causing a ZeroDivisionError
2005-06-02 backend_gtk.py remove DBL_BUFFER, add line to expose_event to try to fix pygtk 2.6
redraw problem - SC
2005-06-01 The default behavior of ScalarFormatter now renders scientific notation and large numerical offsets in a label at the end of the axis. - DSD
2005-06-01 Added Nicholas’ frombyte image patch - JDH
2005-05-31 Added vertical TeX support for agg - JDH
2005-05-31 Applied Eric’s cntr patch - JDH
2005-05-27 Finally found the pesky agg bug (which Maxim was kind enough to fix within hours) that
was causing a segfault in the win32 cached marker drawing. Now windows users can get the enormouse performance benefits of caced markers w/o those occasional pesy screenshots. - JDH
2005-05-27 Got win32 build system working again, using a more recent version of gtk and pygtk in the
win32 build, gtk 2.6 from http://www.gimp.org/~tml/gimp/win32/downloads.html (you will also need
libpng12.dll to use these). I haven’t tested whether this binary build of mpl for win32 will work with
older gtk runtimes, so you may need to upgrade.
2005-05-27 Fixed bug where 2nd wxapp could be started if using wxagg backend. - ADS
2005-05-26 Added Daishi text with dash patch – see examples/dashtick.py
366
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-05-26 Moved backend_latex functionality into backend_ps. If text.usetex=True, the PostScript
backend will use LaTeX to generate the .ps or .eps file. Ghostscript is required for eps output. DSD
2005-05-24 Fixed alignment and color issues in latex backend. - DSD
2005-05-21 Fixed raster problem for small rasters with dvipng – looks like it was a premultipled alpha
problem - JDH
2005-05-20 Added linewidth and faceted kwarg to scatter to control edgewidth and color. Also added
autolegend patch to inspect line segments.
2005-05-18 Added Orsay and JPL qt fixes - JDH
2005-05-17 Added a psfrag latex backend – some alignment issues need to be worked out. Run with dLaTeX and a .tex file and *.eps file are generated. latex and dvips the generated latex file to get ps
output. Note xdvi *does not work, you must generate ps.- JDH
2005-05-13 Added Florent Rougon’s Axis set_label1 patch
2005-05-17 pcolor optimization, fixed bug in previous pcolor patch - JSWHIT
2005-05-16 Added support for masked arrays in pcolor - JSWHIT
2005-05-12 Started work on TeX text for antigrain using pngdvi – see examples/tex_demo.py and the
new module matplotlib.texmanager. Rotated text not supported and rendering small glyps is not working right yet. BUt large fontsizes and/or high dpi saved figs work great.
2005-05-10 New image resize options interpolation options. New values for the interp kwarg are
‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’,
‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’, ‘blackman’
See help(imshow) for details, particularly the interpolation, filternorm and filterrad kwargs
2005-05-10 Applied Eric’s contour mem leak fixes - JDH
2005-05-10 Extended python agg wrapper and started implementing backend_agg2, an agg renderer
based on the python wrapper. This will be more flexible and easier to extend than the current backend_agg. See also examples/agg_test.py - JDH
2005-05-09 Added Marcin’s no legend patch to exclude lines from the autolegend builder
plot(x, y, label=’nolegend’)
2005-05-05 Upgraded to agg23
2005-05-05 Added newscalarformatter_demo.py to examples. -DSD
2005-05-04 Added NewScalarFormatter. Improved formatting of ticklabels, scientific notation, and
the ability to plot large large numbers with small ranges, by determining a numerical offset. See
ticker.NewScalarFormatter for more details. -DSD
2005-05-03 Added the option to specify a delimiter in pylab.load -DSD
2005-04-28 Added Darren’s line collection example
2005-04-28 Fixed aa property in agg - JDH
5.2. Previous Whats New
367
Matplotlib, Release 2.1.2
2005-04-27 Set postscript page size in .matplotlibrc - DSD
2005-04-26 Added embedding in qt example. - JDH
2005-04-14 Applied Michael Brady’s qt backend patch: 1) fix a bug where keyboard input was
grabbed by the figure and not released 2) turn on cursor changes 3) clean up a typo and commentedout print statement. - JDH
2005-04-14 Applied Eric Firing’s masked data lines patch and contour patch. Support for masked arrays has been added to the plot command and to the Line2D object. Only the valid points are plotted.
A “valid_only” kwarg was added to the get_xdata() and get_ydata() methods of Line2D; by default it
is False, so that the original data arrays are returned. Setting it to True returns the plottable points. see examples/masked_demo.py - JDH
2005-04-13 Applied Tim Leslie’s arrow key event handling patch - JDH
0.80 released
2005-04-11 Applied a variant of rick’s xlim/ylim/axis patch. These functions now take kwargs to let
you selectively alter only the min or max if desired. e.g., xlim(xmin=2) or axis(ymax=3). They
always return the new lim. - JDH
2005-04-11 Incorporated Werner’s wx patch – wx backend should be compatible with wxpython2.4
and recent versions of 2.5. Some early versions of wxpython 2.5 will not work because there was
a temporary change in the dc API that was rolled back to make it 2.4 compliant
2005-04-11 modified tkagg show so that new figure window pops up on call to figure
2005-04-11 fixed wxapp init bug
2005-04-02 updated backend_ps.draw_lines, draw_markers for use with the new API - DSD
2005-04-01 Added editable polygon example
2005-03-31 0.74 released
2005-03-30 Fixed and added checks for floating point inaccuracy in ticker.Base - DSD
2005-03-30 updated /ellipse definition in backend_ps.py to address bug #1122041 - DSD
2005-03-29 Added unicode support for Agg and PS - JDH
2005-03-28 Added Jarrod’s svg patch for text - JDH
2005-03-28 Added Ludal’s arrow and quiver patch - JDH
2005-03-28 Added label kwarg to Axes to facilitate forcing the creation of new Axes with otherwise
identical attributes
2005-03-28 Applied boxplot and OSX font search patches
2005-03-27 Added ft2font NULL check to fix Japanase font bug - JDH
2005-03-27 Added sprint legend patch plus John Gill’s tests and fix – see examples/legend_auto.py JDH
368
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-03-19 0.73.1 released
2005-03-19 Reverted wxapp handling because it crashed win32 - JDH
2005-03-18 Add .number attribute to figure objects returned by figure() - FP
2005-03-18 0.73 released
2005-03-16 Fixed labelsep bug
2005-03-16 Applied Darren’s ticker fix for small ranges - JDH
2005-03-16 Fixed tick on horiz colorbar - JDH
2005-03-16 Added Japanses winreg patch - JDH
2005-03-15 backend_gtkagg.py: changed to use double buffering, this fixes the problem reported
Joachim Berdal Haga - “Parts of plot lagging from previous frame in animation”. Tested with
anim.py and it makes no noticable difference to performance (23.7 before, 23.6 after) - SC
2005-03-14 add src/_backend_gdk.c extension to provide a substitute function for
pixbuf.get_pixels_array(). Currently pixbuf.get_pixels_array() only works with Numeric, and
then only works if pygtk has been compiled with Numeric support. The change provides a function
pixbuf_get_pixels_array() which works with Numeric and numarray and is always available. It
means that backend_gtk should be able to display images and mathtext in all circumstances. - SC
2005-03-11 Upgraded CXX to 5.3.1
2005-03-10 remove GraphicsContextPS.set_linestyle() and GraphicsContextSVG.set_linestyle() since
they do no more than the base class GraphicsContext.set_linestyle() - SC
2005-03-09 Refactored contour functionality into dedicated module
2005-03-09 Added Eric’s contourf updates and Nadia’s clabel functionality
2005-03-09 Moved colorbar to figure.Figure to expose it for API developers
• JDH
2005-03-09 backend_cairo.py: implemented draw_markers() - SC
2005-03-09 cbook.py: only use enumerate() (the python version) if the builtin
version is not available. Add new function ‘izip’ which is set to itertools.izip if available and the
python equivalent if not available. - SC
2005-03-07 backend_gdk.py: remove PIXELS_PER_INCH from points_to_pixels(), but
still use it to adjust font sizes. This allows the GTK version of line_styles.py to more closely
match GTKAgg, previously the markers were being drawn too large. - SC
2005-03-01 Added Eric’s contourf routines
2005-03-01 Added start of proper agg SWIG wrapper. I would like to expose agg functionality directly a the user level and this module will serve that purpose eventually, and will hopefully take
over most of the functionality of the current _image and _backend_agg modules. - JDH
5.2. Previous Whats New
369
Matplotlib, Release 2.1.2
2005-02-28 Fixed polyfit / polyval to convert input args to float arrays - JDH
2005-02-25 Add experimental feature to backend_gtk.py to enable/disable double
(DBL_BUFFER=True/False) - SC
buffering
2005-02-24 colors.py change ColorConverter.to_rgb() so it always returns rgb (and not rgba), allow
cnames keys to be cached, change the exception raised from RuntimeError to ValueError (like
hex2color()) hex2color() use a regular expression to check the color string is valid - SC
2005-02-23 Added rc param ps.useafm so backend ps can use native afm fonts or truetype.
afme
breaks mathtext but causes much smaller font sizes and may result in images that display better in
some contexts (e.g., pdfs incorporated into latex docs viewed in acrobat reader). I would like to
extend this approach to allow the user to use truetype only for mathtext, which should be easy.
2005-02-23 Used sequence protocol rather than tuple in agg collection drawing routines for greater
flexibility - JDH
2005-02-22 0.72.1 released
2005-02-21 fixed linestyles for collections – contour now dashes for levels <0
2005-02-21 fixed ps color bug - JDH
2005-02-15 fixed missing qt file
2005-02-15 banished error_msg and report_error. Internal backend methods like error_msg_gtk are
preserved. backend writers, check your backends, and diff against 0.72 to make sure I did the right
thing! - JDH
2005-02-14 Added enthought traits to matplotlib tree - JDH
2005-02-14 0.72 released
2005-02-14 fix bug in cbook alltrue() and onetrue() - SC
2005-02-11 updated qtagg backend from Ted - JDH
2005-02-11 matshow fixes for figure numbering, return value and docs - FP
2005-02-09 new zorder example for fine control in zorder_demo.py - FP
2005-02-09 backend renderer draw_lines now has transform in backend, as in draw_markers; use numerix in _backend_agg, aded small line optimization to agg
2005-02-09 subplot now deletes axes that it overlaps
2005-02-08 Added transparent support for gzipped files in load/save - Fernando Perez (FP from now
on).
2005-02-08 Small optimizations in PS backend. They may have a big impact for large plots, otherwise they don’t hurt - FP
2005-02-08 Added transparent support for gzipped files in load/save - Fernando Perez (FP from now
on).
370
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2005-02-07 Added newstyle path drawing for markers - only implemented in agg currently - JDH
2005-02-05 Some superscript text optimizations for ticking log plots
2005-02-05 Added some default key press events to pylab figures: ‘g’ toggles grid - JDH
2005-02-05 Added some support for handling log switching for lines that have nonpos data - JDH
2005-02-04 Added Nadia’s contour patch - contour now has matlab compatible syntax; this also fixed
an unequal sized contour array bug- JDH
2005-02-04 Modified GTK backends to allow the FigureCanvas to be resized smaller than its original
size - SC
2005-02-02 Fixed a bug in dates mx2num - JDH
2005-02-02 Incorporated Fernando’s matshow - JDH
2005-02-01 Added Fernando’s figure num patch, including experemental support for pylab backend
switching, LineCOllection.color warns, savefig now a figure method, fixed a close(fig) bug - JDH
2005-01-31 updated datalim in contour - JDH
2005-01-30 Added backend_qtagg.py provided by Sigve Tjora - SC
2005-01-28 Added tk.inspect rc param to .matplotlibrc. IDLE users should set tk.pythoninspect:True
and interactive:True and backend:TkAgg
2005-01-28 Replaced examples/interactive.py with an updated script from Fernando Perez - SC
2005-01-27 Added support for shared x or y axes. See examples/shared_axis_demo.py
ples/ganged_plots.py
and
exam-
2005-01-27 Added Lee’s patch for missing symbols leq and LEFTbracket to _mathtext_data - JDH
2005-01-26 Added Baptiste’s two scales patch – see help(twinx) in the pylab interface for more info.
See also examples/two_scales.py
2005-01-24 Fixed a mathtext parser bug that prevented font changes in sub/superscripts - JDH
2005-01-24 Fixed contour to work w/ interactive changes in colormaps, clim, etc - JDH
2005-01-21 matplotlib-0.71 released
2005-01-21 Refactored numerix to solve vexing namespace issues - JDH
2005-01-21 Applied Nadia’s contour bug fix - JDH
2005-01-20 Made some changes to the contour routine - particularly region=1 seems t fix a lot of the
zigzag strangeness. Added colormaps as default for contour - JDH
2005-01-19 Restored builtin names which were overridden (min, max, abs, round, and sum) in pylab.
This is a potentially significant change for those who were relying on an array version of those functions that previously overrode builtin function names. - ADS
2005-01-18 Added accents to mathtext: hat, breve, grave, bar, acute, tilde, vec, dot, ddot. All of them
have the same syntax, e.g., to make an overbar you do bar{o} or to make an o umlaut you do ddot{o}.
The shortcuts are also provided, e.g., “o ‘e ‘e ~n .x ^y - JDH
5.2. Previous Whats New
371
Matplotlib, Release 2.1.2
2005-01-18 Plugged image resize memory leaks - JDH
2005-01-18 Fixed some mathtext parser problems relating to superscripts
2005-01-17 Fixed a yticklabel problem for colorbars under change of clim - JDH
2005-01-17 Cleaned up Destroy handling in wx reducing memleak/fig from approx 800k to approx
6k- JDH
2005-01-17 Added kappa to latex_to_bakoma - JDH
2005-01-15 Support arbitrary colorbar axes and horizontal colorbars - JDH
2005-01-15 Fixed colormap number of colors bug so that the colorbar has the same discretization as
the image - JDH
2005-01-15 Added Nadia’s x,y contour fix - JDH
2005-01-15 backend_cairo: added PDF support which requires pycairo 0.1.4. Its not usable yet, but is
ready for when the Cairo PDF backend matures - SC
2005-01-15 Added Nadia’s x,y contour fix
2005-01-12 Fixed set clip_on bug in artist - JDH
2005-01-11 Reverted pythoninspect in tkagg - JDH
2005-01-09 Fixed a backend_bases event bug caused when an event is triggered when location is None
- JDH
2005-01-07 Add patch from Stephen Walton to fix bug in pylab.load() when the % character is included in a comment. - ADS
2005-01-07 Added markerscale attribute to Legend class. This allows the marker size in the legend to
be adjusted relative to that in the plot. - ADS
2005-01-06 Add patch from Ben Vanhaeren to make the FigureManagerGTK vbox a public attribute
- SC
2004-12-30 Release 0.70
2004-12-28 Added coord location to key press and added a examples/picker_demo.py
2004-12-28 Fixed coords notification in wx toolbar - JDH
2004-12-28 Moved connection and disconnection event handling to the FigureCanvasBase. Backends
now only need to connect one time for each of the button press, button release and key press/release
functions. The base class deals with callbacks and multiple connections. This fixes flakiness on some
backends (tk, wx) in the presence of multiple connections and/or disconnect - JDH
2004-12-27 Fixed PS mathtext bug where color was not set - Jochen please verify correct - JDH
2004-12-27 Added Shadow class and added shadow kwarg to legend and pie for shadow effect - JDH
2004-12-27 Added pie charts and new example/pie_demo.py
372
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-12-23 Fixed an agg text rotation alignment bug, fixed some text kwarg processing bugs, and
added examples/text_rotation.py to explain and demonstrate how text rotations and alignment work
in matplotlib. - JDH
2004-12-22 0.65.1 released - JDH
2004-12-22 Fixed colorbar bug which caused colorbar not to respond to changes in colormap in some
instances - JDH
2004-12-22 Refactored NavigationToolbar in tkagg to support app embedding , init now takes (canvas,
window) rather than (canvas, figman) - JDH
2004-12-21 Refactored axes and subplot management - removed add_subplot and add_axes from the
FigureManager. classic toolbar updates are done via an observer pattern on the figure using
add_axobserver. Figure now maintains the axes stack (for gca) and supports axes deletion. Ported
changes to GTK, Tk, Wx, and FLTK. Please test! Added delaxes - JDH
2004-12-21 Lots of image optimizations - 4x performance boost over 0.65 JDH
2004-12-20 Fixed a figimage bug where the axes is shown and modified tkagg to move the destroy
binding into the show method.
2004-12-18 Minor refactoring of NavigationToolbar2 to support embedding in an application - JDH
2004-12-14 Added linestyle to collections (currently broken) - JDH
2004-12-14 Applied Nadia’s setupext patch to fix libstdc++ link problem with contour and solaris JDH
2004-12-14 A number of pychecker inspired fixes, including removal of True and False from cbook
which I erroneously thought was needed for python2.2 - JDH
2004-12-14 Finished porting doc strings for set introspection. Used silent_list for many get funcs that
return lists. JDH
2004-12-13 dates.py: removed all timezone() calls, except for UTC - SC
2004-12-13 0.65 released - JDH
2004-12-13 colors.py: rgb2hex(), hex2color() made simpler (and faster), also rgb2hex()
added
round() instead of integer truncation hex2color() - changed 256.0 divisor to 255.0, so now ‘#ffffff’
becomes (1.0,1.0,1.0) not (0.996,0.996,0.996) - SC
2004-12-11 Added ion and ioff to pylab interface - JDH
2004-12-11 backend_template.py: delete FigureCanvasTemplate.realize() - most backends don’t use
it and its no longer needed
backend_ps.py, backend_svg.py: delete show() and draw_if_interactive() - they are not needed for
image backends
backend_svg.py: write direct to file instead of StringIO - SC
2004-12-10 Added zorder to artists to control drawing order of lines, patches and text in axes. See examples/zoder_demo.py - JDH
5.2. Previous Whats New
373
Matplotlib, Release 2.1.2
2004-12-10 Fixed colorbar bug with scatter - JDH
2004-12-10 Added Nadia Dencheva <dencheva@stsci.edu> contour code - JDH
2004-12-10 backend_cairo.py: got mathtext working - SC
2004-12-09 Added Norm Peterson’s svg clipping patch
2004-12-09 Added Matthew Newville’s wx printing patch
2004-12-09 Migrated matlab to pylab - JDH
2004-12-09 backend_gtk.py: split into two parts
• backend_gdk.py - an image backend
• backend_gtk.py - A GUI backend that uses GDK - SC
2004-12-08 backend_gtk.py: remove quit_after_print_xvfb(*args), show_xvfb(),
Dialog_MeasureTool(gtk.Dialog) one month after sending mail to matplotlib-users asking if
anyone still uses these functions - SC
2004-12-02 backend_bases.py, backend_template.py: updated some of the method documentation to
make them consistent with each other - SC
2004-12-04 Fixed multiple bindings per event for TkAgg mpl_connect and mpl_disconnect. Added a
“test_disconnect” command line parameter to coords_demo.py JTM
2004-12-04 Fixed some legend bugs JDH
2004-11-30 Added over command for oneoff over plots. e.g., over(plot, x, y, lw=2). Works with any
plot function.
2004-11-30 Added bbox property to text - JDH
2004-11-29 Zoom to rect now respect reversed axes limits (for both linear and log axes). - GL
2004-11-29 Added the over command to the matlab interface. over allows you to add an overlay plot
regardless of hold state. - JDH
2004-11-25 Added Printf to mplutils for printf style format string formatting in C++ (should help
write better exceptions)
2004-11-24 IMAGE_FORMAT: remove from agg and gtkagg backends as its no longer used - SC
2004-11-23 Added matplotlib compatible set and get introspection. See set_and_get.py
2004-11-23 applied Norbert’s patched and exposed legend configuration to kwargs - JDH
2004-11-23 backend_gtk.py: added a default exception handler - SC
2004-11-18 backend_gtk.py: change so that the backend knows about all image formats and does not
need to use IMAGE_FORMAT in other backends - SC
2004-11-18 Fixed some report_error bugs in string interpolation as reported on SF bug tracker- JDH
2004-11-17 backend_gtkcairo.py: change so all print_figure() calls render using Cairo and get saved
using backend_gtk.print_figure() - SC
374
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-11-13 backend_cairo.py: Discovered the magic number (96) required for Cairo PS plots to
come out the right size. Restored Cairo PS output and added support for landscape mode - SC
2004-11-13 Added ishold - JDH
2004-11-12 Added many new matlab colormaps - autumn bone cool copper flag gray hot hsv jet pink
prism spring summer winter - PG
2004-11-11 greatly simplify the emitted postscript code - JV
2004-11-12 Added new plotting functions spy, spy2 for sparse matrix visualization - JDH
2004-11-11 Added rgrids, thetragrids for customizing the grid locations and labels for polar plots JDH
2004-11-11 make the Gtk backends build without an X-server connection - JV
2004-11-10 matplotlib/__init__.py: Added FROZEN to signal we are running under py2exe (or similar) - is used by backend_gtk.py - SC
2004-11-09 backend_gtk.py: Made fix suggested by maffew@cat.org.au to prevent problems when
py2exe calls pygtk.require(). - SC
2004-11-09 backend_cairo.py: Added support for printing to a fileobject. Disabled cairo PS output
which is not working correctly. - SC
2004-11-08 matplotlib-0.64 released
2004-11-04 Changed -dbackend processing to only use known backends, so we don’t clobber other
non-matplotlib uses of -d, like -debug.
2004-11-04 backend_agg.py: added IMAGE_FORMAT to list the formats that the backend can save
to. backend_gtkagg.py: added support for saving JPG files by using the GTK backend - SC
2004-10-31 backend_cairo.py: now produces png and ps files (although the figure sizing needs some
work). pycairo did not wrap all the necessary functions, so I wrapped them myself, they are included
in the backend_cairo.py doc string. - SC
2004-10-31 backend_ps.py: clean up the generated PostScript code, use the PostScript stack to hold
itermediate values instead of storing them in the dictionary. - JV
2004-10-30 backend_ps.py, ft2font.cpp, ft2font.h: fix the position of text in the PostScript output. The
new FT2Font method get_descent gives the distance between the lower edge of the bounding box and
the baseline of a string. In backend_ps the text is shifted upwards by this amount. - JV
2004-10-30 backend_ps.py: clean up the code a lot. Change the PostScript output to be more DSC
compliant. All definitions for the generated PostScript are now in a PostScript dictionary ‘mpldict’.
Moved the long comment about drawing ellipses from the PostScript output into a Python comment.
- JV
2004-10-30 backend_gtk.py: removed FigureCanvasGTK.realize() as its no longer needed. Merged
ColorManager into GraphicsContext backend_bases.py: For set_capstyle/joinstyle() only set cap or
joinstyle if there is no error. - SC
5.2. Previous Whats New
375
Matplotlib, Release 2.1.2
2004-10-30 backend_gtk.py: tidied up print_figure() and removed some of the dependency on widget
events - SC
2004-10-28 backend_cairo.py: The renderer is complete except for mathtext, draw_image() and clipping. gtkcairo works reasonably well. cairo does not yet create any files since I can’t figure how to
set the ‘target surface’, I don’t think pycairo wraps the required functions - SC
2004-10-28 backend_gtk.py: Improved the save dialog (GTK 2.4 only) so it presents the user with a
menu of supported image formats - SC
2004-10-28 backend_svg.py: change print_figure() to restore original face/edge color backend_ps.py :
change print_figure() to ensure original face/edge colors are restored even if there’s an IOError - SC
2004-10-27 Applied Norbert’s errorbar patch to support barsabove kwarg
2004-10-27 Applied Norbert’s legend patch to support None handles
2004-10-27 Added two more backends: backend_cairo.py, backend_gtkcairo.py They are not complete yet, currently backend_gtkcairo just renders polygons, rectangles and lines - SC
2004-10-21 Added polar axes and plots - JDH
2004-10-20 Fixed corrcoef bug exposed by corrcoef(X) where X is matrix
• JDH
2004-10-19 Added kwarg support to xticks and yticks to set ticklabel text properties – thanks to T. Edward Whalen for the suggestion
2004-10-19 Added support for PIL images in imshow(), image.py - ADS
2004-10-19 Re-worked exception handling in _image.py and _transforms.py to avoid masking problems with shared libraries. - JTM
2004-10-16 Streamlined the matlab interface wrapper, removed the noplot option to hist - just use
mlab.hist instead.
2004-09-30 Added Andrew Dalke’s strftime code to extend the range of dates supported by the DateFormatter - JDH
2004-09-30 Added barh - JDH
2004-09-30 Removed fallback to alternate array package from numerix so that ImportErrors are easier to debug. JTM
2004-09-30 Add GTK+ 2.4 support for the message in the toolbar. SC
2004-09-30 Made some changes to support python22 - lots of doc fixes. - JDH
2004-09-29 Added a Verbose class for reporting - JDH
2004-09-28 Released 0.63.0
2004-09-28 Added save to file object for agg - see examples/print_stdout.py
2004-09-24 Reorganized all py code to lib subdir
376
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-09-24 Fixed axes resize image edge effects on interpolation - required upgrade to agg22 which
fixed an agg bug related to this problem
2004-09-20 Added toolbar2 message display for backend_tkagg. JTM
2004-09-17 Added coords formatter attributes. These must be callable,
and return a string for the x or y data. These will be used to format the x and y data for the
coords box. Default is the axis major formatter. e.g.:
# format the coords message box def price(x):
DateFormatter(‘%Y-%m-%d’) ax.format_ydata = price
return ‘$%1.2f’%x ax.format_xdata =
2004-09-17 Total rewrite of dates handling to use python datetime with num2date, date2num and
drange. pytz for timezone handling, dateutils for spohisticated ticking. date ranges from 0001-9999
are supported. rrules allow arbitrary date ticking. examples/date_demo*.py converted to show
new usage. new example examples/date_demo_rrule.py shows how to use rrules in date plots.
The date locators are much more general and almost all of them have different constructors. See
matplotlib.dates for more info.
2004-09-15 Applied Fernando’s backend __init__ patch to support easier backend
Added his numutils to mlab. JDH
maintenance.
2004-09-16 Re-designated all files in matplotlib/images as binary and w/o keyword substitution using
“cvs admin -kb *.svg . . . ”. See binary files in “info cvs” under Linux. This was messing up builds
from CVS on windows since CVS was doing lf -> cr/lf and keyword substitution on the bitmaps. JTM
2004-09-15 Modified setup to build array-package-specific extensions for those extensions which are
array-aware. Setup builds extensions automatically for either Numeric, numarray, or both, depending
on what you have installed. Python proxy modules for the array-aware extensions import the version
optimized for numarray or Numeric determined by numerix. - JTM
2004-09-15 Moved definitions of infinity from mlab to numerix to avoid divide by zero warnings for
numarray - JTM
2004-09-09 Added axhline, axvline, axhspan and axvspan
2004-08-30 matplotlib 0.62.4 released
2004-08-30 Fixed a multiple images with different extent bug, Fixed markerfacecolor as RGB tuple
2004-08-27 Mathtext now more than 5x faster. Thanks to Paul Mcguire for fixes both to pyparsing
and to the matplotlib grammar! mathtext broken on python2.2
2004-08-25 Exposed Darren’s and Greg’s log ticking and formatting options to semilogx and friends
2004-08-23 Fixed grid w/o args to toggle grid state - JDH
2004-08-11 Added Gregory’s log patches for major and minor ticking
2004-08-18 Some pixel edge effects fixes for images
2004-08-18 Fixed TTF files reads in backend_ps on win32.
5.2. Previous Whats New
377
Matplotlib, Release 2.1.2
2004-08-18 Added base and subs properties for logscale plots, user modifiable
set_[x,y]scale(‘log’,base=b,subs=[mt1,mt2,. . . ]) - GL
using
2004-08-18 fixed a bug exposed by trying to find the HOME dir on win32 thanks to Alan Issac for
pointing to the light - JDH
2004-08-18 fixed errorbar bug in setting ecolor - JDH
2004-08-12 Added Darren Dale’s exponential ticking patch
2004-08-11 Added Gregory’s fltkagg backend
2004-08-09 matplotlib-0.61.0 released
2004-08-08 backend_gtk.py: get rid of the final PyGTK deprecation warning by replacing
tionMenu with gtkMenu in the 2.4 version of the classic toolbar.
gtkOp-
2004-08-06 Added Tk zoom to rect rectangle, proper idle drawing, and keybinding - JDH
2004-08-05 Updated installing.html and INSTALL - JDH
2004-08-01 backend_gtk.py: move all drawing code into the expose_event()
2004-07-28 Added Greg’s toolbar2 and backend_*agg patches - JDH
2004-07-28 Added image.imread with support for loading png into numerix arrays
2004-07-28 Added key modifiers to events - implemented dynamic updates and rubber banding for interactive pan/zoom - JDH
2004-07-27 did a readthrough of SVG, replacing all the string additions with string interps for efficiency, fixed some layout problems, added font and image support (through external pngs) - JDH
2004-07-25 backend_gtk.py: modify toolbar2 to make it easier to support GTK+ 2.4. Add GTK+ 2.4
toolbar support. - SC
2004-07-24 backend_gtk.py: Simplified classic toolbar creation - SC
2004-07-24 Added images/matplotlib.svg to be used when GTK+ windows are minimised - SC
2004-07-22 Added right mouse click zoom for NavigationToolbar2 panning mode. - JTM
2004-07-22 Added NavigationToolbar2 support to backend_tkagg. Minor tweak to backend_bases. JTM
2004-07-22 Incorporated Gergory’s renderer cache and buffer object cache - JDH
2004-07-22 Backend_gtk.py: Added support for GtkFileChooser, changed FileSelection/FileChooser
so that only one instance pops up, and made them both modal. - SC
2004-07-21 Applied backend_agg memory leak patch from hayden - jocallo@online.no. Found and
fixed a leak in binary operations on transforms. Moral of the story: never incref where you meant
to decref! Fixed several leaks in ft2font: moral of story: almost always return Py::asObject over
Py::Object - JDH
2004-07-21 Fixed a to string memory allocation bug in agg and image modules - JDH
2004-07-21 Added mpl_connect and mpl_disconnect to matlab interface - JDH
378
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-07-21 Added beginnings of users_guide to CVS - JDH
2004-07-20 ported toolbar2 to wx
2004-07-20 upgraded to agg21 - JDH
2004-07-20 Added new icons for toolbar2 - JDH
2004-07-19 Added vertical mathtext for *Agg and GTK - thanks Jim Benson! - JDH
2004-07-16 Added ps/eps/svg savefig options to wx and gtk JDH
2004-07-15 Fixed python framework tk finder in setupext.py - JDH
2004-07-14 Fixed layer images demo which was broken by the 07/12 image extent fixes - JDH
2004-07-13 Modified line collections to handle arbitrary length segments for each line segment. - JDH
2004-07-13 Fixed problems with image extent and origin - set_image_extent
imshow(blah, blah, extent=(xmin, xmax, ymin, ymax) instead - JDH
deprecated.
Use
2004-07-12 Added prototype for new nav bar with codifed event handling. Use mpl_connect rather
than connect for matplotlib event handling. toolbar style determined by rc toolbar param. backend
status: gtk: prototype, wx: in progress, tk: not started - JDH
2004-07-11 backend_gtk.py: use builtin round() instead of redefining it.
• SC
2004-07-10 Added embedding_in_wx3 example - ADS
2004-07-09 Added dynamic_image_wxagg to examples - ADS
2004-07-09 added support for embedding TrueType fonts in PS files - PEB
2004-07-09 fixed a sfnt bug exposed if font cache is not built
2004-07-09 added default arg None to matplotlib.matlab grid command to toggle current grid state
2004-07-08 0.60.2 released
2004-07-08 fixed a mathtext bug for ‘6’
2004-07-08 added some numarray bug workarounds
2004-07-07 0.60 released
2004-07-07 Fixed a bug in dynamic_demo_wx
2004-07-07 backend_gtk.py: raise SystemExit immediately if ‘import pygtk’ fails - SC
2004-07-05 Added new mathtext commands over{sym1}{sym2} and under{sym1}{sym2}
2004-07-05 Unified image and patch collections colormapping and scaling args. Updated docstrings
for all - JDH
2004-07-05 Fixed a figure legend bug and added examples/figlegend_demo.py - JDH
5.2. Previous Whats New
379
Matplotlib, Release 2.1.2
2004-07-01 Fixed a memory leak in image and agg to string methods
2004-06-25 Fixed fonts_demo spacing problems and added a kwargs version
fonts_demo_kw.py - JDH
of
the
fonts_demo
2004-06-25 finance.py: handle case when urlopen() fails - SC
2004-06-24 Support for multiple images on axes and figure, with blending. Support for upper and
lower image origins. clim, jet and gray functions in matlab interface operate on current image JDH
2004-06-23 ported code to Perry’s new colormap and norm scheme. Added new rc attributes image.aspect, image.interpolation, image.cmap, image.lut, image.origin
2004-06-20 backend_gtk.py: replace gtk.TRUE/FALSE with True/False. simplified
_make_axis_menu(). - SC
2004-06-19 anim_tk.py: Updated to use TkAgg by default (not GTK) backend_gtk_py: Added ‘_’ in
front of private widget creation functions - SC
2004-06-17 backend_gtk.py: Create a GC once in realise(), not every time draw() is called. - SC
2004-06-16 Added new py2exe FAQ entry and added frozen support in get_data_path for py2exe JDH
2004-06-16 Removed GTKGD, which was always just a proof-of-concept backend - JDH
2004-06-16 backend_gtk.py updates to replace deprecated functions
gtk.mainquit(), gtk.mainloop(). Update NavigationToolbar to use the new GtkToolbar API - SC
2004-06-15 removed set_default_font from font_manager to unify font customization using the new
function rc. See API_CHANGES for more info. The examples fonts_demo.py and fonts_demo_kw.py
are ported to the new API - JDH
2004-06-15 Improved (yet again!) axis scaling to properly handle singleton plots - JDH
2004-06-15 Restored the old FigureCanvasGTK.draw() - SC
2004-06-11 More memory leak fixes in transforms and ft2font - JDH
2004-06-11 Eliminated numerix .numerix file and environment variable NUMERIX. Fixed bug which
prevented command line overrides: –numarray or –numeric. - JTM
2004-06-10 Added rc configuration function rc; deferred all rc param setting until object creation
time; added new rc attrs: lines.markerfacecolor, lines.markeredgecolor, lines.markeredgewidth,
patch.linewidth, patch.facecolor, patch.edgecolor, patch.antialiased; see examples/customize_rc.py
for usage - JDH
2004-06-09 0.54.2 released
2004-06-08 Rewrote ft2font using CXX as part of general memory leak fixes; also fixed transform
memory leaks - JDH
2004-06-07 Fixed several problems with log ticks and scaling - JDH
2004-06-07 Fixed width/height issues for images - JDH
380
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-06-03 Fixed draw_if_interactive bug for semilogx;
2004-06-02 Fixed text clipping to clip to axes - JDH
2004-06-02 Fixed leading newline text and multiple newline text - JDH
2004-06-02 Fixed plot_date to return lines - JDH
2004-06-01 Fixed plot to work with x or y having shape N,1 or 1,N - JDH
2004-05-31 Added renderer markeredgewidth attribute of Line2D. - ADS
2004-05-29 Fixed tick label clipping to work with navigation.
2004-05-28 Added renderer grouping commands to support groups in SVG/PS. - JDH
2004-05-28 Fixed, this time I really mean it, the singleton plot plot([0]) scaling bug; Fixed Flavio’s
shape = N,1 bug - JDH
2004-05-28 added colorbar - JDH
2004-05-28 Made some changes to the matplotlib.colors.Colormap to propertly support clim - JDH
2004-05-27 0.54.1 released
2004-05-27 Lots of small bug fixes: rotated text at negative angles, errorbar capsize and autoscaling,
right tick label position, gtkagg on win98, alpha of figure background, singleton plots - JDH
2004-05-26 Added Gary’s errorbar stuff and made some fixes for length one plots and constant data
plots - JDH
2004-05-25 Tweaked TkAgg backend so that canvas.draw() works more like the other backends. Fixed
a bug resulting in 2 draws per figure mangager show(). - JTM
2004-05-19 0.54 released
2004-05-18 Added newline separated text with rotations to text.Text layout - JDH
2004-05-16 Added fast pcolor using PolyCollections. - JDH
2004-05-14 Added fast polygon collections - changed scatter to use them. Added multiple symbols to
scatter. 10x speedup on large scatters using *Agg and 5X speedup for ps. - JDH
2004-05-14 On second thought. . . created an “nx” namespace in in numerix which maps type names
onto typecodes the same way for both numarray and Numeric. This undoes my previous change
immediately below. To get a typename for Int16 useable in a Numeric extension: say nx.Int16. - JTM
2004-05-15 Rewrote transformation class in extension code, simplified all the artist constructors - JDH
2004-05-14 Modified the type definitions in the numarray side of numerix so that they are Numeric
typecodes and can be used with Numeric compilex extensions. The original numarray types were
renamed to type<old_name>. - JTM
2004-05-06 Gary Ruben sent me a bevy of new plot symbols and markers. See matplotlib.matlab.plot
- JDH
5.2. Previous Whats New
381
Matplotlib, Release 2.1.2
2004-05-06 Total rewrite of mathtext - factored ft2font stuff out of layout engine and defined abstract
class for font handling to lay groundwork for ps mathtext. Rewrote parser and made layout engine
much more precise. Fixed all the layout hacks. Added spacing commands / and hspace. Added
composite chars and defined angstrom. - JDH
2004-05-05 Refactored text instances out of backend; aligned text with arbitrary rotations is now supported - JDH
2004-05-05 Added a Matrix capability for numarray to numerix. JTM
2004-05-04 Updated whats_new.html.template to use dictionary and template loop, added anchors for
all versions and items; updated goals.txt to use those for links. PG
2004-05-04 Added fonts_demo.py to backend_driver, and AFM and TTF font caches
font_manager.py - PEB
to
2004-05-03 Redid goals.html.template to use a goals.txt file that has a pseudo restructured text organization. PG
2004-05-03 Removed the close buttons on all GUIs and added the python #! bang line to the examples
following Steve Chaplin’s advice on matplotlib dev
2004-04-29 Added CXX and rewrote backend_agg using it; tracked down and fixed agg memory leak
- JDH
2004-04-29 Added stem plot command - JDH
2004-04-28 Fixed PS scaling and centering bug - JDH
2004-04-26 Fixed errorbar autoscale problem - JDH
2004-04-22 Fixed copy tick attribute bug, fixed singular datalim ticker bug; fixed mathtext fontsize interactive bug. - JDH
2004-04-21 Added calls to draw_if_interactive to axes(), legend(), and pcolor().
pcolor(). - JTM
Deleted duplicate
2004-04-21 matplotlib 0.53 release
2004-04-19 Fixed vertical alignment bug in PS backend - JDH
2004-04-17 Added support for two scales on the “same axes” with tick different ticking and labeling
left right or top bottom. See examples/two_scales.py - JDH
2004-04-17 Added default dirs as list rather than single dir in setupext.py - JDH
2004-04-16 Fixed wx exception swallowing bug (and there was much rejoicing!) - JDH
2004-04-16 Added new ticker locator a formatter, fixed default font return - JDH
2004-04-16 Added get_name method to FontProperties class. Fixed font lookup in GTK and WX
backends. - PEB
2004-04-16 Added get- and set_fontstyle msethods. - PEB
2004-04-10 Mathtext fixes: scaling with dpi, - JDH
382
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2004-04-09 Improved font detection algorithm. - PEB
2004-04-09 Move deprecation warnings from text.py to __init__.py - PEB
2004-04-09 Added default font customization - JDH
2004-04-08 Fixed viewlim set problem on axes and axis. - JDH
2004-04-07 Added validate_comma_sep_str and font properties paramaters to __init__.
Removed
font families and added rcParams to FontProperties __init__ arguments in font_manager. Added
default font property parameters to .matplotlibrc file with descriptions. Added deprecation warnings
to the get_ - and set_fontXXX methods of the Text object. - PEB
2004-04-06 Added load and save commands for ASCII data - JDH
2004-04-05 Improved font caching by not reading AFM fonts until needed. Added better documentation. Changed the behaviour of the get_family, set_family, and set_name methods of FontProperties.
- PEB
2004-04-05 Added WXAgg backend - JDH
2004-04-04 Improved font caching in backend_agg with changes to font_manager - JDH
2004-03-29 Fixed fontdicts and kwargs to work with new font manager - JDH
This is the Old, stale, never used changelog
2002-12-10 - Added a TODO file and CHANGELOG. Lots to do – get
crackin’!
• Fixed y zoom tool bug
• Adopted a compromise fix for the y data clipping problem. The problem was that for solid lines,
the y data clipping (as opposed to the gc clipping) caused artifactual horizontal solid lines near
the ylim boundaries. I did a 5% offset hack in Axes set_ylim functions which helped, but didn’t
cure the problem for very high gain y zooms. So I disabled y data clipping for connected lines
. If you need extensive y clipping, either plot(y,x) because x data clipping is always enabled, or
change the _set_clip code to ‘if 1’ as indicated in the lines.py src. See _set_clip in lines.py and
set_ylim in figure.py for more information.
2002-12-11 - Added a measurement dialog to the figure window to
measure axes position and the delta x delta y with a left mouse drag. These defaults
can be overridden by deriving from Figure and overrriding button_press_event, button_release_event, and motion_notify_event, and _dialog_measure_tool.
• fixed the navigation dialog so you can check the axes the navigation buttons apply to.
2003-04-23 Released matplotlib v0.1
2003-04-24 Added a new line style PixelLine2D which is the plots the markers as pixels (as small as
possible) with format symbol ‘,’
Added a new class Patch with derived classes Rectangle, RegularPolygon and Circle
2003-04-25 Implemented new functions errorbar, scatter and hist
5.2. Previous Whats New
383
Matplotlib, Release 2.1.2
Added a new line type ‘|’ which is a vline. syntax is plot(x, Y, ‘|’) where y.shape = len(x),2
and each row gives the ymin,ymax for the respective values of x. Previously I had implemented
vlines as a list of lines, but I needed the efficientcy of the numeric clipping for large numbers of
vlines outside the viewport, so I wrote a dedicated class Vline2D which derives from Line2D
2003-05-01
Fixed ytick bug where grid and tick show outside axis viewport with gc clip
2003-05-14
Added new ways to specify colors 1) matlab format string 2) html-style hex string, 3) rgb tuple.
See examples/color_demo.py
2003-05-28
Changed figure rendering to draw form a pixmap to reduce flicker.
See examples/system_monitor.py for an example where the plot is continusouly updated w/o flicker. This
example is meant to simulate a system monitor that shows free CPU, RAM, etc. . .
2003-08-04
Added Jon Anderson’s GTK shell, which doesn’t require pygtk to have threading built-in and
looks nice!
2003-08-25
Fixed deprecation warnings for python2.3 and pygtk-1.99.18
2003-08-26
Added figure text with new example examples/figtext.py
2003-08-27
Fixed bugs i figure text with font override dictionairies and fig text that was placed outside the
window bounding box
2003-09-1 thru 2003-09-15
Added a postscript and a GD module backend
2003-09-16
Fixed font scaling and point scaling so circles, squares, etc on lines will scale with DPI as will
fonts. Font scaling is not fully implemented on the gtk backend because I have not figured out
how to scale fonts to arbitrary sizes with GTK
2003-09-17
Fixed figure text bug which crashed X windows on long figure text extending beyond display
area. This was, I believe, due to the vestigial erase functionality that was no longer needed since
I began rendering to a pixmap
2003-09-30 Added legend
2003-10-01 Fixed bug when colors are specified with rgb tuple or hex string.
384
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
2003-10-21 Andrew Straw provided some legend code which I modified and incorporated.
Andrew!
Thanks
2003-10-27 Fixed a bug in axis.get_view_distance that affected zoom in versus out with interactive
scrolling, and a bug in the axis text reset system that prevented the text from being redrawn on a
interactive gtk view lim set with the widget
Fixed a bug in that prevented the manual setting of ticklabel strings from working properly
2003-11-02 - Do a nearest neighbor color pick on GD when allocate fails
2003-11-02
• Added pcolor plot
• Added MRI example
• Fixed bug that screwed up label position if xticks or yticks were empty
• added nearest neighbor color picker when GD max colors exceeded
• fixed figure background color bug in GD backend
2003-11-10 - 2003-11-11
• major refactoring.
– Ticks (with labels, lines and grid) handled by dedicated class
– Artist now know bounding box and dpi
– Bounding boxes and transforms handled by dedicated classes
– legend in dedicated class. Does a better job of alignment and bordering. Can be initialized
with specific line instances. See examples/legend_demo2.py
2003-11-14 Fixed legend positioning bug and added new position args
2003-11-16 Finsihed porting GD to new axes API
2003-11-20 - add TM for matlab on website and in docs
2003-11-20 - make a nice errorbar and scatter screenshot
2003-11-20 - auto line style cycling for multiple line types broken
2003-11-18 (using inkrect) :logical rect too big on gtk backend
2003-11-18 ticks don’t reach edge of axes in gtk mode – rounding error?
2003-11-20 - port Gary’s errorbar code to new API before 0.40
2003-11-20 - problem with stale _set_font. legend axes box doesn’t resize on save in GTK backend –
see htdocs legend_demo.py
2003-11-21 - make a dash-dot dict for the GC
2003-12-15 - fix install path bug
5.2. Previous Whats New
385
Matplotlib, Release 2.1.2
5.2.2 New in matplotlib 0.98.4
Table of Contents
• New in matplotlib 0.98.4
– Legend enhancements
– Fancy annotations and arrows
– Native OS X backend
– psd amplitude scaling
– Fill between
– Lots more
It’s been four months since the last matplotlib release, and there are a lot of new features and bug-fixes.
Thanks to Charlie Moad for testing and preparing the source release, including binaries for OS X and
Windows for python 2.4 and 2.5 (2.6 and 3.0 will not be available until numpy is available on those releases). Thanks to the many developers who contributed to this release, with contributions from Jae-Joon
Lee, Michael Droettboom, Ryan May, Eric Firing, Manuel Metz, Jouni K. Seppänen, Jeff Whitaker, Darren
Dale, David Kaplan, Michiel de Hoon and many others who submitted patches
Legend enhancements
Jae-Joon has rewritten the legend class, and added support for multiple columns and rows, as well as fancy
box drawing. See legend() and matplotlib.legend.Legend.
Fig. 5.5: Whats New 98 4 Legend
386
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fancy annotations and arrows
Jae-Joon has added lots of support to annotations for drawing fancy boxes and connectors in annotations.
See annotate() and BoxStyle, ArrowStyle, and ConnectionStyle.
Fig. 5.6: Whats New 98 4 Fancy
Native OS X backend
Michiel de Hoon has provided a native Mac OSX backend that is almost completely implemented in C. The
backend can therefore use Quartz directly and, depending on the application, can be orders of magnitude
faster than the existing backends. In addition, no third-party libraries are needed other than Python and
NumPy. The backend is interactive from the usual terminal application on Mac using regular Python. It
hasn’t been tested with ipython yet, but in principle it should to work there as well. Set ‘backend : macosx’
in your matplotlibrc file, or run your script with:
> python myfile.py -dmacosx
psd amplitude scaling
Ryan May did a lot of work to rationalize the amplitude scaling of psd() and friends. See
sphx_glr_gallery_lines_bars_and_markers_psd_demo.py. The changes should increase MATLAB compatibility and increase scaling options.
5.2. Previous Whats New
387
Matplotlib, Release 2.1.2
Fill between
Added a fill_between() function to make it easier to do shaded region plots in the presence of masked
data. You can pass an x array and a ylower and yupper array to fill between, and an optional where argument
which is a logical mask where you want to do the filling.
Fig. 5.7: Whats New 98 4 Fill Between
Lots more
Here are the 0.98.4 notes from the CHANGELOG:
Added mdehoon's native macosx backend from sf patch 2179017 - JDH
Removed the prints in the set_*style commands.
pretty-printed strings instead - JDH
Return the list of
Some of the changes Michael made to improve the output of the
property tables in the rest docs broke of made difficult to use
some of the interactive doc helpers, e.g., setp and getp. Having all
the rest markup in the ipython shell also confused the docstrings.
I added a new rc param docstring.harcopy, to format the docstrings
differently for hardcopy and other use. The ArtistInspector
could use a little refactoring now since there is duplication of
effort between the rest out put and the non-rest output - JDH
Updated spectral methods (psd, csd, etc.) to scale one-sided
densities by a factor of 2 and, optionally, scale all densities by
the sampling frequency. This gives better MATLAB
compatibility. -RM
Fixed alignment of ticks in colorbars. -MGD
drop the deprecated "new" keyword of np.histogram() for numpy 1.2
or later. -JJL
388
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fixed a bug in svg backend that new_figure_manager() ignores
keywords arguments such as figsize, etc. -JJL
Fixed a bug that the handlelength of the new legend class set too
short when numpoints=1 -JJL
Added support for data with units (e.g., dates) to
Axes.fill_between. -RM
Added fancybox keyword to legend. Also applied some changes for
better look, including baseline adjustment of the multiline texts
so that it is center aligned. -JJL
The transmuter classes in the patches.py are reorganized as
subclasses of the Style classes. A few more box and arrow styles
are added. -JJL
Fixed a bug in the new legend class that didn't allowed a tuple of
coordinate values as loc. -JJL
Improve checks for external dependencies, using subprocess
(instead of deprecated popen*) and distutils (for version
checking) - DSD
Reimplementation of the legend which supports baseline alignment,
multi-column, and expand mode. - JJL
Fixed histogram autoscaling bug when bins or range are given
explicitly (fixes Debian bug 503148) - MM
Added rcParam axes.unicode_minus which allows plain hyphen for
minus when False - JDH
Added scatterpoints support in Legend. patch by Erik Tollerud JJL
Fix crash in log ticking. - MGD
Added static helper method BrokenHBarCollection.span_where and
Axes/pyplot method fill_between. See
examples/pylab/fill_between.py - JDH
Add x_isdata and y_isdata attributes to Artist instances, and use
them to determine whether either or both coordinates are used when
updating dataLim. This is used to fix autoscaling problems that
had been triggered by axhline, axhspan, axvline, axvspan. - EF
Update the psd(), csd(), cohere(), and specgram() methods of Axes
and the csd() cohere(), and specgram() functions in mlab to be in
sync with the changes to psd(). In fact, under the hood, these
all call the same core to do computations. - RM
Add 'pad_to' and 'sides' parameters to mlab.psd() to allow
5.2. Previous Whats New
389
Matplotlib, Release 2.1.2
controlling of zero padding and returning of negative frequency
components, respectively. These are added in a way that does not
change the API. - RM
Fix handling of c kwarg by scatter; generalize is_string_like to
accept numpy and numpy.ma string array scalars. - RM and EF
Fix a possible EINTR problem in dviread, which might help when
saving pdf files from the qt backend. - JKS
Fix bug with zoom to rectangle and twin axes - MGD
Added Jae Joon's fancy arrow, box and annotation enhancements -see examples/pylab_examples/annotation_demo2.py
Autoscaling is now supported with shared axes - EF
Fixed exception in dviread that happened with Minion - JKS
set_xlim, ylim now return a copy of the viewlim array to avoid
modify inplace surprises
Added image thumbnail generating function
matplotlib.image.thumbnail. See examples/misc/image_thumbnail.py
- JDH
Applied scatleg patch based on ideas and work by Erik Tollerud and
Jae-Joon Lee. - MM
Fixed bug in pdf backend: if you pass a file object for output
instead of a filename, e.g., in a wep app, we now flush the object
at the end. - JKS
Add path simplification support to paths with gaps. - EF
Fix problem with AFM files that don't specify the font's full name
or family name. - JKS
Added 'scilimits' kwarg to Axes.ticklabel_format() method, for
easy access to the set_powerlimits method of the major
ScalarFormatter. - EF
Experimental new kwarg borderpad to replace pad in legend, based
on suggestion by Jae-Joon Lee. - EF
Allow spy to ignore zero values in sparse arrays, based on patch
by Tony Yu. Also fixed plot to handle empty data arrays, and
fixed handling of markers in figlegend. - EF
Introduce drawstyles for lines. Transparently split linestyles
like 'steps--' into drawstyle 'steps' and linestyle '--'. Legends
always use drawstyle 'default'. - MM
390
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fixed quiver and quiverkey bugs (failure to scale properly when
resizing) and added additional methods for determining the arrow
angles - EF
Fix polar interpolation to handle negative values of theta - MGD
Reorganized cbook and mlab methods related to numerical
calculations that have little to do with the goals of those two
modules into a separate module numerical_methods.py Also, added
ability to select points and stop point selection with keyboard in
ginput and manual contour labeling code. Finally, fixed contour
labeling bug. - DMK
Fix backtick in Postscript output. - MGD
[ 2089958 ] Path simplification for vector output backends
Leverage the simplification code exposed through path_to_polygons
to simplify certain well-behaved paths in the vector backends
(PDF, PS and SVG). "path.simplify" must be set to True in
matplotlibrc for this to work. - MGD
Add "filled" kwarg to Path.intersects_path and
Path.intersects_bbox. - MGD
Changed full arrows slightly to avoid an xpdf rendering problem
reported by Friedrich Hagedorn. - JKS
Fix conversion of quadratic to cubic Bezier curves in PDF and PS
backends. Patch by Jae-Joon Lee. - JKS
Added 5-point star marker to plot command q- EF
Fix hatching in PS backend - MGD
Fix log with base 2 - MGD
Added support for bilinear interpolation in
NonUniformImage; patch by Gregory Lielens. - EF
Added support for multiple histograms with data of
different length - MM
Fix step plots with log scale - MGD
Fix masked arrays with markers in non-Agg backends - MGD
Fix clip_on kwarg so it actually works correctly - MGD
Fix locale problems in SVG backend - MGD
fix quiver so masked values are not plotted - JSW
improve interactive pan/zoom in qt4 backend on windows - DSD
5.2. Previous Whats New
391
Matplotlib, Release 2.1.2
Fix more bugs in NaN/inf handling. In particular, path
simplification (which does not handle NaNs or infs) will be turned
off automatically when infs or NaNs are present. Also masked
arrays are now converted to arrays with NaNs for consistent
handling of masks and NaNs - MGD and EF
Added support for arbitrary rasterization resolutions to the SVG
backend. - MW
5.2.3 New in matplotlib 0.99
Table of Contents
• New in matplotlib 0.99
– New documentation
– mplot3d
– axes grid toolkit
– Axis spine placement
New documentation
Jae-Joon Lee has written two new guides Legend guide and Advanced Annotation. Michael Sarahan has
written Image tutorial. John Hunter has written two new tutorials on working with paths and transformations: Path Tutorial and Transformations Tutorial.
mplot3d
Reinier Heeres has ported John Porter’s mplot3d over to the new matplotlib transformations framework, and
it is now available as a toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl installs). See
mplot3d-examples-index and Getting started
axes grid toolkit
Jae-Joon Lee has added a new toolkit to ease displaying multiple images in matplotlib, as well as some
support for curvilinear grids to support the world coordinate system. The toolkit is included standard with
all new mpl installs. See axes_grid1-examples-index, axisartist-examples-index, What is axes_grid1 toolkit?
and axisartist
392
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fig. 5.8: Whats New 99 Mplot3d
Fig. 5.9: Whats New 99 Axes Grid
5.2. Previous Whats New
393
Matplotlib, Release 2.1.2
Axis spine placement
Andrew Straw has added the ability to place “axis spines” – the lines that denote the data limits – in various
arbitrary locations. No longer are your axis lines constrained to be a simple rectangle around the figure –
you can turn on or off left, bottom, right and top, as well as “detach” the spine to offset it away from the data.
See sphx_glr_gallery_ticks_and_spines_spine_placement_demo.py and matplotlib.spines.Spine.
Fig. 5.10: Whats New 99 Spines
5.2.4 New in matplotlib 1.0
Table of Contents
• New in matplotlib 1.0
– HTML5/Canvas backend
– Sophisticated subplot grid layout
– Easy pythonic subplots
– Contour fixes and and triplot
– multiple calls to show supported
– mplot3d graphs can be embedded in arbitrary axes
– tick_params
– Lots of performance and feature enhancements
– Much improved software carpentry
– Bugfix marathon
394
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
HTML5/Canvas backend
Simon Ratcliffe and Ludwig Schwardt have released an HTML5/Canvas backend for matplotlib. The backend is almost feature complete, and they have done a lot of work comparing their html5 rendered images
with our core renderer Agg. The backend features client/server interactive navigation of matplotlib figures
in an html5 compliant browser.
Sophisticated subplot grid layout
Jae-Joon Lee has written gridspec, a new module for doing complex subplot layouts, featuring row and
column spans and more. See Customizing Location of Subplot Using GridSpec for a tutorial overview.
Fig. 5.11: Demo Gridspec01
Easy pythonic subplots
Fernando Perez got tired of all the boilerplate code needed to create a figure and multiple subplots when
using the matplotlib API, and wrote a subplots() helper function. Basic usage allows you to create the
figure and an array of subplots with numpy indexing (starts with 0). e.g.:
fig, axarr = plt.subplots(2, 2)
axarr[0,0].plot([1,2,3])
# upper, left
See sphx_glr_gallery_subplots_axes_and_figures_subplot_demo.py for several code examples.
Contour fixes and and triplot
Ian Thomas has fixed a long-standing bug that has vexed our most talented developers for years.
contourf() now handles interior masked regions, and the boundaries of line and filled contours coincide.
Additionally, he has contributed a new module tri and helper function triplot() for creating and plotting
unstructured triangular grids.
5.2. Previous Whats New
395
Matplotlib, Release 2.1.2
Fig. 5.12: Triplot Demo
multiple calls to show supported
A long standing request is to support multiple calls to show(). This has been difficult because it is hard
to get consistent behavior across operating systems, user interface toolkits and versions. Eric Firing has
done a lot of work on rationalizing show across backends, with the desired behavior to make show raise all
newly created figures and block execution until they are closed. Repeated calls to show should raise newly
created figures since the last call. Eric has done a lot of testing on the user interface toolkits and versions
and platforms he has access to, but it is not possible to test them all, so please report problems to the mailing
list and bug tracker.
mplot3d graphs can be embedded in arbitrary axes
You can now place an mplot3d graph into an arbitrary axes location, supporting mixing of 2D and 3D graphs
in the same figure, and/or multiple 3D graphs in a single figure, using the “projection” keyword argument to
add_axes or add_subplot. Thanks Ben Root.
Fig. 5.13: Whats New 1 Subplot3d
396
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
tick_params
Eric Firing wrote tick_params, a convenience method for changing the appearance of ticks and tick labels.
See pyplot function tick_params() and associated Axes method tick_params().
Lots of performance and feature enhancements
• Faster magnification of large images, and the ability to zoom in to a single pixel
• Local installs of documentation work better
• Improved “widgets” – mouse grabbing is supported
• More accurate snapping of lines to pixel boundaries
• More consistent handling of color, particularly the alpha channel, throughout the API
Much improved software carpentry
The matplotlib trunk is probably in as good a shape as it has ever been, thanks to improved software carpentry. We now have a buildbot which runs a suite of nose regression tests on every svn commit, auto-generating
a set of images and comparing them against a set of known-goods, sending emails to developers on failures
with a pixel-by-pixel image comparison. Releases and release bugfixes happen in branches, allowing active new feature development to happen in the trunk while keeping the release branches stable. Thanks to
Andrew Straw, Michael Droettboom and other matplotlib developers for the heavy lifting.
Bugfix marathon
Eric Firing went on a bug fixing and closing marathon, closing over 100 bugs on the bug tracker with help
from Jae-Joon Lee, Michael Droettboom, Christoph Gohlke and Michiel de Hoon.
5.2.5 New in matplotlib 1.1
Table of Contents
• New in matplotlib 1.1
– Sankey Diagrams
– Animation
– Tight Layout
– PyQT4, PySide, and IPython
– Legend
– mplot3d
5.2. Previous Whats New
397
Matplotlib, Release 2.1.2
– Numerix support removed
– Markers
– Other improvements
Note: matplotlib 1.1 supports Python 2.4 to 2.7
Sankey Diagrams
Kevin Davies has extended Yannick Copin’s original Sankey example into a module (sankey) and
provided new examples (sphx_glr_gallery_api_sankey_basics.py, sphx_glr_gallery_api_sankey_links.py,
sphx_glr_gallery_api_sankey_rankine.py).
Fig. 5.14: Sankey Rankine
Animation
Ryan May has written a backend-independent framework for creating animated figures. The animation
module is intended to replace the backend-specific examples formerly in the examples-index listings. Exam398
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
ples using the new framework are in animation-examples-index; see the entrancing double pendulum which
uses matplotlib.animation.Animation.save() to create the movie below.
This should be considered as a beta release of the framework; please try it and provide feedback.
Tight Layout
A frequent issue raised by users of matplotlib is the lack of a layout engine to nicely space out elements of
the plots. While matplotlib still adheres to the philosophy of giving users complete control over the placement of plot elements, Jae-Joon Lee created the tight_layout module and introduced a new command
tight_layout() to address the most common layout issues.
before tight_layout
y-label
1.0
0.5
y-label
0.0
0.050.0
0.2 before
0.4tight_layout
0.6
0.8
x-label
1.0
0.00
0.05
y-label
y-label
0.05
0.00
x-label
1.0
0.5
0.0
0.0
0.05
0.00
0.05
0.05
after tight_layout
0.2
0.4
0.6
x-label
0.8
1.0
after tight_layout
0.05
0.00
x-label
0.05
The usage of this functionality can be as simple as
5.2. Previous Whats New
399
Matplotlib, Release 2.1.2
plt.tight_layout()
and it will adjust the spacing between subplots so that the axis labels do not overlap with neighboring
subplots. A Tight Layout guide has been created to show how to use this new tool.
PyQT4, PySide, and IPython
Gerald Storer made the Qt4 backend compatible with PySide as well as PyQT4. At present, however, PySide
does not support the PyOS_InputHook mechanism for handling gui events while waiting for text input, so
it cannot be used with the new version 0.11 of IPython. Until this feature appears in PySide, IPython users
should use the PyQT4 wrapper for QT4, which remains the matplotlib default.
An rcParam entry, “backend.qt4”, has been added to allow users to select PyQt4, PyQt4v2, or PySide. The
latter two use the Version 2 Qt API. In most cases, users can ignore this rcParam variable; it is available to
aid in testing, and to provide control for users who are embedding matplotlib in a PyQt4 or PySide app.
Legend
Jae-Joon Lee has improved plot legends. First, legends for complex plots such as stem() plots will now
display correctly. Second, the ‘best’ placement of a legend has been improved in the presence of NANs.
See the Legend guide for more detailed explanation and examples.
Fig. 5.15: Legend Demo4
mplot3d
In continuing the efforts to make 3D plotting in matplotlib just as easy as 2D plotting, Ben Root has made
several improvements to the mplot3d module.
• Axes3D has been improved to bring the class towards feature-parity with regular Axes objects
• Documentation for Getting started was significantly expanded
400
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
• Axis labels and orientation improved
• Most 3D plotting functions now support empty inputs
• Ticker offset display added:
Fig. 5.16: Offset
• contourf() gains zdir and offset kwargs. You can now do this:
Fig. 5.17: Contourf3d 2
Numerix support removed
After more than two years of deprecation warnings, Numerix support has now been completely removed
from matplotlib.
Markers
The list of available markers for plot() and scatter() has now been merged. While they were mostly
similar, some markers existed for one function, but not the other. This merge did result in a conflict for
5.2. Previous Whats New
401
Matplotlib, Release 2.1.2
the ‘d’ diamond marker. Now, ‘d’ will be interpreted to always mean “thin” diamond while ‘D’ will mean
“regular” diamond.
Thanks to Michael Droettboom for this effort.
Other improvements
• Unit support for polar axes and arrow()
• PolarAxes gains getters and setters for “theta_direction”, and “theta_offset” to allow for theta to go
in either the clock-wise or counter-clockwise direction and to specify where zero degrees should be
placed. set_theta_zero_location() is an added convenience function.
• Fixed error in argument handling for tri-functions such as tripcolor()
• axes.labelweight parameter added to rcParams.
• For imshow(), interpolation=’nearest’ will now always perform an interpolation. A “none” option
has been added to indicate no interpolation at all.
• An error in the Hammer projection has been fixed.
• clabel for contour() now accepts a callable. Thanks to Daniel Hyams for the original patch.
• Jae-Joon Lee added the HBox and VBox classes.
• Christoph Gohlke reduced memory usage in imshow().
• scatter() now accepts empty inputs.
• The behavior for ‘symlog’ scale has been fixed, but this may result in some minor changes to existing
plots. This work was refined by ssyr.
• Peter Butterworth added named figure support to figure().
• Michiel de Hoon has modified the MacOSX backend to make its interactive behavior consistent with
the other backends.
• Pim Schellart added a new colormap called “cubehelix”. Sameer Grover also added a colormap called
“coolwarm”. See it and all other colormaps here.
• Many bug fixes and documentation improvements.
5.2.6 New in matplotlib 1.2
Table of Contents
• New in matplotlib 1.2
– Python 3.x support
– PGF/TikZ backend
– Locator interface
402
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
– Tri-Surface Plots
– Control the lengths of colorbar extensions
– Figures are picklable
– Set default bounding box in matplotlibrc
– New Boxplot Functionality
– New RC parameter functionality
– Streamplot
– New hist functionality
– Updated shipped dependencies
– Face-centred colors in tripcolor plots
– Hatching patterns in filled contour plots, with legends
– Known issues in the matplotlib 1.2 release
Note: matplotlib 1.2 supports Python 2.6, 2.7, and 3.1
Python 3.x support
Matplotlib 1.2 is the first version to support Python 3.x, specifically Python 3.1 and 3.2. To make this happen
in a reasonable way, we also had to drop support for Python versions earlier than 2.6.
This work was done by Michael Droettboom, the Cape Town Python Users’ Group, many others and supported financially in part by the SAGE project.
The following GUI backends work under Python 3.x: Gtk3Cairo, Qt4Agg, TkAgg and MacOSX. The other
GUI backends do not yet have adequate bindings for Python 3.x, but continue to work on Python 2.6 and
2.7, particularly the Qt and QtAgg backends (which have been deprecated). The non-GUI backends, such
as PDF, PS and SVG, work on both Python 2.x and 3.x.
Features that depend on the Python Imaging Library, such as JPEG handling, do not work, since the version
of PIL for Python 3.x is not sufficiently mature.
PGF/TikZ backend
Peter Würtz wrote a backend that allows matplotlib to export figures as drawing commands for LaTeX. These
can be processed by PdfLaTeX, XeLaTeX or LuaLaTeX using the PGF/TikZ package. Usage examples and
documentation are found in Typesetting With XeLaTeX/LuaLaTeX.
5.2. Previous Whats New
403
XƎLATEX
Matplotlib, Release 2.1.2
4.0
3.5
3.0
2.5
2.0
1.5
1.0
0.5
0.0
0.0
∞
2
unicode math:  =

0.5
.
1.0
2.0
3.0
1.5
2.5
3.5
°
unicode text: я, ψ, €, ü, 10 /µm
4.0
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 mplot3d toolkit called plot_trisurf().
Fig. 5.18: Trisurf3d
404
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Control the lengths of colorbar extensions
Andrew Dawson added a new keyword argument extendfrac to colorbar() to control the length of minimum and maximum colorbar extensions.
5.0
2.5
0.0
0
1
0.75
2
3
4
5
0.50 0.25 0.00 0.25 0.50
Default length colorbar extensions
5.0
6
0.75
2.5
0.0
0
1
2
3
4
5
6
0.75 0.50 0.25 0.00 0.25 0.50 0.75
Custom length colorbar extensions
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 boxplot() method. For every column of data passed to boxplot, the user can specify an accompanying
5.2. Previous Whats New
405
Matplotlib, Release 2.1.2
median and confidence interval.
Fig. 5.19: Boxplot Demo3
New RC parameter functionality
Matthew Emmett added a function and a context manager to help manage RC parameters: rc_file() and
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 streamplot() function to plot the streamlines of a vector
field. This has been a long-requested feature and complements the existing quiver() function for plotting
vector fields. In addition to simply plotting the streamlines of the vector field, 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.
New hist functionality
Nic Eggert added a new stacked kwarg to hist() that allows creation of stacked histograms using any of
the histogram types. Previously, this functionality was only available by using the barstacked histogram
406
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fig. 5.20: Plot Streamplot
5.2. Previous Whats New
407
Matplotlib, Release 2.1.2
type. Now, when stacked=True is passed to the function, any of the histogram types can be stacked. The
barstacked histogram type retains its previous functionality for backwards compatibility.
Updated shipped dependencies
The following dependencies that ship with matplotlib and are optionally installed alongside it have been
updated:
• pytz 2012d
• dateutil 1.5 on Python 2.x, and 2.1 on Python 3.x
Face-centred colors in tripcolor plots
Ian Thomas extended tripcolor() to allow one color value to be specified for each triangular face rather
than for each point in a triangulation.
Fig. 5.21: Tripcolor Demo
Hatching patterns in filled contour plots, with legends
Phil Elson added support for hatching to contourf(), together with the ability to use a legend to identify
contoured ranges.
Known issues in the matplotlib 1.2 release
• When using the Qt4Agg backend with IPython 0.11 or later, the save dialog will not display. This
should be fixed in a future version of IPython.
408
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fig. 5.22: Contourf Hatching
5.2.7 New in matplotlib 1.2.2
Table of Contents
• New in matplotlib 1.2.2
– Improved collections
– Multiple images on same axes are correctly transparent
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.
5.2.8 New in matplotlib 1.3
Table of Contents
• New in matplotlib 1.3
– New in 1.3.1
5.2. Previous Whats New
409
Matplotlib, Release 2.1.2
– New plotting features
– Updated Axes3D.contour methods
– Drawing
– Text
– Configuration (rcParams)
– Backends
– Documentation and examples
– Infrastructure
Note: matplotlib 1.3 supports Python 2.6, 2.7, 3.2, and 3.3
New in 1.3.1
1.3.1 is a bugfix release, primarily dealing with improved setup and handling of dependencies, and correcting
and enhancing the documentation.
The following changes were made in 1.3.1 since 1.3.0.
Enhancements
• Added a context manager for creating multi-page pdfs (see matplotlib.backends.backend_pdf.
PdfPages).
• The WebAgg backend should now have lower latency over heterogeneous Internet connections.
Bug fixes
• Histogram plots now contain the endline.
• Fixes to the Molleweide projection.
• Handling recent fonts from Microsoft and Macintosh-style fonts with non-ascii metadata is improved.
• Hatching of fill between plots now works correctly in the PDF backend.
• Tight bounding box support now works in the PGF backend.
• Transparent figures now display correctly in the Qt4Agg backend.
• Drawing lines from one subplot to another now works.
• Unit handling on masked arrays has been improved.
410
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
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 PR #1329) has added an xkcd-style sketch plotting mode. To use it, simply call
matplotlib.pyplot.xkcd() before creating your plot. For really fine control, it is also possible to modify
each artist’s sketch parameters individually with matplotlib.artist.Artist.set_sketch_params().
Fig. 5.23: Xkcd
5.2. Previous Whats New
411
Matplotlib, Release 2.1.2
Updated Axes3D.contour methods
Damon McDougall updated the tricontour() and tricontourf() methods to allow 3D contour plots
on abitrary unstructured user-specified triangulations.
Fig. 5.24: Tricontour3d
New eventplot plot type
Todd Jennings added a eventplot() function to create multiple rows or columns of identical line segments
Fig. 5.25: Eventplot Demo
As part of this feature, there is a new EventCollection class that allows for plotting and manipulating
rows or columns of identical line segments.
412
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Triangular grid interpolation
Geoffroy Billotey and Ian Thomas added classes to perform interpolation within triangular grids:
(LinearTriInterpolator and CubicTriInterpolator) and a utility class to find the triangles in which
points lie (TrapezoidMapTriFinder). A helper class to perform mesh refinement and smooth contouring
was also added (UniformTriRefiner). Finally, a class implementing some basic tools for triangular mesh
improvement was added (TriAnalyzer).
Fig. 5.26: Tricontour Smooth User
Baselines for stackplot
Till Stensitzki added non-zero baselines to stackplot(). They may be symmetric or weighted.
Fig. 5.27: Stackplot Demo2
5.2. Previous Whats New
413
Matplotlib, Release 2.1.2
Rectangular colorbar extensions
Andrew Dawson added a new keyword argument extendrect to colorbar() to optionally make colorbar
extensions rectangular instead of triangular.
More robust boxplots
Paul Hobson provided a fix to the boxplot() method that prevent whiskers from being drawn inside the
box for oddly distributed data sets.
Calling subplot() without arguments
A call to 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 axes() and subplots(),
and now this consistency is shared with subplot().
Drawing
Independent alpha values for face and edge colors
Wes Campaigne modified how 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 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.
Fig. 5.28: Patheffect Demo
414
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Easier creation of colormap and normalizer for levels with colors
Phil Elson added the matplotlib.colors.from_levels_and_colors() function to easily create a colormap and normalizer for representation of discrete colors for plot types such as matplotlib.pyplot.
pcolormesh(), with a similar interface to that of 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 fig.patch.get_alpha() is not 1.
Improved bbox_inches="tight" functionality
Passing bbox_inches="tight" through to 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 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.
5.2. Previous Whats New
415
Matplotlib, Release 2.1.2
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 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 matplotlib.
RcParams.find_all(). 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.
416
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
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.
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
5.2. Previous Whats New
417
Matplotlib, Release 2.1.2
Numpydoc docstrings
Nelle Varoquaux has started an ongoing project to convert matplotlib’s docstrings to numpydoc format. See
MEP10 for more information.
Example reorganization
Tony Yu has begun work reorganizing the examples into more meaningful categories. The new gallery page
is the fruit of this ongoing work. See MEP12 for more information.
Examples now use subplots()
For the sake of brevity and clarity, most of the examples now use the newer subplots(), which creates a
figure and one (or multiple) axes object(s) in one call. The old way involved a call to figure(), followed
by one (or multiple) 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 Changes in 1.3.x for a complete list.
New setup script
matplotlib 1.3 includes an entirely rewritten setup script. We now ship fewer dependencies with the tarballs
and installers themselves. Notably, pytz, dateutil, pyparsing and six are no longer included with
matplotlib. You can either install them manually first, or let pip install them as dependencies along with
matplotlib. It is now possible to not include certain subcomponents, such as the unit test data, in the install.
See setup.cfg.template for more information.
XDG base directory support
On Linux, matplotlib now uses the XDG base directory specification to find the matplotlibrc
configuration file. matplotlibrc should now be kept in config/matplotlib, rather than matplotlib.
If your configuration is found in the old location, it will still be used, but a warning will be displayed.
Catch opening too many figures using pyplot
Figures created through pyplot.figure are retained until they are explicitly closed. It is therefore common
for new users of matplotlib to run out of memory when creating a large series of figures in a loop without
418
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
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.
5.2.9 New in matplotlib 1.4
Thomas A. Caswell served as the release manager for the 1.4 release.
Table of Contents
• New in matplotlib 1.4
– New colormap
– The nbagg backend
– New plotting features
– Date handling
– Configuration (rcParams)
– style package added
– Backends
– Text
– Sphinx extensions
– Legend and PathEffects documentation
– Widgets
– GAE integration
Note: matplotlib 1.4 supports Python 2.6, 2.7, 3.3, and 3.4
New colormap
In heatmaps, a green-to-red spectrum is often used to indicate intensity of activity, but this can be problematic for the red/green colorblind. A new, colorblind-friendly colormap is now available at matplotlib.cm.
Wistia. This colormap maintains the red/green symbolism while achieving deuteranopic legibility through
brightness variations. See here for more information.
5.2. Previous Whats New
419
Matplotlib, Release 2.1.2
The nbagg backend
Phil Elson added a new backend, named “nbagg”, which enables interactive figures in a live IPython notebook session. The backend makes use of the infrastructure developed for the webagg backend, which itself
gives standalone server backed interactive figures in the browser, however nbagg does not require a dedicated
matplotlib server as all communications are handled through the IPython Comm machinery.
As with other backends nbagg can be enabled inside the IPython notebook with:
import matplotlib
matplotlib.use('nbagg')
Once figures are created and then subsequently shown, they will placed in an interactive widget inside the
notebook allowing panning and zooming in the same way as any other matplotlib backend. Because figures
require a connection to the IPython notebook server for their interactivity, once the notebook is saved, each
figure will be rendered as a static image - thus allowing non-interactive viewing of figures on services such
as nbviewer.
New plotting features
Power-law normalization
Ben Gamari added a power-law normalization method, 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 boxplot() method such that it is now completely customizable in terms of
the styles and positions of the individual artists. Under the hood, boxplot() relies on a new function
(boxplot_stats()), which accepts any data structure currently compatible with boxplot(), and returns a
list of dictionaries containing the positions for each element of the boxplots. Then a second method, bxp()
is called to draw the boxplots based on the stats.
The 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 boxplot_stats()
prior to plotting with 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: sphx_glr_gallery_statistics_boxplot.py and
sphx_glr_gallery_statistics_bxp.py
Added a bool kwarg, manage_xticks, which if False disables the management of the ticks and limits on
the x-axis by bxp().
420
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Support for datetime axes in 2d plots
Andrew Dawson added support for datetime axes to contour(), contourf(), pcolormesh() and
pcolor().
Support for additional spectrum types
Todd Jennings added support for new types of frequency spectrum plots: magnitude_spectrum(),
phase_spectrum(), and angle_spectrum(), as well as corresponding functions in mlab.
He also added these spectrum types to 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 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 detrend_mean(), detrend_none(), and detrend(),
as well as adding 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 memoryefficient 2D arrays. This includes stride_repeat(), which repeats an array to create a 2D array, and
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
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 get_xticklabels(), get_yticklabels() and get_ticklabels().
‘which’ can be ‘major’, ‘minor’, or ‘both’ select which ticks to return, like set_ticks_position(). If
‘which’ is None then the old behaviour (controlled by the bool minor).
5.2. Previous Whats New
421
Matplotlib, Release 2.1.2
Separate horizontal/vertical axes padding support in ImageGrid
The kwarg ‘axes_pad’ to 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 Affine2D gained additional methods skew and skew_deg to create skewed transformations. Additionally, matplotlib internals were cleaned up to support using such transforms in Axes. This transform is
important for some plot types, specifically the Skew-T used in meteorology.
Fig. 5.29: Skewt
Support for specifying properties of wedge and text in pie charts.
Added the kwargs ‘wedgeprops’ and ‘textprops’ to 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 errorbar() method such that the upper and lower limits (lolims, uplims, xlolims,
xuplims) now point in the correct direction.
422
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
More consistent add-object API for Axes
Added the Axes method 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:
violin() - Renders a violin plot from a collection of statistics. violin_stats() - Produces a collection
of statistics suitable for rendering a violin plot. violinplot() - Creates a violin plot from a set of sample
data. This method makes use of violin_stats() to process the input data, and violin_stats() to do
the actual rendering. Users are also free to modify or replace the output of 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 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 ( AsteriskPolygonCollection BrokenBarHCollection CircleCollection PathCollection
PolyCollection RegularPolyCollection StarPolygonCollection).
Fixed the mouse coordinates giving the wrong theta value in Polar graph
Added code to 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
5.2. Previous Whats New
423
Matplotlib, Release 2.1.2
as one of their term project. This feature is documented in quiver(). The team members are: Ryan Steve
D’Souza, Victor B, xbtsw, Yang Wang, David, Caradec Bisesar and Vlad Vassilovski.
Fig. 5.30: Quiver3d
polar-plot r-tick locations
Added the ability to control the angular position of the r-tick labels on a polar plot via
set_rlabel_position().
Date handling
n-d array support for date conversion
Andrew Dawson added support for n-d array handling to matplotlib.dates.num2date(), matplotlib.
dates.date2num() and matplotlib.dates.datestr2num(). Support is also added to the unit conversion interfaces matplotlib.dates.DateConverter and 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
424
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
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
5.2. Previous Whats New
425
Matplotlib, Release 2.1.2
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 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 which are more actively maintained than the
pycairo bindings.
Gtk3Agg backend
The Gtk3Agg backend now works on Python 3.x, if the cairocffi bindings 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 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 Text class.
Anchored sizebar font
Added the fontproperties kwarg to AnchoredSizeBar to control the font properties.
Sphinx extensions
The :context: directive in the 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
426
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
documentation. To enable this option, use :context:
to reset the context.
reset instead of :context: any time you want
Legend and PathEffects documentation
The Legend guide and Path effects 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 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.
5.2.10 New in matplotlib 1.5
Table of Contents
• New in matplotlib 1.5
– Interactive OO usage
– Working with labeled data like pandas DataFrames
– Added axes.prop_cycle key to rcParams
– New Colormaps
– Styles
– Backends
– Configuration (rcParams)
– Widgets
– New plotting features
– ToolManager
– cbook.is_sequence_of_strings recognizes string objects
– New close-figs argument for plot directive
– Support for URL string arguments to imread
5.2. Previous Whats New
427
Matplotlib, Release 2.1.2
– Display hook for animations in the IPython notebook
– Prefixed pkg-config for building
Note: matplotlib 1.5 supports Python 2.7, 3.4, and 3.5
Interactive OO usage
All Artists now keep track of if their internal state has been changed but not reflected in the display
(‘stale’) by a call to draw. It is thus possible to pragmatically determine if a given Figure needs to be
re-drawn in an interactive session.
To facilitate interactive usage a draw_all method has been added to pyplot which will redraw all of the
figures which are ‘stale’.
To make this convenient for interactive use matplotlib now registers a function either with IPython’s
‘post_execute’ event or with the displayhook in the standard python REPL to automatically call plt.
draw_all just before control is returned to the REPL. This ensures that the draw command is deferred
and only called once.
The upshot of this is that for interactive backends (including %matplotlib notebook) in interactive mode
(with plt.ion())
In [1]: import matplotlib.pyplot as plt
In [2]: fig, ax = plt.subplots()
In [3]: ln, = ax.plot([0, 1, 4, 9, 16])
In [4]: plt.show()
In [5]: ln.set_color('g')
will automatically update the plot to be green. Any subsequent modifications to the Artist objects will do
likewise.
This is the first step of a larger consolidation and simplification of the pyplot internals.
Working with labeled data like pandas DataFrames
Plot methods which take arrays as inputs can now also work with labeled data and unpack such data.
This means that the following two examples produce the same plot:
Example
df = pandas.DataFrame({"var1":[1,2,3,4,5,6], "var2":[1,2,3,4,5,6]})
plt.plot(df["var1"], df["var2"])
428
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Example
plt.plot("var1", "var2", data=df)
This works for most plotting methods, which expect arrays/sequences as inputs. data can be anything
which supports __getitem__ (dict, pandas.DataFrame, h5py, . . . ) to access array like values with
string keys.
In addition to this, some other changes were made, which makes working with labeled data (ex pandas.
Series) easier:
• For plotting methods with label keyword argument, one of the data inputs is designated as the label
source. If the user does not supply a label that value object will be introspected for a label, currently
by looking for a name attribute. If the value object does not have a name attribute but was specified by
as a key into the data kwarg, then the key is used. In the above examples, this results in an implicit
label="var2" for both cases.
• plot() now uses the index of a Series instead of np.arange(len(y)), if no x argument is supplied.
Added axes.prop_cycle key to rcParams
This is a more generic form of the now-deprecated axes.color_cycle param. Now, we can cycle more
than just colors, but also linestyles, hatches, and just about any other artist property. Cycler notation is used
for defining property cycles. Adding cyclers together will be like you are zip()-ing together two or more
property cycles together:
axes.prop_cycle: cycler('color', 'rgb') + cycler('lw', [1, 2, 3])
You can even multiply cyclers, which is like using itertools.product() on two or more property cycles.
Remember to use parentheses if writing a multi-line prop_cycle parameter.
Fig. 5.31: Color Cycle
5.2. Previous Whats New
429
Matplotlib, Release 2.1.2
New Colormaps
All four of the colormaps proposed as the new default are available as 'viridis' (the new default in 2.0),
'magma', 'plasma', and 'inferno'
viridis
0
50
50
100
100
150
150
200
0
100
200
plasma
0
200
50
100
100
150
150
0
100
0
200
200
100
200
inferno
0
50
200
magma
0
0
100
200
Styles
Several new styles have been added, including many styles from the Seaborn project. Additionally, in order
to prep for the upcoming 2.0 style-change release, a ‘classic’ and ‘default’ style has been added. For this
release, the ‘default’ and ‘classic’ styles are identical. By using them now in your scripts, you can help
ensure a smooth transition during future upgrades of matplotlib, so that you can upgrade to the snazzy new
defaults when you are ready!
import matplotlib.style
matplotlib.style.use('classic')
The ‘default’ style will give you matplotlib’s latest plotting styles:
matplotlib.style.use('default')
Backends
430
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
New backend selection
The environment variable MPLBACKEND can now be used to set the matplotlib backend.
wx backend has been updated
The wx backend can now be used with both wxPython classic and Phoenix.
wxPython classic has to be at least version 2.8.12 and works on Python 2.x. As of May 2015 no official
release of wxPython Phoenix is available but a current snapshot will work on Python 2.7+ and 3.4+.
If you have multiple versions of wxPython installed, then the user code is responsible setting the
wxPython version. How to do this is explained in the comment at the beginning of the example
examplesuser_interfacesembedding_in_wx2.py.
Configuration (rcParams)
Some parameters have been added, others have been improved.
Parameter
Description
{x,y}axis.
mplot3d now respects these parameters
labelpad
axes.
Default space between the axis and the label
labelpad
errorbar.
Default length of end caps on error bars
capsize
{x,y}tick.
Default visibility of minor x/y ticks
minor.
visible
legend.
Default transparency of the legend frame box
framealpha
legend.
Default facecolor of legend frame box (or 'inherit' from axes.facecolor)
facecolor
legend.
Default edgecolor of legend frame box (or 'inherit' from axes.edgecolor)
edgecolor
figure.
Default font size for figure suptitles
titlesize
figure.
Default font weight for figure suptitles
titleweight
image.
Whether a vector graphics backend should composite several images into a single image
composite_image
or not when saving. Useful when needing to edit the files further in Inkscape or other
programs.
markers.
Default fillstyle of markers. Possible values are 'full' (the default), 'left',
fillstyle
'right', 'bottom', 'top' and 'none'
toolbar
Added 'toolmanager' as a valid value, enabling the experimental ToolManager feature.
5.2. Previous Whats New
431
Matplotlib, Release 2.1.2
Widgets
Active state of Selectors
All selectors now implement set_active and get_active methods (also called when accessing the
active property) to properly update and query whether they are active.
Moved ignore, set_active, and get_active methods to base class Widget
Pushes up duplicate methods in child class to parent class to avoid duplication of code.
Adds enable/disable feature to MultiCursor
A MultiCursor object can be disabled (and enabled) after it has been created without destroying the object.
Example:
multi_cursor.active = False
Improved RectangleSelector and new EllipseSelector Widget
Adds an interactive keyword which enables visible handles for manipulating the shape after it has been
drawn.
Adds keyboard modifiers for:
• Moving the existing shape (default key = ‘space’)
• Making the shape square (default ‘shift’)
• Make the initial point the center of the shape (default ‘control’)
• Square and center can be combined
Allow Artists to Display Pixel Data in Cursor
Adds get_pixel_data and format_pixel_data methods to artists which can be used to add zdata to the
cursor display in the status bar. Also adds an implementation for Images.
New plotting features
Auto-wrapping Text
Added the keyword argument “wrap” to Text, which automatically breaks long lines of text when being
drawn. Works for any rotated text, different modes of alignment, and for text that are either labels or titles.
This breaks at the Figure, not Axes edge.
432
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
1.0
This is a really long string that should
be wrapped so that it does not go
outside the figure.
0.8
0.6
0.4
0.2
0.0
0.0
0.2
0.4
0.6
0.8
1.0
Contour plot corner masking
Ian Thomas rewrote the C++ code that calculates contours to add support for corner masking. This is controlled by a new keyword argument corner_mask in the functions contour() and contourf(). The previous behaviour, which is now obtained using corner_mask=False, was for a single masked point to completely mask out all four quads touching that point. The new behaviour, obtained using corner_mask=True,
only masks the corners of those quads touching the point; any triangular corners comprising three unmasked
points are contoured as usual. If the corner_mask keyword argument is not specified, the default value is
taken from rcParams.
Mostly unified linestyles for Line2D, Patch and Collection
The handling of linestyles for Lines, Patches and Collections has been unified. Now they all support defining
linestyles with short symbols, like "--", as well as with full names, like "dashed". Also the definition using
a dash pattern ((0., [3., 3.])) is supported for all methods using Line2D, Patch or Collection.
Legend marker order
Added ability to place the label before the marker in a legend box with markerfirst keyword
5.2. Previous Whats New
433
Matplotlib, Release 2.1.2
Fig. 5.32: Contour Corner Mask
Support for legend for PolyCollection and stackplot
Added a legend_handler for PolyCollection as well as a labels argument to stackplot().
Support for alternate pivots in mplot3d quiver plot
Added a pivot kwarg to quiver() that controls the pivot point around which the quiver line rotates. This
also determines the placement of the arrow head along the quiver line.
Logit Scale
Added support for the ‘logit’ axis scale, a nonlinear transformation
x− > log 10(x/(1 − x))
(5.1)
for data between 0 and 1 excluded.
Add step kwargs to fill_between
Added step kwarg to Axes.fill_between to allow to fill between lines drawn using the ‘step’ draw style.
The values of step match those of the where kwarg of Axes.step. The asymmetry of of the kwargs names
is not ideal, but Axes.fill_between already has a where kwarg.
This is particularly useful for plotting pre-binned histograms.
Square Plot
Implemented square plots feature as a new parameter in the axis function. When argument ‘square’ is
specified, equal scaling is set, and the limits are set such that xmax-xmin == ymax-ymin.
434
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Fig. 5.33: Filled Step
0.04
0.02
0.00
0.02
0.04
0.04
5.2. Previous Whats New
0.02
0.00
0.02
0.04
435
Matplotlib, Release 2.1.2
Updated figimage to take optional resize parameter
Added the ability to plot simple 2D-Array using plt.figimage(X, resize=True). This is useful for
plotting simple 2D-Array without the Axes or whitespacing around the image.
Updated Figure.savefig() can now use figure’s dpi
Added support to save the figure with the same dpi as the figure on the screen using dpi='figure'.
Example:
f = plt.figure(dpi=25)
# dpi set to 25
S = plt.scatter([1,2,3],[4,5,6])
f.savefig('output.png', dpi='figure')
# output savefig dpi set to 25 (same as figure)
Updated Table to control edge visibility
Added the ability to toggle the visibility of lines in Tables. Functionality added to the pyplot.table()
factory function under the keyword argument “edges”. Values can be the strings “open”, “closed”, “horizon436
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
tal”, “vertical” or combinations of the letters “L”, “R”, “T”, “B” which represent left, right, top, and bottom
respectively.
Example:
table(...,
table(...,
table(...,
table(...,
edges="open") # No line visible
edges="closed") # All lines visible
edges="horizontal") # Only top and bottom lines visible
edges="LT") # Only left and top lines visible.
Zero r/cstride support in plot_wireframe
Adam Hughes added support to mplot3d’s plot_wireframe to draw only row or column line plots.
80
60
40
20
0
20
40
60
30 20
10 0
10 20
30
0
10
20
30
30
20
10
Plot bar and barh with labels
Added kwarg "tick_label" to bar and barh to support plotting bar graphs with a text label for each bar.
Added center and frame kwargs to pie
These control where the center of the pie graph are and if the Axes frame is shown.
5.2. Previous Whats New
437
Matplotlib, Release 2.1.2
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0.0
bar1
bar2
Fixed 3D filled contour plot polygon rendering
Certain cases of 3D filled contour plots that produce polygons with multiple holes produced improper rendering due to a loss of path information between PolyCollection and Poly3DCollection. A function
set_verts_and_codes() was added to allow path information to be retained for proper rendering.
Dense colorbars are rasterized
Vector file formats (pdf, ps, svg) are efficient for many types of plot element, but for some they can yield
excessive file size and even rendering artifacts, depending on the renderer used for screen display. This is a
problem for colorbars that show a large number of shades, as is most commonly the case. Now, if a colorbar
is showing 50 or more colors, it will be rasterized in vector backends.
DateFormatter strftime
strftime method will format a datetime.datetime object with the format string passed to the formatter’s constructor. This method accepts datetimes with years before 1900, unlike datetime.datetime.
strftime().
438
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Artist-level {get,set}_usetex for text
Add {get,set}_usetex methods to Text objects which allow artist-level control of LaTeX rendering vs
the internal mathtex rendering.
ax.remove() works as expected
As with artists added to an Axes, Axes objects can be removed from their figure via remove().
API Consistency fix within Locators set_params() function
set_params() function, which sets parameters within a Locator type instance, is now available to all
Locator types. The implementation also prevents unsafe usage by strictly defining the parameters that a
user can set.
To use, call set_params() on a Locator instance with desired arguments:
loc = matplotlib.ticker.LogLocator()
# Set given attributes for loc.
loc.set_params(numticks=8, numdecs=8, subs=[2.0], base=8)
# The below will error, as there is no such parameter for LogLocator
# named foo
# loc.set_params(foo='bar')
Date Locators
Date Locators (derived from DateLocator) now implement the tick_values() method. This is expected
of all Locators derived from Locator.
The Date Locators can now be used easily without creating axes
from datetime import datetime
from matplotlib.dates import YearLocator
t0 = datetime(2002, 10, 9, 12, 10)
tf = datetime(2005, 10, 9, 12, 15)
loc = YearLocator()
values = loc.tick_values(t0, tf)
OffsetBoxes now support clipping
Artists draw onto objects of type OffsetBox through DrawingArea and TextArea. The TextArea
calculates the required space for the text and so the text is always within the bounds, for this nothing has
changed.
However, DrawingArea acts as a parent for zero or more Artists that draw on it and may do so beyond
the bounds. Now child Artists can be clipped to the bounds of the DrawingArea.
5.2. Previous Whats New
439
Matplotlib, Release 2.1.2
OffsetBoxes now considered by tight_layout
When tight_layout() or Figure.tight_layout() or GridSpec.tight_layout() is called,
OffsetBoxes that are anchored outside the axes will not get chopped out. The OffsetBoxes will also
not get overlapped by other axes in case of multiple subplots.
Per-page pdf notes in multi-page pdfs (PdfPages)
Add a new method attach_note() to the PdfPages class, allowing the attachment of simple text notes to
pages in a multi-page pdf of figures. The new note is visible in the list of pdf annotations in a viewer that has
this facility (Adobe Reader, OSX Preview, Skim, etc.). Per default the note itself is kept off-page to prevent
it to appear in print-outs.
PdfPages.attach_note needs to be called before savefig() in order to be added to the correct figure.
Updated fignum_exists to take figure name
Added the ability to check the existence of a figure using its name instead of just the figure number. Example:
figure('figure')
fignum_exists('figure') #true
ToolManager
Federico Ariza wrote the new ToolManager that comes as replacement for NavigationToolbar2
ToolManager offers a new way of looking at the user interactions with the figures. Before we had
the NavigationToolbar2 with its own tools like zoom/pan/home/save/... and also we had the
shortcuts like yscale/grid/quit/.... Toolmanager relocate all those actions as Tools (located in
backend_tools), and defines a way to access/trigger/reconfigure them.
The Toolbars are replaced for ToolContainers that are just GUI interfaces to trigger the tools. But
don’t worry the default backends include a ToolContainer called toolbar
Note: At the moment, we release this primarily for feedback purposes and should be treated as experimental
until further notice as API changes will occur. For the moment the ToolManager works only with the GTK3
and Tk backends. Make sure you use one of those. Port for the rest of the backends is comming soon.
To activate the ToolManager include the following at the top of your file
>>> matplotlib.rcParams['toolbar'] = 'toolmanager'
440
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Interact with the ToolContainer
The most important feature is the ability to easily reconfigure the ToolContainer (aka toolbar). For example,
if we want to remove the “forward” button we would just do.
>>> fig.canvas.manager.toolmanager.remove_tool('forward')
Now if you want to programmatically trigger the “home” button
>>> fig.canvas.manager.toolmanager.trigger_tool('home')
New Tools for ToolManager
It is possible to add new tools to the ToolManager
A very simple tool that prints “You’re awesome” would be:
from matplotlib.backend_tools import ToolBase
class AwesomeTool(ToolBase):
def trigger(self, *args, **kwargs):
print("You're awesome")
To add this tool to ToolManager
>>> fig.canvas.manager.toolmanager.add_tool('Awesome', AwesomeTool)
If we want to add a shortcut (“d”) for the tool
>>> fig.canvas.manager.toolmanager.update_keymap('Awesome', 'd')
To add it to the toolbar inside the group ‘foo’
>>> fig.canvas.manager.toolbar.add_tool('Awesome', 'foo')
There is a second class of tools, “Toggleable Tools”, this are almost the same as our basic tools, just that
belong to a group, and are mutually exclusive inside that group. For tools derived from ToolToggleBase
there are two basic methods enable and disable that are called automatically whenever it is toggled.
A full example is located in sphx_glr_gallery_user_interfaces_toolmanager_sgskip.py
cbook.is_sequence_of_strings recognizes string objects
This is primarily how pandas stores a sequence of strings
import pandas as pd
import matplotlib.cbook as cbook
a = np.array(['a', 'b', 'c'])
print(cbook.is_sequence_of_strings(a))
5.2. Previous Whats New
# True
441
Matplotlib, Release 2.1.2
a = np.array(['a', 'b', 'c'], dtype=object)
print(cbook.is_sequence_of_strings(a)) # True
s = pd.Series(['a', 'b', 'c'])
print(cbook.is_sequence_of_strings(s))
# True
Previously, the last two prints returned false.
New close-figs argument for plot directive
Matplotlib has a sphinx extension plot_directive that creates plots for inclusion in sphinx documents.
Matplotlib 1.5 adds a new option to the plot directive - close-figs - that closes any previous figure
windows before creating the plots. This can help avoid some surprising duplicates of plots when using
plot_directive.
Support for URL string arguments to imread
The imread() function now accepts URL strings that point to remote PNG files. This circumvents the
generation of a HTTPResponse object directly.
Display hook for animations in the IPython notebook
Animation instances gained a _repr_html_ method to support inline display of animations in the notebook. The method used to display is controlled by the animation.html rc parameter, which currently
supports values of none and html5. none is the default, performing no display. html5 converts the animation to an h264 encoded video, which is embedded directly in the notebook.
Users not wishing to use the _repr_html_ display hook can also manually call the to_html5_video
method to get the HTML and display using IPython’s HTML display class:
from IPython.display import HTML
HTML(anim.to_html5_video())
Prefixed pkg-config for building
Handling of pkg-config has been fixed in so far as it is now possible to set it using the environment variable
PKG_CONFIG. This is important if your toolchain is prefixed. This is done in a simpilar way as setting CC or
CXX before building. An example follows.
export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config
5.2.11 New in matplotlib 2.0
442
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Note: matplotlib 2.0 supports Python 2.7, and 3.4+
Default style changes
The major changes in v2.0 are related to overhauling the default styles.
Changes to the default style
The most important changes in matplotlib 2.0 are the changes to the default style.
While it is impossible to select the best default for all cases, these are designed to work well in the most
common cases.
A ‘classic’ style sheet is provided so reverting to the 1.x default values is a single line of python
import matplotlib.style
import matplotlib as mpl
mpl.style.use('classic')
See The matplotlibrc file for details about how to persistently and selectively revert many of these changes.
Table of Contents
• Colors, color cycles, and color maps
– Colors in default property cycle
– Colormap
– Interactive figures
– Grid lines
• Figure size, font size, and screen dpi
• Plotting functions
– scatter
– plot
– errorbar
– boxplot
– fill_between and fill_betweenx
– Patch edges and color
– hexbin
– bar and barh
5.2. Previous Whats New
443
Matplotlib, Release 2.1.2
• Hatching
• Fonts
– Normal text
– Math text
• Legends
• Image
– Interpolation
– Colormapping pipeline
– Shading
• Plot layout
– Auto limits
– Z-order
– Ticks
– Tick label formatting
• mplot3d
Colors, color cycles, and color maps
Colors in default property cycle
The colors in the default property cycle have been changed from ['b', 'g', 'r', 'c', 'm', 'y',
'k'] to the category10 color palette used by Vega and d3 originally developed at Tableau.
In addition to changing the colors, an additional method to specify colors was added. Previously, the default
colors were the single character short-hand notations for red, green, blue, cyan, magenta, yellow, and black.
This made them easy to type and usable in the abbreviated style string in plot, however the new default
colors are only specified via hex values. To access these colors outside of the property cycling the notation
for colors 'CN', where N takes values 0-9, was added to denote the first 10 colors in mpl.rcParams['axes.
prop_cycle'] See Specifying Colors for more details.
To restore the old color cycle use
from cycler import cycler
mpl.rcParams['axes.prop_cycle'] = cycler(color='bgrcmyk')
or set
axes.prop_cycle
: cycler('color', 'bgrcmyk')
in your matplotlibrc file.
444
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
classic
v2.0
'C0'
'b' 'C0'
'#1f77b4'
'C1'
'g'
'C1'
'#ff7f0e'
'C2'
'#2ca02c'
'C2'
'r' 'C3'
'#d62728'
'C3'
'c'
'C4'
'#9467bd'
'C5'
'#8c564b'
'C4'
'm' 'C6'
'#e377c2'
'C5'
'y'
'C7'
'#7f7f7f'
'C8'
'#bcbd22'
'C6'
'k' 'C9'
'#17becf'
Colormap
The new default color map used by matplotlib.cm.ScalarMappable instances is 'viridis' (aka
option D).
classic: 'jet'
200
150
100
50
0
0
50
100
150
v2.0: 'viridis'
200
200
0.75
0.50 150
0.25
0.00 100
0.25
0.50 50
0.75
0
0.75
0.50
0.25
0.00
0.25
0.50
0.75
0
50
100
150
200
For an introduction to color theory and how ‘viridis’ was generated watch Nathaniel Smith and Stéfan van
der Walt’s talk from SciPy2015. See here for many more details about the other alternatives and the tools
used to create the color map. For details on all of the color maps available in matplotlib see Colormaps in
Matplotlib.
The previous default can be restored using
mpl.rcParams['image.cmap'] = 'jet'
or setting
5.2. Previous Whats New
445
Matplotlib, Release 2.1.2
image.cmap
: 'jet'
in your matplotlibrc file; however this is strongly discouraged.
Interactive figures
The default interactive figure background color has changed from grey to white, which matches the default
background color used when saving.
The previous defaults can be restored by
mpl.rcParams['figure.facecolor'] = '0.75'
or by setting
figure.facecolor : '0.75'
in your matplotlibrc file.
Grid lines
The default style of grid lines was changed from black dashed lines to thicker solid light grey lines.
1.0
classic
1.0
0.8
0.8
0.6
0.6
0.4
0.4
0.2
0.2
v2.0
0.0
0.0
0.0 0.2 0.4 0.6 0.8 1.0 0.0 0.2 0.4 0.6 0.8 1.0
The previous default can be restored by using:
mpl.rcParams['grid.color'] = 'k'
mpl.rcParams['grid.linestyle'] = ':'
mpl.rcParams['grid.linewidth'] = 0.5
or by setting:
446
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
grid.color
grid.linestyle
grid.linewidth
:
:
:
k
:
0.5
# grid color
# dotted
# in points
in your matplotlibrc file.
Figure size, font size, and screen dpi
The default dpi used for on-screen display was changed from 80 dpi to 100 dpi, the same as the default dpi
for saving files. Due to this change, the on-screen display is now more what-you-see-is-what-you-get for
saved files. To keep the figure the same size in terms of pixels, in order to maintain approximately the same
size on the screen, the default figure size was reduced from 8x6 inches to 6.4x4.8 inches. As a consequence
of this the default font sizes used for the title, tick labels, and axes labels were reduced to maintain their size
relative to the overall size of the figure. By default the dpi of the saved image is now the dpi of the Figure
instance being saved.
This will have consequences if you are trying to match text in a figure directly with external text.
The previous defaults can be restored by
mpl.rcParams['figure.figsize'] = [8.0, 6.0]
mpl.rcParams['figure.dpi'] = 80
mpl.rcParams['savefig.dpi'] = 100
mpl.rcParams['font.size'] = 12
mpl.rcParams['legend.fontsize'] = 'large'
mpl.rcParams['figure.titlesize'] = 'medium'
or by setting:
figure.figsize
figure.dpi
savefig.dpi
: [8.0, 6.0]
: 80
: 100
font.size
: 12.0
legend.fontsize : 'large'
figure.titlesize : 'medium'
In your matplotlibrc file.
In addition, the forward kwarg to set_size_inches now defaults to True to improve the interactive
experience. Backend canvases that adjust the size of their bound matplotlib.figure.Figure must pass
forward=False to avoid circular behavior. This default is not configurable.
Plotting functions
scatter
The following changes were made to the default behavior of scatter
5.2. Previous Whats New
447
Matplotlib, Release 2.1.2
• The default size of the elements in a scatter plot is now based on the rcParam lines.markersize so
it is consistent with plot(X, Y, 'o'). The old value was 20, and the new value is 36 (6^2).
• scatter markers no longer have a black edge.
• if the color of the markers is not specified it will follow the property cycle, pulling from the ‘patches’
cycle on the Axes.
classic
v2.0
a
b
0.8
0.6
0.6
0.4
0.4
0.2
0.2
0.0
0.0
0
5
10
a
b
0.8
0
5
10
The classic default behavior of scatter can only be recovered through mpl.style.use('classic').
The marker size can be recovered via
mpl.rcParam['lines.markersize'] = np.sqrt(20)
however, this will also affect the default marker size of plot. To recover the classic behavior on a per-call
basis pass the following kwargs:
classic_kwargs = {'s': 20, 'edgecolors': 'k', 'c': 'b'}
plot
The following changes were made to the default behavior of plot
• the default linewidth increased from 1 to 1.5
• the dash patterns associated with '--', ':', and '-.' have changed
• the dash patterns now scale with line width
The previous defaults can be restored by setting:
mpl.rcParams['lines.linewidth'] = 1.0
mpl.rcParams['lines.dashed_pattern'] = [6, 6]
mpl.rcParams['lines.dashdot_pattern'] = [3, 5, 1, 5]
448
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
classic
v2.0
mpl.rcParams['lines.dotted_pattern'] = [1, 3]
mpl.rcParams['lines.scale_dashes'] = False
or by setting:
lines.linewidth
: 1.0
lines.dashed_pattern : 6, 6
lines.dashdot_pattern : 3, 5, 1, 5
lines.dotted_pattern : 1, 3
lines.scale_dashes: False
in your matplotlibrc file.
errorbar
By default, caps on the ends of errorbars are not present.
This also changes the return value of errorbar() as the list of ‘caplines’ will be empty by default.
The previous defaults can be restored by setting:
mpl.rcParams['errorbar.capsize'] = 3
or by setting
errorbar.capsize : 3
in your matplotlibrc file.
5.2. Previous Whats New
449
Matplotlib, Release 2.1.2
classic
v2.0
1.25
1.00
0.75
0.50
0.25
0.00
0.25
1.25
1.00
0.75
0.50
0.25
0.00
0.25
0
1
2
3
4
0
1
2
3
4
boxplot
Previously, boxplots were composed of a mish-mash of styles that were, for better for worse, inherited from
Matlab. Most of the elements were blue, but the medians were red. The fliers (outliers) were black plussymbols (+) and the whiskers were dashed lines, which created ambiguity if the (solid and black) caps were
not drawn.
For the new defaults, everything is black except for the median and mean lines (if drawn), which are set
to the first two elements of the current color cycle. Also, the default flier markers are now hollow circles,
which maintain the ability of the plus-symbols to overlap without obscuring data too much.
The previous defaults can be restored by setting:
mpl.rcParams['boxplot.flierprops.color'] = 'k'
mpl.rcParams['boxplot.flierprops.marker'] = '+'
mpl.rcParams['boxplot.flierprops.markerfacecolor'] = 'none'
mpl.rcParams['boxplot.flierprops.markeredgecolor'] = 'k'
mpl.rcParams['boxplot.boxprops.color'] = 'b'
mpl.rcParams['boxplot.whiskerprops.color'] = 'b'
mpl.rcParams['boxplot.whiskerprops.linestyle'] = '--'
mpl.rcParams['boxplot.medianprops.color'] = 'r'
mpl.rcParams['boxplot.meanprops.color'] = 'r'
mpl.rcParams['boxplot.meanprops.marker'] = '^'
mpl.rcParams['boxplot.meanprops.markerfacecolor'] = 'r'
mpl.rcParams['boxplot.meanprops.markeredgecolor'] = 'k'
mpl.rcParams['boxplot.meanprops.markersize'] = 6
mpl.rcParams['boxplot.meanprops.linestyle'] = '--'
mpl.rcParams['boxplot.meanprops.linewidth'] = 1.0
or by setting:
boxplot.flierprops.color:
boxplot.flierprops.marker:
450
'k'
'+'
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
classic
v2.0
101
100
10
1
A
B
C
boxplot.flierprops.markerfacecolor:
boxplot.flierprops.markeredgecolor:
boxplot.boxprops.color:
boxplot.whiskerprops.color:
boxplot.whiskerprops.linestyle:
boxplot.medianprops.color:
boxplot.meanprops.color:
boxplot.meanprops.marker:
boxplot.meanprops.markerfacecolor:
boxplot.meanprops.markeredgecolor:
boxplot.meanprops.markersize:
boxplot.meanprops.linestyle:
boxplot.meanprops.linewidth:
D
A
B
C
D
'none'
'k'
'b'
'b'
'--'
'r'
'r'
'^'
'r'
'k'
6
'--'
1.0
in your matplotlibrc file.
fill_between and fill_betweenx
fill_between and fill_betweenx both follow the patch color cycle.
If the facecolor is set via the facecolors or color keyword argument, then the color is not cycled.
To restore the previous behavior, explicitly pass the keyword argument facecolors='C0' to the method
5.2. Previous Whats New
451
Matplotlib, Release 2.1.2
classic
1.0
1.0
0.5
0.5
0.0
0.0
0.5
0.5
1.0
1.0
0
2
4
v2.0
6
0
2
4
6
call.
Patch edges and color
Most artists drawn with a patch (~matplotlib.axes.Axes.bar, ~matplotlib.axes.Axes.pie, etc) no
longer have a black edge by default. The default face color is now 'C0' instead of 'b'.
The previous defaults can be restored by setting:
mpl.rcParams['patch.force_edgecolor'] = True
mpl.rcParams['patch.facecolor'] = 'b'
or by setting:
patch.facecolor
patch.force_edgecolor
: b
: True
in your matplotlibrc file.
hexbin
The default value of the linecolor kwarg for hexbin has changed from 'none' to 'face'. If ‘none’ is
now supplied, no line edges are drawn around the hexagons.
bar and barh
The default value of the align kwarg for both bar and barh is changed from 'edge' to 'center'.
To restore the previous behavior explicitly pass the keyword argument align='edge' to the method call.
452
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
classic
v2.0
Hogs
Hogs
Frogs
Frogs
Logs
Logs
Dogs
Dogs
40
40
20
20
0
0
gs
Lo
gs
Do
gs
Ho s
g
Fro
gs
Lo
gs
Do
gs
Ho s
g
Fro
5.2. Previous Whats New
453
Matplotlib, Release 2.1.2
classic
3
3
2
2
1
1
0
a
b
0
c
b
c
b
b
454
a
c
c
a
v2.0
a
0
1
2
3
0
1
2
3
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Hatching
The color of the lines in the hatch is now determined by
• If an edge color is explicitly set, use that for the hatch color
• If the edge color is not explicitly set, use rcParam['hatch.color'] which is looked up at artist
creation time.
The width of the lines in a hatch pattern is now configurable by the rcParams hatch.linewidth, which
defaults to 1 point. The old behavior for the line width was different depending on backend:
• PDF: 0.1 pt
• SVG: 1.0 pt
• PS: 1 px
• Agg: 1 px
The old line width behavior can not be restored across all backends simultaneously, but can be restored for
a single backend by setting:
mpl.rcParams['hatch.linewidth'] = 0.1
mpl.rcParams['hatch.linewidth'] = 1.0
# previous pdf hatch linewidth
# previous svg hatch linewidth
The behavior of the PS and Agg backends was DPI dependent, thus:
mpl.rcParams['figure.dpi'] = dpi
mpl.rcParams['savefig.dpi'] = dpi # or leave as default 'figure'
mpl.rcParams['hatch.linewidth'] = 1.0 / dpi # previous ps and Agg hatch linewidth
There is no direct API level control of the hatch color or linewidth.
Hatching patterns are now rendered at a consistent density, regardless of DPI. Formerly, high DPI figures
would be more dense than the default, and low DPI figures would be less dense. This old behavior cannot
be directly restored, but the density may be increased by repeating the hatch specifier.
Fonts
Normal text
The default font has changed from “Bitstream Vera Sans” to “DejaVu Sans”. DejaVu Sans has additional
international and math characters, but otherwise has the same appearance as Bitstream Vera Sans. Latin,
Greek, Cyrillic, Armenian, Georgian, Hebrew, and Arabic are all supported (but right-to-left rendering is
still not handled by matplotlib). In addition, DejaVu contains a sub-set of emoji symbols.
See the DejaVu Sans PDF sample for full coverage.
5.2. Previous Whats New
455
Matplotlib, Release 2.1.2
25
20
15
10
5
0
Math text
The default math font when using the built-in math rendering engine (mathtext) has changed from “Computer Modern” (i.e. LaTeX-like) to “DejaVu Sans”. This change has no effect if the TeX backend is used
(i.e. text.usetex is True).
To revert to the old behavior set the:
mpl.rcParams['mathtext.fontset'] = 'cm'
mpl.rcParams['mathtext.rm'] = 'serif'
or set:
mathtext.fontset: cm
mathtext.rm : serif
in your matplotlibrc file.
This rcParam is consulted when the text is drawn, not when the artist is created. Thus all mathtext on a
given canvas will use the same fontset.
456
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
14
12
10
8
6
4
2
0
14
12
10
8
6
4
2
0
5.2. Previous Whats New
classic
Z ∞
int: 15
0
0
dx
5
10
v2.0
int: 15 0 dx
0
5
10
457
Matplotlib, Release 2.1.2
Legends
• By default, the number of points displayed in a legend is now 1.
• The default legend location is 'best', so the legend will be automatically placed in a location to
minimize overlap with data.
• The legend defaults now include rounded corners, a lighter boundary, and partially transparent boundary and background.
classic
v2.0
plot
fill
scatter
0
2
0
4
4
6
6
0
10
20
plot
fill
scatter
2
0
10
20
The previous defaults can be restored by setting:
mpl.rcParams['legend.fancybox'] = False
mpl.rcParams['legend.loc'] = 'upper right'
mpl.rcParams['legend.numpoints'] = 2
mpl.rcParams['legend.fontsize'] = 'large'
mpl.rcParams['legend.framealpha'] = None
mpl.rcParams['legend.scatterpoints'] = 3
mpl.rcParams['legend.edgecolor'] = 'inherit'
or by setting:
legend.fancybox
legend.loc
legend.numpoints
legend.fontsize
legend.framealpha
legend.scatterpoints
legend.edgecolor
:
:
:
:
:
:
:
False
upper right
2
# the number of points in the legend line
large
None
# opacity of legend frame
3 # number of scatter points
inherit
# legend edge color ('inherit'
# means it uses axes.edgecolor)
in your matplotlibrc file.
458
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Image
Interpolation
The default interpolation method for imshow is now 'nearest' and by default it resamples the data (both
up and down sampling) before color mapping.
classic
v2.0
0
0
1
1
2
2
3
3
4
4
0
1
2
3
4
0
1
2
3
4
To restore the previous behavior set:
mpl.rcParams['image.interpolation'] = 'bilinear'
mpl.rcParams['image.resample'] = False
or set:
image.interpolation : bilinear
image.resample : False
# see help(imshow) for options
in your matplotlibrc file.
Colormapping pipeline
Previously, the input data was normalized, then color mapped, and then resampled to the resolution required
for the screen. This meant that the final resampling was being done in color space. Because the color maps
are not generally linear in RGB space, colors not in the color map may appear in the final image. This bug
was addressed by an almost complete overhaul of the image handling code.
The input data is now normalized, then resampled to the correct resolution (in normalized dataspace), and
then color mapped to RGB space. This ensures that only colors from the color map appear in the final image.
(If your viewer subsequently resamples the image, the artifact may reappear.)
The previous behavior cannot be restored.
5.2. Previous Whats New
459
Matplotlib, Release 2.1.2
Shading
• The default shading mode for light source shading, in matplotlib.colors.LightSource.shade,
is now overlay. Formerly, it was hsv.
Plot layout
Auto limits
The previous auto-scaling behavior was to find ‘nice’ round numbers as view limits that enclosed the data
limits, but this could produce bad plots if the data happened to fall on a vertical or horizontal line near the
chosen ‘round number’ limit. The new default sets the view limits to 5% wider than the data range.
classic
1.0
1.0
0.8
0.8
0.6
0.6
0.4
0.4
0.2
0.2
0.0
0
0.0
200 400 600 800 1000 0
v2.0
250 500 750 1000
The size of the padding in the x and y directions is controlled by the 'axes.xmargin' and 'axes.
ymargin' rcParams respectively. Whether the view limits should be ‘round numbers’ is controlled by
the 'axes.autolimit_mode' rcParam. In the original 'round_number' mode, the view limits coincide
with ticks.
The previous default can be restored by using:
mpl.rcParams['axes.autolimit_mode'] = 'round_numbers'
mpl.rcParams['axes.xmargin'] = 0
mpl.rcParams['axes.ymargin'] = 0
or setting:
axes.autolimit_mode: round_numbers
axes.xmargin: 0
axes.ymargin: 0
in your matplotlibrc file.
460
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Z-order
• Ticks and grids are now plotted above solid elements such as filled contours, but below lines. To return
to the previous behavior of plotting ticks and grids above lines, set rcParams['axes.axisbelow']
= False.
Ticks
Direction
To reduce the collision of tick marks with data, the default ticks now point outward by default. In addition,
ticks are now drawn only on the bottom and left spines to prevent a porcupine appearance, and for a cleaner
separation between subplots.
classic
v2.0
3.0
3.0
2.5
2.5
2.0
2.0
1.5
1.5
1.0
1.0
0.5
0.5
0.00.0
0.2
0.4
0.6
1.0 0.00.0
0.8
0
0
1
1
2
2
3
3
4
4
0
1
5.2. Previous Whats New
2
3
4
0.2
0
0.4
1
0.6
2
0.8
3
1.0
4
461
Matplotlib, Release 2.1.2
To restore the previous behavior set:
mpl.rcParams['xtick.direction'] = 'in'
mpl.rcParams['ytick.direction'] = 'in'
mpl.rcParams['xtick.top'] = True
mpl.rcParams['ytick.right'] = True
or set:
xtick.top: True
xtick.direction: in
ytick.right: True
ytick.direction: in
in your matplotlibrc file.
Number of ticks
The default Locator used for the x and y axis is AutoLocator which tries to find, up to some maximum
number, ‘nicely’ spaced ticks. The locator now includes an algorithm to estimate the maximum number of
ticks that will leave room for the tick labels. By default it also ensures that there are at least two ticks visible.
1.0
classic
1.0
0.8
0.8
0.6
0.6
0.4
0.4
0.2
0.2
0.0
0.0
0.000.020.040.060.080.10 0.00
v2.0
0.05
0.10
There is no way, other than using mpl.style.use('classic'), to restore the previous behavior as the
default. On an axis-by-axis basis you may either control the existing locator via:
ax.xaxis.get_major_locator().set_params(nbins=9, steps=[1, 2, 5, 10])
or create a new MaxNLocator:
import matplotlib.ticker as mticker
ax.set_major_locator(mticker.MaxNLocator(nbins=9, steps=[1, 2, 5, 10])
462
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
The algorithm used by MaxNLocator has been improved, and this may change the choice of tick locations
in some cases. This also affects AutoLocator, which uses MaxNLocator internally.
For a log-scaled axis the default locator is the LogLocator. Previously the maximum number of ticks was
set to 15, and could not be changed. Now there is a numticks kwarg for setting the maximum to any integer
value, to the string ‘auto’, or to its default value of None which is equivalent to ‘auto’. With the ‘auto’
setting the maximum number will be no larger than 9, and will be reduced depending on the length of the
axis in units of the tick font size. As in the case of the AutoLocator, the heuristic algorithm reduces the
incidence of overlapping tick labels but does not prevent it.
Tick label formatting
LogFormatter labeling of minor ticks
Minor ticks on a log axis are now labeled when the axis view limits span a range less than or equal to the
interval between two major ticks. See LogFormatter for details. The minor tick labeling is turned off when
using mpl.style.use('classic'), but cannot be controlled independently via rcParams.
classic
v2.0
4 × 101
3 × 101
2 × 101
101
101
1.0
1.2
1.4
1.6
1.0
1.2
1.4
1.6
ScalarFormatter tick label formatting with offsets
With the default of rcParams['axes.formatter.useoffset'] = True, an offset will be used when
it will save 4 or more digits. This can be controlled with the new rcParam, axes.formatter.
offset_threshold. To restore the previous behavior of using an offset to save 2 or more digits, use
rcParams['axes.formatter.offset_threshold'] = 2.
5.2. Previous Whats New
463
Matplotlib, Release 2.1.2
classic
+5e4
2
2
1
1
0
0
1
0
2
4
v2.0
+5e4
6
8
+2e3
1
2000 2002 2004 2006 2008
AutoDateFormatter format strings
The default date formats are now all based on ISO format, i.e., with the slowest-moving value first. The date
formatters are configurable through the date.autoformatter.* rcParams.
Threshold (tick interval >=
than)
rcParam
classic
v2.0
365 days
30 days
1 day
1 hour
1 minute
'date.autoformatter.year'
'date.autoformatter.month'
'date.autoformatter.day'
'date.autoformatter.hour'
'date.autoformatter.minute'
'%Y'
'%Y-%m'
'%Y-%m-%d'
'%H:%M'
'%H:%M:%S'
1 second
'date.autoformatter.second'
1 microsecond
'date.autoformatter.
microsecond'
'%Y'
'%b %Y'
'%b %d %Y'
'%H:%M:%S'
'%H:%M:%S.
%f'
'%H:%M:%S.
%f'
'%H:%M:%S.
%f'
'%H:%M:%S'
'%H:%M:%S.
%f'
Python’s %x and %X date formats may be of particular interest to format dates based on the current locale.
The previous default can be restored by:
mpl.rcParams['date.autoformatter.year'] = '%Y'
mpl.rcParams['date.autoformatter.month'] = '%b %Y'
mpl.rcParams['date.autoformatter.day'] = '%b %d %Y'
mpl.rcParams['date.autoformatter.hour'] = '%H:%M:%S'
mpl.rcParams['date.autoformatter.minute'] = '%H:%M:%S.%f '
mpl.rcParams['date.autoformatter.second'] = '%H:%M:%S.%f '
mpl.rcParams['date.autoformatter.microsecond'] = '%H:%M:%S.%f '
or setting
464
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
date.autoformatter.year
: %Y
date.autoformatter.month : %b %Y
date.autoformatter.day
: %b %d %Y
date.autoformatter.hour
: %H:%M:%S
date.autoformatter.minute : %H:%M:%S.%f
date.autoformatter.second : %H:%M:%S.%f
date.autoformatter.microsecond : %H:%M:%S.%f
in your matplotlibrc file.
mplot3d
• mplot3d now obeys some style-related rcParams, rather than using hard-coded defaults. These include:
– xtick.major.width
– ytick.major.width
– xtick.color
– ytick.color
– axes.linewidth
– axes.edgecolor
– grid.color
– grid.linewidth
– grid.linestyle
Improved color conversion API and RGBA support
The colors gained a new color conversion API with full support for the alpha channel. The
main public functions are is_color_like(), matplotlib.colors.to_rgba(), matplotlib.colors.
to_rgba_array() and to_hex(). RGBA quadruplets are encoded in hex format as #rrggbbaa.
A side benefit is that the Qt options editor now allows setting the alpha channel of the artists as well.
New Configuration (rcParams)
New rcparams added
5.2. Previous Whats New
465
Matplotlib, Release 2.1.2
Parameter
Description
date.autoformatter.year
date.autoformatter.month
format string for ‘year’ scale dates
format string for ‘month’ scale
dates
format string for ‘day’ scale dates
format string for ‘hour’ scale
times
format string for ‘minute’ scale
times
format string for ‘second’ scale
times
format string for ‘microsecond’
scale times
default marker for scatter plot
see note
Control where major and minor
ticks are drawn. The global values
are and ed with the corresponding
major/minor values.
The default number of bins to use
in hist. This can be an int, a list
of floats, or 'auto' if numpy >=
1.11 is installed.
Whether the line dash patterns
should scale with linewidth.
Minimum number of digits saved
in tick labels that triggers using an
offset.
date.autoformatter.day
date.autoformatter.hour
date.autoformatter.minute
date.autoformatter.second
date.autoformatter.microsecond
scatter.marker
svg.hashsalt
xtick.top, xtick.minor.top, xtick.major.top xtick.
bottom, xtick.minor.bottom, xtick.major.bottom ytick.
left, ytick.minor.left, ytick.major.left ytick.right,
ytick.minor.right, ytick.major.right
hist.bins
lines.scale_dashes
axes.formatter.offset_threshold
Added svg.hashsalt key to rcParams
If svg.hashsalt is None (which it is by default), the svg backend uses uuid4 to generate the hash salt. If
it is not None, it must be a string that is used as the hash salt instead of uuid4. This allows for deterministic
SVG output.
Removed the svg.image_noscale rcParam
As a result of the extensive changes to image handling, the svg.image_noscale rcParam has been removed. The same functionality may be achieved by setting interpolation='none' on individual images
or globally using the image.interpolation rcParam.
466
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Qualitative colormaps
ColorBrewer’s “qualitative” colormaps (“Accent”, “Dark2”, “Paired”, “Pastel1”, “Pastel2”, “Set1”, “Set2”,
“Set3”) were intended for discrete categorical data, with no implication of value, and therefore have been
converted to ListedColormap instead of LinearSegmentedColormap, so the colors will no longer be
interpolated and they can be used for choropleths, labeled image features, etc.
Axis offset label now responds to labelcolor
Axis offset labels are now colored the same as axis tick markers when labelcolor is altered.
Improved offset text choice
The default offset-text choice was changed to only use significant digits that are common to all ticks (e.g.
1231..1239 -> 1230, instead of 1231), except when they straddle a relatively large multiple of a power of
ten, in which case that multiple is chosen (e.g. 1999..2001->2000).
Style parameter blacklist
In order to prevent unexpected consequences from using a style, style files are no longer able to set parameters that affect things unrelated to style. These parameters include:
'interactive', 'backend', 'backend.qt4', 'webagg.port',
'webagg.port_retries', 'webagg.open_in_browser', 'backend_fallback',
'toolbar', 'timezone', 'datapath', 'figure.max_open_warning',
'savefig.directory', 'tk.window_focus', 'docstring.hardcopy'
Change in default font
The default font used by matplotlib in text has been changed to DejaVu Sans and DejaVu Serif for the sansserif and serif families, respectively. The DejaVu font family is based on the previous matplotlib default
–Bitstream Vera– but includes a much wider range of characters.
The default mathtext font has been changed from Computer Modern to the DejaVu family to maintain
consistency with regular text. Two new options for the mathtext.fontset configuration parameter have
been added: dejavusans (default) and dejavuserif. Both of these options use DejaVu glyphs whenever
possible and fall back to STIX symbols when a glyph is not found in DejaVu. To return to the previous
behavior, set the rcParam mathtext.fontset to cm.
Faster text rendering
Rendering text in the Agg backend is now less fuzzy and about 20% faster to draw.
5.2. Previous Whats New
467
Matplotlib, Release 2.1.2
Improvements for the Qt figure options editor
Various usability improvements were implemented for the Qt figure options editor, among which:
• Line style entries are now sorted without duplicates.
• The colormap and normalization limits can now be set for images.
• Line edits for floating values now display only as many digits as necessary to avoid precision loss.
An important bug was also fixed regarding input validation using Qt5 and a locale where the decimal
separator is “,”.
• The axes selector now uses shorter, more user-friendly names for axes, and does not crash if there are
no axes.
• Line and image entries using the default labels (“_lineX”, “_imageX”) are now sorted numerically
even when there are more than 10 entries.
Improved image support
Prior to version 2.0, matplotlib resampled images by first applying the color map and then resizing the result.
Since the resampling was performed on the colored image, this introduced colors in the output image that
didn’t actually exist in the color map. Now, images are resampled first (and entirely in floating-point, if the
input image is floating-point), and then the color map is applied.
In order to make this important change, the image handling code was almost entirely rewritten. As a side
effect, image resampling uses less memory and fewer datatype conversions than before.
The experimental private feature where one could “skew” an image by setting the private member
_image_skew_coordinate has been removed. Instead, images will obey the transform of the axes on
which they are drawn.
Non-linear scales on image plots
imshow() now draws data at the requested points in data space after the application of non-linear scales.
The image on the left demonstrates the new, correct behavior. The old behavior can be recreated using
pcolormesh() as demonstrated on the right.
This can be understood by analogy to plotting a histogram with linearly spaced bins with a logarithmic
x-axis. Equal sized bins will be displayed as wider for small x and narrower for large x.
Support for HiDPI (Retina) displays in the NbAgg and WebAgg backends
The NbAgg and WebAgg backends will now use the full resolution of your high-pixel-density display.
468
Chapter 5. What’s new in Matplotlib
Matplotlib, Release 2.1.2
Using ax.imshow
105
104
104
103
103
102
102
101
101
100
0
1
2
3
4
Using ax.pcolormesh
105
5
6
100
0
1
2
3
4
5
6
Change in the default animation codec
The default animation codec has been changed from mpeg4 to h264, which is more efficient. It can be set
via the animation.codec rcParam.
Deprecated support for mencoder in animation
The use of mencoder for writing video files with mpl is problematic; switching to ffmpeg is strongly advised.
All support for mencoder will be removed in version 2.2.
Boxplot Zorder Keyword Argument
The zorder parameter now exists for boxplot(). This allows the zorder of a boxplot to be set in the
plotting function call.
boxplot(np.arange(10), zorder=10)
Filled + and x markers
New fillable plus and x markers have been added. See the markers module and marker reference examples.
rcount and ccount for plot_surface()
As of v2.0, mplot3d’s plot_surface() now accepts rcount and ccount arguments for controlling the
sampling of the input data for plotting. These arguments specify the maximum number of evenly spaced
5.2. Previous Whats New
469
Matplotlib, Release 2.1.2
samples to take from the input data. These arguments are also the new default sampling method for the
function, and is considered a style change.
The old rstride and cstride arguments, which specified the size of the evenly spaced samples, become
the default when ‘classic’ mode is invoked, and are still available for use. There are no plans for deprecating
these arguments.
Streamplot Zorder Keyword Argument Changes
The zorder parameter for streamplot() now has default value of None instead of 2. If None is given as
zorder, streamplot() has a default zorder of matplotlib.lines.Line2D.zorder.
Extension to matplotlib.backend_bases.GraphicsContextBase
To support standardizing hatch behavior across the backends we ship the matplotlib.backend_bases.
GraphicsContextBase.get_hatch_color method as added to matplotlib.backend_bases.
GraphicsContextBase. This is only used during the render process in the backends we ship so will
not break any third-party backends.
If you maintain a third-party backend which extends GraphicsContextBase this method is now available
to you and should be used to color hatch patterns.
470
Chapter 5. What’s new in Matplotlib
CHAPTER
SIX
GITHUB STATS
GitHub stats for 2017/10/03 - 2017/12/09 (tag: v2.1.1)
These lists are automatically generated, and may be incomplete or contain duplicates.
We closed 78 issues and merged 172 pull requests. The full list can be seen on GitHub
The following 44 authors contributed 455 commits.
• Adrien F. Vincent
• ahed87
• Allan Haldane
• Antony Lee
• apodemus
• Arthur Paulino
• Atharva Khare
• Ben Root
• cgohlke
• Christoph Gohlke
• David Stansby
• deepyaman
• Doug Blank
• Elliott Sales de Andrade
• Eric Firing
• Filip Dimitrovski
• hannah
• Importance of Being Ernest
• Jake Vanderplas
• Jan Schulz
471
Matplotlib, Release 2.1.2
• Jody Klymak
• Joe C
• Jose Luis Cortes Varela
• Jun Tan
• JunTan
• Kevin Ji
• Kexuan Sun
• Matthew Brett
• Matthias Bussonnier
• mcquin
• Michael Seifert
• Nathan Musoke
• Nelle Varoquaux
• Nikita Kniazev
• Patrick Faion
• Paul Hobson
• Ryan May
• Sean Farley
• Ted Petrou
• Thomas A Caswell
• Tim Hoffmann
• Tom
• Tom Dupré la Tour
• TomDonoghue
GitHub issues and pull requests:
Pull Requests (172):
• PR #9947: Backport PR #9942 on branch v2.1.x
• PR #9942: Minor doc formatting cleanups in pyplot
• PR #9924: setupext: fix missing js files for web_backend
• PR #9909: Backport PR #9881 on branch v2.1.x
• PR #9881: Polar tick fixes
• PR #9448: Fix instance of ‘RendererPS’ has no ‘tex’ member
472
Chapter 6. GitHub Stats
Matplotlib, Release 2.1.2
• PR #9901: Backport PR #9897 on branch v2.1.x
• PR #9902: DOC: correct inverted description of aspect
• PR #9874: Backport PR #9272 on branch v2.1.x
• PR #9897: changed line to ‘alias for set_multialignment’
• PR #9850: Merge pull request #9773 from dopplershift/fix-appveyor
• PR #9773: MNT: Make sure AppVeyor fails if tests fail
• PR #9760: Fix exception when guessing the AFM familyname
• PR #9340: bugfix/test for #9336 integer overwrite in categorical
• PR #9318: Don’t sort categorical keys.
• PR #9796: Add deprecation for Axes.set_thetagrids(frac).
• PR #9772: FIX: TextBox.disconnect remove from registries that TextBox has
• PR #9803: Add links to python’s strftime method
• PR #9793: FIX: treat zorder=None as falling back to the default
• PR #9777: PR: Port Figure docstrings to numpydoc
• PR #9770: Backport PR #9670 on branch v2.1.x
• PR #9768: BLD: update MANIFEST.in to account for moved files
• PR #9769: Backport PR #9723 on branch v2.1.x
• PR #9257: FIX: segfault on truncated png
• PR #9670: Make tick_left/right keep labels off if they are already off
• PR #9723: ENH: Catch masked array and invalid x, y to pcolormesh
• PR #9767: Backport PR #9766 on branch v2.1.x
• PR #9766: Fix mixed_subplots example
• PR #9762: Backport PR #9759 on branch v2.1.x
• PR #9759: blocking_input: Fix “manager” attr check
• PR #9755: Backport PR #9743 on branch v2.1.x
• PR #9754: Backport PR #9752 on branch v2.1.x
• PR #9743: FIX: check if contour level in format dictionary, or return a default
• PR #9752: DOC: example demo_parasite_axes2.py broken on 2.1.0
• PR #9749: Backport PR #9748 on branch v2.1.x
• PR #9746: Backport PR #9724 on branch v2.1.x
• PR #9748: Reword subplot() doc.
• PR #9724: Fix PDFpages bug
473
Matplotlib, Release 2.1.2
• PR #9726: FIX/TST: update tests for pandas 0.21
• PR #9734: Backport PR #9733 on branch v2.1.x
• PR #9733: Allow _BackendNbAgg.show() to take keyword “block”
• PR #9721: Backport PR #9711 on branch v2.1.x
• PR #9722: FIX: copy=False for masked arrays in pcolormesh
• PR #9711: Minor markup fix.
• PR #9714: Backport PR #9662 on branch v2.1.x
• PR #9662: Fix crash when restarting OSX single shot timer
• PR #9461: Property tables
• PR #9709: FIX: ensure errorbar creates line collection even with empty data
• PR #9710: Backport PR #9705 on branch v2.1.x
• PR #9705: Fix scatterplot categorical support
• PR #9692: Backport PR #9687 on branch v2.1.x
• PR #9687: Fix callbackregistry docstring.
• PR #9691: Backport PR #9689 on branch v2.1.x
• PR #9689: Updates to font-related examples.
• PR #9679: Backport PR #9676 on branch v2.1.x
• PR #9676: FIX: Catch IOError on font-cache write
• PR #9675: Backport PR #9649 on branch v2.1.x
• PR #9644: Backport PR #9324 on branch v2.1.x
• PR #9649: Reoder Axes API docs.
• PR #9667: Backport PR #9661 on branch v2.1.x
• PR #9661: Fix arcs with very large width/height.
• PR #9324: [MRG] Allow kwarg handles and labels figure.legend and make doc for kwargs the same
• PR #9633: FIX: make labelrotation work as kwarg to tick_params as documented
• PR #9632: Backport PR #9359 on branch v2.1.x
• PR #9631: Backport PR #9389 on branch v2.1.x
• PR #9630: Backport PR #9612 on branch v2.1.x
• PR #9359: Keep track of axes in interactive navigation.
• PR #9534: Fix webagg
• PR #9389: Assign event to later Axes if zorders are tied.
• PR #9612: Only set view/data intervals if axis is set in AutoDateLocator
474
Chapter 6. GitHub Stats
Matplotlib, Release 2.1.2
• PR #9618: Backport PR #9262 on branch v2.1.x
• PR #9623: Backport PR #9600 on branch v2.1.x
• PR #9621: Backport PR #9617 on branch v2.1.x
• PR #9600: Fix some widget docstrings.
• PR #9262: Minor doc markup fixes.
• PR #9605: Backport PR #9604 on branch v2.1.x
• PR #9603: Fix xkcd() not resetting context anymore.
• PR #9604: Gridspec doc fixes
• PR #9521: fix xkcd context
• PR #9596: Backport PR #9589 on branch v2.1.x
• PR #9589: Fix typo in isinstance
• PR #9586: Backport PR #9564 on branch v2.1.x
• PR #9563: Backport PR #9121 on branch v2.1.x
• PR #9584: Add returns documentation to fill_between methods
• PR #9575: Add some legend handler documentation
• PR #9576: Backport PR #9477 on branch v2.1.x
• PR #9572: Backport PR #9569 on branch v2.1.x
• PR #9477: In LogTransform, clip after log, not before.
• PR #9568: Add a proper docstring to AutoLocator
• PR #9569: Docstring fix.
• PR #9564: TST: add test of normed histogram with unequal bins
• PR #9561: Backport PR #9555 on branch v2.1.x
• PR #9554: Backport PR #9549 on branch v2.1.x
• PR #9555: MRG: expand docstring for hist
• PR #9549: Fix stale draws on MacOSX backend
• PR #9547: Backport PR #9540 on branch v2.1.x
• PR #9542: Backport PR #9442 on branch v2.1.x
• PR #9540: DOC fix set_xticklabels docstring
• PR #9304: Fedora build patches
• PR #9442: BUG: Fix _extent not set in PcolorImage
• PR #9533: Backport PR #9292 on branch v2.1.x
• PR #9539: Backport PR #9363 on branch v2.1.x
475
Matplotlib, Release 2.1.2
• PR #9363: Allow invalid limits when panning
• PR #9527: Backport PR #9516 on branch v2.1.x
• PR #9505: Doc draw event details
• PR #9526: Backport PR #9517 on branch v2.1.x
• PR #9292: Fix TypeError: a bytes-like object is required, not ‘str’
• PR #9522: Backport PR #9504 on branch v2.1.x
• PR #9525: Backport PR #9517 on branch v2.1.x
• PR #9517: Convert slider docstrings to numpydoc
• PR #9516: Make colorbar docstring numpydoc
• PR #9504: Truncate windows registry entries after null byte.
• PR #9500: Backport PR #9495 on branch v2.1.x
• PR #9495: Macosx fixes
• PR #9492: Backport PR #9465 on branch v2.1.x
• PR #9465: Avoid dividing by zero in AutoMinorLocator (fixes #8804)
• PR #9468: FIX: provide __ne__ implementation for transforms in py2
• PR #9446: Backport PR #9418 on branch v2.1.x
• PR #9449: TST: Enable xdist on Appveyor
• PR #9444: STY: Remove explicit return in __init__
• PR #9431: Backport PR #9427 on branch v2.1.x
• PR #9418: TST: Disable faulthandler on Windows if CPython 3.6-3.6.3
• PR #9440: Remove reimport of modules
• PR #9439: Fix undefined variable ‘warnings’
• PR #9437: Fix Undefined variable ‘symbol’
• PR #9430: Backport PR #9428 on branch v2.1.x
• PR #9411: Backport PR #9410 on branch v2.1.x
• PR #9427: Fix NameError: name ‘exc’ is not defined
• PR #9428: Fix NameError: name ‘ArgumentError’ is not defined
• PR #9416: Backport PR #9415 on branch v2.1.x
• PR #9415: Import time module so that pyplot.pause works
• PR #9382: Backport PR #9343 on branch v2.1.x
• PR #9410: BUG: Fix savefig GUI in GTK backend
• PR #9399: Backport PR #9395 on branch v2.1.x
476
Chapter 6. GitHub Stats
Matplotlib, Release 2.1.2
• PR #9393: Don’t pass mixed str/bytes inputs to subprocess.
• PR #9395: TST: Unblock Appveyor build by patching subprocess
• PR #9398: Backport PR #9347 on branch v2.1.x
• PR #9347: Fix backend refactor
• PR #9285: FIX: handle fully masked data
• PR #9343: Fix broken link to proxy artists documentation
• PR #9364: Backport PR #9353 on branch v2.1.x
• PR #9353: Fix edgecolor being only applied to first bar.
• PR #9352: Backport PR #9335 on branch v2.1.x
• PR #9335: Fix poorly done deprecations in image.py.
• PR #9337: Backport PR #9242 on branch v2.1.x
• PR #9338: Backport PR #9279 on branch v2.1.x
• PR #9279: Update doc strings
• PR #9242: Errorbar bugfix
• PR #9310: Backport PR #9299 on branch v2.1.x
• PR #9309: DOC: Update docstring to numpy format for last few functions in transforms
• PR #6969: CI: add appveyor script to build Windows wheels
• PR #9308: Backport PR #9295 on branch v2.1.x
• PR #9299: Restore better error message on std::runtime_error.
• PR #9295: In text, warn and return instead of raise exception for non-finite x, y
• PR #9283: Backport PR #9277 on branch v2.1.x
• PR #9307: Backport PR #9303 on branch v2.1.x
• PR #9303: Don’t use pytest.filterwarings, which needs pytest>=3.2.
• PR #9297: Backport PR #9289 on branch v2.1.x
• PR #9289: Throw std::runtime_exception instead of char*.
• PR #9290: Backport PR #9268 on branch v2.1.x
• PR #9268: Fix documents of semilogx and semilogy.
• PR #9287: Backport PR #9286 on branch v2.1.x
• PR #9286: Ask Appveyor to ignore certain branches.
• PR #9277: plot_surface docstring + edge case fix
• PR #9270: Fix C++ warnings
• PR #9272: Include the default of “plot_pre_code” of the plot directive in the documentation
477
Matplotlib, Release 2.1.2
• PR #9258: Remove four unused variables in src/_path.h.
• PR #7335: fix the stack remove error
• PR #6949: Value checking the numpoints argument to be a whole number.
• PR #6161: Fix #5456: Keep margins <= .5 in tight_layout
• PR #8602: doc: State default for legend’s markerfirst
• PR #8605: Add mpl.contour to api docs; minor fix to docstring.
Issues (78):
• #9739: doc inconsistency: definition of “aspect”
• #9896: Simple documentation typo
• #9719: Appveyor passing, even when tests are failing
• #9436: Instance of ‘TextBox’ has no ‘observers’ member?
• #9744: frac in set_thetagrids() doesn’t work
• #9819: Multi-page PDF file size jumps since 2.0.0
• #9818: edgecolor arg set to scalar applies to the first bar in bar() method
• #9785: zorder=None not properly handled
• #9735: 2.1.0 sdist does not allow building docs
• #9808: inconsistent hatch and border color in barh in matplotlib 2.1.0
• #8982: Backend MacOSX keyboard not working
• #9256: reading truncated png can segfault python
• #9664: Change in behavior of axis.tick_left() with shared axes from 2.0 to 2.1
• #9358: zoom/pan stack bug in 2.1.0
• #9720: plt.pcolormesh stopped working with Masked Arrays
• #9758: plt.ginput broken on 2.1.0: plot does not appear
• #9742: clabel raises KeyError with level on boundary since matplotlib 2.1.0
• #9651: “block” keyword unrecognized in 2.1 in notebook backend
• #9716: Large size of plots saved as pdf
• #9729: plt.pause() with notebook backend causes error
• #8122: keyword labelrotation is not recognized
• #9655: Segmentation fault when starting a timer a second time (MacOS X backend)
• #9699: IndexError thrown by pyplot.legend()
• #9494: Categorical not hitting update path on fill_between
• #9700: Subsequent calls to plt.scatter with different categories raise ValueError
478
Chapter 6. GitHub Stats
Matplotlib, Release 2.1.2
• #9702: Broken pdf export when using genuine TeX (Missing encode)
• #9701: Bars are not visible in bar plot when log scale is enabled
• #9548: failure on import due to IOError writing font cache
• #9659: patches.Arc objects randomly drawing the full ellipse
• #9380: Cannot import pyplot. NameError: ‘FigureManagerWebAgg’ is not defined
• #8623: fill_between incorrect with log y-axis and value 0
• #9320: 2.1 figure.legend broken
• #9388: Mouse events have incorrect inaxes/data properties when axes overlap (matplotlib 2.1.0)
• #9457: ax.fill_between broken for log scale and values below zero
• #9558: Inconsistency between AutoLocator and AutoDateLocator
• #9288: Histograms disappear with logarithmic y-axis
• #9628: Histogram missing in Matplotlib 2.1.0
• #9611: Unexpected behaviour with string input to .plot and .fill_between
• #7158: Arrays are not equal in 2.0.0b4 testsuite on Fedora rawhide/aarch64 (ARM v8 64bit)
• #9557: Behavior of hist() with normed=True changes from v2.0 to v2.1
• #9585: Cannot write JPG images anymore with Pillow 4.2
• #8282: changing facecolor to ‘none’ prevents updating canvas
• #6538: On armv7hl, some get_cursor_data calls return 0 instead of None.
• #8426: PcolorImage does not set _extent
• #9406: 2.1.0 serious regression in Qt5 backend
• #9361: 2.1 change - Axis Limit Error
• #9390: Save to .pdf doesn’t work in 2.1.0
• #9485: FileNotFoundError while import matplotlib (maybe pyplot)
• #9332: Qt backend figureoptions.py does not work due to change in image.py
• #9491: TextBox widget on MacOSX fails with RuntimeError: Cannot get window extent w/o renderer
• #8814: 3D plot camera-rotation does not update with mouse movement when using the MacOS backend
• #8804: Division by zero in AutoMinorLocator
• #9455: ticklabel and gridlines in polar projection in v2.1.0
• #9412: pyplot.pause doesn’t import the time module but uses it (v2.1.0)
• #9176: Appveyor build failing
• #9280: imshow errors when plotting completely masked array
479
Matplotlib, Release 2.1.2
• #9351: mpl 2.1 barcharts edgecolor and linewidth only apply to first bar
• #9345: matplotlib 2.1.0, backend macosx: need _BackendMac, got FigureManagerMac
• #9241: Errorbar plot with first value masked raises TypeError
• #3707: re-write release guide
• #8706: Bug with 3D graphing
• #7358: PEP8: making travis run pep8 on diff instead of comparing the total number of violation to be
more robust.
• #6976: LaTeX wrong symbol displayed for sup- and subscript
• #9206: Interactive mode frozen on python 3.6.2 (Windows 7)
• #6572: segfault saving a high dpi png
• #9210: ValueError: ordinal must be >= 1 by plotting the index and its SMA
• #7050: Segmentation fault inside _backend_agg.so
• #9017: Getting “No module named ‘_tkinter’” error
• #6420: matplotlib Qt5Agg backend error: ‘figure’ is an unknown keyword argument
• #5421: Rectangle patch constructor fails with units
• #4020: Document default key-bindings
• #5950: Issues with Numpy 1.11 release candidate
• #7319: Alternative dev install instructions
• #4936: Memory leak in NavigationToolbar2.mouse_over
• #5689: Mac: Save button not working on 1.5.0 or 2.x with backend.qt4 in ipython 4
• #6411: Rendered text images do not exactly overlap for same text content
• #7168: Future warning: elementwise comparison failed
• #7851: very small errors in test suite, py3.6 and 3.5
480
Chapter 6. GitHub Stats
CHAPTER
SEVEN
LICENSE
Matplotlib only uses BSD compatible code, and its license is based on the PSF license. See the Open
Source Initiative licenses page for details on individual licenses. Non-BSD compatible licenses (e.g., LGPL)
are acceptable in matplotlib toolkits. For a discussion of the motivations behind the licencing choice, see
Licenses.
7.1 Copyright Policy
John Hunter began matplotlib around 2003. Since shortly before his passing in 2012, Michael Droettboom
has been the lead maintainer of matplotlib, but, as has always been the case, matplotlib is the work of many.
Prior to July of 2013, and the 1.3.0 release, the copyright of the source code was held by John Hunter. As
of July 2013, and the 1.3.0 release, matplotlib has moved to a shared copyright model.
matplotlib uses a shared copyright model. Each contributor maintains copyright over their contributions to
matplotlib. But, it is important to note that these contributions are typically only changes to the repositories.
Thus, the matplotlib source code, in its entirety, is not the copyright of any single person or institution.
Instead, it is the collective copyright of the entire matplotlib Development Team. If individual contributors
want to maintain a record of what changes/contributions they have specific copyright on, they should indicate
their copyright in the commit message of the change, when they commit the change to one of the matplotlib
repositories.
The Matplotlib Development Team is the set of all contributors to the matplotlib project. A full list can be
obtained from the git version control logs.
7.2 License agreement for matplotlib 2.1.2
1. This LICENSE AGREEMENT is between the Matplotlib Development Team (“MDT”), and the Individual or Organization (“Licensee”) accessing and otherwise using matplotlib software in source or binary
form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, MDT hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare
derivative works, distribute, and otherwise use matplotlib 2.1.2 alone or in any derivative version, provided,
however, that MDT’s License Agreement and MDT’s notice of copyright, i.e., “Copyright (c) 2012-2013
481
Matplotlib, Release 2.1.2
Matplotlib Development Team; All Rights Reserved” are retained in matplotlib 2.1.2 alone or in any derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on or incorporates matplotlib 2.1.2 or any
part thereof, and wants to make the derivative work available to others as provided herein, then Licensee
hereby agrees to include in any such work a brief summary of the changes made to matplotlib 2.1.2.
4. MDT is making matplotlib 2.1.2 available to Licensee on an “AS IS” basis. MDT MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT
LIMITATION, MDT MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
MATPLOTLIB 2.1.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. MDT SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF MATPLOTLIB 2.1.2
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING MATPLOTLIB 2.1.2, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or
joint venture between MDT and Licensee. This License Agreement does not grant permission to use MDT
trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or
any third party.
8. By copying, installing or otherwise using matplotlib 2.1.2, Licensee agrees to be bound by the terms and
conditions of this License Agreement.
7.3 License agreement for matplotlib versions prior to 1.3.0
1. This LICENSE AGREEMENT is between John D. Hunter (“JDH”), and the Individual or Organization
(“Licensee”) accessing and otherwise using matplotlib software in source or binary form and its associated
documentation.
2. Subject to the terms and conditions of this License Agreement, JDH hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare
derivative works, distribute, and otherwise use matplotlib 2.1.2 alone or in any derivative version, provided,
however, that JDH’s License Agreement and JDH’s notice of copyright, i.e., “Copyright (c) 2002-2009 John
D. Hunter; All Rights Reserved” are retained in matplotlib 2.1.2 alone or in any derivative version prepared
by Licensee.
3. In the event Licensee prepares a derivative work that is based on or incorporates matplotlib 2.1.2 or any
part thereof, and wants to make the derivative work available to others as provided herein, then Licensee
hereby agrees to include in any such work a brief summary of the changes made to matplotlib 2.1.2.
4. JDH is making matplotlib 2.1.2 available to Licensee on an “AS IS” basis. JDH MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT
LIMITATION, JDH MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
MATPLOTLIB 2.1.2 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
482
Chapter 7. License
Matplotlib, Release 2.1.2
5. JDH SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF MATPLOTLIB 2.1.2
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING MATPLOTLIB 2.1.2, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or
joint venture between JDH and Licensee. This License Agreement does not grant permission to use JDH
trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or
any third party.
8. By copying, installing or otherwise using matplotlib 2.1.2, Licensee agrees to be bound by the terms and
conditions of this License Agreement.
7.3. License agreement for matplotlib versions prior to 1.3.0
483
Matplotlib, Release 2.1.2
484
Chapter 7. License
CHAPTER
EIGHT
CREDITS
Matplotlib was written by John D. Hunter, with contributions from an ever-increasing number of users and
developers. The current co-lead developers are Michael Droettboom and Thomas A. Caswell; they are
assisted by many active developers.
The following is a list of contributors extracted from the git revision control history of the project:
4over7, Aaron Boushley, Acanthostega, Adam Ginsburg, Adam Heck, Adam Ortiz, Adrian Price-Whelan,
Adrien F. Vincent, Ahmet Bakan, Alan Du, Alejandro Dubrovsky, Alex C. Szatmary, Alex Loew, Alexander
Taylor, Alexei Colin, Ali Mehdi, Alistair Muldal, Allan Haldane, Amit Aronovitch, Amy, AmyTeegarden,
Andrea Bedini, Andreas Hilboll, Andreas Wallner, Andrew Dawson, Andrew Merrill, Andrew Straw, Andy
Zhu, Anton Akhmerov, Antony Lee, Arie, Ariel Hernán Curiale, Arnaud Gardelein, Arpad Horvath, Aseem
Bansal, Behram Mistree, Ben Cohen, Ben Gamari, Ben Keller, Ben Root, Benjamin Reedlunn, Binglin
Chang, Bradley M. Froehle, Brandon Liu, Brett Cannon, Brett Graham, Brian Mattern, Brian McLaughlin, Bruno Beltran, CJ Carey, Cameron Bates, Cameron Davidson-Pilon, Carissa Brittain, Carl Michal,
Carwyn Pelley, Casey Webster, Casper van der Wel, Charles Moad, Chris Beaumont, Chris G, Christian
Brueffer, Christian Stade-Schuldt, Christoph Dann, Christoph Gohlke, Christoph Hoffmann, Cimarron Mittelsteadt, Corey Farwell, Craig M, Craig Tenney, Damon McDougall, Dan Hickstein, Daniel Hyams, Daniel
O’Connor, Dara Adib, Darren Dale, David Anderson, David Haberthür, David Huard, David Kaplan, David
Kua, David Trémouilles, Dean Malmgren, Dmitry Lupyan, DonaldSeo, Dora Fraeman, Duncan Macleod,
Edin Salkovic, Elena Glassman, Elias Pipping, Elliott Sales de Andrade, Emil Mikulic, Eric Dill, Eric Firing, Eric Ma, Eric O. LEBIGOT (EOL), Erik Bray, Eugen Beck, Eugene Yurtsev, Evan Davey, Ezra Peisach,
Fabien Maussion, Fabio Zanini, Federico Ariza, Felipe, Fernando Perez, Filipe Fernandes, Florian Rhiem,
Francesco Montesano, Francis Colas, François Magimel, Gaute Hope, Gellule Xg, Geoffroy Billotey, Gerald
Storer, Giovanni, Graham Poulter, Gregory Ashton, Gregory R. Lee, Grégory Lielens, Guillaume Gay, Gustavo Braganca, Hans Dembinski, Hans Meine, Hans Moritz Günther, Hassan Kibirige, Holger Peters, Hubert
Holin, Ian Thomas, Ignas Anikevicius (gns_ank), Ilia Kurenkov, Ioannis Filippidis, Ismo Toijala, J. Goutin,
Jack Kelly, Jae-Joon Lee, Jaime Fernandez, Jake Vanderplas, James A. Bednar, James Pallister, James R.
Evans, JamesMakela, Jan Schulz, Jan-Philip Gehrcke, Jan-willem De Bleser, Jarrod Millman, Jascha Ulrich, Jason Grout, Jason Liw Yan Chong, Jason Miller, JayP16, Jeff Lutgen, Jeff Whitaker, Jeffrey Bingham,
Jens Hedegaard Nielsen, Jeremy Fix, Jeremy O’Donoghue, Jeremy Thurgood, Jessica B. Hamrick, Jim
Radford, Jochen Voss, Jody Klymak, Joe Kington, Joel B. Mohler, John Hunter, Jonathan Waltman, Jorrit
Wronski, Josef Heinen, Joseph Jon Booker, José Ricardo, Jouni K. Seppänen, Julian Mehne, Julian Taylor,
JulianCienfuegos, Julien Lhermitte, Julien Schueller, Julien Woillez, Julien-Charles Lévesque, Kanwar245,
Katy Huff, Ken McIvor, Kevin Chan, Kevin Davies, Kevin Keating, Kimmo Palin, Konrad Förstner, Konstantin Tretyakov, Kristen M. Thyng, Lance Hepler, Larry Bradley, Leeonadoh, Lennart Fricke, Leo Singer,
Levi Kilcher, Lion Krischer, Lodato Luciano, Lori J, Loïc Estève, Loïc Séguin-C, Magnus Nord, Majid
alDosari, Maksym P, Manuel GOACOLOU, Manuel Metz, Marc Abramowitz, Marcos Duarte, Marek Rud485
Matplotlib, Release 2.1.2
nicki, Marianne Corvellec, Marin Gilles, Markus Roth, Markus Rothe, Martin Dengler, Martin Fitzpatrick,
Martin Spacek, Martin Teichmann, Martin Thoma, Martin Ueding, Masud Rahman, Mathieu Duponchelle,
Matt Giuca, Matt Klein, Matt Li, Matt Newville, Matt Shen, Matt Terry, Matthew Brett, Matthew Emmett, Matthias Bussonnier, Matthieu Caneill, Matěj Týč, Maximilian Albert, Maximilian Trescher, Mellissa
Cross, Michael, Michael Droettboom, Michael Sarahan, Michael Welter, Michiel de Hoon, Michka Popoff,
Mike Kaufman, Mikhail Korobov, MinRK, Minty Zhang, MirandaXM, Miriam Sierig, Muhammad Mehdi,
Neil, Neil Crighton, Nelle Varoquaux, Niall Robinson, Nic Eggert, Nicholas Devenish, Nick Semenkovich,
Nicolas P. Rougier, Nicolas Pinto, Nikita Kniazev, Niklas Koep, Nikolay Vyahhi, Norbert Nemec, OceanWolf, Oleg Selivanov, Olga Botvinnik, Oliver Willekens, Parfenov Sergey, Pascal Bugnion, Patrick Chen,
Patrick Marsh, Paul, Paul Barret, Paul G, Paul Hobson, Paul Ivanov, Pauli Virtanen, Per Parker, Perry
Greenfield, Pete Bachant, Peter Iannucci, Peter St. John, Peter Würtz, Phil Elson, Pierre Haessig, Pim
Schellart, Piti Ongmongkolkul, Puneeth Chaganti, Ramiro Gómez, Randy Olson, Reinier Heeres, Remi
Rampin, Richard Hattersley, Richard Trieu, Ricky, Robert Johansson, Robin Dunn, Rohan Walker, Roland
Wirth, Russell Owen, RutgerK, Ryan Blomberg, Ryan D’Souza, Ryan Dale, Ryan May, Ryan Nelson,
RyanPan, Salil Vanvari, Sameer D’Costa, Sandro Tosi, Scott Lasley, Scott Lawrence, Scott Stevenson, Sebastian Pinnau, Sebastian Raschka, Sergey Kholodilov, Sergey Koposov, Silviu Tantos, Simon Cross, Simon
Gibbons, Skelpdar, Skipper Seabold, Slav Basharov, Spencer McIntyre, Stanley, Simon, Stefan Lehmann,
Stefan van der Walt, Stefano Rivera, Stephen Horst, Sterling Smith, Steve Chaplin, Steven Silvester, Stuart
Mumford, Takafumi Arakaki, Takeshi Kanmae, Tamas Gal, Thomas A Caswell, Thomas Hisch, Thomas
Kluyver, Thomas Lake, Thomas Robitaille, Thomas Spura, Till Stensitzki, Timo Vanwynsberghe, Tobias
Hoppe, Tobias Megies, Todd Jennings, Todd Miller, Tomas Kazmar, Tony S Yu, Tor Colvin, Travis Oliphant,
Trevor Bekolay, Ulrich Dobramysl, Umair Idris, Vadim Markovtsev, Valentin Haenel, Victor Zabalza, Viktor Kerkez, Vlad Seghete, Víctor Terrón, Víctor Zabalza, Wen Li, Wendell Smith, Werner F Bruhin, Wes
Campaigne, Wieland Hoffmann, William Manley, Wouter Overmeire, Xiaowen Tang, Yann Tambouret,
Yaron de Leeuw, Yu Feng, Yunfei Yang, Yuri D’Elia, Yuval Langer, Zach Pincus, Zair Mubashar, alex,
anykraus, arokem, aseagram, aszilagyi, bblay, bev-a-tron, blackw1ng, blah blah, burrbull, butterw, cammil,
captainwhippet, chadawagner, chebee7i, danielballan, davidovitch, daydreamt, domspad, donald, drevicko,
e-q, elpres, endolith, fardal, ffteja, fgb, fibersnet, frenchwr, fvgoto, gitj, gluap, goir, hugadams, insertroar,
itziakos, jbbrokaw, juan.gonzalez, kcrisman, kelsiegr, khyox, kikocorreoso, kramer65, kshramt, lichri12,
limtaesu, marky, masamson, mbyt, mcelrath, mdipierro, mrkrd, nickystringer, nwin, pkienzle, profholzer,
pupssman, rahiel, rhoef, rsnape, s9w, sdementen, sfroid, sohero, spiessbuerger, stahlous, switham, syngron,
torfbolt, u55, ugurthemaster, vbr, xbtsw, and xuanyuansen.
Some earlier contributors not included above are (with apologies to any we have missed):
Charles Twardy, Gary Ruben, John Gill, David Moore, Paul Barrett, Jared Wahlstrand, Jim Benson, Paul
Mcguire, Andrew Dalke, Nadia Dencheva, Baptiste Carvello, Sigve Tjoraand, Ted Drain, James Amundson,
Daishi Harada, Nicolas Young, Paul Kienzle, John Porter, and Jonathon Taylor.
We also thank all who have reported bugs, commented on proposed changes, or otherwise contributed to
Matplotlib’s development and usefulness.
486
Chapter 8. Credits
Part II
The Matplotlib FAQ
487
CHAPTER
NINE
INSTALLATION
Contents
• Installation
– Report a compilation problem
– matplotlib compiled fine, but nothing shows up when I use it
– How to completely remove Matplotlib
– Linux Notes
– OSX Notes
* Which python for OSX?
* Installing OSX binary wheels
· Python.org Python
· Macports Python
· Homebrew Python
· pip problems
* Checking your installation
– Windows Notes
– Install from source
9.1 Report a compilation problem
See Getting help.
489
Matplotlib, Release 2.1.2
9.2 matplotlib compiled fine, but nothing shows up when I use it
The first thing to try is a clean install and see if that helps. If not, the best way to test your install is
by running a script, rather than working interactively from a python shell or an integrated development
environment such as IDLE which add additional complexities. Open up a UNIX shell or a DOS command
prompt and run, for example:
python -c "from pylab import *; plot(); show()" --verbose-helpful
This will give you additional information about which backends matplotlib is loading, version information,
and more. At this point you might want to make sure you understand matplotlib’s configuration process,
governed by the matplotlibrc configuration file which contains instructions within and the concept of the
matplotlib backend.
If you are still having trouble, see Getting help.
9.3 How to completely remove Matplotlib
Occasionally, problems with Matplotlib can be solved with a clean installation of the package. In order to
fully remove an installed Matplotlib:
1. Delete the caches from your Matplotlib configuration directory.
2. Delete any Matplotlib directories or eggs from your installation directory.
9.4 Linux Notes
To install Matplotlib at the system-level, we recommend that you use your distribution’s package manager.
This will guarantee that Matplotlib’s dependencies will be installed as well.
If, for some reason, you cannot use the package manager, you may use the wheels available on PyPI:
python -mpip install matplotlib
or build Matplotlib from source.
9.5 OSX Notes
9.5.1 Which python for OSX?
Apple ships OSX with its own Python, in /usr/bin/python, and its own copy of Matplotlib. Unfortunately, the way Apple currently installs its own copies of NumPy, Scipy and Matplotlib means that these
packages are difficult to upgrade (see system python packages). For that reason we strongly suggest that
you install a fresh version of Python and use that as the basis for installing libraries such as NumPy and
Matplotlib. One convenient way to install matplotlib with other useful Python software is to use one of the
excellent Python scientific software collections that are now available:
490
Chapter 9. Installation
Matplotlib, Release 2.1.2
• Anaconda from Continuum Analytics
• Canopy from Enthought
These collections include Python itself and a wide range of libraries; if you need a library that is not available from the collection, you can install it yourself using standard methods such as pip. Continuum and
Enthought offer their own installation support for these collections; see the Ananconda and Canopy web
pages for more information.
Other options for a fresh Python install are the standard installer from python.org, or installing Python using
a general OSX package management system such as homebrew or macports. Power users on OSX will
likely want one of homebrew or macports on their system to install open source software packages, but it
is perfectly possible to use these systems with another source for your Python binary, such as Anaconda,
Canopy or Python.org Python.
9.5.2 Installing OSX binary wheels
If you are using recent Python from https://www.python.org, Macports or Homebrew, then you can use the
standard pip installer to install Matplotlib binaries in the form of wheels.
Python.org Python
Install pip following the standard pip install instructions. For the impatient, open a new Terminal.app window and:
curl -O https://bootstrap.pypa.io/get-pip.py
Then (Python 2):
python get-pip.py
or (Python 3):
python3 get-pip.py
You can now install matplotlib and all its dependencies with
python -mpip install matplotlib
or
python3 -mpip install matplotlib
Macports Python
For Python 2:
9.5. OSX Notes
491
Matplotlib, Release 2.1.2
sudo port install py27-pip
sudo python2 -mpip install matplotlib
For Python 3:
sudo port install py36-pip
sudo python3.6 -mpip install matplotlib
Homebrew Python
For Python 2:
python2 -mpip install matplotlib
For Python 3:
python3 -mpip install matplotlib
You might also want to install IPython or the Jupyter notebook (pythonX -mpip install ipython,
pythonX -mpip install notebook, where pythonX is set as above).
pip problems
If you get errors with pip trying to run a compiler like gcc or clang, then the first thing to try is to install
xcode and retry the install. If that does not work, then check Getting help.
9.5.3 Checking your installation
The new version of Matplotlib should now be on your Python “path”. Check this with one of these commands at the Terminal.app command line:
python2 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
(Python 2) or:
python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'
(Python 3). You should see something like this:
2.1.0 /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/
,→matplotlib/__init__.pyc
where 2.1.0 is the Matplotlib version you just installed, and the path following depends on whether you
are using Python.org Python, Homebrew or Macports. If you see another version, or you get an error like
this:
492
Chapter 9. Installation
Matplotlib, Release 2.1.2
Traceback (most recent call last):
File "<string>", line 1, in <module>
ImportError: No module named matplotlib
then check that the Python binary is the one you expected by doing one of these commands in Terminal.app:
which python2
or:
which python3
If you get the result /usr/bin/python2.7, then you are getting the Python installed with OSX, which is
probably not what you want. Try closing and restarting Terminal.app before running the check again. If that
doesn’t fix the problem, depending on which Python you wanted to use, consider reinstalling Python.org
Python, or check your homebrew or macports setup. Remember that the disk image installer only works for
Python.org Python, and will not get picked up by other Pythons. If all these fail, please let us know.
9.6 Windows Notes
See Windows.
9.7 Install from source
Clone the main source using one of:
git clone git@github.com:matplotlib/matplotlib.git
or:
git clone git://github.com/matplotlib/matplotlib.git
and build and install as usual with:
cd matplotlib
python -mpip install .
Note: If you are on Debian/Ubuntu, you can get all the dependencies required to build Matplotlib with:
sudo apt-get build-dep python-matplotlib
If you are on Fedora/RedHat, you can get all the dependencies required to build matplotlib by first installing
yum-builddep and then running:
su -c 'yum-builddep python-matplotlib'
9.6. Windows Notes
493
Matplotlib, Release 2.1.2
This does not build Matplotlib, but it does get all of the build dependencies, which will make building from
source easier.
If you want to be able to follow the development branch as it changes just replace the last step with:
python -mpip install -e .
This creates links and installs the command line script in the appropriate places.
Note: OSX users please see the Building on macOS guide.
Windows users please see the Building on Windows guide.
Then, if you want to update your matplotlib at any time, just do:
git pull
When you run git pull, if the output shows that only Python files have been updated, you are all set. If C
files have changed, you need to run pip install -e . again to compile them.
There is more information on using git in the developer docs.
494
Chapter 9. Installation
CHAPTER
TEN
HOW-TO
Contents
• How-To
– Plotting: howto
* Plot numpy.datetime64 values
* Find all objects in a figure of a certain type
* How to prevent ticklabels from having an offset
* Save transparent figures
* Save multiple plots to one pdf file
* Move the edge of an axes to make room for tick labels
* Automatically make room for tick labels
* Configure the tick widths
* Align my ylabels across multiple subplots
* Skip dates where there is no data
* Control the depth of plot elements
* Make the aspect ratio for plots equal
* Multiple y-axis scales
* Generate images without having a window appear
* Use show()
* Interpreting box plots and violin plots
– Contributing: howto
* Request a new feature
* Reporting a bug or submitting a patch
* Contribute to Matplotlib documentation
495
Matplotlib, Release 2.1.2
– Matplotlib in a web application server
* Matplotlib with apache
* Matplotlib with django
* Matplotlib with zope
* Clickable images for HTML
– Search examples
– Cite Matplotlib
10.1 Plotting: howto
10.1.1 Plot numpy.datetime64 values
For Matplotlib to plot dates (or any scalar with units) a converter to float needs to be registered with the
matplolib.units module. The current best converters for datetime64 values are in pandas. To enable
the converter, import it from pandas:
from pandas.tseries import converter as pdtc
pdtc.register()
If you only want to use the pandas converter for datetime64 values
from pandas.tseries import converter as pdtc
import matplotlib.units as munits
import numpy as np
munits.registry[np.datetime64] = pdtc.DatetimeConverter()
10.1.2 Find all objects in a figure of a certain type
Every Matplotlib artist (see Artist tutorial) has a method called findobj() that can be used to recursively
search the artist for any artists it may contain that meet some criteria (e.g., match all Line2D instances or
match some arbitrary filter function). For example, the following snippet finds every object in the figure
which has a set_color property and makes the object blue:
def myfunc(x):
return hasattr(x, 'set_color')
for o in fig.findobj(myfunc):
o.set_color('blue')
You can also filter on class instances:
496
Chapter 10. How-To
Matplotlib, Release 2.1.2
import matplotlib.text as text
for o in fig.findobj(text.Text):
o.set_fontstyle('italic')
10.1.3 How to prevent ticklabels from having an offset
The default formatter will use an offset to reduce the length of the ticklabels. To turn this feature off on a
per-axis basis:
ax.get_xaxis().get_major_formatter().set_useOffset(False)
set the rcParam axes.formatter.useoffset, or use a different formatter. See ticker for details.
10.1.4 Save transparent figures
The savefig() command has a keyword argument transparent which, if ‘True’, will make the figure and
axes backgrounds transparent when saving, but will not affect the displayed image on the screen.
If you need finer grained control, e.g., you do not want full transparency or you want to affect the screen
displayed version as well, you can set the alpha properties directly. The figure has a Rectangle instance
called patch and the axes has a Rectangle instance called patch. You can set any property on them directly
(facecolor, edgecolor, linewidth, linestyle, alpha). e.g.:
fig = plt.figure()
fig.patch.set_alpha(0.5)
ax = fig.add_subplot(111)
ax.patch.set_alpha(0.5)
If you need all the figure elements to be transparent, there is currently no global alpha setting, but you can
set the alpha channel on individual elements, e.g.:
ax.plot(x, y, alpha=0.5)
ax.set_xlabel('volts', alpha=0.5)
10.1.5 Save multiple plots to one pdf file
Many image file formats can only have one image per file, but some formats support multi-page files.
Currently only the pdf backend has support for this. To make a multi-page pdf file, first initialize the file:
from matplotlib.backends.backend_pdf import PdfPages
pp = PdfPages('multipage.pdf')
You can give the PdfPages object to savefig(), but you have to specify the format:
plt.savefig(pp, format='pdf')
An easier way is to call PdfPages.savefig:
10.1. Plotting: howto
497
Matplotlib, Release 2.1.2
pp.savefig()
Finally, the multipage pdf object has to be closed:
pp.close()
10.1.6 Move the edge of an axes to make room for tick labels
For subplots, you can control the default spacing on the left, right, bottom, and top as well as the horizontal and vertical spacing between multiple rows and columns using the matplotlib.figure.Figure.
subplots_adjust() method (in pyplot it is subplots_adjust()). For example, to move the bottom of
the subplots up to make room for some rotated x tick labels:
fig = plt.figure()
fig.subplots_adjust(bottom=0.2)
ax = fig.add_subplot(111)
You can control the defaults for these parameters in your matplotlibrc file; see Customizing matplotlib.
For example, to make the above setting permanent, you would set:
figure.subplot.bottom : 0.2
# the bottom of the subplots of the figure
The other parameters you can configure are, with their defaults
left = 0.125 the left side of the subplots of the figure
right = 0.9 the right side of the subplots of the figure
bottom = 0.1 the bottom of the subplots of the figure
top = 0.9 the top of the subplots of the figure
wspace = 0.2 the amount of width reserved for blank space between subplots, expressed as a fraction of
the average axis width
hspace = 0.2 the amount of height reserved for white space between subplots, expressed as a fraction of
the average axis height
If you want additional control, you can create an Axes using the axes() command (or equivalently the
figure add_axes() method), which allows you to specify the location explicitly:
ax = fig.add_axes([left, bottom, width, height])
where
all
values
are
in
fractional
(0
to
1)
coordinates.
See
sphx_glr_gallery_subplots_axes_and_figures_axes_demo.py for an example of placing axes manually.
10.1.7 Automatically make room for tick labels
Note: This is now easier to handle than ever before. Calling tight_layout() can fix many common
layout issues. See the Tight Layout guide.
498
Chapter 10. How-To
Matplotlib, Release 2.1.2
The information below is kept here in case it is useful for other purposes.
In most use cases, it is enough to simply change the subplots adjust parameters as described in Move the
edge of an axes to make room for tick labels. But in some cases, you don’t know ahead of time what your
tick labels will be, or how large they will be (data and labels outside your control may be being fed into your
graphing application), and you may need to automatically adjust your subplot parameters based on the size
of the tick labels. Any Text instance can report its extent in window coordinates (a negative x coordinate is
outside the window), but there is a rub.
The RendererBase instance, which is used to calculate the text size, is not known until the figure is
drawn (draw()). After the window is drawn and the text instance knows its renderer, you can call
get_window_extent(). One way to solve this chicken and egg problem is to wait until the figure is
draw by connecting (mpl_connect()) to the “on_draw” signal (DrawEvent) and get the window extent
there, and then do something with it, e.g., move the left of the canvas over; see Event handling and picking.
Here is an example that gets a bounding box in relative figure coordinates (0..1) of each of the labels and
uses it to move the left of the subplots over so that the tick labels fit in the figure:
Fig. 10.1: Auto Subplots Adjust
10.1.8 Configure the tick widths
Wherever possible, it is recommended to use the tick_params() or set_tick_params() methods to
modify tick properties:
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot(range(10))
ax.tick_params(width=10)
plt.show()
10.1. Plotting: howto
499
Matplotlib, Release 2.1.2
For more control of tick properties that are not provided by the above methods, it is important to know that
in Matplotlib, the ticks are markers. All Line2D objects support a line (solid, dashed, etc) and a marker
(circle, square, tick). The tick width is controlled by the "markeredgewidth" property, so the above effect
can also be achieved by:
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot(range(10))
for line in ax.get_xticklines() + ax.get_yticklines():
line.set_markeredgewidth(10)
plt.show()
The other properties that control the tick marker, and all markers, are markerfacecolor,
markeredgecolor, markeredgewidth, markersize. For more information on configuring ticks, see
Axis containers and Tick containers.
10.1.9 Align my ylabels across multiple subplots
If you have multiple subplots over one another, and the y data have different scales, you can often get ylabels
that do not align vertically across the multiple subplots, which can be unattractive. By default, Matplotlib
positions the x location of the ylabel so that it does not overlap any of the y ticks. You can override this
default behavior by specifying the coordinates of the label. The example below shows the default behavior
in the left subplots, and the manual setting in the right subplots.
Fig. 10.2: Align Ylabels
10.1.10 Skip dates where there is no data
When plotting time series, e.g., financial time series, one often wants to leave out days on which there is
no data, e.g., weekends. By passing in dates on the x-xaxis, you get large horizontal gaps on periods when
there is not data. The solution is to pass in some proxy x-data, e.g., evenly sampled indices, and then use
500
Chapter 10. How-To
Matplotlib, Release 2.1.2
a custom formatter to format these as dates. The example below shows how to use an ‘index formatter’ to
achieve the desired plot:
import
import
import
import
numpy as np
matplotlib.pyplot as plt
matplotlib.mlab as mlab
matplotlib.ticker as ticker
r = mlab.csv2rec('../data/aapl.csv')
r.sort()
r = r[-30:] # get the last 30 days
N = len(r)
ind = np.arange(N)
# the evenly spaced plot indices
def format_date(x, pos=None):
thisind = np.clip(int(x+0.5), 0, N-1)
return r.date[thisind].strftime('%Y-%m-%d')
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot(ind, r.adj_close, 'o-')
ax.xaxis.set_major_formatter(ticker.FuncFormatter(format_date))
fig.autofmt_xdate()
plt.show()
10.1.11 Control the depth of plot elements
Within an axes, the order that the various lines, markers, text, collections, etc appear is determined by the
set_zorder() property. The default order is patches, lines, text, with collections of lines and collections
of patches appearing at the same level as regular lines and patches, respectively:
line, = ax.plot(x, y, zorder=10)
You can also use the Axes property set_axisbelow() to control whether the grid lines are placed above
or below your other plot elements.
10.1.12 Make the aspect ratio for plots equal
The Axes property set_aspect() controls the aspect ratio of the axes. You can set it to be ‘auto’, ‘equal’,
or some ratio which controls the ratio:
ax = fig.add_subplot(111, aspect='equal')
10.1.13 Multiple y-axis scales
A frequent request is to have two scales for the left and right y-axis, which is possible using twinx() (more
than two scales are not currently supported, though it is on the wish list). This works pretty well, though
10.1. Plotting: howto
501
Matplotlib, Release 2.1.2
there are some quirks when you are trying to interactively pan and zoom, because both scales do not get the
signals.
The approach uses twinx() (and its sister twiny()) to use 2 different axes, turning the axes rectangular
frame off on the 2nd axes to keep it from obscuring the first, and manually setting the tick locs and labels
as desired. You can use separate matplotlib.ticker formatters and locators as desired because the two
axes are independent.
1.00
20000
0.75
0.50
0.25
0.00
10000
sin
exp
15000
0.25
0.50
5000
0.75
1.00
0
0
2
4
time (s)
6
8
10
10.1.14 Generate images without having a window appear
The easiest way to do this is use a non-interactive backend (see What is a backend?) such as Agg (for
PNGs), PDF, SVG or PS. In your figure-generating script, just call the matplotlib.use() directive before
importing pylab or pyplot:
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
plt.plot([1,2,3])
plt.savefig('myfig')
See also:
Matplotlib in a web application server for information about running matplotlib inside of a web application.
502
Chapter 10. How-To
Matplotlib, Release 2.1.2
10.1.15 Use show()
When you want to view your plots on your display, the user interface backend will need to start the GUI
mainloop. This is what show() does. It tells Matplotlib to raise all of the figure windows created so far
and start the mainloop. Because this mainloop is blocking by default (i.e., script execution is paused), you
should only call this once per script, at the end. Script execution is resumed after the last window is closed.
Therefore, if you are using Matplotlib to generate only images and do not want a user interface window, you
do not need to call show (see Generate images without having a window appear and What is a backend?).
Note: Because closing a figure window invokes the destruction of its plotting elements, you should call
savefig() before calling show if you wish to save the figure as well as view it.
New in version v1.0.0: show now starts the GUI mainloop only if it isn’t already running. Therefore,
multiple calls to show are now allowed.
Having show block further execution of the script or the python interpreter depends on whether Matplotlib
is set for interactive mode or not. In non-interactive mode (the default setting), execution is paused until the
last figure window is closed. In interactive mode, the execution is not paused, which allows you to create
additional figures (but the script won’t finish until the last figure window is closed).
Note: Support for interactive/non-interactive mode depends upon the backend. Until version 1.0.0 (and
subsequent fixes for 1.0.1), the behavior of the interactive mode was not consistent across backends. As of
v1.0.1, only the macosx backend differs from other backends because it does not support non-interactive
mode.
Because it is expensive to draw, you typically will not want Matplotlib to redraw a figure many times in a
script such as the following:
plot([1,2,3])
xlabel('time')
ylabel('volts')
title('a simple plot')
show()
#
#
#
#
draw here ?
and here ?
and here ?
and here ?
However, it is possible to force Matplotlib to draw after every command, which might be what you want
when working interactively at the python console (see Using matplotlib in a python shell), but in a script
you want to defer all drawing until the call to show. This is especially important for complex figures that
take some time to draw. show() is designed to tell Matplotlib that you’re all done issuing commands and
you want to draw the figure now.
Note: show() should typically only be called at most once per script and it should be the last line of your
script. At that point, the GUI takes control of the interpreter. If you want to force a figure draw, use draw()
instead.
Many users are frustrated by show because they want it to be a blocking call that raises the figure, pauses the
script until they close the figure, and then allow the script to continue running until the next figure is created
10.1. Plotting: howto
503
Matplotlib, Release 2.1.2
and the next show is made. Something like this:
# WARNING : illustrating how NOT to use show
for i in range(10):
# make figure i
show()
This is not what show does and unfortunately, because doing blocking calls across user interfaces can be
tricky, is currently unsupported, though we have made significant progress towards supporting blocking
events.
New in version v1.0.0: As noted earlier, this restriction has been relaxed to allow multiple calls to show. In
most backends, you can now expect to be able to create new figures and raise them in a subsequent call to
show after closing the figures from a previous call to show.
10.1.16 Interpreting box plots and violin plots
Tukey’s box plots (Robert McGill, John W. Tukey and Wayne A. Larsen: “The American Statistician”
Vol. 32, No. 1, Feb., 1978, pp. 12-16) are statistical plots that provide useful information about the data
distribution such as skewness. However, bar plots with error bars are still the common standard in most
scientific literature, and thus, the interpretation of box plots can be challenging for the unfamiliar reader.
The figure below illustrates the different visual features of a box plot.
Violin plots are closely related to box plots but add useful information such as the distribution of the sample
data (density trace). Violin plots were added in Matplotlib 1.4.
504
Chapter 10. How-To
Matplotlib, Release 2.1.2
10.2 Contributing: howto
10.2.1 Request a new feature
Is there a feature you wish Matplotlib had? Then ask! The best way to get started is to email the developer
mailing list for discussion. This is an open source project developed primarily in the contributors free time,
so there is no guarantee that your feature will be added. The best way to get the feature you need added is
to contribute it your self.
10.2.2 Reporting a bug or submitting a patch
The development of Matplotlib is organized through github. If you would like to report a bug or submit a
patch please use that interface.
To report a bug create an issue on github (this requires having a github account). Please include a Short,
Self Contained, Correct (Compilable), Example demonstrating what the bug is. Including a clear, easy to
test example makes it easy for the developers to evaluate the bug. Expect that the bug reports will be a
conversation. If you do not want to register with github, please email bug reports to the mailing list.
The easiest way to submit patches to Matplotlib is through pull requests on github. Please see the The
Matplotlib Developers’ Guide for the details.
10.2.3 Contribute to Matplotlib documentation
Matplotlib is a big library, which is used in many ways, and the documentation has only scratched the surface
of everything it can do. So far, the place most people have learned all these features are through studying
the examples (Search examples), which is a recommended and great way to learn, but it would be nice to
have more official narrative documentation guiding people through all the dark corners. This is where you
come in.
There is a good chance you know more about Matplotlib usage in some areas, the stuff you do every day,
than many of the core developers who wrote most of the documentation. Just pulled your hair out compiling
Matplotlib for windows? Write a FAQ or a section for the Installation page. Are you a digital signal
processing wizard? Write a tutorial on the signal analysis plotting functions like xcorr(), psd() and
specgram(). Do you use Matplotlib with django or other popular web application servers? Write a FAQ or
tutorial and we’ll find a place for it in the User’s Guide. Bundle Matplotlib in a py2exe app? . . . I think you
get the idea.
Matplotlib is documented using the sphinx extensions to restructured text (ReST). sphinx is an extensible
python framework for documentation projects which generates HTML and PDF, and is pretty easy to write;
you can see the source for this document or any page on this site by clicking on the Show Source link at the
end of the page in the sidebar.
The sphinx website is a good resource for learning sphinx, but we have put together a cheat-sheet at Writing
documentation which shows you how to get started, and outlines the Matplotlib conventions and extensions,
e.g., for including plots directly from external code in your documents.
10.2. Contributing: howto
505
Matplotlib, Release 2.1.2
Once your documentation contributions are working (and hopefully tested by actually building the docs) you
can submit them as a patch against git. See Install git and Reporting a bug or submitting a patch. Looking
for something to do? Search for TODO or look at the open issues on github.
10.3 Matplotlib in a web application server
Many users report initial problems trying to use maptlotlib in web application servers, because by default
Matplotlib ships configured to work with a graphical user interface which may require an X11 connection.
Since many barebones application servers do not have X11 enabled, you may get errors if you don’t configure Matplotlib for use in these environments. Most importantly, you need to decide what kinds of images
you want to generate (PNG, PDF, SVG) and configure the appropriate default backend. For 99% of users,
this will be the Agg backend, which uses the C++ antigrain rendering engine to make nice PNGs. The Agg
backend is also configured to recognize requests to generate other output formats (PDF, PS, EPS, SVG).
The easiest way to configure Matplotlib to use Agg is to call:
# do this before importing pylab or pyplot
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
For more on configuring your backend, see What is a backend?.
Alternatively, you can avoid pylab/pyplot altogether, which will give you a little more control, by calling the
API directly as shown in sphx_glr_gallery_api_agg_oo_sgskip.py.
You can either generate hardcopy on the filesystem by calling savefig:
# do this before importing pylab or pyplot
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(111)
ax.plot([1,2,3])
fig.savefig('test.png')
or by saving to a file handle:
import sys
fig.savefig(sys.stdout)
Here is an example using Pillow. First, the figure is saved to a BytesIO object which is then fed to Pillow
for further processing:
from io import BytesIO
from PIL import Image
imgdata = BytesIO()
fig.savefig(imgdata, format='png')
imgdata.seek(0) # rewind the data
im = Image.open(imgdata)
506
Chapter 10. How-To
Matplotlib, Release 2.1.2
10.3.1 Matplotlib with apache
TODO; see Contribute to Matplotlib documentation.
10.3.2 Matplotlib with django
TODO; see Contribute to Matplotlib documentation.
10.3.3 Matplotlib with zope
TODO; see Contribute to Matplotlib documentation.
10.3.4 Clickable images for HTML
Andrew Dalke of Dalke Scientific has written a nice article on how to make html click maps with Matplotlib
agg PNGs. We would also like to add this functionality to SVG. If you are interested in contributing to these
efforts that would be great.
10.4 Search examples
The nearly 300 code examples-index included with the Matplotlib source distribution are full-text searchable
from the search page, but sometimes when you search, you get a lot of results from the The Matplotlib API
or other documentation that you may not be interested in if you just want to find a complete, free-standing,
working piece of example code. To facilitate example searches, we have tagged every code example page
with the keyword codex for code example which shouldn’t appear anywhere else on this site except in the
FAQ. So if you want to search for an example that uses an ellipse, search for codex ellipse.
10.5 Cite Matplotlib
If you want to refer to Matplotlib in a publication, you can use “Matplotlib: A 2D Graphics Environment”
by J. D. Hunter In Computing in Science & Engineering, Vol. 9, No. 3. (2007), pp. 90-95 (see this reference
page):
@article{Hunter:2007,
Address = {10662 LOS VAQUEROS CIRCLE, PO BOX 3014, LOS ALAMITOS, CA 90720-1314␣
,→USA},
Author = {Hunter, John D.},
Date-Added = {2010-09-23 12:22:10 -0700},
Date-Modified = {2010-09-23 12:22:10 -0700},
Isi = {000245668100019},
Isi-Recid = {155389429},
Journal = {Computing In Science \& Engineering},
Month = {May-Jun},
Number = {3},
10.4. Search examples
507
Matplotlib, Release 2.1.2
Pages = {90--95},
Publisher = {IEEE COMPUTER SOC},
Times-Cited = {21},
Title = {Matplotlib: A 2D graphics environment},
Type = {Editorial Material},
Volume = {9},
Year = {2007},
Abstract = {Matplotlib is a 2D graphics package used for Python for application
development, interactive scripting, and publication-quality image
generation across user interfaces and operating systems.},
Bdsk-Url-1 = {http://gateway.isiknowledge.com/gateway/Gateway.cgi?GWVersion=2&
,→SrcAuth=Alerting&SrcApp=Alerting&DestApp=WOS&DestLinkType=FullRecord;
,→KeyUT=000245668100019}}
508
Chapter 10. How-To
CHAPTER
ELEVEN
TROUBLESHOOTING
Contents
• Troubleshooting
– Obtaining matplotlib version
– matplotlib install location
– matplotlib configuration and cache directory locations
– Getting help
– Problems with recent git versions
11.1 Obtaining matplotlib version
To find out your matplotlib version number, import it and print the __version__ attribute:
>>> import matplotlib
>>> matplotlib.__version__
'0.98.0'
11.2 matplotlib install location
You can find what directory matplotlib is installed in by importing it and printing the __file__ attribute:
>>> import matplotlib
>>> matplotlib.__file__
'/home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/__init__.pyc'
509
Matplotlib, Release 2.1.2
11.3 matplotlib configuration and cache directory locations
Each user has a matplotlib configuration directory which may contain a matplotlibrc file. To locate your
matplotlib/ configuration directory, use matplotlib.get_configdir():
>>> import matplotlib as mpl
>>> mpl.get_configdir()
'/home/darren/.config/matplotlib'
On unix-like systems, this directory is generally located in your HOME directory under the .config/ directory.
In addition, users have a cache directory. On unix-like systems, this is separate from the configuration
directory by default. To locate your .cache/ directory, use matplotlib.get_cachedir():
>>> import matplotlib as mpl
>>> mpl.get_cachedir()
'/home/darren/.cache/matplotlib'
On windows, both the config directory and the cache directory are the same and are in your Documents
and Settings or Users directory by default:
>>> import matplotlib as mpl
>>> mpl.get_configdir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
>>> mpl.get_cachedir()
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
If you would like to use a different configuration directory, you can do so by specifying the location in your
MPLCONFIGDIR environment variable – see Setting environment variables in Linux and OS-X. Note that
MPLCONFIGDIR sets the location of both the configuration directory and the cache directory.
11.4 Getting help
There are a number of good resources for getting help with matplotlib. There is a good chance your question
has already been asked:
• The mailing list archive.
• Github issues.
• Stackoverflow questions tagged matplotlib.
If you are unable to find an answer to your question through search, please provide the following information
in your e-mail to the mailing list:
• Your operating system (Linux/UNIX users: post the output of uname -a).
• Matplotlib version:
510
Chapter 11. Troubleshooting
Matplotlib, Release 2.1.2
python -c "import matplotlib; print matplotlib.__version__"
• Where you obtained Matplotlib (e.g., your Linux distribution’s packages, Github, PyPi, or Anaconda
or Enthought Canopy).
• Any customizations to your matplotlibrc file (see Customizing matplotlib).
• If the problem is reproducible, please try to provide a minimal, standalone Python script that demonstrates the problem. This is the critical step. If you can’t post a piece of code that we can run and
reproduce your error, the chances of getting help are significantly diminished. Very often, the mere
act of trying to minimize your code to the smallest bit that produces the error will help you find a bug
in your code that is causing the problem.
• You can get very helpful debugging output from matlotlib by running your script with a
verbose-helpful or --verbose-debug flags and posting the verbose output the lists:
python simple_plot.py --verbose-helpful > output.txt
If you compiled Matplotlib yourself, please also provide:
• any changes you have made to setup.py or setupext.py.
• the output of:
rm -rf build
python setup.py build
The beginning of the build output contains lots of details about your platform that are useful for the
Matplotlib developers to diagnose your problem.
• your compiler version – e.g., gcc --version.
Including this information in your first e-mail to the mailing list will save a lot of time.
You will likely get a faster response writing to the mailing list than filing a bug in the bug tracker. Most
developers check the bug tracker only periodically. If your problem has been determined to be a bug and
can not be quickly solved, you may be asked to file a bug in the tracker so the issue doesn’t get lost.
11.5 Problems with recent git versions
First make sure you have a clean build and install (see How to completely remove Matplotlib), get the latest
git update, install it and run a simple test script in debug mode:
rm -rf /path/to/site-packages/matplotlib*
git clean -xdf
git pull
python -mpip install -v . > build.out
python examples/pylab_examples/simple_plot.py --verbose-debug > run.out
and post build.out and run.out to the matplotlib-devel mailing list (please do not post git problems to
the users list).
11.5. Problems with recent git versions
511
Matplotlib, Release 2.1.2
Of course, you will want to clearly describe your problem, what you are expecting and what you are getting,
but often a clean build and install will help. See also Getting help.
512
Chapter 11. Troubleshooting
CHAPTER
TWELVE
ENVIRONMENT VARIABLES
Contents
• Environment Variables
– Setting environment variables in Linux and OS-X
* BASH/KSH
* CSH/TCSH
– Setting environment variables in windows
HOME
The user’s home directory. On linux, ~ is shorthand for HOME.
PATH
The list of directories searched to find executable programs
PYTHONPATH
The list of directories that is added to Python’s standard search list when importing packages and
modules
MPLCONFIGDIR
This is the directory used to store user customizations to matplotlib, as well as some caches to improve performance. If MPLCONFIGDIR is not defined, HOME/.config/matplotlib is generally
used on unix-like systems and HOME/.matplotlib is used on other platforms, if they are writable.
Otherwise, the python standard library tempfile.gettempdir() is used to find a base directory in
which the matplotlib subdirectory is created.
MPLBACKEND
This optional variable can be set to choose the matplotlib backend. See What is a backend?.
12.1 Setting environment variables in Linux and OS-X
To list the current value of PYTHONPATH, which may be empty, try:
513
Matplotlib, Release 2.1.2
echo $PYTHONPATH
The procedure for setting environment variables in depends on what your default shell is. BASH seems to
be the most common, but CSH is also common. You should be able to determine which by running at the
command prompt:
echo $SHELL
12.1.1 BASH/KSH
To create a new environment variable:
export PYTHONPATH=~/Python
To prepend to an existing environment variable:
export PATH=~/bin:${PATH}
The search order may be important to you, do you want ~/bin to be searched first or last? To append to an
existing environment variable:
export PATH=${PATH}:~/bin
To make your changes available in the future, add the commands to your ~/.bashrc file.
12.1.2 CSH/TCSH
To create a new environment variable:
setenv PYTHONPATH ~/Python
To prepend to an existing environment variable:
setenv PATH ~/bin:${PATH}
The search order may be important to you, do you want ~/bin to be searched first or last? To append to an
existing environment variable:
setenv PATH ${PATH}:~/bin
To make your changes available in the future, add the commands to your ~/.cshrc file.
12.2 Setting environment variables in windows
Open the Control Panel (Start → Control Panel), start the System program. Click the Advanced tab and
select the Environment Variables button. You can edit or add to the User Variables.
514
Chapter 12. Environment Variables
CHAPTER
THIRTEEN
WORKING WITH MATPLOTLIB IN VIRTUAL ENVIRONMENTS
When running Matplotlib in a virtual environment you may discover a few issues. Matplotlib itself has
no issue with virtual environments. However, some of the external GUI frameworks that Matplotlib uses
for interactive figures may be tricky to install in a virtual environment. Everything below assumes some
familiarity with the Matplotlib backends as found in What is a backend?.
If you only use the IPython and Jupyter Notebook’s inline and notebook backends, or non-interactive
backends, you should not have any issues and can ignore everything below.
Likewise, the Tk framework (TkAgg backend) does not require any external dependencies and is normally
always available. On certain Linux distributions, a package named python-tk (or similar) needs to be
installed.
Otherwise, the situation (at the time of writing) is as follows:
GUI framework
pip-installable?
conda or conda-forge-installable?
PyQt5
PyQt4
PyGObject
PyGTK
wxPython
on Python>=3.5
PySide: on Windows and OSX
no
no
yes1
yes
yes
on Linux
no
yes
In other cases, you need to install the package in the global (system) site-packages, and somehow make it
available from within the virtual environment. This can be achieved by any of the following methods (in all
cases, the system-wide Python and the virtualenv Python must be of the same version):
• Using virtualenv’s --system-site-packages option when creating an environment adds all
system-wide packages to the virtual environment. However, this breaks the isolation between the
virtual environment and the system install. Among other issues it results in hard to debug problems
with system packages shadowing the environment packages. If you use virtualenvwrapper, this can
be toggled with the toggleglobalsitepackages command.
• vext allows controlled access from within the virtualenv to specific system-wide packages without the
overall shadowing issue. A specific package needs to be installed for each framework, e.g. vext.pyqt5,
etc.
1
OSX and Windows wheels available on PyPI. Linux wheels available but not on PyPI, see https://wxpython.org/pages/
downloads/.
515
Matplotlib, Release 2.1.2
• The GUI frameworks can be manually symlinked into the environment, e.g. for PyQt5, you should
symlink PyQt5 and sip from the system site-packages into the virtualenv site-packages.
If you are using Matplotlib on OSX, you may also want to consider the OSX framework FAQ.
516
Chapter 13. Working with Matplotlib in Virtual environments
CHAPTER
FOURTEEN
WORKING WITH MATPLOTLIB ON OSX
Contents
• Working with Matplotlib on OSX
– Introduction
– Short version
* VirtualEnv
* Pyenv
* Conda
– Long version
* PYTHONHOME Function
· PYTHONHOME and Jupyter
· PYTHONHOME Script
* PythonW Compiler
14.1 Introduction
On OSX, two different types of Python builds exist: a regular build and a framework build. In order to
interact correctly with OSX through the native GUI frameworks you need a framework build of Python. At
the time of writing the macosx and WXAgg backends require a framework build to function correctly. This
can result in issues for a Python installation not build as a framework and may also happen in virtual envs
and when using (Ana)Conda. From Matplotlib 1.5 onwards, both backends check that a framework build is
available and fail if a non framework build is found.
Without this check a partially functional figure is created. Among the issues with it is that it is produced in
the background and cannot be put in front of any other window. Several solutions and work arounds exist
see below.
517
Matplotlib, Release 2.1.2
14.2 Short version
14.2.1 VirtualEnv
If you are on Python 3, use venv instead of virtualenv:
python -m venv my-virtualenv
source my-virtualenv/bin/activate
Otherwise you will need one of the workarounds below.
14.2.2 Pyenv
If you are using pyenv and virtualenv you can enable your python version to be installed as a framework:
PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install x.x.x
14.2.3 Conda
The default python provided in (Ana)Conda is not a framework build. However, the Conda developers have
made it easy to install a framework build in both the main environment and in Conda envs. To use this install
python.app conda install python.app and use pythonw rather than python
14.3 Long version
Unfortunately virtualenv creates a non framework build even if created from a framework build of Python.
As documented above you can use venv as an alternative on Python 3.
The issue has been reported on the virtualenv bug tracker here and here
Until this is fixed, one of the following workarounds can be used:
14.3.1 PYTHONHOME Function
The best known work around is to use the non virtualenv python along with the PYTHONHOME environment variable. This can be done by defining a function in your .bashrc using
function frameworkpython {
if [[ ! -z "$VIRTUAL_ENV" ]]; then
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
else
/usr/local/bin/python "$@"
fi
}
518
Chapter 14. Working with Matplotlib on OSX
Matplotlib, Release 2.1.2
This function can then be used in all of your virtualenvs without having to fix every single one of them.
With this in place you can run frameworkpython to get an interactive framework build within the virtualenv. To run a script you can do frameworkpython test.py where test.py is a script that requires
a framework build. To run an interactive IPython session with the framework build within the virtual
environment you can do frameworkpython -m IPython
PYTHONHOME and Jupyter
This approach can be followed even if using Jupyter notebooks: you just need to setup a kernel with the
suitable PYTHONHOME definition. The jupyter-virtualenv-osx script automates the creation of such a kernel.
PYTHONHOME Script
An alternative work around borrowed from the WX wiki, is to use the non virtualenv python along with
the PYTHONHOME environment variable. This can be implemented in a script as below. To use this
modify PYVER and PATHTOPYTHON and put the script in the virtualenv bin directory i.e. PATHTOVENV/bin/
frameworkpython
#!/bin/bash
# what real Python executable to use
PYVER=2.7
PATHTOPYTHON=/usr/local/bin/
PYTHON=${PATHTOPYTHON}python${PYVER}
# find the root of the virtualenv, it should be the parent of the dir this script is in
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"),
,→'..')))"`
# now run Python with the virtualenv set as Python's HOME
export PYTHONHOME=$ENV
exec $PYTHON "$@"
With this in place you can run frameworkpython as above but will need to add this script to every virtualenv
14.3.2 PythonW Compiler
In addition virtualenv-pythonw-osx provides an alternative workaround which may be used to solve the
issue.
14.3. Long version
519
Matplotlib, Release 2.1.2
520
Chapter 14. Working with Matplotlib on OSX
Part III
Toolkits
521
Matplotlib, Release 2.1.2
Toolkits are collections of application-specific functions that extend Matplotlib.
523
Matplotlib, Release 2.1.2
524
CHAPTER
FIFTEEN
MPLOT3D
mpl_toolkits.mplot3d provides some basic 3D plotting (scatter, surf, line, mesh) tools. Not the fastest
or most feature complete 3D library out there, but it ships with Matplotlib and thus may be a lighter weight
solution for some use cases. Check out the mplot3d tutorial for more information.
Fig. 15.1: Contourf3d 2
15.1 mplot3d
15.1.1 Matplotlib mplot3d toolkit
The mplot3d toolkit adds simple 3D plotting capabilities to matplotlib by supplying an axes object that can
create a 2D projection of a 3D scene. The resulting graph will have the same look and feel as regular 2D
plots.
See the mplot3d tutorial for more information on how to use this toolkit.
525
Matplotlib, Release 2.1.2
The interactive backends also provide the ability to rotate and zoom the 3D scene. One can rotate the 3D
scene by simply clicking-and-dragging the scene. Zooming is done by right-clicking the scene and dragging
the mouse up and down. Note that one does not use the zoom button like one would use for regular 2D plots.
mplot3d FAQ
How is mplot3d different from MayaVi?
MayaVi2 is a very powerful and featureful 3D graphing library. For advanced 3D scenes and excellent
rendering capabilities, it is highly recomended to use MayaVi2.
mplot3d was intended to allow users to create simple 3D graphs with the same “look-and-feel” as matplotlib’s 2D plots. Furthermore, users can use the same toolkit that they are already familiar with to generate
both their 2D and 3D plots.
My 3D plot doesn’t look right at certain viewing angles
This is probably the most commonly reported issue with mplot3d. The problem is that – from some viewing
angles – a 3D object would appear in front of another object, even though it is physically behind it. This can
result in plots that do not look “physically correct.”
526
Chapter 15. mplot3d
Matplotlib, Release 2.1.2
Unfortunately, while some work is being done to reduce the occurance of this artifact, it is currently an
intractable problem, and can not be fully solved until matplotlib supports 3D graphics rendering at its core.
The problem occurs due to the reduction of 3D data down to 2D + z-order scalar. A single value represents
the 3rd dimension for all parts of 3D objects in a collection. Therefore, when the bounding boxes of two
collections intersect, it becomes possible for this artifact to occur. Furthermore, the intersection of two 3D
objects (such as polygons or patches) can not be rendered properly in matplotlib’s 2D rendering engine.
This problem will likely not be solved until OpenGL support is added to all of the backends (patches are
greatly welcomed). Until then, if you need complex 3D scenes, we recommend using MayaVi.
I don’t like how the 3D plot is laid out, how do I change that?
Historically, mplot3d has suffered from a hard-coding of parameters used to control visuals such as label
spacing, tick length, and grid line width. Work is being done to eliminate this issue. For matplotlib v1.1.0,
there is a semi-official manner to modify these parameters. See the note in the axis3d section of the mplot3d
API documentation for more information.
15.2 Links
• mpl3d API: mplot3d API
15.2. Links
527
Matplotlib, Release 2.1.2
528
Chapter 15. mplot3d
CHAPTER
SIXTEEN
AXES_GRID1
The mpl_toolkits.axes_grid1 toolkit is a collection of helper classes for displaying multiple axes in
Matplotlib.
16.1 Matplotlib axes_grid1 Toolkit
The matplotlib mpl_toolkits.axes_grid1 toolkit is a collection of helper classes to ease displaying
multiple images in matplotlib. While the aspect parameter in matplotlib adjust the position of the single axes,
axesgrid1 toolkit provides a framework to adjust the position of multiple axes according to their aspects.
See What is axes_grid1 toolkit? for a guide on the usage of axes_grid1.
529
Matplotlib, Release 2.1.2
Note: AxesGrid toolkit has been a part of matplotlib since v 0.99. Originally, the toolkit had a single namespace of axes_grid. In more recent version, the toolkit has divided into two separate namespace (axes_grid1
and axisartist). While axes_grid namespace is maintained for the backward compatibility, use of axes_grid1
and axisartist is recommended.
530
Chapter 16. axes_grid1
CHAPTER
SEVENTEEN
AXISARTIST
The mpl_toolkits.axisartist toolkit contains a custom Axes class that is meant to support curvilinear
grids.
17.1 Matplotlib axisartist Toolkit
The axisartist namespace includes a derived Axes implementation ( mpl_toolkits.axisartist.Axes).
The biggest difference is that the artists that are responsible for drawing axis lines, ticks, ticklabels, and
axis labels are separated out from the mpl’s Axis class. This change was strongly motivated to support
curvilinear grid.
You can find a tutorial describing usage of axisartist at axisartist.
17.2 API
• Axes Grid and Axis Artist API: The Matplotlib axes_grid Toolkit API
531
Matplotlib, Release 2.1.2
532
Chapter 17. axisartist
Part IV
External Resources
533
CHAPTER
EIGHTEEN
BOOKS, CHAPTERS AND ARTICLES
• Mastering matplotlib by Duncan M. McGreggor
• Interactive Applications Using Matplotlib by Benjamin Root
• Matplotlib for Python Developers by Sandro Tosi
• Matplotlib chapter by John Hunter and Michael Droettboom in The Architecture of Open Source
Applications
• Graphics with Matplotlib by David J. Raymond
• Ten Simple Rules for Better Figures by Nicolas P. Rougier, Michael Droettboom and Philip E. Bourne
• Learning Scientific Programming with Python chapter 7 by Christian Hill
535
Matplotlib, Release 2.1.2
536
Chapter 18. Books, Chapters and Articles
CHAPTER
NINETEEN
VIDEOS
• Plotting with matplotlib by Mike Müller
• Introduction to NumPy and Matplotlib by Eric Jones
• Anatomy of Matplotlib by Benjamin Root
• Data Visualization Basics with Python (O’Reilly) by Randal S. Olson
537
Matplotlib, Release 2.1.2
538
Chapter 19. Videos
CHAPTER
TWENTY
TUTORIALS
• Matplotlib tutorial by Nicolas P. Rougier
• Anatomy of Matplotlib - IPython Notebooks by Benjamin Root
539
Matplotlib, Release 2.1.2
540
Chapter 20. Tutorials
Part V
Third party packages
541
Matplotlib, Release 2.1.2
Several external packages that extend or build on Matplotlib functionality are listed below. They are maintained and distributed separately from Matplotlib and thus need to be installed individually.
Please submit an issue or pull request on Github if you have created a package that you would like to have
included. We are also happy to host third party packages within the Matplotlib Github Organization.
543
Matplotlib, Release 2.1.2
544
CHAPTER
TWENTYONE
MAPPING TOOLKITS
21.1 Basemap
Basemap plots data on map projections, with continental and political boundaries.
21.2 Cartopy
Cartopy builds on top of Matplotlib to provide object oriented map projection definitions and close integration with Shapely for powerful yet easy-to-use vector data processing tools. An example plot from the
Cartopy gallery:
545
Matplotlib, Release 2.1.2
546
Chapter 21. Mapping toolkits
CHAPTER
TWENTYTWO
DECLARATIVE LIBRARIES
22.1 plotnine
plotnine implements a grammar of graphics, similar to R’s ggplot2. The grammar allows users to compose
plots by explicitly mapping data to the visual objects that make up the plot.
22.2 ggplot
ggplot is a port of the R ggplot2 package to python based on Matplotlib.
547
Matplotlib, Release 2.1.2
22.3 holoviews
holoviews makes it easier to visualize data interactively, especially in a Jupyter notebook, by providing a set
of declarative plotting objects that store your data and associated metadata. Your data is then immediately
visualizable alongside or overlaid with other data, either statically or with automatically provided widgets
for parameter exploration.
548
Chapter 22. Declarative libraries
CHAPTER
TWENTYTHREE
SPECIALTY PLOTS
23.1 DeCiDa
DeCiDa is a library of functions and classes for electron device characterization, electronic circuit design
and general data visualization and analysis.
23.2 Matplotlib-Venn
Matplotlib-Venn provides a set of functions for plotting 2- and 3-set area-weighted (or unweighted) Venn
diagrams.
23.3 mpl-probscale
mpl-probscale is a small extension that allows Matplotlib users to specify probabilty scales. Simply importing the probscale module registers the scale with Matplotlib, making it accessible via e.g., ax.
set_xscale('prob') or plt.yscale('prob').
549
Matplotlib, Release 2.1.2
23.4 mpl-scatter-density
mpl-scatter-density is a small package that makes it easy to make scatter plots of large numbers of points
using a density map. The following example contains around 13 million points and the plotting (excluding
reading in the data) took less than a second on an average laptop:
550
Chapter 23. Specialty plots
Matplotlib, Release 2.1.2
When used in interactive mode, the density map is downsampled on-the-fly while panning/zooming in order
to provide a smooth interactive experience.
23.5 mplstereonet
mplstereonet provides stereonets for plotting and analyzing orientation data in Matplotlib.
23.6 Natgrid
mpl_toolkits.natgrid is an interface to the natgrid C library for gridding irregularly spaced data.
23.7 pyUpSet
pyUpSet is a static Python implementation of the UpSet suite by Lex et al. to explore complex intersections
of sets and data frames.
23.8 seaborn
seaborn is a high level interface for drawing statistical graphics with Matplotlib. It aims to make visualization
a central part of exploring and understanding complex datasets.
23.5. mplstereonet
551
Matplotlib, Release 2.1.2
23.9 Windrose
Windrose is a Python Matplotlib, Numpy library to manage wind data, draw windroses (also known as polar
rose plots), draw probability density functions and fit Weibull distributions.
552
Chapter 23. Specialty plots
CHAPTER
TWENTYFOUR
INTERACTIVITY
24.1 mplcursors
mplcursors provides interactive data cursors for Matplotlib.
24.2 MplDataCursor
MplDataCursor is a toolkit written by Joe Kington to provide interactive “data cursors” (clickable annotation
boxes) for Matplotlib.
553
Matplotlib, Release 2.1.2
554
Chapter 24. Interactivity
CHAPTER
TWENTYFIVE
MISCELLANEOUS
25.1 mpl-template
mpl-template provides a customizable way to add engineering figure elements such as a title block, border,
and logo.
25.2 adjustText
adjustText is a small library for automatically adjusting text position in Matplotlib plots to minimize overlaps
between them, specified points and other objects.
555
Matplotlib, Release 2.1.2
25.3 iTerm2 terminal backend
matplotlib_iterm2 is an external Matplotlib backend using the iTerm2 nightly build inline image display
feature.
556
Chapter 25. Miscellaneous
Matplotlib, Release 2.1.2
25.3. iTerm2 terminal backend
557
Matplotlib, Release 2.1.2
558
Chapter 25. Miscellaneous
Part VI
The Matplotlib API
559
Matplotlib, Release 2.1.2
Below we describe several common approaches to plotting with Matplotlib.
Contents
• The Pyplot API
• The Object-Oriented API
• Colors in Matplotlib
561
Matplotlib, Release 2.1.2
562
CHAPTER
TWENTYSIX
THE PYPLOT API
The matplotlib.pyplot module contains functions that allow you to generate many kinds of plots
quickly. For examples that showcase the use of the matplotlib.pyplot module, see the Pyplot tutorial
or the pyplots_examples. We also recommend that you look into the object-oriented approach to plotting,
described below.
matplotlib.pyplot.plotting()
Function
Description
acorr
angle_spectrum
annotate
arrow
autoscale
axes
axhline
axhspan
axis
axvline
axvspan
bar
barbs
barh
box
boxplot
broken_barh
cla
clabel
clf
clim
close
cohere
colorbar
contour
Plot the autocorrelation of x.
Plot the angle spectrum.
Annotate the point xy with text s.
Add an arrow to the axes.
Autoscale the axis view to the data (toggle).
Add an axes to the figure.
Add a horizontal line across the axis.
Add a horizontal span (rectangle) across the axis.
Convenience method to get or set axis properties.
Add a vertical line across the axes.
Add a vertical span (rectangle) across the axes.
Make a bar plot.
Plot a 2-D field of barbs.
Make a horizontal bar plot.
Turn the axes box on or off.
Make a box and whisker plot.
Plot horizontal bars.
Clear the current axes.
Label a contour plot.
Clear the current figure.
Set the color limits of the current image.
Close a figure window.
Plot the coherence between x and y.
Add a colorbar to a plot.
Plot contours.
563
Matplotlib, Release 2.1.2
Table 26.1 – continued from previous pa
Function
Description
contourf
csd
delaxes
draw
errorbar
eventplot
figimage
figlegend
fignum_exists
figtext
figure
fill
fill_between
fill_betweenx
findobj
gca
gcf
gci
get_figlabels
get_fignums
grid
hexbin
hist
hist2d
hlines
hold
imread
imsave
imshow
install_repl_displayhook
ioff
ion
ishold
isinteractive
legend
locator_params
loglog
magnitude_spectrum
margins
matshow
minorticks_off
minorticks_on
over
Plot contours.
Plot the cross-spectral density.
Remove an axes from the current figure.
Redraw the current figure.
Plot an errorbar graph.
Plot identical parallel lines at the given positions.
Adds a non-resampled image to the figure.
Place a legend in the figure.
564
Add text to figure.
Creates a new figure.
Plot filled polygons.
Make filled polygons between two curves.
Make filled polygons between two horizontal curves.
Find artist objects.
Get the current Axes instance on the current figure matching the given keyword args,
Get a reference to the current figure.
Get the current colorable artist.
Return a list of existing figure labels.
Return a list of existing figure numbers.
Turn the axes grids on or off.
Make a hexagonal binning plot.
Plot a histogram.
Make a 2D histogram plot.
Plot horizontal lines at each y from xmin to xmax.
Read an image from a file into an array.
Save an array as in image file.
Display an image on the axes.
Install a repl display hook so that any stale figure are automatically redrawn when con
Turn interactive mode off.
Turn interactive mode on.
Return status of interactive mode.
Places a legend on the axes.
Control behavior of tick locators.
Make a plot with log scaling on both the x and y axis.
Plot the magnitude spectrum.
Set or retrieve autoscaling margins.
Display an array as a matrix in a new figure window.
Remove minor ticks from the current plot.
Display minor ticks on the current plot.
Chapter 26. The Pyplot API
Matplotlib, Release 2.1.2
Table 26.1 – continued from previous pa
Function
Description
pause
pcolor
pcolormesh
phase_spectrum
pie
plot
plot_date
plotfile
polar
psd
quiver
quiverkey
rc
rc_context
rcdefaults
rgrids
savefig
sca
scatter
sci
semilogx
semilogy
set_cmap
setp
show
specgram
spy
stackplot
stem
step
streamplot
subplot
subplot2grid
subplot_tool
subplots
subplots_adjust
suptitle
switch_backend
table
text
thetagrids
tick_params
ticklabel_format
Pause for interval seconds.
Create a pseudocolor plot of a 2-D array.
Plot a quadrilateral mesh.
Plot the phase spectrum.
Plot a pie chart.
Plot lines and/or markers to the Axes.
Plot data that contains dates.
Plot the data in a file.
Make a polar plot.
Plot the power spectral density.
Plot a 2-D field of arrows.
Add a key to a quiver plot.
Set the current rc params.
Return a context manager for managing rc settings.
Restore the rc params from Matplotlib’s internal defaults.
Get or set the radial gridlines on a polar plot.
Save the current figure.
Set the current Axes instance to ax.
Make a scatter plot of x vs y.
Set the current image.
Make a plot with log scaling on the x axis.
Make a plot with log scaling on the y axis.
Set the default colormap.
Set a property on an artist object.
Display a figure.
Plot a spectrogram.
Plot the sparsity pattern on a 2-D array.
Draws a stacked area plot.
Create a stem plot.
Make a step plot.
Draws streamlines of a vector flow.
Return a subplot axes at the given grid position.
Create an axis at specific location inside a regular grid.
Launch a subplot tool window for a figure.
Create a figure and a set of subplots This utility wrapper makes it convenient to create
Tune the subplot layout.
Add a centered title to the figure.
Switch the default backend.
Add a table to the current axes.
Add text to the axes.
Get or set the theta locations of the gridlines in a polar plot.
Change the appearance of ticks and tick labels.
Change the ScalarFormatter used by default for linear axes.
565
Matplotlib, Release 2.1.2
Table 26.1 – continued from previous pa
Function
Description
tight_layout
title
tricontour
tricontourf
tripcolor
triplot
twinx
twiny
uninstall_repl_displayhook
violinplot
vlines
xcorr
xkcd
xlabel
xlim
xscale
xticks
ylabel
ylim
yscale
yticks
Automatically adjust subplot parameters to give specified padding.
Set a title of the current axes.
Draw contours on an unstructured triangular grid.
Draw contours on an unstructured triangular grid.
Create a pseudocolor plot of an unstructured triangular grid.
Draw a unstructured triangular grid as lines and/or markers.
Make a second axes that shares the x-axis.
Make a second axes that shares the y-axis.
Uninstalls the matplotlib display hook.
Make a violin plot.
Plot vertical lines.
Plot the cross correlation between x and y.
Turns on xkcd sketch-style drawing mode.
Set the x axis label of the current axis.
Get or set the x limits of the current axes.
Set the scaling of the x-axis.
Get or set the x-limits of the current tick locations and labels.
Set the y axis label of the current axis.
Get or set the y-limits of the current axes.
Set the scaling of the y-axis.
Get or set the y-limits of the current tick locations and labels.
566
Chapter 26. The Pyplot API
CHAPTER
TWENTYSEVEN
THE OBJECT-ORIENTED API
Most of these functions also exist as methods in the matplotlib.axes.Axes class. You can use them with
the “Object Oriented” approach to Matplotlib.
While it is easy to quickly generate plots with the matplotlib.pyplot module, we recommend using
the object-oriented approach for more control and customization of your plots. See the methods in the
matplotlib.axes.Axes() class for many of the same plotting functions. For examples of the OO approach to Matplotlib, see the API Examples.
567
Matplotlib, Release 2.1.2
568
Chapter 27. The Object-Oriented API
CHAPTER
TWENTYEIGHT
COLORS IN MATPLOTLIB
There are many colormaps you can use to map data onto color values. Below we list several ways in which
color can be utilized in Matplotlib.
For a more in-depth look at colormaps, see the Colormaps in Matplotlib tutorial.
matplotlib.pyplot.colormaps()
Matplotlib provides a number of colormaps, and others can be added using register_cmap(). This
function documents the built-in colormaps, and will also return a list of all registered colormaps if
called.
You can set the colormap for an image, pcolor, scatter, etc, using a keyword argument:
imshow(X, cmap=cm.hot)
or using the set_cmap() function:
imshow(X)
pyplot.set_cmap('hot')
pyplot.set_cmap('jet')
In interactive mode, set_cmap() will update the colormap post-hoc, allowing you to see which one
works best for your data.
All built-in colormaps can be reversed by appending _r: For instance, gray_r is the reverse of gray.
There are several common color schemes used in visualization:
Sequential schemes for unipolar data that progresses from low to high
Diverging schemes for bipolar data that emphasizes positive or negative deviations from a central
value
Cyclic schemes meant for plotting values that wrap around at the endpoints, such as phase angle,
wind direction, or time of day
Qualitative schemes for nominal data that has no inherent ordering, where color is used only to
distinguish categories
Matplotlib ships with 4 perceptually uniform color maps which are the recommended color maps for
sequential data:
569
Matplotlib, Release 2.1.2
Colormap
Description
inferno
magma
plasma
viridis
perceptually uniform shades of black-red-yellow
perceptually uniform shades of black-red-white
perceptually uniform shades of blue-red-yellow
perceptually uniform shades of blue-green-yellow
The following colormaps are based on the ColorBrewer color specifications and designs developed by
Cynthia Brewer:
ColorBrewer Diverging (luminance is highest at the midpoint, and decreases towards differentlycolored endpoints):
Colormap
Description
BrBG
PiYG
PRGn
PuOr
RdBu
RdGy
RdYlBu
RdYlGn
Spectral
brown, white, blue-green
pink, white, yellow-green
purple, white, green
orange, white, purple
red, white, blue
red, white, gray
red, yellow, blue
red, yellow, green
red, orange, yellow, green, blue
ColorBrewer Sequential (luminance decreases monotonically):
Colormap
Description
Blues
BuGn
BuPu
GnBu
Greens
Greys
Oranges
OrRd
PuBu
PuBuGn
PuRd
Purples
RdPu
Reds
YlGn
YlGnBu
YlOrBr
YlOrRd
white to dark blue
white, light blue, dark green
white, light blue, dark purple
white, light green, dark blue
white to dark green
white to black (not linear)
white, orange, dark brown
white, orange, dark red
white, light purple, dark blue
white, light purple, dark green
white, light purple, dark red
white to dark purple
white, pink, dark purple
white to dark red
light yellow, dark green
light yellow, light green, dark blue
light yellow, orange, dark brown
light yellow, orange, dark red
ColorBrewer Qualitative:
570
Chapter 28. Colors in Matplotlib
Matplotlib, Release 2.1.2
(For plotting nominal data, ListedColormap is used, not LinearSegmentedColormap. Different
sets of colors are recommended for different numbers of categories.)
• Accent
• Dark2
• Paired
• Pastel1
• Pastel2
• Set1
• Set2
• Set3
A set of colormaps derived from those of the same name provided with Matlab are also included:
Colormap
Description
autumn
bone
sequential linearly-increasing shades of red-orange-yellow
cool
copper
flag
gray
hot
hsv
jet
pink
prism
spring
summer
winter
sequential increasing black-white color map with a tinge of blue, to emulate
X-ray film
linearly-decreasing shades of cyan-magenta
sequential increasing shades of black-copper
repetitive red-white-blue-black pattern (not cyclic at endpoints)
sequential linearly-increasing black-to-white grayscale
sequential black-red-yellow-white, to emulate blackbody radiation from an
object at increasing temperatures
cyclic red-yellow-green-cyan-blue-magenta-red, formed by changing the hue
component in the HSV color space
a spectral map with dark endpoints, blue-cyan-yellow-red; based on a fluid-jet
simulation by NCSA1
sequential increasing pastel black-pink-white, meant for sepia tone colorization of photographs
repetitive red-yellow-green-blue-purple-. . . -green pattern (not cyclic at endpoints)
linearly-increasing shades of magenta-yellow
sequential linearly-increasing shades of green-yellow
linearly-increasing shades of blue-green
A set of palettes from the Yorick scientific visualisation package, an evolution of the GIST package,
both by David H. Munro are included:
1
Rainbow colormaps, jet in particular, are considered a poor choice for scientific visualization by many researchers: Rainbow
Color Map (Still) Considered Harmful
571
Matplotlib, Release 2.1.2
Colormap
Description
gist_earth mapmaker’s colors from dark blue deep ocean to green lowlands to brown
highlands to white mountains
gist_heat sequential increasing black-red-orange-white, to emulate blackbody radiation from an iron bar as it grows hotter
gist_ncar pseudo-spectral black-blue-green-yellow-red-purple-white colormap from
National Center for Atmospheric Research2
gist_rainbow
runs through the colors in spectral order from red to violet at full saturation
(like hsv but not cyclic)
gist_stern “Stern special” color table from Interactive Data Language software
Other miscellaneous schemes:
Col- Description
ormap
afmhotsequential black-orange-yellow-white blackbody spectrum, commonly used in
atomic force microscopy
brg blue-red-green
bwr diverging blue-white-red
cool- diverging blue-gray-red, meant to avoid issues with 3D shading, color blindness,
warm and ordering of colors3
CM- “Default colormaps on color images often reproduce to confusing grayscale imRmap ages. The proposed colormap maintains an aesthetically pleasing color image
that automatically reproduces to a monotonic grayscale with discrete, quantifiable saturation levels.”4
cube- Unlike most other color schemes cubehelix was designed by D.A. Green to be
he- monotonically increasing in terms of perceived brightness. Also, when printed
lix
on a black and white postscript printer, the scheme results in a greyscale with
monotonically increasing brightness. This color scheme is named cubehelix because the r,g,b values produced can be visualised as a squashed helix around the
diagonal in the r,g,b color cube.
gnu- gnuplot’s traditional pm3d scheme (black-blue-red-yellow)
plot
gnu- sequential color printable as gray (black-blue-violet-yellow-white)
plot2
ocean green-blue-white
rain- spectral purple-blue-green-yellow-orange-red colormap with diverging lumibow nance
seis- diverging blue-white-red
mic
nipy_spectral
black-purple-blue-green-yellow-red-white spectrum, originally from the Neuroimaging in Python project
ter- mapmaker’s colors, blue-green-yellow-brown-white, originally from IGOR Pro
rain
2
572
Resembles “BkBlAqGrYeOrReViWh200” from NCAR Command Language. See Color Table Gallery
Chapter 28. Colors in Matplotlib
Matplotlib, Release 2.1.2
The following colormaps are redundant and may be removed in future versions. It’s recommended to
use the names in the descriptions instead, which produce identical output:
Colormap
Description
gist_gray
gist_yarg
binary
spectral
identical to gray
identical to gray_r
identical to gray_r
identical to nipy_spectral5
3
See Diverging Color Maps for Scientific Visualization by Kenneth Moreland.
See A Color Map for Effective Black-and-White Rendering of Color-Scale Images by Carey Rappaport
5
Changed to distinguish from ColorBrewer’s Spectral map. spectral() still works, but set_cmap('nipy_spectral') is
recommended for clarity.
4
573
Matplotlib, Release 2.1.2
574
Chapter 28. Colors in Matplotlib
CHAPTER
TWENTYNINE
API CHANGES
Log of changes to Matplotlib that affect the outward-facing API. If updating Matplotlib breaks your scripts,
this list may help you figure out what caused the breakage and how to fix it by updating your code.
For new features that were added to Matplotlib, please see What’s new in Matplotlib.
29.1 API Changes in 2.1.2
29.1.1 Figure.legend no longer checks for repeated lines to ignore
matplotlib.Figure.legend used to check if a line had the same label as an existing legend entry. If it
also had the same line color or marker color legend didn’t add a new entry for that line. However, the list of
conditions was incomplete, didn’t handle RGB tupples, didn’t handle linewidths or linestyles etc.
This logic did not exist in Axes.legend. It was included (erroneously) in Matplotlib 2.1.1 when the legend argument parsing was unified [#9324](https://github.com/matplotlib/matplotlib/pull/9324). This change
removes that check in Axes.legend again to restore the old behavior.
This logic has also been dropped from Figure.legend, where it was previously undocumented. Repeated
lines with the same label will now each have an entry in the legend. If you do not want the duplicate entries,
don’t add a label to the line, or prepend the label with an underscore.
29.2 API Changes in 2.1.1
29.2.1 Default behavior of log scales reverted to clip <= 0 values
The change it 2.1.0 to mask in logscale by default had more disruptive changes than anticipated and has
been reverted, however the clipping is now done in a way that fixes the issues that motivated changing the
default behavior to 'mask'.
As a side effect of this change, error bars which go negative now work as expected on log scales.
575
Matplotlib, Release 2.1.2
29.3 API Changes in 2.1.0
29.3.1 Default behavior of log scales changed to mask <= 0 values
Calling matplotlib.axes.Axes.set_xscale or matplotlib.axes.Axes.set_yscale now uses
‘mask’ as the default method to handle invalid values (as opposed to ‘clip’). This means that any values
<= 0 on a log scale will not be shown.
Previously they were clipped to a very small number and shown.
29.3.2 matplotlib.cbook.CallbackRegistry.process() suppresses exceptions by
default
Matplotlib uses instances of CallbackRegistry as a bridge between user input event from the GUI and
user callbacks. Previously, any exceptions raised in a user call back would bubble out of of the process
method, which is typically in the GUI event loop. Most GUI frameworks simple print the traceback to the
screen and continue as there is not always a clear method of getting the exception back to the user. However
PyQt5 now exits the process when it receives an un-handled python exception in the event loop. Thus,
process() now suppresses and prints tracebacks to stderr by default.
What process() does with exceptions is now user configurable via the exception_handler attribute and
kwarg. To restore the previous behavior pass None
cb = CallbackRegistry(exception_handler=None)
A function which take and Exception as its only argument may also be passed
def maybe_reraise(exc):
if isinstance(exc, RuntimeError):
pass
else:
raise exc
cb = CallbackRegistry(exception_handler=maybe_reraise)
29.3.3 Improved toggling of the axes grids
The g key binding now switches the states of the x and y grids independently (by cycling through all four
on/off combinations).
The new G key binding switches the states of the minor grids.
Both bindings are disabled if only a subset of the grid lines (in either direction) is visible, to avoid making
irreversible changes to the figure.
29.3.4 Removal of warning on empty legends
plt.legend used to issue a warning when no labeled artist could be found. This warning has been removed.
576
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.3.5 More accurate legend autopositioning
Automatic positioning of legends now prefers using the area surrounded by a Line2D rather than placing
the legend over the line itself.
29.3.6 Cleanup of stock sample data
The sample data of stocks has been cleaned up to remove redundancies and increase portability. The AAPL.
dat.gz, INTC.dat.gz and aapl.csv files have been removed entirely and will also no longer be available
from matplotlib.cbook.get_sample_data. If a CSV file is required, we suggest using the msft.csv
that continues to be shipped in the sample data. If a NumPy binary file is acceptable, we suggest using one
of the following two new files. The aapl.npy.gz and goog.npy files have been replaced by aapl.npz
and goog.npz, wherein the first column’s type has changed from datetime.date to np.datetime64 for
better portability across Python versions. Note that Matplotlib does not fully support np.datetime64 as
yet.
29.3.7 Updated qhull to 2015.2
The version of qhull shipped with Matplotlib, which is used for Delaunay triangulation, has been updated
from version 2012.1 to 2015.2.
29.3.8 Improved Delaunay triangulations with large offsets
Delaunay triangulations now deal with large x,y offsets in a better way. This can cause minor changes
to any triangulations calculated using Matplotlib, i.e. any use of matplotlib.tri.Triangulation
that requests that a Delaunay triangulation is calculated, which includes matplotlib.pyplot.
tricontour, matplotlib.pyplot.tricontourf , matplotlib.pyplot.tripcolor, matplotlib.
pyplot.triplot, matplotlib.mlab.griddata and mpl_toolkits.mplot3d.axes3d.Axes3D.
plot_trisurf .
29.3.9 Use backports.functools_lru_cache instead of functools32
It’s better maintained and more widely used (by pylint, jaraco, etc).
29.3.10 cbook.is_numlike only performs an instance check
is_numlike() now only checks that its argument is an instance of (numbers.Number, np.Number). In
particular, this means that arrays are now not num-like.
29.3.11 Elliptical arcs now drawn between correct angles
The matplotlib.patches.Arc patch is now correctly drawn between the given angles.
29.3. API Changes in 2.1.0
577
Matplotlib, Release 2.1.2
Previously a circular arc was drawn and then stretched into an ellipse, so the resulting arc did not lie between
theta1 and theta2.
29.3.12 -d$backend no longer sets the backend
It is no longer possible to set the backend by passing -d$backend at the command line.
MPLBACKEND environment variable instead.
Use the
29.3.13 Path.intersects_bbox always treats the bounding box as filled
Previously, when Path.intersects_bbox was called with filled set to False, it would treat both the
path and the bounding box as unfilled. This behavior was not well documented and it is usually not the desired behavior, since bounding boxes are used to represent more complex shapes located inside the bounding
box. This behavior has now been changed: when filled is False, the path will be treated as unfilled, but
the bounding box is still treated as filled. The old behavior was arguably an implementation bug.
When Path.intersects_bbox is called with filled set to True (the default value), there is no change in
behavior. For those rare cases where Path.intersects_bbox was called with filled set to False and
where the old behavior is actually desired, the suggested workaround is to call Path.intersects_path
with a rectangle as the path:
from matplotlib.path import Path
from matplotlib.transforms import Bbox, BboxTransformTo
rect = Path.unit_rectangle().transformed(BboxTransformTo(bbox))
result = path.intersects_path(rect, filled=False)
29.3.14 WX no longer calls generates IdleEvent events or calls idle_event
Removed unused private method _onIdle from FigureCanvasWx.
The IdleEvent class and FigureCanvasBase.idle_event method will be removed in 2.2
29.3.15 Correct scaling of magnitude_spectrum()
The
functions
matplotlib.mlab.magnitude_spectrum()
and
matplotlib.pyplot.
magnitude_spectrum() implicitly assumed the sum of windowing function values to be one. In
Matplotlib and Numpy the standard windowing functions are scaled to have maximum value of one,
which usually results in a sum of the order of n/2 for a n-point signal. Thus the amplitude scaling
magnitude_spectrum() was off by that amount when using standard windowing functions (Bug 8417
). Now the behavior is consistent with matplotlib.pyplot.psd() and scipy.signal.welch(). The
following example demonstrates the new and old scaling:
import matplotlib.pyplot as plt
import numpy as np
tau, n = 10, 1024 # 10 second signal with 1024 points
T = tau/n # sampling interval
578
Chapter 29. API Changes
Matplotlib, Release 2.1.2
t = np.arange(n)*T
a = 4 # amplitude
x = a*np.sin(40*np.pi*t)
# 20 Hz sine with amplitude a
# New correct behavior: Amplitude at 20 Hz is a/2
plt.magnitude_spectrum(x, Fs=1/T, sides='onesided', scale='linear')
# Original behavior: Amplitude at 20 Hz is (a/2)*(n/2) for a Hanning window
w = np.hanning(n) # default window is a Hanning window
plt.magnitude_spectrum(x*np.sum(w), Fs=1/T, sides='onesided', scale='linear')
29.3.16 Change to signatures of bar() & barh()
For 2.0 the default value of *align* changed to 'center'. However this caused the signature of bar() and
barh() to be misleading as the first parameters were still left and bottom respectively:
bar(left, height, *, align='center', **kwargs)
barh(bottom, width, *, align='center', **kwargs)
despite behaving as the center in both cases. The methods now take *args, **kwargs as input and are
documented to have the primary signatures of:
bar(x, height, *, align='center', **kwargs)
barh(y, width, *, align='center', **kwargs)
Passing left and bottom as keyword arguments to bar() and barh() respectively will warn. Support will
be removed in Matplotlib 3.0.
29.3.17 Font cache as json
The font cache is now saved as json, rather than a pickle.
29.3.18 Invalid (Non-finite) Axis Limit Error
When using set_xlim() and set_ylim(), passing non-finite values now results in a ValueError. The
previous behavior resulted in the limits being erroneously reset to (-0.001, 0.001).
29.3.19 scatter and Collection offsets are no longer implicitly flattened
Collection (and thus both 2D scatter and 3D scatter) no longer implicitly flattens its offsets. As a
consequence, scatter’s x and y arguments can no longer be 2+-dimensional arrays.
29.3. API Changes in 2.1.0
579
Matplotlib, Release 2.1.2
29.3.20 Deprecations
GraphicsContextBase’s linestyle property.
The GraphicsContextBase.get_linestyle and GraphicsContextBase.set_linestyle methods, which had no effect, have been deprecated.
All of the backends Matplotlib ships use
GraphicsContextBase.get_dashes and GraphicsContextBase.set_dashes which are more general. Third-party backends should also migrate to the *_dashes methods.
NavigationToolbar2.dynamic_update
Use draw_idle() method on the Canvas instance instead.
Testing
matplotlib.testing.noseclasses is deprecated and will be removed in 2.3
EngFormatter num arg as string
Passing a string as num argument when calling an instance of matplotlib.ticker.EngFormatter is
deprecated and will be removed in 2.3.
mpl_toolkits.axes_grid module
All functionally from mpl_toolkits.axes_grid can be found in either mpl_toolkits.axes_grid1
or mpl_toolkits.axisartist. Axes classes from mpl_toolkits.axes_grid based on Axis from
mpl_toolkits.axisartist can be found in mpl_toolkits.axisartist.
Axes collision in Figure.add_axes
Adding an axes instance to a figure by using the same arguments as for a previous axes instance currently
reuses the earlier instance. This behavior has been deprecated in Matplotlib 2.1. In a future version, a new
instance will always be created and returned. Meanwhile, in such a situation, a deprecation warning is raised
by AxesStack.
This warning can be suppressed, and the future behavior ensured, by passing a unique label to each axes
instance. See the docstring of add_axes() for more information.
Additional details on the rationale behind this deprecation can be found in #7377 and #9024.
Former validators for contour.negative_linestyle
The
former
public
validation
functions
validate_negative_linestyle
and
validate_negative_linestyle_legacy will be deprecated in 2.1 and may be removed in 2.3.
There are no public functions to replace them.
580
Chapter 29. API Changes
Matplotlib, Release 2.1.2
cbook
Many unused or near-unused matplotlib.cbook functions and classes have been deprecated: converter,
tostr, todatetime, todate, tofloat, toint, unique, is_string_like, is_sequence_of_strings,
is_scalar, Sorter, Xlator, soundex, Null, dict_delall, RingBuffer, get_split_ind,
wrap, get_recursive_filelist, pieces, exception_to_str, allequal, alltrue, onetrue,
allpairs, finddir, reverse_dict, restrict_dict, issubclass_safe, recursive_remove,
unmasked_index_ranges.
29.3.21 Code Removal
qt4_compat.py
Moved to qt_compat.py. Renamed because it now handles Qt5 as well.
Previously Deprecated methods
The GraphicsContextBase.set_graylevel, FigureCanvasBase.onHilite and mpl_toolkits.
axes_grid1.mpl_axes.Axes.toggle_axisline methods have been removed.
The ArtistInspector.findobj method, which was never working due to the lack of a get_children
method, has been removed.
The
deprecated
point_in_path,
get_path_extents,
point_in_path_collection,
path_intersects_path, convert_path_to_polygons, cleanup_path and clip_path_to_rect
functions in the matplotlib.path module have been removed. Their functionality remains exposed as
methods on the Path class.
The deprecated Artist.get_axes and Artist.set_axes methods have been removed
The matplotlib.backends.backend_ps.seq_allequal function has been removed.
array_equal instead.
Use np.
The
deprecated
matplotlib.rcsetup.validate_maskedarray,
matplotlib.rcsetup.
deprecate_savefig_extension and matplotlib.rcsetup.validate_tkpythoninspect functions,
and associated savefig.extension and tk.pythoninspect rcparams entries have been removed.
The kwarg resolution of matplotlib.projections.polar.PolarAxes has been removed. It has
deprecation with no effect from version 0.98.x.
Axes.set_aspect("normal")
Support for setting an Axes’s aspect to "normal" has been removed, in favor of the synonym "auto".
shading kwarg to pcolor
The shading kwarg to pcolor has been removed. Set edgecolors appropriately instead.
29.3. API Changes in 2.1.0
581
Matplotlib, Release 2.1.2
Functions removed from the lines module
The matplotlib.lines module no longer imports the pts_to_prestep, pts_to_midstep and
pts_to_poststep functions from matplotlib.cbook.
PDF backend functions
The methods embedTeXFont and tex_font_mapping of matplotlib.backqend_pdf.PdfFile have
been removed. It is unlikely that external users would have called these methods, which are related to
the font system internal to the PDF backend.
matplotlib.delaunay
Remove the delaunay triangulation code which is now handled by Qhull via matplotlib.tri.
29.4 API Changes in 2.0.1
29.4.1 Extensions to matplotlib.backend_bases.GraphicsContextBase
To better support controlling the color of hatches, the method matplotlib.backend_bases.
GraphicsContextBase.set_hatch_color was added to the expected API of GraphicsContext
classes. Calls to this method are currently wrapped with a try:...except Attribute: block to preserve back-compatibility with any third-party backends which do not extend GraphicsContextBase.
This value can be accessed in the backends via matplotlib.backend_bases.
GraphicsContextBase.get_hatch_color (which was added in 2.0 see Extension to matplotlib.backend_bases.GraphicsContextBase) and should be used to color the hatches.
In the future there may also be hatch_linewidth and hatch_density related methods added. It is encouraged, but not required that third-party backends extend GraphicsContextBase to make adapting to
these changes easier.
29.4.2 afm.get_fontconfig_fonts returns a list of paths and does not check for existence
afm.get_fontconfig_fonts used to return a set of paths encoded as a {key: 1, ...} dict, and
checked for the existence of the paths. It now returns a list and dropped the existence check, as the same
check is performed by the caller (afm.findSystemFonts) as well.
29.4.3 bar now returns rectangles of negative height or width if the corresponding input
is negative
plt.bar used to normalize the coordinates of the rectangles that it created, to keep their height and width
positives, even if the corresponding input was negative. This normalization has been removed to permit a
simpler computation of the correct sticky_edges to use.
582
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.4.4 Do not clip line width when scaling dashes
The algorithm to scale dashes was changed to no longer clip the scaling factor: the dash patterns now
continue to shrink at thin line widths. If the line width is smaller than the effective pixel size, this may result
in dashed lines turning into solid gray-ish lines. This also required slightly tweaking the default patterns for
‘–’, ‘:’, and ‘.-‘ so that with the default line width the final patterns would not change.
There is no way to restore the old behavior.
29.4.5 Deprecate ‘Vega’ color maps
The “Vega” colormaps are deprecated in Matplotlib 2.0.1 and will be removed in Matplotlib 2.2. Use the
“tab” colormaps instead: “tab10”, “tab20”, “tab20b”, “tab20c”.
29.5 API Changes in 2.0.0
29.5.1 Deprecation and removal
Color of Axes
The axisbg and axis_bgcolor properties on Axes have been deprecated in favor of facecolor.
GTK and GDK backends deprecated
The GDK and GTK backends have been deprecated. These obsolete backends allow figures to be rendered
via the GDK API to files and GTK2 figures. They are untested and known to be broken, and their use has
been discouraged for some time. Instead, use the GTKAgg and GTKCairo backends for rendering to GTK2
windows.
WX backend deprecated
The WX backend has been deprecated. It is untested, and its use has been discouraged for some time.
Instead, use the WXAgg backend for rendering figures to WX windows.
CocoaAgg backend removed
The deprecated and not fully functional CocoaAgg backend has been removed.
round removed from TkAgg Backend
The TkAgg backend had its own implementation of the round function. This was unused internally and has
been removed. Instead, use either the round builtin function or numpy.round.
29.5. API Changes in 2.0.0
583
Matplotlib, Release 2.1.2
‘hold’ functionality deprecated
The ‘hold’ keyword argument and all functions and methods related to it are deprecated, along with the
‘axes.hold’ rcParams entry. The behavior will remain consistent with the default hold=True state that has
long been in place. Instead of using a function or keyword argument (hold=False) to change that behavior,
explicitly clear the axes or figure as needed prior to subsequent plotting commands.
29.5.2 Artist.update has return value
The methods matplotlib.artist.Artist.set, matplotlib.Artist.update, and the function
matplotlib.artist.setp now use a common codepath to look up how to update the given artist properties (either using the setter methods or an attribute/property).
The behavior of matplotlib.Artist.update is slightly changed to return a list of the values returned
from the setter methods to avoid changing the API of matplotlib.Artist.set and matplotlib.
artist.setp.
The keys passed into matplotlib.Artist.update are now converted to lower case before being processed, to match the behavior of matplotlib.Artist.set and matplotlib.artist.setp. This should
not break any user code because there are no set methods with capitals in their names, but this puts a constraint on naming properties in the future.
29.5.3 Legend initializers gain edgecolor and facecolor kwargs
The Legend background patch (or ‘frame’) can have its edgecolor and facecolor determined by the
corresponding keyword arguments to the matplotlib.legend.Legend initializer, or to any of the methods
or functions that call that initializer. If left to their default values of None, their values will be taken from
matplotlib.rcParams. The previously-existing framealpha kwarg still controls the alpha transparency
of the patch.
29.5.4 Qualitative colormaps
Colorbrewer’s qualitative/discrete colormaps (“Accent”, “Dark2”, “Paired”, “Pastel1”, “Pastel2”, “Set1”,
“Set2”, “Set3”) are now implemented as ListedColormap instead of LinearSegmentedColormap.
To use these for images where categories are specified as integers, for instance, use:
plt.imshow(x, cmap='Dark2', norm=colors.NoNorm())
29.5.5 Change in the draw_image backend API
The draw_image method implemented by backends has changed its interface.
This change is only relevant if the backend declares that it is able to transform images by returning True
from option_scale_image. See the draw_image docstring for more information.
584
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.5.6 matplotlib.ticker.LinearLocator algorithm update
The matplotlib.ticker.LinearLocator is used to define the range and location of axis ticks when the
user wants an exact number of ticks. LinearLocator thus differs from the default locator MaxNLocator,
for which the user specifies a maximum number of intervals rather than a precise number of ticks.
The view range algorithm in matplotlib.ticker.LinearLocator has been changed so that more convenient tick locations are chosen. The new algorithm returns a plot view range that is a multiple of the
user-requested number of ticks. This ensures tick marks will be located at whole integers more consistently. For example, when both y-axes of a‘‘twinx‘‘ plot use matplotlib.ticker.LinearLocator with
the same number of ticks, their y-tick locations and grid lines will coincide.
29.5.7 matplotlib.ticker.LogLocator gains numticks kwarg
The maximum number of ticks generated by the LogLocator can now be controlled explicitly via setting
the new ‘numticks’ kwarg to an integer. By default the kwarg is None which internally sets it to the ‘auto’
string, triggering a new algorithm for adjusting the maximum according to the axis length relative to the
ticklabel font size.
29.5.8 matplotlib.ticker.LogFormatter: two new kwargs
Previously, minor ticks on log-scaled axes were not labeled by default. An algorithm has been added to the
LogFormatter to control the labeling of ticks between integer powers of the base. The algorithm uses two
parameters supplied in a kwarg tuple named ‘minor_thresholds’. See the docstring for further explanation.
To improve support for axes using SymmetricLogLocator, a ‘linthresh’ kwarg was added.
29.5.9 New defaults for 3D quiver function in mpl_toolkits.mplot3d.axes3d.py
Matplotlib has both a 2D and a 3D quiver function. These changes affect only the 3D function and make
the default behavior of the 3D function match the 2D version. There are two changes:
1. The 3D quiver function previously normalized the arrows to be the same length, which makes it
unusable for situations where the arrows should be different lengths and does not match the behavior
of the 2D function. This normalization behavior is now controlled with the normalize keyword,
which defaults to False.
2. The pivot keyword now defaults to tail instead of tip. This was done in order to match the default
behavior of the 2D quiver function.
To obtain the previous behavior with the 3D quiver function, one can call the function with
ax.quiver(x, y, z, u, v, w, normalize=True, pivot='tip')
where “ax” is an Axes3d object created with something like
import mpl_toolkits.mplot3d.axes3d
ax = plt.sublot(111, projection='3d')
29.5. API Changes in 2.0.0
585
Matplotlib, Release 2.1.2
29.5.10 Stale figure behavior
Attempting to draw the figure will now mark it as not stale (independent if the draw succeeds). This change
is to prevent repeatedly trying to re-draw a figure which is raising an error on draw. The previous behavior
would only mark a figure as not stale after a full re-draw succeeded.
29.5.11 The spectral colormap is now nipy_spectral
The colormaps formerly known as spectral and spectral_r have been replaced by nipy_spectral and
nipy_spectral_r since Matplotlib 1.3.0. Even though the colormap was deprecated in Matplotlib 1.3.0,
it never raised a warning. As of Matplotlib 2.0.0, using the old names raises a deprecation warning. In the
future, using the old names will raise an error.
29.5.12 Default install no longer includes test images
To reduce the size of wheels and source installs, the tests and baseline images are no longer included by
default.
To restore installing the tests and images, use a setup.cfg with
[packages]
tests = True
toolkits_tests = True
in the source directory at build/install time.
29.6 Changes in 1.5.3
29.6.1 ax.plot(..., marker=None) gives default marker
Prior to 1.5.3 kwargs passed to plot were handled in two parts – default kwargs generated internal to
plot (such as the cycled styles) and user supplied kwargs. The internally generated kwargs were passed to
the matplotlib.lines.Line2D.__init__ and the user kwargs were passed to ln.set(**kwargs) to
update the artist after it was created. Now both sets of kwargs are merged and passed to __init__. This
change was made to allow None to be passed in via the user kwargs to mean ‘do the default thing’ as is the
convention through out mpl rather than raising an exception.
Unlike most Line2D setter methods set_marker did accept None as a valid input which was mapped to
‘no marker’. Thus, by routing this marker=None through __init__ rather than set(...) the meaning of
ax.plot(..., marker=None) changed from ‘no markers’ to ‘default markers from rcparams’.
This is change is only evident if mpl.rcParams['lines.marker'] has a value other than 'None' (which
is string 'None' which means ‘no marker’).
586
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.7 Changes in 1.5.2
29.7.1 Default Behavior Changes
Changed default autorange behavior in boxplots
Prior to v1.5.2, the whiskers of boxplots would extend to the mininum and maximum values if the quartiles
were all equal (i.e., Q1 = median = Q3). This behavior has been disabled by default to restore consistency
with other plotting packages.
To restore the old behavior, simply set autorange=True when calling plt.boxplot.
29.8 Changes in 1.5.0
29.8.1 Code Changes
Reversed matplotlib.cbook.ls_mapper, added ls_mapper_r
Formerly, matplotlib.cbook.ls_mapper was a dictionary with the long-form line-style names
("solid") as keys and the short forms ("-") as values. This long-to-short mapping is now done by
ls_mapper_r, and the short-to-long mapping is done by the ls_mapper.
Prevent moving artists between Axes, Property-ify Artist.axes, deprecate Artist.{get,set}_axes
This was done to prevent an Artist that is already associated with an Axes from being moved/added to a
different Axes. This was never supported as it causes havoc with the transform stack. The apparent support
for this (as it did not raise an exception) was the source of multiple bug reports and questions on SO.
For almost all use-cases, the assignment of the axes to an artist should be taken care of by the axes as part
of the Axes.add_* method, hence the deprecation of {get,set}_axes.
Removing the set_axes method will also remove the ‘axes’ line from the ACCEPTS kwarg tables (assuming that the removal date gets here before that gets overhauled).
Tightened input validation on ‘pivot’ kwarg to quiver
Tightened validation so that only {‘tip’, ‘tail’, ‘mid’, and ‘middle’} (but any capitalization) are valid values
for the ‘pivot’ kwarg in the Quiver.__init__ (and hence Axes.quiver and plt.quiver which both
fully delegate to Quiver). Previously any input matching ‘mid.*’ would be interpreted as ‘middle’, ‘tip.*’
as ‘tip’ and any string not matching one of those patterns as ‘tail’.
The value of Quiver.pivot is normalized to be in the set {‘tip’, ‘tail’, ‘middle’} in Quiver.__init__.
29.7. Changes in 1.5.2
587
Matplotlib, Release 2.1.2
Reordered Axes.get_children
The artist order returned by Axes.get_children did not match the one used by Axes.draw. They now
use the same order, as Axes.draw now calls Axes.get_children.
Changed behaviour of contour plots
The default behaviour of contour() and contourf() when using a masked array is now determined
by the new keyword argument corner_mask, or if this is not specified then the new rcParam contour.
corner_mask instead. The new default behaviour is equivalent to using corner_mask=True; the previous behaviour can be obtained using corner_mask=False or by changing the rcParam. The example http://matplotlib.org/examples/pylab_examples/contour_corner_mask.html demonstrates the difference.
Use of the old contouring algorithm, which is obtained with corner_mask='legacy', is now deprecated.
Contour labels may now appear in different places than in earlier versions of Matplotlib.
In addition, the keyword argument nchunk now applies to contour() as well as contourf(), and it
subdivides the domain into subdomains of exactly nchunk by nchunk quads, whereas previously it was
only roughly nchunk by nchunk quads.
The C/C++ object that performs contour calculations used to be stored in the public attribute QuadContourSet.Cntr, but is now stored in a private attribute and should not be accessed by end users.
Added set_params function to all Locator types
This was a bug fix targeted at making the api for Locators more consistent.
In the old behavior, only locators of type MaxNLocator have set_params() defined, causing its use on any
other Locator to raise an AttributeError ( aside: set_params(args) is a function that sets the parameters of a
Locator instance to be as specified within args). The fix involves moving set_params() to the Locator class
such that all subtypes will have this function defined.
Since each of the Locator subtypes have their own modifiable parameters, a universal set_params() in Locator isn’t ideal. Instead, a default no-operation function that raises a warning is implemented in Locator.
Subtypes extending Locator will then override with their own implementations. Subtypes that do not have a
need for set_params() will fall back onto their parent’s implementation, which raises a warning as intended.
In the new behavior, Locator instances will not raise an AttributeError when set_params() is called. For
Locators that do not implement set_params(), the default implementation in Locator is used.
Disallow None as x or y value in ax.plot
Do not allow None as a valid input for the x or y args in ax.plot. This may break some user code, but this
was never officially supported (ex documented) and allowing None objects through can lead to confusing
exceptions downstream.
To create an empty line use
588
Chapter 29. API Changes
Matplotlib, Release 2.1.2
ln1, = ax.plot([], [], ...)
ln2, = ax.plot([], ...)
In either case to update the data in the Line2D object you must update both the x and y data.
Removed args and kwargs from MicrosecondLocator.__call__
The call signature of __call__() has changed from __call__(self, *args, **kwargs) to
__call__(self). This is consistent with the superclass Locator and also all the other Locators derived
from this superclass.
No ValueError for the MicrosecondLocator and YearLocator
The MicrosecondLocator and YearLocator objects when called will return an empty list if the axes have
no data or the view has no interval. Previously, they raised a ValueError. This is consistent with all the
Date Locators.
‘OffsetBox.DrawingArea’ respects the ‘clip’ keyword argument
The call signature was OffsetBox.DrawingArea(..., clip=True) but nothing was done with the clip
argument. The object did not do any clipping regardless of that parameter. Now the object can and does clip
the child Artists if they are set to be clipped.
You can turn off the clipping on a per-child basis using child.set_clip_on(False).
Add salt to clipPath id
Add salt to the hash used to determine the id of the clipPath nodes. This is to avoid conflicts when two
svg documents with the same clip path are included in the same document (see https://github.com/ipython/
ipython/issues/8133 and https://github.com/matplotlib/matplotlib/issues/4349 ), however this means that the
svg output is no longer deterministic if the same figure is saved twice. It is not expected that this will affect
any users as the current ids are generated from an md5 hash of properties of the clip path and any user would
have a very difficult time anticipating the value of the id.
Changed snap threshold for circle markers to inf
When drawing circle markers above some marker size (previously 6.0) the path used to generate the marker
was snapped to pixel centers. However, this ends up distorting the marker away from a circle. By setting
the snap threshold to inf snapping is never done on circles.
This change broke several tests, but is an improvement.
29.8. Changes in 1.5.0
589
Matplotlib, Release 2.1.2
Preserve units with Text position
Previously the ‘get_position’ method on Text would strip away unit information even though the units were
still present. There was no inherent need to do this, so it has been changed so that unit data (if present) will
be preserved. Essentially a call to ‘get_position’ will return the exact value from a call to ‘set_position’.
If you wish to get the old behaviour, then you can use the new method called ‘get_unitless_position’.
New API for custom Axes view changes
Interactive pan and zoom were previously implemented using a Cartesian-specific algorithm that was not
necessarily applicable to custom Axes. Three new private methods, _get_view(), _set_view(), and
_set_view_from_bbox(), allow for custom Axes classes to override the pan and zoom algorithms. Implementors of custom Axes who override these methods may provide suitable behaviour for both pan and
zoom as well as the view navigation buttons on the interactive toolbars.
29.8.2 MathTex visual changes
The spacing commands in mathtext have been changed to more closely match vanilla TeX.
Improved spacing in mathtext
The extra space that appeared after subscripts and superscripts has been removed.
No annotation coordinates wrap
In #2351 for 1.4.0 the behavior of [‘axes points’, ‘axes pixel’, ‘figure points’, ‘figure pixel’] as coordinates
was change to no longer wrap for negative values. In 1.4.3 this change was reverted for ‘axes points’ and
‘axes pixel’ and in addition caused ‘axes fraction’ to wrap. For 1.5 the behavior has been reverted to as it
was in 1.4.0-1.4.2, no wrapping for any type of coordinate.
29.8.3 Deprecation
Deprecated GraphicsContextBase.set_graylevel
The GraphicsContextBase.set_graylevel function has been deprecated in 1.5 and will be removed in
1.6. It has been unused. The GraphicsContextBase.set_foreground could be used instead.
deprecated idle_event
The idle_event was broken or missing in most backends and causes spurious warnings in some cases,
and its use in creating animations is now obsolete due to the animations module. Therefore code involving
it has been removed from all but the wx backend (where it partially works), and its use is deprecated. The
animations module may be used instead to create animations.
590
Chapter 29. API Changes
Matplotlib, Release 2.1.2
color_cycle deprecated
In light of the new property cycling feature, the Axes method set_color_cycle is now deprecated. Calling
this method will replace the current property cycle with one that cycles just the given colors.
Similarly, the rc parameter axes.color_cycle is also deprecated in lieu of the new axes.prop_cycle parameter.
Having both parameters in the same rc file is not recommended as the result cannot be predicted. For compatibility, setting axes.color_cycle will replace the cycler in axes.prop_cycle with a color cycle. Accessing
axes.color_cycle will return just the color portion of the property cycle, if it exists.
Timeline for removal has not been set.
29.8.4 Bundled jquery
The version of jquery bundled with the webagg backend has been upgraded from 1.7.1 to 1.11.3. If you are
using the version of jquery bundled with webagg you will need to update your html files as such
+
<script src="_static/jquery/js/jquery-1.7.1.min.js"></script>
<script src="_static/jquery/js/jquery-1.11.3.min.js"></script>
29.8.5 Code Removed
Removed Image from main namespace
Image was imported from PIL/pillow to test if PIL is available, but there is no reason to keep Image in the
namespace once the availability has been determined.
Removed lod from Artist
Removed the method set_lod and all references to the attribute _lod as the are not used anywhere else in the
code base. It appears to be a feature stub that was never built out.
Removed threading related classes from cbook
The classes Scheduler, Timeout, and Idle were in cbook, but are not used internally. They appear to be
a prototype for the idle event system which was not working and has recently been pulled out.
Removed Lena images from sample_data
The lena.png and lena.jpg images have been removed from Matplotlib’s sample_data directory.
The images are also no longer available from matplotlib.cbook.get_sample_data. We suggest using matplotlib.cbook.get_sample_data('grace_hopper.png') or matplotlib.cbook.
get_sample_data('grace_hopper.jpg') instead.
29.8. Changes in 1.5.0
591
Matplotlib, Release 2.1.2
Legend
Removed handling of loc as a positional argument to Legend
Legend handlers
Remove code to allow legend handlers to be callable. They must now implement a method legend_artist.
Axis
Removed method set_scale. This is now handled via a private method which should not be used directly
by users. It is called via Axes.set_{x,y}scale which takes care of ensuring the related changes are also
made to the Axes object.
finance.py
Removed functions with ambiguous argument order from finance.py
Annotation
Removed textcoords and xytext proprieties from Annotation objects.
spinxext.ipython_*.py
Both ipython_console_highlighting and ipython_directive have been moved to IPython.
Change your import from ‘matplotlib.sphinxext.ipython_directive’ to ‘IPython.sphinxext.ipython_directive’
and from ‘matplotlib.sphinxext.ipython_directive’ to ‘IPython.sphinxext.ipython_directive’
LineCollection.color
Deprecated in 2005, use set_color
remove 'faceted' as a valid value for shading in tri.tripcolor
Use edgecolor instead. Added validation on shading to only be valid values.
Remove faceted kwarg from scatter
Remove
support
for
the
faceted
kwarg.
This
was
deprecated
d48b34288e9651ff95c3b8a071ef5ac5cf50bae7 (2008-04-18!) and replaced by edgecolor.
592
in
Chapter 29. API Changes
Matplotlib, Release 2.1.2
Remove set_colorbar method from ScalarMappable
Remove set_colorbar method, use colorbar attribute directly.
patheffects.svg
• remove get_proxy_renderer method from AbstarctPathEffect class
• remove patch_alpha and offset_xy from SimplePatchShadow
Remove testing.image_util.py
Contained only a no-longer used port of functionality from PIL
Remove mlab.FIFOBuffer
Not used internally and not part of core mission of mpl.
Remove mlab.prepca
Deprecated in 2009.
Remove NavigationToolbar2QTAgg
Added no functionality over the base NavigationToolbar2Qt
mpl.py
Remove the module matplotlib.mpl.
78ce67d161625833cacff23cfe5d74920248c5b2
Deprecated in 1.3 by PR #1670 and commit
29.9 Changes in 1.4.x
29.9.1 Code changes
• A major refactoring of the axes module was made. The axes module has been split into smaller
modules:
– the _base module, which contains a new private _AxesBase class. This class contains all methods except plotting and labelling methods.
– the axes module, which contains the Axes class. This class inherits from _AxesBase, and
contains all plotting and labelling methods.
29.9. Changes in 1.4.x
593
Matplotlib, Release 2.1.2
– the _subplot module, with all the classes concerning subplotting.
There are a couple of things that do not exists in the axes module’s namespace anymore. If you use them,
you need to import them from their original location:
• math -> import math
• ma -> from numpy import ma
• cbook -> from matplotlib import cbook
• docstring -> from matplotlib import docstring
• is_sequence_of_strings -> from matplotlib.cbook import is_sequence_of_strings
• is_string_like -> from matplotlib.cbook import is_string_like
• iterable -> from matplotlib.cbook import iterable
• itertools -> import itertools
• martist -> from matplotlib import artist as martist
• matplotlib -> import matplotlib
• mcoll -> from matplotlib import collections as mcoll
• mcolors -> from matplotlib import colors as mcolors
• mcontour -> from matplotlib import contour as mcontour
• mpatches -> from matplotlib import patches as mpatches
• mpath -> from matplotlib import path as mpath
• mquiver -> from matplotlib import quiver as mquiver
• mstack -> from matplotlib import stack as mstack
• mstream -> from matplotlib import stream as mstream
• mtable -> from matplotlib import table as mtable
• As part of the refactoring to enable Qt5 support, the module matplotlib.backends.qt4_compat
was renamed to matplotlib.qt_compat. qt4_compat is deprecated in 1.4 and will be removed in
1.5.
• The errorbar() method has been changed such that the upper and lower limits (lolims, uplims,
xlolims, xuplims) now point in the correct direction.
• The fmt kwarg for plot() defaults.
• A bug has been fixed in the path effects rendering of fonts, which now means that the font size is
consistent with non-path effect fonts. See https://github.com/matplotlib/matplotlib/issues/2889 for
more detail.
• The Sphinx extensions ipython_directive and ipython_console_highlighting have been
moved to the IPython project itself. While they remain in Matplotlib for this release, they
have been deprecated. Update your extensions in conf.py to point to IPython.sphinxext.
ipython_directive instead of matplotlib.sphinxext.ipython_directive.
594
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• In finance, almost all functions have been deprecated and replaced with a pair of functions name
*_ochl and *_ohlc. The former is the ‘open-close-high-low’ order of quotes used previously in this
module, and the latter is the ‘open-high-low-close’ order that is standard in finance.
• For consistency the face_alpha keyword to matplotlib.patheffects.SimplePatchShadow
has been deprecated in favour of the alpha keyword. Similarly, the keyword offset_xy
is now named offset across all _Base` has been renamed to matplotlib.patheffects.
AbstractPathEffect.
matplotlib.patheffect.ProxyRenderer has been renamed to
matplotlib.patheffects.PathEffectRenderer and is now a full RendererBase subclass.
• The artist used to draw the outline of a colorbar has been changed from a matplotlib.lines.
Line2D to matplotlib.patches.Polygon, thus colorbar.ColorbarBase.outline is now a
matplotlib.patches.Polygon object.
• The legend handler interface has changed from a callable, to any object which implements the
legend_artists method (a deprecation phase will see this interface be maintained for v1.4). See
Legend guide for further details. Further legend changes include:
– matplotlib.axes.Axes._get_legend_handles() now returns a generator of handles,
rather than a list.
– The legend() function’s “loc” positional argument has been deprecated. Use the “loc” keyword
instead.
• The rcParams savefig.transparent has been added to control default transparency when saving
figures.
• Slightly refactored the Annotation family. The text location in Annotation is now handled entirely
handled by the underlying Text object so set_position works as expected. The attributes xytext
and textcoords have been deprecated in favor of xyann and anncoords so that Annotation and
AnnotaionBbox can share a common sensibly named api for getting/setting the location of the text
or box.
– xyann -> set the location of the annotation
– xy -> set where the arrow points to
– anncoords -> set the units of the annotation location
– xycoords -> set the units of the point location
– set_position() -> Annotation only set location of annotation
• matplotlib.mlab.specgram, matplotlib.mlab.psd, matplotlib.mlab.csd, matplotlib.
mlab.cohere,
matplotlib.mlab.cohere_pairs,
matplotlib.pyplot.specgram,
matplotlib.pyplot.psd, matplotlib.pyplot.csd, and matplotlib.pyplot.cohere
now raise ValueError where they previously raised AssertionError.
• For
matplotlib.mlab.psd,
matplotlib.mlab.csd,
matplotlib.mlab.cohere,
matplotlib.mlab.cohere_pairs, matplotlib.pyplot.specgram, matplotlib.pyplot.
psd, matplotlib.pyplot.csd, and matplotlib.pyplot.cohere, in cases where a shape (n, 1)
array is returned, this is now converted to a (n, ) array. Previously, (n, m) arrays were averaged to an
(n, ) array, but (n, 1) arrays were returend unchanged. This change makes the dimensions consistent
in both cases.
29.9. Changes in 1.4.x
595
Matplotlib, Release 2.1.2
• Added the rcParam axes.fromatter.useoffset to control the default value of useOffset in
ticker.ScalarFormatter
• Added Formatter sub-class StrMethodFormatter which does the exact same thing as
FormatStrFormatter, but for new-style formatting strings.
• Deprecated matplotlib.testing.image_util and the only function within, matplotlib.
testing.image_util.autocontrast. These will be removed completely in v1.5.0.
• The fmt argument of plot_date() has been changed from bo to just o, so color cycling can happen
by default.
• Removed the class FigureManagerQTAgg and deprecated NavigationToolbar2QTAgg which will
be removed in 1.5.
• Removed formerly public (non-prefixed) attributes rect and drawRect from FigureCanvasQTAgg;
they were always an implementation detail of the (preserved) drawRectangle() function.
• The
function
signatures
of
tight_bbox.adjust_bbox
and
tight_bbox.
process_figure_for_rasterizing have been changed. A new fixed_dpi parameter allows for
overriding the figure.dpi setting instead of trying to deduce the intended behaviour from the file
format.
• Added support for horizontal/vertical axes padding to mpl_toolkits.axes_grid1.ImageGrid —
argument axes_pad can now be tuple-like if separate axis padding is required. The original behavior
is preserved.
• Added support for skewed transforms to matplotlib.transforms.Affine2D, which can be created using the skew and skew_deg methods.
• Added clockwise parameter to control sectors direction in axes.pie
• In matplotlib.lines.Line2D the markevery functionality has been extended. Previously an integer start-index and stride-length could be specified using either a two-element-list or a two-elementtuple. Now this can only be done using a two-element-tuple. If a two-element-list is used then it will
be treated as numpy fancy indexing and only the two markers corresponding to the given indexes will
be shown.
• removed prop kwarg from mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar
call. It was passed through to the base-class __init__ and is only used for setting padding. Now
fontproperties (which is what is really used to set the font properties of AnchoredSizeBar) is
passed through in place of prop. If fontpropreties is not passed in, but prop is, then prop is used
inplace of fontpropreties. If both are passed in, prop is silently ignored.
• The use of the index 0 in plt.subplot and related commands is deprecated. Due to a lack of
validation calling plt.subplots(2, 2, 0) does not raise an exception, but puts an axes in the
_last_ position. This is due to the indexing in subplot being 1-based (to mirror MATLAB) so before
indexing into the GridSpec object used to determine where the axes should go, 1 is subtracted off.
Passing in 0 results in passing -1 to GridSpec which results in getting the last position back. Even
though this behavior is clearly wrong and not intended, we are going through a deprecation cycle in
an abundance of caution that any users are exploiting this ‘feature’. The use of 0 as an index will raise
a warning in 1.4 and an exception in 1.5.
• Clipping is now off by default on offset boxes.
596
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• Matplotlib now uses a less-aggressive call to gc.collect(1) when closing figures to avoid major
delays with large numbers of user objects in memory.
• The default clip value of all pie artists now defaults to False.
29.9.2 Code removal
• Removed mlab.levypdf. The code raised a numpy error (and has for a long time) and was not the
standard form of the Levy distribution. scipy.stats.levy should be used instead
29.10 Changes in 1.3.x
29.10.1 Changes in 1.3.1
It is rare that we make an API change in a bugfix release, however, for 1.3.1 since 1.3.0 the following change
was made:
• text.Text.cached (used to cache font objects) has been made into a private variable. Among the
obvious encapsulation benefit, this removes this confusing-looking member from the documentation.
• The method hist() now always returns bin occupancies as an array of type float. Previously, it
was sometimes an array of type int, depending on the call.
29.10.2 Code removal
• The following items that were deprecated in version 1.2 or earlier have now been removed completely.
– The Qt 3.x backends (qt and qtagg) have been removed in favor of the Qt 4.x backends (qt4
and qt4agg).
– The FltkAgg and Emf backends have been removed.
– The matplotlib.nxutils module has been removed. Use the functionality on matplotlib.
path.Path.contains_point and friends instead.
– Instead of axes.Axes.get_frame, use axes.Axes.patch.
– The following kwargs to the legend function have been renamed:
* pad -> borderpad
* labelsep -> labelspacing
* handlelen -> handlelength
* handletextsep -> handletextpad
* axespad -> borderaxespad
Related to this, the following rcParams have been removed:
29.10. Changes in 1.3.x
597
Matplotlib, Release 2.1.2
* legend.pad, legend.labelsep, legend.handlelen, legend.handletextsep and
legend.axespad
– For the hist function, instead of width, use rwidth (relative width).
– On patches.Circle, the resolution kwarg has been removed. For a circle made up of line
segments, use patches.CirclePolygon.
– The printing functions in the Wx backend have been removed due to the burden of keeping them
up-to-date.
– mlab.liaupunov has been removed.
– mlab.save, mlab.load, pylab.save and pylab.load have been removed. We recommend
using numpy.savetxt and numpy.loadtxt instead.
– widgets.HorizontalSpanSelector has been removed. Use widgets.SpanSelector instead.
29.10.3 Code deprecation
• The CocoaAgg backend has been deprecated, with the possibility for deletion or resurrection in a
future release.
• The top-level functions in matplotlib.path that are implemented in C++ were never meant
to be public. Instead, users should use the Pythonic wrappers for them in the path.Path and
collections.Collection classes. Use the following mapping to update your code:
– point_in_path -> path.Path.contains_point
– get_path_extents -> path.Path.get_extents
– point_in_path_collection -> collection.Collection.contains
– path_in_path -> path.Path.contains_path
– path_intersects_path -> path.Path.intersects_path
– convert_path_to_polygons -> path.Path.to_polygons
– cleanup_path -> path.Path.cleaned
– points_in_path -> path.Path.contains_points
– clip_path_to_rect -> path.Path.clip_to_bbox
• matplotlib.colors.normalize and matplotlib.colors.no_norm have been deprecated in
favour of matplotlib.colors.Normalize and matplotlib.colors.NoNorm respectively.
• The ScalarMappable class’ set_colorbar is now deprecated. Instead, the matplotlib.cm.
ScalarMappable.colorbar attribute should be used. In previous Matplotlib versions this attribute was an undocumented tuple of (colorbar_instance, colorbar_axes) but is now just
colorbar_instance. To get the colorbar axes it is possible to just use the ax attribute on a colorbar
instance.
598
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• The mpl module is now deprecated. Those who relied on this module should transition to simply
using import matplotlib as mpl.
29.10.4 Code changes
• Patch now fully supports using RGBA values for its facecolor and edgecolor attributes, which
enables faces and edges to have different alpha values. If the Patch object’s alpha attribute is set to
anything other than None, that value will override any alpha-channel value in both the face and edge
colors. Previously, if Patch had alpha=None, the alpha component of edgecolor would be applied
to both the edge and face.
• The optional isRGB argument to set_foreground() (and the other GraphicsContext classes that
descend from it) has been renamed to isRGBA, and should now only be set to True if the fg color
argument is known to be an RGBA tuple.
• For Patch , the capstyle used is now butt, to be consistent with the default for most other objects,
and to avoid problems with non-solid linestyle appearing solid when using a large linewidth.
Previously, Patch used capstyle='projecting'.
• Path objects can now be marked as readonly by passing readonly=True to its constructor. The
built-in path singletons, obtained through Path.unit* class methods return readonly paths. If you
have code that modified these, you will need to make a deepcopy first, using either:
import copy
path = copy.deepcopy(Path.unit_circle())
# or
path = Path.unit_circle().deepcopy()
Deep copying a Path always creates an editable (i.e. non-readonly) Path.
• The list at Path.NUM_VERTICES was replaced by a dictionary mapping Path codes to the number of
expected vertices at NUM_VERTICES_FOR_CODE.
• To support XKCD style plots, the matplotlib.path.cleanup_path() method’s signature was updated to require a sketch argument. Users of matplotlib.path.cleanup_path() are encouraged
to use the new cleaned() Path method.
• Data limits on a plot now start from a state of having “null” limits, rather than limits in the range
(0, 1). This has an effect on artists that only control limits in one direction, such as axvline and
axhline, since their limits will not longer also include the range (0, 1). This fixes some problems
where the computed limits would be dependent on the order in which artists were added to the axes.
• Fixed a bug in setting the position for the right/top spine with data position type. Previously, it would
draw the right or top spine at +1 data offset.
• In FancyArrow, the default arrow head width, head_width, has been made larger to produce a visible
arrow head. The new value of this kwarg is head_width = 20 * width.
• It is now possible to provide number of levels + 1 colors in the case of extend='both' for
contourf (or just number of levels colors for an extend value min or max) such that the resulting
29.10. Changes in 1.3.x
599
Matplotlib, Release 2.1.2
colormap’s set_under and set_over are defined appropriately. Any other number of colors will
continue to behave as before (if more colors are provided than levels, the colors will be unused).
A similar change has been applied to contour, where extend='both' would expect number of
levels + 2 colors.
• A new keyword extendrect in colorbar() and ColorbarBase allows one to control the shape of
colorbar extensions.
• The extension of MultiCursor to both vertical (default) and/or horizontal cursor implied that self.
line is replaced by self.vline for vertical cursors lines and self.hline is added for the horizontal
cursors lines.
• On POSIX platforms, the report_memory() function raises NotImplementedError instead of
OSError if the ps command cannot be run.
• The matplotlib.cbook.check_output() function has been moved to matplotlib.compat.
subprocess().
29.10.5 Configuration and rcParams
• On Linux, the user-specific matplotlibrc configuration file is now located in config/
matplotlib/matplotlibrc to conform to the XDG Base Directory Specification.
• 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.
• Removed call of grid() in plotfile(). To draw the axes grid, set the axes.grid rcParam to True,
or explicitly call grid().
29.11 Changes in 1.2.x
• The classic option of the rc parameter toolbar is deprecated and will be removed in the next
release.
• The isvector() method has been removed since it is no longer functional.
• The rasterization_zorder property on Axes a zorder below which artists are rasterized. This has
defaulted to -30000.0, but it now defaults to None, meaning no artists will be rasterized. In order to
rasterize artists below a given zorder value, set_rasterization_zorder must be explicitly called.
• In scatter(), and scatter, when specifying a marker using a tuple, the angle is now specified in
degrees, not radians.
• Using twinx() or twiny() no longer overrides the current locaters and formatters on the axes.
• In contourf(), the handling of the extend kwarg has changed. Formerly, the extended ranges were
mapped after to 0, 1 after being normed, so that they always corresponded to the extreme values of the
colormap. Now they are mapped outside this range so that they correspond to the special colormap
values determined by the set_under() and set_over() methods, which default to the colormap
end points.
600
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• The new rc parameter savefig.format replaces cairo.format and savefig.extension, and
sets the default file format used by matplotlib.figure.Figure.savefig().
• In pie() and pie(), one can now set the radius of the pie; setting the radius to ‘None’ (the default
value), will result in a pie with a radius of 1 as before.
• Use of projection_factory() is now deprecated in favour of axes class identification using
process_projection_requirements() followed by direct axes class invocation (at the time of
writing, functions which do this are: add_axes(), add_subplot() and gca()). Therefore:
key = figure._make_key(*args, **kwargs)
ispolar = kwargs.pop('polar', False)
projection = kwargs.pop('projection', None)
if ispolar:
if projection is not None and projection != 'polar':
raise ValueError('polar and projection args are inconsistent')
projection = 'polar'
ax = projection_factory(projection, self, rect, **kwargs)
key = self._make_key(*args, **kwargs)
# is now
projection_class, kwargs, key = \
process_projection_requirements(self, *args, **kwargs)
ax = projection_class(self, rect, **kwargs)
This change means that third party objects can expose themselves as Matplotlib axes by providing
a _as_mpl_axes method. See Developer’s guide for creating scales and transformations for more
detail.
• A new keyword extendfrac in colorbar() and ColorbarBase allows one to control the size of the
triangular minimum and maximum extensions on colorbars.
• A new keyword capthick in errorbar() has been added as an intuitive alias to the markeredgewidth
and mew keyword arguments, which indirectly controlled the thickness of the caps on the errorbars.
For backwards compatibility, specifying either of the original keyword arguments will override any
value provided by capthick.
• Transform subclassing behaviour is now subtly changed. If your transform implements a non-affine
transformation, then it should override the transform_non_affine method, rather than the generic
transform method. Previously transforms would define transform and then copy the method into
transform_non_affine:
class MyTransform(mtrans.Transform):
def transform(self, xy):
...
transform_non_affine = transform
This approach will no longer function correctly and should be changed to:
class MyTransform(mtrans.Transform):
def transform_non_affine(self, xy):
...
29.11. Changes in 1.2.x
601
Matplotlib, Release 2.1.2
• Artists no longer have x_isdata or y_isdata attributes; instead any artist’s transform can be interrogated with artist_instance.get_transform().contains_branch(ax.transData)
• Lines added to an axes now take into account their transform when updating the data and view limits.
This means transforms can now be used as a pre-transform. For instance:
>>> import matplotlib.pyplot as plt
>>> import matplotlib.transforms as mtrans
>>> ax = plt.axes()
>>> ax.plot(range(10), transform=mtrans.Affine2D().scale(10) + ax.transData)
>>> print(ax.viewLim)
Bbox('array([[ 0.,
0.],\n
[ 90., 90.]])')
• One can now easily get a transform which goes from one transform’s coordinate system to another,
in an optimized way, using the new subtract method on a transform. For instance, to go from data
coordinates to axes coordinates:
>>> import matplotlib.pyplot as plt
>>> ax = plt.axes()
>>> data2ax = ax.transData - ax.transAxes
>>> print(ax.transData.depth, ax.transAxes.depth)
3, 1
>>> print(data2ax.depth)
2
for versions before 1.2 this could only be achieved in a sub-optimal way, using ax.transData +
ax.transAxes.inverted() (depth is a new concept, but had it existed it would return 4 for this
example).
• twinx and twiny now returns an instance of SubplotBase if parent axes is an instance of SubplotBase.
• All Qt3-based backends are now deprecated due to the lack of py3k bindings. Qt and QtAgg backends
will continue to work in v1.2.x for py2.6 and py2.7. It is anticipated that the Qt3 support will be
completely removed for the next release.
• ColorConverter, Colormap and Normalize now subclasses object
• ContourSet instances no longer have a transform attribute. Instead, access the transform with the
get_transform method.
29.12 Changes in 1.1.x
• Added new matplotlib.sankey.Sankey for generating Sankey diagrams.
• In imshow(), setting interpolation to ‘nearest’ will now always mean that the nearest-neighbor interpolation is performed. If you want the no-op interpolation to be performed, choose ‘none’.
• There were errors in how the tri-functions were handling input parameters that had to be fixed. If your
tri-plots are not working correctly anymore, or you were working around apparent mistakes, please
see issue #203 in the github tracker. When in doubt, use kwargs.
602
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• The ‘symlog’ scale had some bad behavior in previous versions. This has now been fixed and users
should now be able to use it without frustrations. The fixes did result in some minor changes in
appearance for some users who may have been depending on the bad behavior.
• There is now a common set of markers for all plotting functions. Previously, some markers existed
only for scatter() or just for plot(). This is now no longer the case. This merge did result in a
conflict. The string ‘d’ now means “thin diamond” while ‘D’ will mean “regular diamond”.
29.13 Changes beyond 0.99.x
• The default behavior of matplotlib.axes.Axes.set_xlim(), matplotlib.axes.Axes.
set_ylim(), and matplotlib.axes.Axes.axis(), and their corresponding pyplot functions, has
been changed: when view limits are set explicitly with one of these methods, autoscaling is turned
off for the matching axis. A new auto kwarg is available to control this behavior. The limit kwargs
have been renamed to left and right instead of xmin and xmax, and bottom and top instead of ymin and
ymax. The old names may still be used, however.
• There are five new Axes methods with corresponding pyplot functions to facilitate autoscaling, tick
location, and tick label formatting, and the general appearance of ticks and tick labels:
– matplotlib.axes.Axes.autoscale() turns autoscaling on or off, and applies it.
– matplotlib.axes.Axes.margins() sets margins used to autoscale the matplotlib.axes.
Axes.viewLim based on the matplotlib.axes.Axes.dataLim.
– matplotlib.axes.Axes.locator_params() allows one to adjust axes locator parameters
such as nbins.
– matplotlib.axes.Axes.ticklabel_format() is a convenience method for controlling the
matplotlib.ticker.ScalarFormatter that is used by default with linear axes.
– matplotlib.axes.Axes.tick_params() controls direction, size, visibility, and color of
ticks and their labels.
• The matplotlib.axes.Axes.bar() method accepts a error_kw kwarg; it is a dictionary of kwargs
to be passed to the errorbar function.
• The matplotlib.axes.Axes.hist() color kwarg now accepts a sequence of color specs to match
a sequence of datasets.
• The EllipseCollection has been changed in two ways:
– There is a new units option, ‘xy’, that scales the ellipse with the data units. This matches the
:class:’~matplotlib.patches.Ellipse‘ scaling.
– The height and width kwargs have been changed to specify the height and width, again for
consistency with Ellipse, and to better match their names; previously they specified the halfheight and half-width.
• There is a new rc parameter axes.color_cycle, and the color cycle is now independent of the rc
parameter lines.color. matplotlib.Axes.set_default_color_cycle() is deprecated.
29.13. Changes beyond 0.99.x
603
Matplotlib, Release 2.1.2
• You can now print several figures to one pdf file and modify the document information dictionary of a
pdf file. See the docstrings of the class matplotlib.backends.backend_pdf.PdfPages for more
information.
• Removed configobj and enthought.traits packages, which are only required by the experimental traited
config and are somewhat out of date. If needed, install them independently.
• The new rc parameter savefig.extension sets the filename extension that is used by matplotlib.
figure.Figure.savefig() if its fname argument lacks an extension.
• In an effort to simplify the backend API, all clipping rectangles and paths are now passed in using
GraphicsContext objects, even on collections and images. Therefore:
draw_path_collection(self, master_transform, cliprect, clippath,
clippath_trans, paths, all_transforms, offsets,
offsetTrans, facecolors, edgecolors, linewidths,
linestyles, antialiaseds, urls)
# is now
draw_path_collection(self, gc, master_transform, paths, all_transforms,
offsets, offsetTrans, facecolors, edgecolors,
linewidths, linestyles, antialiaseds, urls)
draw_quad_mesh(self, master_transform, cliprect, clippath,
clippath_trans, meshWidth, meshHeight, coordinates,
offsets, offsetTrans, facecolors, antialiased,
showedges)
# is now
draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,
coordinates, offsets, offsetTrans, facecolors,
antialiased, showedges)
draw_image(self, x, y, im, bbox, clippath=None, clippath_trans=None)
# is now
draw_image(self, gc, x, y, im)
• There are four new Axes methods with corresponding pyplot functions that deal with unstructured
triangular grids:
– matplotlib.axes.Axes.tricontour() draws contour lines on a triangular grid.
– matplotlib.axes.Axes.tricontourf() draws filled contours on a triangular grid.
– matplotlib.axes.Axes.tripcolor() draws a pseudocolor plot on a triangular grid.
– matplotlib.axes.Axes.triplot() draws a triangular grid as lines and/or markers.
604
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.14 Changes in 0.99
• pylab no longer provides a load and save function. These are available in matplotlib.mlab, or you can
use numpy.loadtxt and numpy.savetxt for text files, or np.save and np.load for binary numpy arrays.
• User-generated colormaps can now be added to the set recognized by matplotlib.cm.get_cmap().
Colormaps can be made the default and applied to the current image using matplotlib.pyplot.
set_cmap().
• changed use_mrecords default to False in mlab.csv2rec since this is partially broken
• Axes instances no longer have a “frame” attribute. Instead, use the new “spines” attribute. Spines is a
dictionary where the keys are the names of the spines (e.g., ‘left’,’right’ and so on) and the values are
the artists that draw the spines. For normal (rectilinear) axes, these artists are Line2D instances. For
other axes (such as polar axes), these artists may be Patch instances.
• Polar plots no longer accept a resolution kwarg. Instead, each Path must specify its own number of
interpolation steps. This is unlikely to be a user-visible change – if interpolation of data is required,
that should be done before passing it to Matplotlib.
29.15 Changes for 0.98.x
• psd(), csd(), and cohere() will now automatically wrap negative frequency components to the beginning of the returned arrays. This is much more sensible behavior and makes them consistent with
specgram(). The previous behavior was more of an oversight than a design decision.
• Added new keyword parameters nonposx, nonposy to matplotlib.axes.Axes methods that set log
scale parameters. The default is still to mask out non-positive values, but the kwargs accept ‘clip’,
which causes non-positive values to be replaced with a very small positive value.
• Added new matplotlib.pyplot.fignum_exists() and matplotlib.pyplot.get_fignums();
they merely expose information that had been hidden in matplotlib._pylab_helpers.
• Deprecated numerix package.
• Added new matplotlib.image.imsave() and exposed it to the matplotlib.pyplot interface.
• Remove support for pyExcelerator in exceltools – use xlwt instead
• Changed the defaults of acorr and xcorr to use usevlines=True, maxlags=10 and normed=True since
these are the best defaults
• Following keyword parameters for matplotlib.label.Label are now deprecated and new set of
parameters are introduced. The new parameters are given as a fraction of the font-size. Also, scatteryoffsets, fancybox and columnspacing are added as keyword parameters.
29.14. Changes in 0.99
605
Matplotlib, Release 2.1.2
Deprecated
New
pad
labelsep
handlelen
handlestextsep
axespad
borderpad
labelspacing
handlelength
handletextpad
borderaxespad
• Removed the configobj and experimental traits rc support
• Modified matplotlib.mlab.psd(), matplotlib.mlab.csd(), matplotlib.mlab.cohere(),
and matplotlib.mlab.specgram() to scale one-sided densities by a factor of 2. Also, optionally scale the densities by the sampling frequency, which gives true values of densities that can be
integrated by the returned frequency values. This also gives better MATLAB compatibility. The corresponding matplotlib.axes.Axes methods and matplotlib.pyplot functions were updated as
well.
• Font lookup now uses a nearest-neighbor approach rather than an exact match. Some fonts may be
different in plots, but should be closer to what was requested.
• matplotlib.axes.Axes.set_xlim(), matplotlib.axes.Axes.set_ylim() now return a copy
of the viewlim array to avoid modify-in-place surprises.
• matplotlib.afm.AFM.get_fullname() and matplotlib.afm.AFM.get_familyname() no
longer raise an exception if the AFM file does not specify these optional attributes, but returns a
guess based on the required FontName attribute.
• Changed precision kwarg in matplotlib.pyplot.spy(); default is 0, and the string value ‘present’
is used for sparse arrays only to show filled locations.
• matplotlib.collections.EllipseCollection added.
• Added angles kwarg to matplotlib.pyplot.quiver() for more flexible specification of the arrow angles.
• Deprecated (raise NotImplementedError) all the mlab2 functions from matplotlib.mlab out of
concern that some of them were not clean room implementations.
• Methods
matplotlib.collections.Collection.get_offsets()
and
collections.Collection.set_offsets() added to Collection base class.
matplotlib.
• matplotlib.figure.Figure.figurePatch renamed matplotlib.figure.Figure.patch;
matplotlib.axes.Axes.axesPatch renamed matplotlib.axes.Axes.patch; matplotlib.
axes.Axes.axesFrame renamed matplotlib.axes.Axes.frame. matplotlib.axes.Axes.
get_frame(), which returns matplotlib.axes.Axes.patch, is deprecated.
• Changes in the matplotlib.contour.ContourLabeler attributes (matplotlib.pyplot.
clabel() function) so that they all have a form like .labelAttribute. The three attributes that
are most likely to be used by end users, .cl, .cl_xy and .cl_cvalues have been maintained for
the moment (in addition to their renamed versions), but they are deprecated and will eventually be
removed.
606
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• Moved several functions in matplotlib.mlab and matplotlib.cbook into a separate module
matplotlib.numerical_methods because they were unrelated to the initial purpose of mlab or
cbook and appeared more coherent elsewhere.
29.16 Changes for 0.98.1
• Removed broken matplotlib.axes3d support and replaced it with a non-implemented error pointing to 0.91.x
29.17 Changes for 0.98.0
• matplotlib.image.imread() now no longer always returns RGBA data—if the image is luminance or RGB, it will return a MxN or MxNx3 array if possible. Also uint8 is no longer always forced
to float.
• Rewrote the matplotlib.cm.ScalarMappable callback infrastructure to use matplotlib.cbook.
CallbackRegistry rather than custom callback handling. Any users of matplotlib.cm.
ScalarMappable.add_observer() of the ScalarMappable should use the matplotlib.cm.
ScalarMappable.callbacks CallbackRegistry instead.
• New axes function and Axes method provide control over the plot color cycle: matplotlib.axes.
set_default_color_cycle() and matplotlib.axes.Axes.set_color_cycle().
• Matplotlib now requires Python 2.4, so matplotlib.cbook will no longer provide set,
enumerate(), reversed() or izip() compatibility functions.
• In Numpy 1.0, bins are specified by the left edges only. The axes method matplotlib.axes.Axes.
hist() now uses future Numpy 1.3 semantics for histograms. Providing binedges, the last value
gives the upper-right edge now, which was implicitly set to +infinity in Numpy 1.0. This also means
that the last bin doesn’t contain upper outliers any more by default.
• New axes method and pyplot function, hexbin(), is an alternative to scatter() for large datasets.
It makes something like a pcolor() of a 2-D histogram, but uses hexagonal bins.
• New kwarg, symmetric, in matplotlib.ticker.MaxNLocator allows one require an axis to be
centered around zero.
• Toolkits must now be imported from mpl_toolkits (not matplotlib.toolkits)
29.17.1 Notes about the transforms refactoring
A major new feature of the 0.98 series is a more flexible and extensible transformation infrastructure, written
in Python/Numpy rather than a custom C extension.
The primary goal of this refactoring was to make it easier to extend matplotlib to support new kinds of
projections. This is mostly an internal improvement, and the possible user-visible changes it allows are yet
to come.
See matplotlib.transforms for a description of the design of the new transformation framework.
29.16. Changes for 0.98.1
607
Matplotlib, Release 2.1.2
For efficiency, many of these functions return views into Numpy arrays. This means that if you hold on to a
reference to them, their contents may change. If you want to store a snapshot of their current values, use the
Numpy array method copy().
The view intervals are now stored only in one place – in the matplotlib.axes.Axes instance, not in the
locator instances as well. This means locators must get their limits from their matplotlib.axis.Axis,
which in turn looks up its limits from the Axes. If a locator is used temporarily and not assigned to an
Axis or Axes, (e.g., in matplotlib.contour), a dummy axis must be created to store its bounds. Call
matplotlib.ticker.Locator.create_dummy_axis() to do so.
The functionality of Pbox has been merged with Bbox. Its methods now all return copies rather than modifying in place.
The following lists many of the simple changes necessary to update code from the old transformation framework to the new one. In particular, methods that return a copy are named with a verb in the past tense,
whereas methods that alter an object in place are named with a verb in the present tense.
608
Chapter 29. API Changes
Matplotlib, Release 2.1.2
matplotlib.transforms
Old method
New method
Bbox.get_bounds()
Bbox.width()
Bbox.height()
Bbox.intervalx().
get_bounds()
Bbox.intervalx().
set_bounds()
Bbox.intervaly().
get_bounds()
Bbox.intervaly().
set_bounds()
Bbox.xmin()
Bbox.ymin()
Bbox.xmax()
Bbox.ymax()
Bbox.overlaps(bboxes)
bbox_all(bboxes)
transforms.Bbox.bounds
transforms.Bbox.width
transforms.Bbox.height
transforms.Bbox.intervalx
[Bbox.intervalx is now a property.]
transforms.Bbox.intervaly
[Bbox.intervaly is now a property.]
transforms.Bbox.x0 or transforms.Bbox.xmin1
transforms.Bbox.y0 or transforms.Bbox.ymin1
transforms.Bbox.x1 or transforms.Bbox.xmax1
transforms.Bbox.y1 or transforms.Bbox.ymax1
Bbox.count_overlaps(bboxes)
Bbox.union(bboxes) [transforms.Bbox.union() is a staticmethod.]
lbwh_to_bbox(l, b, w, h)
Bbox.from_bounds(x0, y0, w, h)
[transforms.Bbox.
from_bounds() is a staticmethod.]
inverse_transform_bbox(trans,
Bbox.inverse_transformed(trans)
bbox)
Interval.
interval_contains_open(tuple, v)
contains_open(v)
Interval.contains(v)
interval_contains(tuple, v)
identity_transform()
matplotlib.transforms.IdentityTransform
blend_xy_sep_transform(xtrans,
blended_transform_factory(xtrans, ytrans)
ytrans)
scale_transform(xs, ys)
Affine2D().scale(xs[, ys])
get_bbox_transform(boxin, BboxTransform(boxin, boxout)
or
boxout)
BboxTransformFrom(boxin) or BboxTransformTo(boxout)
Transform.
Transform.transform(points)
seq_xy_tup(points)
Transform.
Transform.inverted().transform(points)
inverse_xy_tup(points)
1
The Bbox is bound by the points (x0, y0) to (x1, y1) and there is no defined order to these points, that is, x0 is not necessarily
the left edge of the box. To get the left edge of the Bbox, use the read-only property xmin.
29.17. Changes for 0.98.0
609
Matplotlib, Release 2.1.2
matplotlib.axes
Old method
New method
Axes.get_position()
Axes.set_position()
Axes.toggle_log_lineary()
Subplot class
matplotlib.axes.Axes.get_position()2
matplotlib.axes.Axes.set_position()3
matplotlib.axes.Axes.set_yscale()4
removed.
The Polar class has moved to matplotlib.projections.polar.
matplotlib.artist
Old method
New method
Artist.set_clip_path(path)
Artist.set_clip_path(path, transform)5
matplotlib.collections
Old method
New method
linestyle
linestyles6
matplotlib.colors
Old method
New method
ColorConvertor.
to_rgba_list(c)
ColorConvertor.to_rgba_array(c)
[matplotlib.colors.
ColorConvertor.to_rgba_array() returns an Nx4 Numpy array of RGBA
color quadruples.]
matplotlib.contour
Old method
New method
Contour.
_segments
matplotlib.contour.Contour.get_paths`() [Returns a list of matplotlib.
path.Path instances.]
2
matplotlib.axes.Axes.get_position() used to return a list of points, now it returns a matplotlib.transforms.Bbox
instance.
3
matplotlib.axes.Axes.set_position() now accepts either four scalars or a matplotlib.transforms.Bbox instance.
4
Since the recfactoring allows for more than two scale types (‘log’ or ‘linear’), it no longer makes sense to have a toggle.
Axes.toggle_log_lineary() has been removed.
5
matplotlib.artist.Artist.set_clip_path() now accepts a matplotlib.path.Path instance and a matplotlib.
transforms.Transform that will be applied to the path immediately before clipping.
6
Linestyles are now treated like all other collection attributes, i.e. a single value or multiple values may be provided.
610
Chapter 29. API Changes
Matplotlib, Release 2.1.2
matplotlib.figure
Old method
New method
Figure.dpi.get() / Figure.dpi.set()
matplotlib.figure.Figure.dpi (a property)
matplotlib.patches
Old method
New method
Patch.
get_verts()
matplotlib.patches.Patch.get_path() [Returns a matplotlib.path.
Path instance]
matplotlib.backend_bases
Old method
New method
GraphicsContext.
set_clip_rectangle(tuple)
GraphicsContext.get_clip_path()
GraphicsContext.set_clip_path()
GraphicsContext.
set_clip_rectangle(bbox)
GraphicsContext.get_clip_path()7
GraphicsContext.set_clip_path()8
RendererBase
New methods:
• draw_path(self, gc, path, transform, rgbFace)
• draw_markers(self, gc, marker_path, marker_trans, path, trans, rgbFace)
• draw_path_collection(self, master_transform, cliprect, clippath,
clippath_trans, paths, all_transforms, offsets, offsetTrans, facecolors,
edgecolors, linewidths, linestyles, antialiaseds) [optional]
Changed methods:
• draw_image(self, x, y, im, bbox)
clippath, clippath_trans)
is
now
draw_image(self, x, y, im, bbox,
Removed methods:
• draw_arc
• draw_line_collection
• draw_line
7
matplotlib.backend_bases.GraphicsContext.get_clip_path() returns a tuple of the form (path, affine_transform),
where path is a matplotlib.path.Path instance and affine_transform is a matplotlib.transforms.Affine2D instance.
8
matplotlib.backend_bases.GraphicsContext.set_clip_path() now only accepts a matplotlib.transforms.
TransformedPath instance.
29.17. Changes for 0.98.0
611
Matplotlib, Release 2.1.2
• draw_lines
• draw_point
• draw_quad_mesh
• draw_poly_collection
• draw_polygon
• draw_rectangle
• draw_regpoly_collection
29.18 Changes for 0.91.2
• For csv2rec(), checkrows=0 is the new default indicating all rows will be checked for type inference
• A warning is issued when an image is drawn on log-scaled axes, since it will not log-scale the image
data.
• Moved rec2gtk() to matplotlib.toolkits.gtktools
• Moved rec2excel() to matplotlib.toolkits.exceltools
• Removed, dead/experimental ExampleInfo, Namespace and Importer code from matplotlib.
__init__
29.19 Changes for 0.91.1
29.20 Changes for 0.91.0
• Changed cbook.is_file_like() to cbook.is_writable_file_like() and corrected behavior.
• Added ax kwarg to pyplot.colorbar() and Figure.colorbar() so that one can specify the axes
object from which space for the colorbar is to be taken, if one does not want to make the colorbar axes
manually.
• Changed cbook.reversed() so it yields a tuple rather than a (index, tuple). This agrees with the
python reversed builtin, and cbook only defines reversed if python doesn’t provide the builtin.
• Made skiprows=1 the default on csv2rec()
• The gd and paint backends have been deleted.
• The errorbar method and function now accept additional kwargs so that upper and lower limits can be
indicated by capping the bar with a caret instead of a straight line segment.
• The matplotlib.dviread file now has a parser for files like psfonts.map and pdftex.map, to map
TeX font names to external files.
612
Chapter 29. API Changes
Matplotlib, Release 2.1.2
• The file matplotlib.type1font contains a new class for Type 1 fonts. Currently it simply reads
pfa and pfb format files and stores the data in a way that is suitable for embedding in pdf files. In the
future the class might actually parse the font to allow e.g., subsetting.
• matplotlib.FT2Font now supports FT_Attach_File(). In practice this can be used to read an
afm file in addition to a pfa/pfb file, to get metrics and kerning information for a Type 1 font.
• The AFM class now supports querying CapHeight and stem widths. The get_name_char method now
has an isord kwarg like get_width_char.
• Changed pcolor() default to shading=’flat’; but as noted now in the docstring, it is preferable to
simply use the edgecolor kwarg.
• The mathtext font commands (\cal, \rm, \it, \tt) now behave as TeX does: they are in effect
until the next font change command or the end of the grouping. Therefore uses of $\cal{R}$
should be changed to ${\cal R}$. Alternatively, you may use the new LaTeX-style font commands (\mathcal, \mathrm, \mathit, \mathtt) which do affect the following group, e.g.,
$\mathcal{R}$.
• Text creation commands have a new default linespacing and a new linespacing kwarg, which is a
multiple of the maximum vertical extent of a line of ordinary text. The default is 1.2; linespacing=2
would be like ordinary double spacing, for example.
• Changed default kwarg in matplotlib.colors.Normalize.__init__`() to clip=False; clipping silently defeats the purpose of the special over, under, and bad values in the colormap, thereby
leading to unexpected behavior. The new default should reduce such surprises.
• Made the emit property of set_xlim() and set_ylim() True by default; removed the Axes custom
callback handling into a ‘callbacks’ attribute which is a CallbackRegistry instance. This now
supports the ‘xlim_changed’ and ‘ylim_changed’ Axes events.
29.21 Changes for 0.90.1
The file dviread.py has a (very limited and fragile) dvi reader
for usetex support. The API might change in the future so don't
depend on it yet.
Removed deprecated support for a float value as a gray-scale;
now it must be a string, like '0.5'. Added alpha kwarg to
ColorConverter.to_rgba_list.
New method set_bounds(vmin, vmax) for formatters, locators sets
the viewInterval and dataInterval from floats.
Removed deprecated colorbar_classic.
Line2D.get_xdata and get_ydata valid_only=False kwarg is replaced
by orig=True. When True, it returns the original data, otherwise
the processed data (masked, converted)
Some modifications to the units interface.
29.21. Changes for 0.90.1
613
Matplotlib, Release 2.1.2
units.ConversionInterface.tickers renamed to
units.ConversionInterface.axisinfo and it now returns a
units.AxisInfo object rather than a tuple. This will make it
easier to add axis info functionality (e.g., I added a default label
on this iteration) w/o having to change the tuple length and hence
the API of the client code every time new functionality is added.
Also, units.ConversionInterface.convert_to_value is now simply
named units.ConversionInterface.convert.
Axes.errorbar uses Axes.vlines and Axes.hlines to draw its error
limits int he vertical and horizontal direction. As you'll see
in the changes below, these functions now return a LineCollection
rather than a list of lines. The new return signature for
errorbar is ylins, caplines, errorcollections where
errorcollections is a xerrcollection, yerrcollection
Axes.vlines and Axes.hlines now create and returns a LineCollection, not a list
of lines. This is much faster. The kwarg signature has changed,
so consult the docs
MaxNLocator accepts a new Boolean kwarg ('integer') to force
ticks to integer locations.
Commands that pass an argument to the Text constructor or to
Text.set_text() now accept any object that can be converted
with '%s'. This affects xlabel(), title(), etc.
Barh now takes a **kwargs dict instead of most of the old
arguments. This helps ensure that bar and barh are kept in sync,
but as a side effect you can no longer pass e.g., color as a
positional argument.
ft2font.get_charmap() now returns a dict that maps character codes
to glyph indices (until now it was reversed)
Moved data files into lib/matplotlib so that setuptools' develop
mode works. Re-organized the mpl-data layout so that this source
structure is maintained in the installation. (i.e., the 'fonts' and
'images' sub-directories are maintained in site-packages.).
Suggest removing site-packages/matplotlib/mpl-data and
~/.matplotlib/ttffont.cache before installing
29.22 Changes for 0.90.0
All artists now implement a "pick" method which users should not
call. Rather, set the "picker" property of any artist you want to
pick on (the epsilon distance in points for a hit test) and
register with the "pick_event" callback. See
examples/pick_event_demo.py for details
614
Chapter 29. API Changes
Matplotlib, Release 2.1.2
Bar, barh, and hist have "log" binary kwarg: log=True
sets the ordinate to a log scale.
Boxplot can handle a list of vectors instead of just
an array, so vectors can have different lengths.
Plot can handle 2-D x and/or y; it plots the columns.
Added linewidth kwarg to bar and barh.
Made the default Artist._transform None (rather than invoking
identity_transform for each artist only to have it overridden
later). Use artist.get_transform() rather than artist._transform,
even in derived classes, so that the default transform will be
created lazily as needed
New LogNorm subclass of Normalize added to colors.py.
All Normalize subclasses have new inverse() method, and
the __call__() method has a new clip kwarg.
Changed class names in colors.py to match convention:
normalize -> Normalize, no_norm -> NoNorm. Old names
are still available for now.
Removed obsolete pcolor_classic command and method.
Removed lineprops and markerprops from the Annotation code and
replaced them with an arrow configurable with kwarg arrowprops.
See examples/annotation_demo.py - JDH
29.23 Changes for 0.87.7
Completely reworked the annotations API because I found the old
API cumbersome. The new design is much more legible and easy to
read. See matplotlib.text.Annotation and
examples/annotation_demo.py
markeredgecolor and markerfacecolor cannot be configured in
matplotlibrc any more. Instead, markers are generally colored
automatically based on the color of the line, unless marker colors
are explicitly set as kwargs - NN
Changed default comment character for load to '#' - JDH
math_parse_s_ft2font_svg from mathtext.py & mathtext2.py now returns
width, height, svg_elements. svg_elements is an instance of Bunch (
cmbook.py) and has the attributes svg_glyphs and svg_lines, which are both
lists.
Renderer.draw_arc now takes an additional parameter, rotation.
29.23. Changes for 0.87.7
615
Matplotlib, Release 2.1.2
It specifies to draw the artist rotated in degrees anticlockwise. It was added for rotated ellipses.
Renamed Figure.set_figsize_inches to Figure.set_size_inches to
better match the get method, Figure.get_size_inches.
Removed the copy_bbox_transform from transforms.py; added
shallowcopy methods to all transforms. All transforms already
had deepcopy methods.
FigureManager.resize(width, height): resize the window
specified in pixels
barh: x and y args have been renamed to width and bottom
respectively, and their order has been swapped to maintain
a (position, value) order.
bar and barh: now accept kwarg 'edgecolor'.
bar and barh: The left, height, width and bottom args can
now all be scalars or sequences; see docstring.
barh: now defaults to edge aligned instead of center
aligned bars
bar, barh and hist: Added a keyword arg 'align' that
controls between edge or center bar alignment.
Collections: PolyCollection and LineCollection now accept
vertices or segments either in the original form [(x,y),
(x,y), ...] or as a 2D numerix array, with X as the first column
and Y as the second. Contour and quiver output the numerix
form. The transforms methods Bbox.update() and
Transformation.seq_xy_tups() now accept either form.
Collections: LineCollection is now a ScalarMappable like
PolyCollection, etc.
Specifying a grayscale color as a float is deprecated; use
a string instead, e.g., 0.75 -> '0.75'.
Collections: initializers now accept any mpl color arg, or
sequence of such args; previously only a sequence of rgba
tuples was accepted.
Colorbar: completely new version and api; see docstring. The
original version is still accessible as colorbar_classic, but
is deprecated.
Contourf: "extend" kwarg replaces "clip_ends"; see docstring.
Masked array support added to pcolormesh.
Modified aspect-ratio handling:
616
Chapter 29. API Changes
Matplotlib, Release 2.1.2
Removed aspect kwarg from imshow
Axes methods:
set_aspect(self, aspect, adjustable=None, anchor=None)
set_adjustable(self, adjustable)
set_anchor(self, anchor)
Pylab interface:
axis('image')
Backend developers: ft2font's load_char now takes a flags
argument, which you can OR together from the LOAD_XXX
constants.
29.24 Changes for 0.86
Matplotlib data is installed into the matplotlib module.
This is similar to package_data. This should get rid of
having to check for many possibilities in _get_data_path().
The MATPLOTLIBDATA env key is still checked first to allow
for flexibility.
1) Separated the color table data from cm.py out into
a new file, _cm.py, to make it easier to find the actual
code in cm.py and to add new colormaps. Everything
from _cm.py is imported by cm.py, so the split should be
transparent.
2) Enabled automatic generation of a colormap from
a list of colors in contour; see modified
examples/contour_demo.py.
3) Support for imshow of a masked array, with the
ability to specify colors (or no color at all) for
masked regions, and for regions that are above or
below the normally mapped region. See
examples/image_masked.py.
4) In support of the above, added two new classes,
ListedColormap, and no_norm, to colors.py, and modified
the Colormap class to include common functionality. Added
a clip kwarg to the normalize class.
29.25 Changes for 0.85
Made xtick and ytick separate props in rc
made pos=None the default for tick formatters rather than 0 to
indicate "not supplied"
Removed "feature" of minor ticks which prevents them from
overlapping major ticks. Often you want major and minor ticks at
the same place, and can offset the major ticks with the pad. This
29.24. Changes for 0.86
617
Matplotlib, Release 2.1.2
could be made configurable
Changed the internal structure of contour.py to a more OO style.
Calls to contour or contourf in axes.py or pylab.py now return
a ContourSet object which contains references to the
LineCollections or PolyCollections created by the call,
as well as the configuration variables that were used.
The ContourSet object is a "mappable" if a colormap was used.
Added a clip_ends kwarg to contourf. From the docstring:
* clip_ends = True
If False, the limits for color scaling are set to the
minimum and maximum contour levels.
True (default) clips the scaling limits. Example:
if the contour boundaries are V = [-100, 2, 1, 0, 1, 2, 100],
then the scaling limits will be [-100, 100] if clip_ends
is False, and [-3, 3] if clip_ends is True.
Added kwargs linewidths, antialiased, and nchunk to contourf. These
are experimental; see the docstring.
Changed Figure.colorbar():
kw argument order changed;
if mappable arg is a non-filled ContourSet, colorbar() shows
lines instead hof polygons.
if mappable arg is a filled ContourSet with clip_ends=True,
the endpoints are not labelled, so as to give the
correct impression of open-endedness.
Changed LineCollection.get_linewidths to get_linewidth, for
consistency.
29.26 Changes for 0.84
Unified argument handling between hlines and vlines. Both now
take optionally a fmt argument (as in plot) and a keyword args
that can be passed onto Line2D.
Removed all references to "data clipping" in rc and lines.py since
these were not used and not optimized. I'm sure they'll be
resurrected later with a better implementation when needed.
'set' removed - no more deprecation warnings.
Use 'setp' instead.
Backend developers: Added flipud method to image and removed it
from to_str. Removed origin kwarg from backend.draw_image.
origin is handled entirely by the frontend now.
618
Chapter 29. API Changes
Matplotlib, Release 2.1.2
29.27 Changes for 0.83
- Made HOME/.matplotlib the new config dir where the matplotlibrc
file, the ttf.cache, and the tex.cache live. The new default
filenames in .matplotlib have no leading dot and are not hidden.
e.g., the new names are matplotlibrc, tex.cache, and ttffont.cache.
This is how ipython does it so it must be right.
If old files are found, a warning is issued and they are moved to
the new location.
- backends/__init__.py no longer imports new_figure_manager,
draw_if_interactive and show from the default backend, but puts
these imports into a call to pylab_setup. Also, the Toolbar is no
longer imported from WX/WXAgg. New usage:
from backends import pylab_setup
new_figure_manager, draw_if_interactive, show = pylab_setup()
- Moved Figure.get_width_height() to FigureCanvasBase. It now
returns int instead of float.
29.28 Changes for 0.82
- toolbar import change in GTKAgg, GTKCairo and WXAgg
- Added subplot config tool to GTK* backends -- note you must now
import the NavigationToolbar2 from your backend of choice rather
than from backend_gtk because it needs to know about the backend
specific canvas -- see examples/embedding_in_gtk2.py. Ditto for
wx backend -- see examples/embedding_in_wxagg.py
- hist bin change
Sean Richards notes there was a problem in the way we created
the binning for histogram, which made the last bin
underrepresented. From his post:
I see that hist uses the linspace function to create the bins
and then uses searchsorted to put the values in their correct
bin. That's all good but I am confused over the use of linspace
for the bin creation. I wouldn't have thought that it does
what is needed, to quote the docstring it creates a "Linear
spaced array from min to max". For it to work correctly
shouldn't the values in the bins array be the same bound for
each bin? (i.e. each value should be the lower bound of a
bin). To provide the correct bins for hist would it not be
something like
29.27. Changes for 0.83
619
Matplotlib, Release 2.1.2
def bins(xmin, xmax, N):
if N==1: return xmax
dx = (xmax-xmin)/N # instead of N-1
return xmin + dx*arange(N)
This suggestion is implemented in 0.81. My test script with these
changes does not reveal any bias in the binning
from matplotlib.numerix.mlab import randn, rand, zeros, Float
from matplotlib.mlab import hist, mean
Nbins = 50
Ntests = 200
results = zeros((Ntests,Nbins), typecode=Float)
for i in range(Ntests):
print 'computing', i
x = rand(10000)
n, bins = hist(x, Nbins)
results[i] = n
print mean(results)
29.29 Changes for 0.81
- pylab and artist "set" functions renamed to setp to avoid clash
with python2.4 built-in set. Current version will issue a
deprecation warning which will be removed in future versions
- imshow interpolation arguments changes for advanced interpolation
schemes. See help imshow, particularly the interpolation,
filternorm and filterrad kwargs
- Support for masked arrays has been added to the plot command and
to the Line2D object. Only the valid points are plotted. A
"valid_only" kwarg was added to the get_xdata() and get_ydata()
methods of Line2D; by default it is False, so that the original
data arrays are returned. Setting it to True returns the plottable
points.
- contour changes:
Masked arrays: contour and contourf now accept masked arrays as
the variable to be contoured. Masking works correctly for
contour, but a bug remains to be fixed before it will work for
contourf. The "badmask" kwarg has been removed from both
functions.
Level argument changes:
Old version: a list of levels as one of the positional
620
Chapter 29. API Changes
Matplotlib, Release 2.1.2
arguments specified the lower bound of each filled region; the
upper bound of the last region was taken as a very large
number. Hence, it was not possible to specify that z values
between 0 and 1, for example, be filled, and that values
outside that range remain unfilled.
New version: a list of N levels is taken as specifying the
boundaries of N-1 z ranges. Now the user has more control over
what is colored and what is not. Repeated calls to contourf
(with different colormaps or color specifications, for example)
can be used to color different ranges of z. Values of z
outside an expected range are left uncolored.
Example:
Old: contourf(z, [0, 1, 2]) would yield 3 regions: 0-1, 1-2, and >2.
New: it would yield 2 regions: 0-1, 1-2. If the same 3 regions were
desired, the equivalent list of levels would be [0, 1, 2,
1e38].
29.30 Changes for 0.80
- xlim/ylim/axis always return the new limits regardless of
arguments. They now take kwargs which allow you to selectively
change the upper or lower limits while leaving unnamed limits
unchanged. See help(xlim) for example
29.31 Changes for 0.73
- Removed deprecated ColormapJet and friends
- Removed all error handling from the verbose object
- figure num of zero is now allowed
29.32 Changes for 0.72
- Line2D, Text, and Patch copy_properties renamed update_from and
moved into artist base class
- LineCollecitons.color renamed to LineCollections.set_color for
consistency with set/get introspection mechanism,
- pylab figure now defaults to num=None, which creates a new figure
with a guaranteed unique number
29.30. Changes for 0.80
621
Matplotlib, Release 2.1.2
- contour method syntax changed - now it is MATLAB compatible
unchanged: contour(Z)
old: contour(Z, x=Y, y=Y)
new: contour(X, Y, Z)
see http://matplotlib.sf.net/matplotlib.pylab.html#-contour
- Increased the default resolution for save command.
- Renamed the base attribute of the ticker classes to _base to avoid conflict
with the base method. Sitt for subs
- subs=none now does autosubbing in the tick locator.
- New subplots that overlap old will delete the old axes. If you
do not want this behavior, use fig.add_subplot or the axes
command
29.33 Changes for 0.71
Significant numerix namespace changes, introduced to resolve
namespace clashes between python built-ins and mlab names.
Refactored numerix to maintain separate modules, rather than
folding all these names into a single namespace. See the following
mailing list threads for more information and background
http://sourceforge.net/mailarchive/forum.php?thread_id=6398890&forum_id=36187
http://sourceforge.net/mailarchive/forum.php?thread_id=6323208&forum_id=36187
OLD usage
from matplotlib.numerix import array, mean, fft
NEW usage
from matplotlib.numerix import array
from matplotlib.numerix.mlab import mean
from matplotlib.numerix.fft import fft
numerix dir structure mirrors numarray (though it is an incomplete
implementation)
numerix
numerix/mlab
numerix/linear_algebra
numerix/fft
numerix/random_array
622
Chapter 29. API Changes
Matplotlib, Release 2.1.2
but of course you can use 'numerix : Numeric' and still get the
symbols.
pylab still imports most of the symbols from Numerix, MLab, fft,
etc, but is more cautious. For names that clash with python names
(min, max, sum), pylab keeps the builtins and provides the numeric
versions with an a* prefix, e.g., (amin, amax, asum)
29.34 Changes for 0.70
MplEvent factored into a base class Event and derived classes
MouseEvent and KeyEvent
Removed definct set_measurement in wx toolbar
29.35 Changes for 0.65.1
removed add_axes and add_subplot from backend_bases. Use
figure.add_axes and add_subplot instead. The figure now manages the
current axes with gca and sca for get and set current axes. If you
have code you are porting which called, e.g., figmanager.add_axes, you
can now simply do figmanager.canvas.figure.add_axes.
29.36 Changes for 0.65
mpl_connect and mpl_disconnect in the MATLAB interface renamed to
connect and disconnect
Did away with the text methods for angle since they were ambiguous.
fontangle could mean fontstyle (obligue, etc) or the rotation of the
text. Use style and rotation instead.
29.37 Changes for 0.63
Dates are now represented internally as float days since 0001-01-01,
UTC.
All date tickers and formatters are now in matplotlib.dates, rather
than matplotlib.tickers
converters have been abolished from all functions and classes.
29.34. Changes for 0.70
623
Matplotlib, Release 2.1.2
num2date and date2num are now the converter functions for all date
plots
Most of the date tick locators have a different meaning in their
constructors. In the prior implementation, the first argument was a
base and multiples of the base were ticked. e.g.,
HourLocator(5)
# old: tick every 5 minutes
In the new implementation, the explicit points you want to tick are
provided as a number or sequence
HourLocator(range(0,5,61))
# new: tick every 5 minutes
This gives much greater flexibility. I have tried to make the
default constructors (no args) behave similarly, where possible.
Note that YearLocator still works under the base/multiple scheme.
The difference between the YearLocator and the other locators is
that years are not recurrent.
Financial functions:
matplotlib.finance.quotes_historical_yahoo(ticker, date1, date2)
date1, date2 are now datetime instances. Return value is a list
of quotes where the quote time is a float - days since gregorian
start, as returned by date2num
See examples/finance_demo.py for example usage of new API
29.38 Changes for 0.61
canvas.connect is now deprecated for event handling. use
mpl_connect and mpl_disconnect instead. The callback signature is
func(event) rather than func(widget, event)
29.39 Changes for 0.60
ColormapJet and Grayscale are deprecated. For backwards
compatibility, they can be obtained either by doing
from matplotlib.cm import ColormapJet
or
from matplotlib.matlab import *
624
Chapter 29. API Changes
Matplotlib, Release 2.1.2
They are replaced by cm.jet and cm.grey
29.40 Changes for 0.54.3
removed the set_default_font / get_default_font scheme from the
font_manager to unify customization of font defaults with the rest of
the rc scheme. See examples/font_properties_demo.py and help(rc) in
matplotlib.matlab.
29.41 Changes for 0.54
29.41.1 MATLAB interface
dpi
Several of the backends used a PIXELS_PER_INCH hack that I added to try and make images render
consistently across backends. This just complicated matters. So you may find that some font sizes and line
widths appear different than before. Apologies for the inconvenience. You should set the dpi to an accurate
value for your screen to get true sizes.
pcolor and scatter
There are two changes to the MATLAB interface API, both involving the patch drawing commands. For
efficiency, pcolor and scatter have been rewritten to use polygon collections, which are a new set of objects
from matplotlib.collections designed to enable efficient handling of large collections of objects. These new
collections make it possible to build large scatter plots or pcolor plots with no loops at the python level,
and are significantly faster than their predecessors. The original pcolor and scatter functions are retained as
pcolor_classic and scatter_classic.
The return value from pcolor is a PolyCollection. Most of the propertes that are available on rectangles or
other patches are also available on PolyCollections, e.g., you can say:
c = scatter(blah, blah)
c.set_linewidth(1.0)
c.set_facecolor('r')
c.set_alpha(0.5)
or:
c = scatter(blah, blah)
set(c, 'linewidth', 1.0, 'facecolor', 'r', 'alpha', 0.5)
Because the collection is a single object, you no longer need to loop over the return value of scatter or pcolor
to set properties for the entire list.
29.40. Changes for 0.54.3
625
Matplotlib, Release 2.1.2
If you want the different elements of a collection to vary on a property, e.g., to have different line widths,
see matplotlib.collections for a discussion on how to set the properties as a sequence.
For scatter, the size argument is now in points^2 (the area of the symbol in points) as in MATLAB and is
not in data coords as before. Using sizes in data coords caused several problems. So you will need to adjust
your size arguments accordingly or use scatter_classic.
mathtext spacing
For reasons not clear to me (and which I’ll eventually fix) spacing no longer works in font groups. However,
I added three new spacing commands which compensate for this ‘’ (regular space), ‘/’ (small space) and
‘hspace{frac}’ where frac is a fraction of fontsize in points. You will need to quote spaces in font strings,
is:
title(r'$\rm{Histogram\ of\ IQ:}\ \mu=100,\ \sigma=15$')
29.41.2 Object interface - Application programmers
Autoscaling
The x and y axis instances no longer have autoscale view.
axes.autoscale_view
These are handled by
Axes creation
You should not instantiate your own Axes any more using the OO API. Rather, create a Figure
as before and in place of:
f = Figure(figsize=(5,4), dpi=100)
a = Subplot(f, 111)
f.add_axis(a)
use:
f = Figure(figsize=(5,4), dpi=100)
a = f.add_subplot(111)
That is, add_axis no longer exists and is replaced by:
add_axes(rect, axisbg=defaultcolor, frameon=True)
add_subplot(num, axisbg=defaultcolor, frameon=True)
Artist methods
If you define your own Artists, you need to rename the _draw method to draw
626
Chapter 29. API Changes
Matplotlib, Release 2.1.2
Bounding boxes
matplotlib.transforms.Bound2D is replaced by matplotlib.transforms.Bbox. If you want to
construct a bbox from left, bottom, width, height (the signature for Bound2D), use matplotlib.transforms.lbwh_to_bbox, as in
bbox = clickBBox = lbwh_to_bbox(left, bottom, width, height)
The Bbox has a different API than the Bound2D. e.g., if you want to get the width and height
of the bbox
OLD:: width = fig.bbox.x.interval() height = fig.bbox.y.interval()
New:: width = fig.bbox.width() height = fig.bbox.height()
Object constructors
You no longer pass the bbox, dpi, or transforms to the various Artist constructors. The old way
or creating lines and rectangles was cumbersome because you had to pass so many attributes to
the Line2D and Rectangle classes not related directly to the geometry and properties of the object. Now default values are added to the object when you call axes.add_line or axes.add_patch,
so they are hidden from the user.
If you want to define a custom transformation on these objects, call o.set_transform(trans)
where trans is a Transformation instance.
In prior versions of you wanted to add a custom line in data coords, you would have to do
l = Line2D(dpi, bbox, x, y, color = color, transx = transx, transy = transy, )
now all you need is
l = Line2D(x, y, color=color)
and the axes will set the transformation for you (unless you have set your own already, in which
case it will eave it unchanged)
Transformations
The entire transformation architecture has been rewritten. Previously the x and y transformations where stored in the xaxis and yaxis instances. The problem with this approach is
it only allows for separable transforms (where the x and y transformations don’t depend on
one another). But for cases like polar, they do. Now transformations operate on x,y together.
There is a new base class matplotlib.transforms.Transformation and two concrete implementations, matplotlib.transforms.SeparableTransformation and matplotlib.transforms.Affine. The
SeparableTransformation is constructed with the bounding box of the input (this determines
the rectangular coordinate system of the input, i.e., the x and y view limits), the bounding box
of the display, and possibly nonlinear transformations of x and y. The 2 most frequently used
transformations, data coordinates -> display and axes coordinates -> display are available as
ax.transData and ax.transAxes. See alignment_demo.py which uses axes coords.
Also, the transformations should be much faster now, for two reasons
29.41. Changes for 0.54
627
Matplotlib, Release 2.1.2
• they are written entirely in extension code
• because they operate on x and y together, they can do the entire transformation in one
loop. Earlier I did something along the lines of:
xt = sx*func(x) + tx
yt = sy*func(y) + ty
Although this was done in numerix, it still involves 6 length(x) for-loops (the multiply,
add, and function evaluation each for x and y). Now all of that is done in a single pass.
If you are using transformations and bounding boxes to get the cursor position in data coordinates, the method calls are a little different now. See the updated examples/coords_demo.py
which shows you how to do this.
Likewise, if you are using the artist bounding boxes to pick items on the canvas with the
GUI, the bbox methods are somewhat different. You will need to see the updated examples/object_picker.py.
See unit/transforms_unit.py for many examples using the new transformations.
29.42 Changes for 0.50
* refactored Figure class so it is no longer backend dependent.
FigureCanvasBackend takes over the backend specific duties of the
Figure. matplotlib.backend_bases.FigureBase moved to
matplotlib.figure.Figure.
* backends must implement FigureCanvasBackend (the thing that
controls the figure and handles the events if any) and
FigureManagerBackend (wraps the canvas and the window for MATLAB
interface). FigureCanvasBase implements a backend switching
mechanism
* Figure is now an Artist (like everything else in the figure) and
is totally backend independent
* GDFONTPATH renamed to TTFPATH
* backend faceColor argument changed to rgbFace
* colormap stuff moved to colors.py
* arg_to_rgb in backend_bases moved to class ColorConverter in
colors.py
* GD users must upgrade to gd-2.0.22 and gdmodule-0.52 since new gd
features (clipping, antialiased lines) are now used.
* Renderer must implement points_to_pixels
Migrating code:
628
Chapter 29. API Changes
Matplotlib, Release 2.1.2
MATLAB interface:
The only API change for those using the MATLAB interface is in how
you call figure redraws for dynamically updating figures. In the
old API, you did
fig.draw()
In the new API, you do
manager = get_current_fig_manager()
manager.canvas.draw()
See the examples system_monitor.py, dynamic_demo.py, and anim.py
API
There is one important API change for application developers.
Figure instances used subclass GUI widgets that enabled them to be
placed directly into figures. e.g., FigureGTK subclassed
gtk.DrawingArea. Now the Figure class is independent of the
backend, and FigureCanvas takes over the functionality formerly
handled by Figure. In order to include figures into your apps,
you now need to do, for example
# gtk example
fig = Figure(figsize=(5,4), dpi=100)
canvas = FigureCanvasGTK(fig) # a gtk.DrawingArea
canvas.show()
vbox.pack_start(canvas)
If you use the NavigationToolbar, this in now initialized with a
FigureCanvas, not a Figure. The examples embedding_in_gtk.py,
embedding_in_gtk2.py, and mpl_with_glade.py all reflect the new
API so use these as a guide.
All prior calls to
figure.draw() and
figure.print_figure(args)
should now be
canvas.draw() and
canvas.print_figure(args)
Apologies for the inconvenience. This refactorization brings
significant more freedom in developing matplotlib and should bring
better plotting capabilities, so I hope the inconvenience is worth
it.
29.42. Changes for 0.50
629
Matplotlib, Release 2.1.2
29.43 Changes for 0.42
* Refactoring AxisText to be backend independent. Text drawing and
get_window_extent functionality will be moved to the Renderer.
* backend_bases.AxisTextBase is now text.Text module
* All the erase and reset functionality removed from AxisText - not
needed with double buffered drawing. Ditto with state change.
Text instances have a get_prop_tup method that returns a hashable
tuple of text properties which you can use to see if text props
have changed, e.g., by caching a font or layout instance in a dict
with the prop tup as a key -- see RendererGTK.get_pango_layout in
backend_gtk for an example.
* Text._get_xy_display renamed Text.get_xy_display
* Artist set_renderer and wash_brushes methods removed
* Moved Legend class from matplotlib.axes into matplotlib.legend
* Moved Tick, XTick, YTick, Axis, XAxis, YAxis from matplotlib.axes
to matplotlib.axis
* moved process_text_args to matplotlib.text
* After getting Text handled in a backend independent fashion, the
import process is much cleaner since there are no longer cyclic
dependencies
* matplotlib.matlab._get_current_fig_manager renamed to
matplotlib.matlab.get_current_fig_manager to allow user access to
the GUI window attribute, e.g., figManager.window for GTK and
figManager.frame for wx
29.44 Changes for 0.40
- Artist
* __init__ takes a DPI instance and a Bound2D instance which is
the bounding box of the artist in display coords
* get_window_extent returns a Bound2D instance
* set_size is removed; replaced by bbox and dpi
* the clip_gc method is removed. Artists now clip themselves with
their box
* added _clipOn boolean attribute. If True, gc clip to bbox.
- AxisTextBase
* Initialized with a transx, transy which are Transform instances
* set_drawing_area removed
* get_left_right and get_top_bottom are replaced by get_window_extent
630
Chapter 29. API Changes
Matplotlib, Release 2.1.2
- Line2D Patches now take transx, transy
* Initialized with a transx, transy which are Transform instances
- Patches
* Initialized with a transx, transy which are Transform instances
- FigureBase attributes dpi is a DPI intance rather than scalar and
new attribute bbox is a Bound2D in display coords, and I got rid
of the left, width, height, etc... attributes. These are now
accessible as, for example, bbox.x.min is left, bbox.x.interval()
is width, bbox.y.max is top, etc...
- GcfBase attribute pagesize renamed to figsize
- Axes
* removed figbg attribute
* added fig instance to __init__
* resizing is handled by figure call to resize.
- Subplot
* added fig instance to __init__
- Renderer methods for patches now take gcEdge and gcFace instances.
gcFace=None takes the place of filled=False
- True and False symbols provided by cbook in a python2.3 compatible
way
- new module transforms supplies Bound1D, Bound2D and Transform
instances and more
- Changes to the MATLAB helpers API
* _matlab_helpers.GcfBase is renamed by Gcf. Backends no longer
need to derive from this class. Instead, they provide a factory
function new_figure_manager(num, figsize, dpi). The destroy
method of the GcfDerived from the backends is moved to the derived
FigureManager.
* FigureManagerBase moved to backend_bases
* Gcf.get_all_figwins renamed to Gcf.get_all_fig_managers
Jeremy:
Make sure to self._reset = False in AxisTextWX._set_font.
something missing in my backend code.
29.44. Changes for 0.40
This was
631
Matplotlib, Release 2.1.2
632
Chapter 29. API Changes
CHAPTER
THIRTY
THE TOP LEVEL MATPLOTLIB MODULE
matplotlib.use(arg, warn=True, force=False)
Set the matplotlib backend to one of the known backends.
The argument is case-insensitive. warn specifies whether a warning should be issued if a backend has
already been set up. force is an experimental flag that tells matplotlib to attempt to initialize a new
backend by reloading the backend module.
Note: This function must be called before importing pyplot for the first time; or, if you are not
using pyplot, it must be called before importing matplotlib.backends. If warn is True, a warning is
issued if you try and call this after pylab or pyplot have been loaded. In certain black magic use cases,
e.g. pyplot.switch_backend(), we are doing the reloading necessary to make the backend switch
work (in some cases, e.g., pure image backends) so one can set warn=False to suppress the warnings.
To find out which backend is currently set, see matplotlib.get_backend().
matplotlib.get_backend()
Return the name of the current backend.
matplotlib.rcParams
An instance of RcParams for handling default matplotlib values.
matplotlib.rc_context(rc=None, fname=None)
Return a context manager for managing rc settings.
This allows one to do:
with mpl.rc_context(fname='screen.rc'):
plt.plot(x, a)
with mpl.rc_context(fname='print.rc'):
plt.plot(x, b)
plt.plot(x, c)
The ‘a’ vs ‘x’ and ‘c’ vs ‘x’ plots would have settings from ‘screen.rc’, while the ‘b’ vs ‘x’ plot would
have settings from ‘print.rc’.
A dictionary can also be passed to the context manager:
with mpl.rc_context(rc={'text.usetex': True}, fname='screen.rc'):
plt.plot(x, a)
633
Matplotlib, Release 2.1.2
The ‘rc’ dictionary takes precedence over the settings loaded from ‘fname’. Passing a dictionary only
is also valid. For example a common usage is:
with mpl.rc_context(rc={'interactive': False}):
fig, ax = plt.subplots()
ax.plot(range(3), range(3))
fig.savefig('A.png', format='png')
plt.close(fig)
matplotlib.rc(group, **kwargs)
Set the current rc params. Group is the grouping for the rc, e.g., for lines.linewidth the group
is lines, for axes.facecolor, the group is axes, and so on. Group may also be a list or tuple of
group names, e.g., (xtick, ytick). kwargs is a dictionary attribute name/value pairs, e.g.,:
rc('lines', linewidth=2, color='r')
sets the current rc params and is equivalent to:
rcParams['lines.linewidth'] = 2
rcParams['lines.color'] = 'r'
The following aliases are available to save typing for interactive users:
Alias
Property
‘lw’
‘ls’
‘c’
‘fc’
‘ec’
‘mew’
‘aa’
‘linewidth’
‘linestyle’
‘color’
‘facecolor’
‘edgecolor’
‘markeredgewidth’
‘antialiased’
Thus you could abbreviate the above rc command as:
rc('lines', lw=2, c='r')
Note you can use python’s kwargs dictionary facility to store dictionaries of default parameters. e.g.,
you can customize the font rc as follows:
font = {'family' : 'monospace',
'weight' : 'bold',
'size'
: 'larger'}
rc('font', **font)
# pass in the font dict as kwargs
This enables you to easily switch between several configurations. Use matplotlib.style.
use('default') or rcdefaults() to restore the default rc params after changes.
634
Chapter 30. The top level matplotlib module
Matplotlib, Release 2.1.2
matplotlib.rc_file(fname)
Update rc params from file.
matplotlib.rcdefaults()
Restore the rc params from Matplotlib’s internal defaults.
See also:
rc_file_defaults Restore the rc params from the rc file originally loaded by Matplotlib.
matplotlib.style.use Use a specific style file. Call style.use('default') to restore the
default style.
matplotlib.rc_file_defaults()
Restore the rc params from the original rc file loaded by Matplotlib.
class matplotlib.RcParams(*args, **kwargs)
A dictionary object including validation
validating functions are defined and associated with rc parameters in matplotlib.rcsetup
find_all(pattern)
Return the subset of this RcParams dictionary whose keys match, using re.search(), the
given pattern.
Note: Changes to the returned dictionary are not propagated to the parent RcParams dictionary.
msg_depr = '%s is deprecated and replaced with %s; please use the latter.'
msg_depr_ignore = '%s is deprecated and ignored. Use %s'
msg_depr_set = '%s is deprecated. Please remove it from your matplotlibrc and/or style fil
msg_obsolete = '%s is obsolete. Please remove it from your matplotlibrc and/or style files
validate = {'_internal.classic_mode':
<function validate_bool at 0x7f9a2903c510>, 'agg.pa
matplotlib.rc_params(fail_on_error=False)
Return a matplotlib.RcParams instance from the default matplotlib rc file.
matplotlib.rc_params_from_file(fname, fail_on_error=False, use_default_template=True)
Return matplotlib.RcParams from the contents of the given file.
Parameters fname : str
Name of file parsed for matplotlib settings.
fail_on_error : bool
If True, raise an error when the parser fails to convert a parameter.
635
Matplotlib, Release 2.1.2
use_default_template : bool
If True, initialize with default parameters before updating with those in the
given file. If False, the configuration class only contains the parameters specified in the file. (Useful for updating dicts.)
matplotlib.matplotlib_fname()
Get the location of the config file.
The file location is determined in the following order
• $PWD/matplotlibrc
• $MATPLOTLIBRC if it is a file
• $MATPLOTLIBRC/matplotlibrc
• $MPLCONFIGDIR/matplotlibrc
• On Linux,
– $XDG_CONFIG_HOME/matplotlib/matplotlibrc (if $XDG_CONFIG_HOME is defined)
– or $HOME/.config/matplotlib/matplotlibrc (if $XDG_CONFIG_HOME is not defined)
• On other platforms,
– $HOME/.matplotlib/matplotlibrc if $HOME is defined.
• Lastly, it looks in $MATPLOTLIBDATA/matplotlibrc for a system-defined copy.
matplotlib.interactive(b)
Set interactive mode to boolean b.
If b is True, then draw after every plotting command, e.g., after xlabel
matplotlib.is_interactive()
Return true if plot mode is interactive
636
Chapter 30. The top level matplotlib module
CHAPTER
THIRTYONE
AFM (ADOBE FONT METRICS INTERFACE)
31.1 matplotlib.afm
This is a python interface to Adobe Font Metrics Files. Although a number of other python implementations
exist, and may be more complete than this, it was decided not to go with them because they were either:
1. copyrighted or used a non-BSD compatible license
2. had too many dependencies and a free standing lib was needed
3. Did more than needed and it was easier to write afresh rather than figure out how to get just what was
needed.
It is pretty easy to use, and requires only built-in python libs:
>>> from matplotlib import rcParams
>>> import os.path
>>> afm_fname = os.path.join(rcParams['datapath'],
...
'fonts', 'afm', 'ptmr8a.afm')
>>>
>>> from matplotlib.afm import AFM
>>> with open(afm_fname) as fh:
...
afm = AFM(fh)
>>> afm.string_width_height('What the heck?')
(6220.0, 694)
>>> afm.get_fontname()
'Times-Roman'
>>> afm.get_kern_dist('A', 'f')
0
>>> afm.get_kern_dist('A', 'y')
-92.0
>>> afm.get_bbox_char('!')
[130, -9, 238, 676]
class matplotlib.afm.AFM(fh)
Bases: object
Parse the AFM file in file object fh
family_name
637
Matplotlib, Release 2.1.2
get_angle()
Return the fontangle as float
get_bbox_char(c, isord=False)
get_capheight()
Return the cap height as float
get_familyname()
Return the font family name, e.g., ‘Times’
get_fontname()
Return the font name, e.g., ‘Times-Roman’
get_fullname()
Return the font full name, e.g., ‘Times-Roman’
get_height_char(c, isord=False)
Get the height of character c from the bounding box. This is the ink height (space is 0)
get_horizontal_stem_width()
Return the standard horizontal stem width as float, or None if not specified in AFM file.
get_kern_dist(c1, c2)
Return the kerning pair distance (possibly 0) for chars c1 and c2
get_kern_dist_from_name(name1, name2)
Return the kerning pair distance (possibly 0) for chars name1 and name2
get_name_char(c, isord=False)
Get the name of the character, i.e., ‘;’ is ‘semicolon’
get_str_bbox(s)
Return the string bounding box
get_str_bbox_and_descent(s)
Return the string bounding box
get_underline_thickness()
Return the underline thickness as float
get_vertical_stem_width()
Return the standard vertical stem width as float, or None if not specified in AFM file.
get_weight()
Return the font weight, e.g., ‘Bold’ or ‘Roman’
get_width_char(c, isord=False)
Get the width of the character from the character metric WX field
get_width_from_char_name(name)
Get the width of the character from a type1 character name
get_xheight()
Return the xheight as float
638
Chapter 31. afm (Adobe Font Metrics interface)
Matplotlib, Release 2.1.2
string_width_height(s)
Return the string width (including kerning) and string height as a (w, h) tuple.
matplotlib.afm.parse_afm(fh)
Parse the Adobe Font Metics file in file handle fh. Return value is a (dhead, dcmetrics_ascii, dmetrics_name, dkernpairs, dcomposite) tuple where dhead is a _parse_header() dict, dcmetrics_ascii
and dcmetrics_name are the two resulting dicts from _parse_char_metrics(), dkernpairs is
a _parse_kern_pairs() dict (possibly {}) and dcomposite is a _parse_composites() dict
(possibly {})
31.1. matplotlib.afm
639
Matplotlib, Release 2.1.2
640
Chapter 31. afm (Adobe Font Metrics interface)
CHAPTER
THIRTYTWO
ANIMATION MODULE
Table of Contents
• Animation
• Writer Classes
• Helper Classes
• Inheritance Diagrams
• Deprecated
32.1 Animation
The easiest way to make a live animation in matplotlib is to use one of the Animation classes.
FuncAnimation
ArtistAnimation
Makes an animation by repeatedly calling a function
func.
Animation using a fixed set of Artist objects.
32.1.1 matplotlib.animation.FuncAnimation
class matplotlib.animation.FuncAnimation(fig, func, frames=None, init_func=None,
fargs=None, save_count=None, **kwargs)
Makes an animation by repeatedly calling a function func.
Parameters fig : matplotlib.figure.Figure
The figure object that is used to get draw, resize, and any other needed events.
func : callable
The function to call at each frame. The first argument will be the next value in
frames. Any additional positional arguments can be supplied via the fargs
parameter.
641
Matplotlib, Release 2.1.2
The required signature is:
def func(frame, *fargs) -> iterable_of_artists:
frames : iterable, int, generator function, or None, optional
Source of data to pass func and each frame of the animation
If an iterable, then simply use the values provided. If the iterable has a length,
it will override the save_count kwarg.
If an integer, then equivalent to passing range(frames)
If a generator function, then must have the signature:
def gen_function() -> obj:
If None, then equivalent to passing itertools.count.
In all of these cases, the values in frames is simply passed through to the
user-supplied func and thus can be of any type.
init_func : callable, optional
A function used to draw a clear frame. If not given, the results of drawing
from the first item in the frames sequence will be used. This function will be
called once before the first frame.
If blit == True, init_func must return an iterable of artists to be redrawn.
The required signature is:
def init_func() -> iterable_of_artists:
fargs : tuple or None, optional
Additional arguments to pass to each call to func.
save_count : int, optional
The number of values from frames to cache.
interval : number, optional
Delay between frames in milliseconds. Defaults to 200.
repeat_delay : number, optional
If the animation in repeated, adds a delay in milliseconds before repeating the
animation. Defaults to None.
repeat : bool, optional
Controls whether the animation should repeat when the sequence of frames
is completed. Defaults to True.
blit : bool, optional
642
Chapter 32. animation module
Matplotlib, Release 2.1.2
Controls whether blitting is used to optimize drawing. Defaults to False.
__init__(fig, func,
**kwargs)
frames=None,
init_func=None,
fargs=None,
save_count=None,
Methods
__init__(fig, func[, frames, init_func, . . . ])
new_frame_seq()
new_saved_frame_seq()
save(filename[, writer, fps, dpi, codec, . . . ])
to_html5_video([embed_limit])
to_jshtml([fps, embed_frames, default_mode])
Saves a movie file by drawing every frame.
Returns animation as an HTML5 video tag.
Generate HTML representation of the animation
new_frame_seq()
new_saved_frame_seq()
32.1.2 matplotlib.animation.ArtistAnimation
class matplotlib.animation.ArtistAnimation(fig, artists, *args, **kwargs)
Animation using a fixed set of Artist objects.
Before creating an instance, all plotting should have taken place and the relevant artists saved.
Parameters fig : matplotlib.figure.Figure
The figure object that is used to get draw, resize, and any other needed events.
artists : list
Each list entry a collection of artists that represent what needs to be enabled
on each frame. These will be disabled for other frames.
interval : number, optional
Delay between frames in milliseconds. Defaults to 200.
repeat_delay : number, optional
If the animation in repeated, adds a delay in milliseconds before repeating the
animation. Defaults to None.
repeat : bool, optional
Controls whether the animation should repeat when the sequence of frames
is completed. Defaults to True.
blit : bool, optional
32.1. Animation
643
Matplotlib, Release 2.1.2
Controls whether blitting is used to optimize drawing. Defaults to False.
__init__(fig, artists, *args, **kwargs)
Methods
__init__(fig, artists, *args, **kwargs)
new_frame_seq()
new_saved_frame_seq()
save(filename[, writer, fps, dpi, codec, . . . ])
to_html5_video([embed_limit])
to_jshtml([fps, embed_frames, default_mode])
Creates a new sequence of frame information.
Creates a new sequence of saved/cached frame information.
Saves a movie file by drawing every frame.
Returns animation as an HTML5 video tag.
Generate HTML representation of the animation
In both cases it is critical to keep a reference to the instance object. The animation is advanced by a timer
(typically from the host GUI framework) which the Animation object holds the only reference to. If you
do not hold a reference to the Animation object, it (and hence the timers), will be garbage collected which
will stop the animation.
To save an animation to disk use Animation.save or Animation.to_html5_video
See Helper Classes below for details about what movie formats are supported.
32.1.3 FuncAnimation
The inner workings of FuncAnimation is more-or-less:
for d in frames:
artists = func(d, *fargs)
fig.canvas.draw_idle()
fig.canvas.start_event_loop(interval)
with details to handle ‘blitting’ (to dramatically improve the live performance), to be non-blocking, not repeatedly start/stop the GUI event loop, handle repeats, multiple animated axes, and easily save the animation
to a movie file.
‘Blitting’ is a old technique in computer graphics. The general gist is to take an existing bit map (in our
case a mostly rasterized figure) and then ‘blit’ one more artist on top. Thus, by managing a saved ‘clean’
bitmap, we can only re-draw the few artists that are changing at each frame and possibly save significant
amounts of time. When using blitting (by passing blit=True) the core loop of FuncAnimation gets a bit
more complicated
ax = fig.gca()
def update_blit(artists):
fig.canvas.restore_region(bg_cache)
for a in artists:
a.axes.draw_artist(a)
644
Chapter 32. animation module
Matplotlib, Release 2.1.2
ax.figure.canvas.blit(ax.bbox)
artists = init_func()
for a in artists:
a.set_animated(True)
fig.canvas.draw()
bg_cache = fig.canvas.copy_from_bbox(ax.bbox)
for f in frames:
artists = func(f, *fargs)
update_blit(artists)
fig.canvas.start_event_loop(interval)
This is of course leaving out many details (such as updating the background when the figure is resized or
fully re-drawn). However, this hopefully minimalist example gives a sense of how init_func and func
are used inside of FuncAnimation and the theory of how ‘blitting’ works.
The expected signature on func and init_func is very simple to keep FuncAnimation out of your book
keeping and plotting logic, but this means that the callable objects you pass in must know what artists
they should be working on. There are several approaches to handling this, of varying complexity and
encapsulation. The simplest approach, which works quite well in the case of a script, is to define the artist
at a global scope and let Python sort things out. For example
import numpy as np
import matplotlib.pyplot as plt
from matplotlib.animation import FuncAnimation
fig, ax = plt.subplots()
xdata, ydata = [], []
ln, = plt.plot([], [], 'ro', animated=True)
def init():
ax.set_xlim(0, 2*np.pi)
ax.set_ylim(-1, 1)
return ln,
def update(frame):
xdata.append(frame)
ydata.append(np.sin(frame))
ln.set_data(xdata, ydata)
return ln,
ani = FuncAnimation(fig, update, frames=np.linspace(0, 2*np.pi, 128),
init_func=init, blit=True)
plt.show()
The second method is to us functools.partial to ‘bind’ artists to function. A third method is to use
closures to build up the required artists and functions. A fourth method is to create a class.
32.1. Animation
645
Matplotlib, Release 2.1.2
Examples
Decay
A sinusoidal decay animation.
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
def data_gen(t=0):
cnt = 0
while cnt < 1000:
cnt += 1
t += 0.1
yield t, np.sin(2*np.pi*t) * np.exp(-t/10.)
def init():
ax.set_ylim(-1.1, 1.1)
ax.set_xlim(0, 10)
del xdata[:]
646
Chapter 32. animation module
Matplotlib, Release 2.1.2
del ydata[:]
line.set_data(xdata, ydata)
return line,
fig, ax = plt.subplots()
line, = ax.plot([], [], lw=2)
ax.grid()
xdata, ydata = [], []
def run(data):
# update the data
t, y = data
xdata.append(t)
ydata.append(y)
xmin, xmax = ax.get_xlim()
if t >= xmax:
ax.set_xlim(xmin, 2*xmax)
ax.figure.canvas.draw()
line.set_data(xdata, ydata)
return line,
ani = animation.FuncAnimation(fig, run, data_gen, blit=False, interval=10,
repeat=False, init_func=init)
plt.show()
Total running time of the script: ( 0 minutes 0.018 seconds)
The Bayes update
This animation displays the posterior estimate updates as it is refitted when new data arrives. The vertical
line represents the theoretical value to which the plotted distribution should converge.
# update a distribution based on new data.
import numpy as np
import matplotlib.pyplot as plt
import scipy.stats as ss
from matplotlib.animation import FuncAnimation
class UpdateDist(object):
def __init__(self, ax, prob=0.5):
self.success = 0
self.prob = prob
self.line, = ax.plot([], [], 'k-')
self.x = np.linspace(0, 1, 200)
self.ax = ax
# Set up plot parameters
32.1. Animation
647
Matplotlib, Release 2.1.2
self.ax.set_xlim(0, 1)
self.ax.set_ylim(0, 15)
self.ax.grid(True)
# This vertical line represents the theoretical value, to
# which the plotted distribution should converge.
self.ax.axvline(prob, linestyle='--', color='black')
def init(self):
self.success = 0
self.line.set_data([], [])
return self.line,
def __call__(self, i):
# This way the plot can continuously run and we just keep
# watching new realizations of the process
if i == 0:
return self.init()
# Choose success based on exceed a threshold with a uniform pick
if np.random.rand(1,) < self.prob:
self.success += 1
y = ss.beta.pdf(self.x, self.success + 1, (i - self.success) + 1)
self.line.set_data(self.x, y)
return self.line,
# Fixing random state for reproducibility
np.random.seed(19680801)
fig, ax = plt.subplots()
ud = UpdateDist(ax, prob=0.7)
anim = FuncAnimation(fig, ud, frames=np.arange(100), init_func=ud.init,
interval=100, blit=True)
plt.show()
Total running time of the script: ( 0 minutes 0.000 seconds)
The double pendulum problem
This animation illustrates the double pendulum problem.
Double pendulum formula translated from the C code at http://www.physics.usyd.edu.au/~wheat/dpend_
html/solve_dpend.c
from numpy import sin, cos
import numpy as np
import matplotlib.pyplot as plt
import scipy.integrate as integrate
import matplotlib.animation as animation
G = 9.8
648
# acceleration due to gravity, in m/s^2
Chapter 32. animation module
Matplotlib, Release 2.1.2
L1
L2
M1
M2
=
=
=
=
1.0
1.0
1.0
1.0
#
#
#
#
length of pendulum
length of pendulum
mass of pendulum 1
mass of pendulum 2
1 in m
2 in m
in kg
in kg
def derivs(state, t):
dydx = np.zeros_like(state)
dydx[0] = state[1]
del_ = state[2] - state[0]
den1 = (M1 + M2)*L1 - M2*L1*cos(del_)*cos(del_)
dydx[1] = (M2*L1*state[1]*state[1]*sin(del_)*cos(del_) +
M2*G*sin(state[2])*cos(del_) +
M2*L2*state[3]*state[3]*sin(del_) (M1 + M2)*G*sin(state[0]))/den1
dydx[2] = state[3]
den2 = (L2/L1)*den1
dydx[3] = (-M2*L2*state[3]*state[3]*sin(del_)*cos(del_) +
(M1 + M2)*G*sin(state[0])*cos(del_) (M1 + M2)*L1*state[1]*state[1]*sin(del_) (M1 + M2)*G*sin(state[2]))/den2
return dydx
# create a time array from 0..100 sampled at 0.05 second steps
dt = 0.05
t = np.arange(0.0, 20, dt)
# th1 and th2 are the initial angles (degrees)
# w10 and w20 are the initial angular velocities (degrees per second)
th1 = 120.0
w1 = 0.0
th2 = -10.0
w2 = 0.0
# initial state
state = np.radians([th1, w1, th2, w2])
# integrate your ODE using scipy.integrate.
y = integrate.odeint(derivs, state, t)
x1 = L1*sin(y[:, 0])
y1 = -L1*cos(y[:, 0])
x2 = L2*sin(y[:, 2]) + x1
y2 = -L2*cos(y[:, 2]) + y1
fig = plt.figure()
ax = fig.add_subplot(111, autoscale_on=False, xlim=(-2, 2), ylim=(-2, 2))
32.1. Animation
649
Matplotlib, Release 2.1.2
ax.set_aspect('equal')
ax.grid()
line, = ax.plot([], [], 'o-', lw=2)
time_template = 'time = %.1f s'
time_text = ax.text(0.05, 0.9, '', transform=ax.transAxes)
def init():
line.set_data([], [])
time_text.set_text('')
return line, time_text
def animate(i):
thisx = [0, x1[i], x2[i]]
thisy = [0, y1[i], y2[i]]
line.set_data(thisx, thisy)
time_text.set_text(time_template % (i*dt))
return line, time_text
ani = animation.FuncAnimation(fig, animate, np.arange(1, len(y)),
interval=25, blit=True, init_func=init)
# ani.save('double_pendulum.mp4', fps=15)
plt.show()
Total running time of the script: ( 0 minutes 0.000 seconds)
An animated image
Animation of an image.
650
Chapter 32. animation module
Matplotlib, Release 2.1.2
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
fig = plt.figure()
def f(x, y):
return np.sin(x) + np.cos(y)
x = np.linspace(0, 2 * np.pi, 120)
y = np.linspace(0, 2 * np.pi, 100).reshape(-1, 1)
im = plt.imshow(f(x, y), animated=True)
def updatefig(*args):
global x, y
x += np.pi / 15.
y += np.pi / 20.
im.set_array(f(x, y))
return im,
ani = animation.FuncAnimation(fig, updatefig, interval=50, blit=True)
32.1. Animation
651
Matplotlib, Release 2.1.2
plt.show()
Total running time of the script: ( 0 minutes 0.040 seconds)
Animated histogram
Use a path patch to draw a bunch of rectangles for an animated histogram.
import numpy as np
import
import
import
import
matplotlib.pyplot as plt
matplotlib.patches as patches
matplotlib.path as path
matplotlib.animation as animation
# Fixing random state for reproducibility
np.random.seed(19680801)
# histogram our data with numpy
data = np.random.randn(1000)
n, bins = np.histogram(data, 100)
# get the corners of the rectangles for the histogram
left = np.array(bins[:-1])
right = np.array(bins[1:])
bottom = np.zeros(len(left))
top = bottom + n
nrects = len(left)
Here comes the tricky part – we have to set up the vertex and path codes arrays using plt.Path.MOVETO,
plt.Path.LINETO and plt.Path.CLOSEPOLY for each rect.
• We need 1 MOVETO per rectangle, which sets the initial point.
• We need 3 LINETO’s, which tell Matplotlib to draw lines from vertex 1 to vertex 2, v2 to v3, and v3
to v4.
• We then need one CLOSEPOLY which tells Matplotlib to draw a line from the v4 to our initial vertex
(the MOVETO vertex), in order to close the polygon.
Note: The vertex for CLOSEPOLY is ignored, but we still need a placeholder in the verts array to keep the
codes aligned with the vertices.
nverts = nrects * (1 + 3 + 1)
verts = np.zeros((nverts, 2))
codes = np.ones(nverts, int) * path.Path.LINETO
codes[0::5] = path.Path.MOVETO
codes[4::5] = path.Path.CLOSEPOLY
verts[0::5, 0] = left
verts[0::5, 1] = bottom
652
Chapter 32. animation module
Matplotlib, Release 2.1.2
verts[1::5,
verts[1::5,
verts[2::5,
verts[2::5,
verts[3::5,
verts[3::5,
0]
1]
0]
1]
0]
1]
=
=
=
=
=
=
left
top
right
top
right
bottom
To animate the histogram, we need an animate function, which generates a random set of numbers and
updates the locations of the vertices for the histogram (in this case, only the heights of each rectangle).
patch will eventually be a Patch object.
patch = None
def animate(i):
# simulate new data coming in
data = np.random.randn(1000)
n, bins = np.histogram(data, 100)
top = bottom + n
verts[1::5, 1] = top
verts[2::5, 1] = top
return [patch, ]
And now we build the Path and Patch instances for the histogram using our vertices and codes. We add
the patch to the Axes instance, and setup the FuncAnimation with our animate function.
fig, ax = plt.subplots()
barpath = path.Path(verts, codes)
patch = patches.PathPatch(
barpath, facecolor='green', edgecolor='yellow', alpha=0.5)
ax.add_patch(patch)
ax.set_xlim(left[0], right[-1])
ax.set_ylim(bottom.min(), top.max())
ani = animation.FuncAnimation(fig, animate, 100, repeat=False, blit=True)
plt.show()
32.1. Animation
653
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.106 seconds)
Rain simulation
Simulates rain drops on a surface by animating the scale and opacity of 50 scatter points.
Author: Nicolas P. Rougier
654
Chapter 32. animation module
Matplotlib, Release 2.1.2
import numpy as np
import matplotlib.pyplot as plt
from matplotlib.animation import FuncAnimation
# Fixing random state for reproducibility
np.random.seed(19680801)
# Create new Figure and an Axes which fills it.
fig = plt.figure(figsize=(7, 7))
ax = fig.add_axes([0, 0, 1, 1], frameon=False)
ax.set_xlim(0, 1), ax.set_xticks([])
ax.set_ylim(0, 1), ax.set_yticks([])
32.1. Animation
655
Matplotlib, Release 2.1.2
# Create rain data
n_drops = 50
rain_drops = np.zeros(n_drops, dtype=[('position',
('size',
('growth',
('color',
float,
float,
float,
float,
2),
1),
1),
4)])
# Initialize the raindrops in random positions and with
# random growth rates.
rain_drops['position'] = np.random.uniform(0, 1, (n_drops, 2))
rain_drops['growth'] = np.random.uniform(50, 200, n_drops)
# Construct the scatter which we will update during animation
# as the raindrops develop.
scat = ax.scatter(rain_drops['position'][:, 0], rain_drops['position'][:, 1],
s=rain_drops['size'], lw=0.5, edgecolors=rain_drops['color'],
facecolors='none')
def update(frame_number):
# Get an index which we can use to re-spawn the oldest raindrop.
current_index = frame_number % n_drops
# Make all colors more transparent as time progresses.
rain_drops['color'][:, 3] -= 1.0/len(rain_drops)
rain_drops['color'][:, 3] = np.clip(rain_drops['color'][:, 3], 0, 1)
# Make all circles bigger.
rain_drops['size'] += rain_drops['growth']
# Pick a new position for oldest rain drop, resetting its size,
# color and growth factor.
rain_drops['position'][current_index] = np.random.uniform(0, 1, 2)
rain_drops['size'][current_index] = 5
rain_drops['color'][current_index] = (0, 0, 0, 1)
rain_drops['growth'][current_index] = np.random.uniform(50, 200)
# Update the scatter collection, with the new colors, sizes and positions.
scat.set_edgecolors(rain_drops['color'])
scat.set_sizes(rain_drops['size'])
scat.set_offsets(rain_drops['position'])
# Construct the animation, using the update function as the animation
# director.
animation = FuncAnimation(fig, update, interval=10)
plt.show()
Total running time of the script: ( 0 minutes 0.019 seconds)
656
Chapter 32. animation module
Matplotlib, Release 2.1.2
Random data
An animation of random data.
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
# Fixing random state for reproducibility
np.random.seed(19680801)
fig, ax = plt.subplots()
line, = ax.plot(np.random.rand(10))
ax.set_ylim(0, 1)
def update(data):
line.set_ydata(data)
return line,
def data_gen():
while True:
32.1. Animation
657
Matplotlib, Release 2.1.2
yield np.random.rand(10)
ani = animation.FuncAnimation(fig, update, data_gen, interval=100)
plt.show()
Total running time of the script: ( 0 minutes 0.018 seconds)
3D animation
An animated plot in 3D.
import
import
import
import
numpy as np
matplotlib.pyplot as plt
mpl_toolkits.mplot3d.axes3d as p3
matplotlib.animation as animation
# Fixing random state for reproducibility
np.random.seed(19680801)
def Gen_RandLine(length, dims=2):
"""
658
Chapter 32. animation module
Matplotlib, Release 2.1.2
Create a line using a random walk algorithm
length is the number of points for the line.
dims is the number of dimensions the line has.
"""
lineData = np.empty((dims, length))
lineData[:, 0] = np.random.rand(dims)
for index in range(1, length):
# scaling the random numbers by 0.1 so
# movement is small compared to position.
# subtraction by 0.5 is to change the range to [-0.5, 0.5]
# to allow a line to move backwards.
step = ((np.random.rand(dims) - 0.5) * 0.1)
lineData[:, index] = lineData[:, index - 1] + step
return lineData
def update_lines(num, dataLines, lines):
for line, data in zip(lines, dataLines):
# NOTE: there is no .set_data() for 3 dim data...
line.set_data(data[0:2, :num])
line.set_3d_properties(data[2, :num])
return lines
# Attaching 3D axis to the figure
fig = plt.figure()
ax = p3.Axes3D(fig)
# Fifty lines of random 3-D lines
data = [Gen_RandLine(25, 3) for index in range(50)]
# Creating fifty line objects.
# NOTE: Can't pass empty arrays into 3d version of plot()
lines = [ax.plot(dat[0, 0:1], dat[1, 0:1], dat[2, 0:1])[0] for dat in data]
# Setting the axes properties
ax.set_xlim3d([0.0, 1.0])
ax.set_xlabel('X')
ax.set_ylim3d([0.0, 1.0])
ax.set_ylabel('Y')
ax.set_zlim3d([0.0, 1.0])
ax.set_zlabel('Z')
ax.set_title('3D Test')
# Creating the Animation object
line_ani = animation.FuncAnimation(fig, update_lines, 25, fargs=(data, lines),
interval=50, blit=False)
plt.show()
32.1. Animation
659
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.077 seconds)
Simple Anim
A simple example of an animated plot
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
fig, ax = plt.subplots()
x = np.arange(0, 2*np.pi, 0.01)
line, = ax.plot(x, np.sin(x))
def animate(i):
line.set_ydata(np.sin(x + i/10.0))
return line,
# update the data
# Init only required for blitting to give a clean slate.
660
Chapter 32. animation module
Matplotlib, Release 2.1.2
def init():
line.set_ydata(np.ma.array(x, mask=True))
return line,
ani = animation.FuncAnimation(fig, animate, np.arange(1, 200), init_func=init,
interval=25, blit=True)
plt.show()
Total running time of the script: ( 0 minutes 0.039 seconds)
Oscilloscope
Emulates an oscilloscope.
import numpy as np
from matplotlib.lines import Line2D
import matplotlib.pyplot as plt
import matplotlib.animation as animation
class Scope(object):
def __init__(self, ax, maxt=2, dt=0.02):
32.1. Animation
661
Matplotlib, Release 2.1.2
self.ax = ax
self.dt = dt
self.maxt = maxt
self.tdata = [0]
self.ydata = [0]
self.line = Line2D(self.tdata, self.ydata)
self.ax.add_line(self.line)
self.ax.set_ylim(-.1, 1.1)
self.ax.set_xlim(0, self.maxt)
def update(self, y):
lastt = self.tdata[-1]
if lastt > self.tdata[0] + self.maxt: # reset the arrays
self.tdata = [self.tdata[-1]]
self.ydata = [self.ydata[-1]]
self.ax.set_xlim(self.tdata[0], self.tdata[0] + self.maxt)
self.ax.figure.canvas.draw()
t = self.tdata[-1] + self.dt
self.tdata.append(t)
self.ydata.append(y)
self.line.set_data(self.tdata, self.ydata)
return self.line,
def emitter(p=0.03):
'return a random value with probability p, else 0'
while True:
v = np.random.rand(1)
if v > p:
yield 0.
else:
yield np.random.rand(1)
# Fixing random state for reproducibility
np.random.seed(19680801)
fig, ax = plt.subplots()
scope = Scope(ax)
# pass a generator in "emitter" to produce data for the update func
ani = animation.FuncAnimation(fig, scope.update, emitter, interval=10,
blit=True)
plt.show()
Total running time of the script: ( 0 minutes 0.040 seconds)
662
Chapter 32. animation module
Matplotlib, Release 2.1.2
MATPLOTLIB UNCHAINED
Comparative path demonstration of frequency from a fake signal of a pulsar. (mostly known because of the
cover for Joy Division’s Unknown Pleasures)
Author: Nicolas P. Rougier
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
# Fixing random state for reproducibility
np.random.seed(19680801)
32.1. Animation
663
Matplotlib, Release 2.1.2
# Create new Figure with black background
fig = plt.figure(figsize=(8, 8), facecolor='black')
# Add a subplot with no frame
ax = plt.subplot(111, frameon=False)
# Generate random data
data = np.random.uniform(0, 1, (64, 75))
X = np.linspace(-1, 1, data.shape[-1])
G = 1.5 * np.exp(-4 * X ** 2)
# Generate line plots
lines = []
for i in range(len(data)):
# Small reduction of the X extents to get a cheap perspective effect
xscale = 1 - i / 200.
# Same for linewidth (thicker strokes on bottom)
lw = 1.5 - i / 100.0
line, = ax.plot(xscale * X, i + G * data[i], color="w", lw=lw)
lines.append(line)
# Set y limit (or first line is cropped because of thickness)
ax.set_ylim(-1, 70)
# No ticks
ax.set_xticks([])
ax.set_yticks([])
# 2 part titles to get different font weights
ax.text(0.5, 1.0, "MATPLOTLIB ", transform=ax.transAxes,
ha="right", va="bottom", color="w",
family="sans-serif", fontweight="light", fontsize=16)
ax.text(0.5, 1.0, "UNCHAINED", transform=ax.transAxes,
ha="left", va="bottom", color="w",
family="sans-serif", fontweight="bold", fontsize=16)
def update(*args):
# Shift all data to the right
data[:, 1:] = data[:, :-1]
# Fill-in new values
data[:, 0] = np.random.uniform(0, 1, len(data))
# Update data
for i in range(len(data)):
lines[i].set_ydata(i + G * data[i])
# Return modified artists
return lines
664
Chapter 32. animation module
Matplotlib, Release 2.1.2
# Construct the animation, using the update function as the animation
# director.
anim = animation.FuncAnimation(fig, update, interval=10)
plt.show()
Total running time of the script: ( 0 minutes 0.071 seconds)
32.1.4 ArtistAnimation
Examples
Simple animation examples
Two animations where the first is a random walk plot and the second is an image animation.
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
def update_line(num, data, line):
line.set_data(data[..., :num])
return line,
fig1 = plt.figure()
# Fixing random state for reproducibility
np.random.seed(19680801)
data = np.random.rand(2, 25)
l, = plt.plot([], [], 'r-')
plt.xlim(0, 1)
plt.ylim(0, 1)
plt.xlabel('x')
plt.title('test')
line_ani = animation.FuncAnimation(fig1, update_line, 25, fargs=(data, l),
interval=50, blit=True)
# To save the animation, use the command: line_ani.save('lines.mp4')
32.1. Animation
665
Matplotlib, Release 2.1.2
fig2 = plt.figure()
x = np.arange(-9, 10)
y = np.arange(-9, 10).reshape(-1, 1)
base = np.hypot(x, y)
ims = []
for add in np.arange(15):
ims.append((plt.pcolor(x, y, base + add, norm=plt.Normalize(0, 30)),))
im_ani = animation.ArtistAnimation(fig2, ims, interval=50, repeat_delay=3000,
blit=True)
# To save this second animation with some metadata, use the following command:
# im_ani.save('im.mp4', metadata={'artist':'Guido'})
plt.show()
666
Chapter 32. animation module
Matplotlib, Release 2.1.2
Total running time of the script: ( 0 minutes 0.200 seconds)
Saving an animation
This example showcases the same animations as basic_example.py, but instead of displaying the animation to the user, it writes to files using a MovieWriter instance.
import numpy as np
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import matplotlib.animation as animation
def update_line(num, data, line):
line.set_data(data[..., :num])
return line,
# Fixing random state for reproducibility
np.random.seed(19680801)
32.1. Animation
667
Matplotlib, Release 2.1.2
# Set up formatting for the movie files
Writer = animation.writers['ffmpeg']
writer = Writer(fps=15, metadata=dict(artist='Me'), bitrate=1800)
fig1 = plt.figure()
data = np.random.rand(2, 25)
l, = plt.plot([], [], 'r-')
plt.xlim(0, 1)
plt.ylim(0, 1)
plt.xlabel('x')
plt.title('test')
line_ani = animation.FuncAnimation(fig1, update_line, 25, fargs=(data, l),
interval=50, blit=True)
line_ani.save('lines.mp4', writer=writer)
fig2 = plt.figure()
x = np.arange(-9, 10)
y = np.arange(-9, 10).reshape(-1, 1)
base = np.hypot(x, y)
ims = []
for add in np.arange(15):
ims.append((plt.pcolor(x, y, base + add, norm=plt.Normalize(0, 30)),))
im_ani = animation.ArtistAnimation(fig2, ims, interval=50, repeat_delay=3000,
blit=True)
im_ani.save('im.mp4', writer=writer)
Total running time of the script: ( 0 minutes 0.000 seconds)
An animated image using a list of images
Animate an image from a list of images (or Artists).
668
Chapter 32. animation module
Matplotlib, Release 2.1.2
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
fig = plt.figure()
def f(x, y):
return np.sin(x) + np.cos(y)
x = np.linspace(0, 2 * np.pi, 120)
y = np.linspace(0, 2 * np.pi, 100).reshape(-1, 1)
# ims is a list of lists, each row is a list of artists to draw in the
# current frame; here we are just animating one artist, the image, in
# each frame
ims = []
for i in range(60):
x += np.pi / 15.
y += np.pi / 20.
im = plt.imshow(f(x, y), animated=True)
ims.append([im])
ani = animation.ArtistAnimation(fig, ims, interval=50, blit=True,
repeat_delay=1000)
32.1. Animation
669
Matplotlib, Release 2.1.2
# ani.save('dynamic_images.mp4')
plt.show()
Total running time of the script: ( 0 minutes 0.420 seconds)
32.2 Writer Classes
The provided writers fall into two broad categories: pipe-based and file-based. The pipe-based writers
stream the captured frames over a pipe to an external process. The pipe-based variants tend to be more
performant, but may not work on all systems.
FFMpegWriter
ImageMagickFileWriter
AVConvWriter
Pipe-based ffmpeg writer.
File-based animated gif writer.
Pipe-based avconv writer.
32.2.1 matplotlib.animation.FFMpegWriter
class matplotlib.animation.FFMpegWriter(fps=5,
codec=None,
bitrate=None,
tra_args=None, metadata=None)
Pipe-based ffmpeg writer.
ex-
Frames are streamed directly to ffmpeg via a pipe and written in a single pass.
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
670
Chapter 32. animation module
Matplotlib, Release 2.1.2
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
__init__(fps=5, codec=None, bitrate=None, extra_args=None, metadata=None)
MovieWriter
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
Methods
__init__([fps, codec, bitrate, extra_args, . . . ])
bin_path()
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
32.2. Writer Classes
MovieWriter
Returns the binary path to the commandline tool
used by a specific subclass.
Clean-up and collect the process used to write the
movie file.
Finish any processing for writing the movie.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
671
Matplotlib, Release 2.1.2
32.2.2 matplotlib.animation.ImageMagickFileWriter
class matplotlib.animation.ImageMagickFileWriter(*args, **kwargs)
File-based animated gif writer.
Frames are written to temporary files on disk and then stitched together at the end.
__init__(*args, **kwargs)
Methods
__init__(*args, **kwargs)
bin_path()
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi, frame_prefix, . . . ])
Returns the binary path to the commandline tool
used by a specific subclass.
Grab the image information from the figure and
save as a movie frame.
Check to see if a ImageMagickWriter is actually
available.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
supported_formats = ['png', 'jpeg', 'ppm', 'tiff', 'sgi', 'bmp', 'pbm', 'raw', 'rgba']
32.2.3 matplotlib.animation.AVConvWriter
class matplotlib.animation.AVConvWriter(fps=5,
codec=None,
bitrate=None,
tra_args=None, metadata=None)
Pipe-based avconv writer.
ex-
Frames are streamed directly to avconv via a pipe and written in a single pass.
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
672
Chapter 32. animation module
Matplotlib, Release 2.1.2
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
__init__(fps=5, codec=None, bitrate=None, extra_args=None, metadata=None)
MovieWriter
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
Methods
__init__([fps, codec, bitrate, extra_args, . . . ])
bin_path()
MovieWriter
Returns the binary path to the commandline tool
used by a specific subclass.
Continued on next page
32.2. Writer Classes
673
Matplotlib, Release 2.1.2
Table 32.7 – continued from previous page
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
Clean-up and collect the process used to write the
movie file.
Finish any processing for writing the movie.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
Alternatively the file-based writers save temporary files for each frame which are stitched into a single file
at the end. Although slower, these writers can be easier to debug.
File-based ffmpeg writer.
Pipe-based animated gif.
File-based avconv writer.
FFMpegFileWriter
ImageMagickWriter
AVConvFileWriter
32.2.4 matplotlib.animation.FFMpegFileWriter
class matplotlib.animation.FFMpegFileWriter(*args, **kwargs)
File-based ffmpeg writer.
Frames are written to temporary files on disk and then stitched together at the end.
__init__(*args, **kwargs)
Methods
__init__(*args, **kwargs)
bin_path()
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi, frame_prefix, . . . ])
Returns the binary path to the commandline tool
used by a specific subclass.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
supported_formats = ['png', 'jpeg', 'ppm', 'tiff', 'sgi', 'bmp', 'pbm', 'raw', 'rgba']
674
Chapter 32. animation module
Matplotlib, Release 2.1.2
32.2.5 matplotlib.animation.ImageMagickWriter
class matplotlib.animation.ImageMagickWriter(fps=5, codec=None, bitrate=None, extra_args=None, metadata=None)
Pipe-based animated gif.
Frames are streamed directly to ImageMagick via a pipe and written in a single pass.
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
__init__(fps=5, codec=None, bitrate=None, extra_args=None, metadata=None)
MovieWriter
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
32.2. Writer Classes
675
Matplotlib, Release 2.1.2
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
Methods
__init__([fps, codec, bitrate, extra_args, . . . ])
bin_path()
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
MovieWriter
Returns the binary path to the commandline tool
used by a specific subclass.
Clean-up and collect the process used to write the
movie file.
Finish any processing for writing the movie.
Grab the image information from the figure and
save as a movie frame.
Check to see if a ImageMagickWriter is actually
available.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
32.2.6 matplotlib.animation.AVConvFileWriter
class matplotlib.animation.AVConvFileWriter(*args, **kwargs)
File-based avconv writer.
Frames are written to temporary files on disk and then stitched together at the end.
__init__(*args, **kwargs)
Methods
__init__(*args, **kwargs)
bin_path()
cleanup()
finish()
grab_frame(**savefig_kwargs)
Returns the binary path to the commandline tool
used by a specific subclass.
Grab the image information from the figure and
save as a movie frame.
Continued on next page
676
Chapter 32. animation module
Matplotlib, Release 2.1.2
Table 32.11 – continued from previous page
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi, frame_prefix, . . . ])
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
Fundamentally, a MovieWriter provides a way to grab sequential frames from the same underlying Figure
object. The base class MovieWriter implements 3 methods and a context manager. The only difference
between the pipe-based and file-based writers is in the arguments to their respective setup methods.
The setup() method is used to prepare the writer (possibly opening a pipe), successive calls to
grab_frame() capture a single frame at a time and finish() finalizes the movie and writes the output file
to disk. For example
moviewriter = MovieWriter(...)
moviewriter.setup(fig=fig, 'my_movie.ext', dpi=100)
for j in range(n):
update_figure(n)
moviewriter.grab_frame()
moviewriter.finish()
If using the writer classes directly (not through Animation.save), it is strongly encouraged to use the
saving context manager
with moviewriter.saving(fig, 'myfile.mp4', dpi=100):
for j in range(n):
update_figure(n)
moviewriter.grab_frame()
to ensures that setup and cleanup are performed as necessary.
sphx_glr_gallery_animation_moviewriter_sgskip.py
32.3 Helper Classes
32.3.1 Animation Base Classes
Animation
TimedAnimation
This class wraps the creation of an animation using
matplotlib.
Animation subclass for time-based animation.
matplotlib.animation.Animation
class matplotlib.animation.Animation(fig, event_source=None, blit=False)
This class wraps the creation of an animation using matplotlib.
It is only a base class which should be subclassed to provide needed behavior.
32.3. Helper Classes
677
Matplotlib, Release 2.1.2
This class is not typically used directly.
Parameters fig : matplotlib.figure.Figure
The figure object that is used to get draw, resize, and any other needed events.
event_source : object, optional
A class that can run a callback when desired events are generated, as well as
be stopped and started.
Examples include timers (see TimedAnimation) and file system notifications.
blit : bool, optional
controls whether blitting is used to optimize drawing. Defaults to False.
See also:
FuncAnimation, ArtistAnimation
__init__(fig, event_source=None, blit=False)
Methods
__init__(fig[, event_source, blit])
new_frame_seq()
new_saved_frame_seq()
save(filename[, writer, fps, dpi, codec, . . . ])
to_html5_video([embed_limit])
to_jshtml([fps, embed_frames, default_mode])
Creates a new sequence of frame information.
Creates a new sequence of saved/cached frame information.
Saves a movie file by drawing every frame.
Returns animation as an HTML5 video tag.
Generate HTML representation of the animation
new_frame_seq()
Creates a new sequence of frame information.
new_saved_frame_seq()
Creates a new sequence of saved/cached frame information.
save(filename, writer=None, fps=None, dpi=None, codec=None, bitrate=None, extra_args=None, metadata=None, extra_anim=None, savefig_kwargs=None)
Saves a movie file by drawing every frame.
Parameters filename : str
The output filename, e.g., mymovie.mp4.
writer : MovieWriter or str, optional
A MovieWriter instance to use or a key that identifies a class to use, such
as ‘ffmpeg’ or ‘mencoder’. If None, defaults to rcParams['animation.
writer'].
678
Chapter 32. animation module
Matplotlib, Release 2.1.2
fps : number, optional
Frames per second in the movie. Defaults to None, which will use the animation’s specified interval to set the frames per second.
dpi : number, optional
Controls the dots per inch for the movie frames. This combined with the
figure’s size in inches controls the size of the movie. If None, defaults to
rcparam['savefig.dpi'].
codec : str, optional
The video codec to be used. Not all codecs are supported by a given
MovieWriter. If None, default to rcParams['animation.codec'].
bitrate : number, optional
Specifies the number of bits used per second in the compressed movie, in
kilobits per second. A higher number means a higher quality movie, but at
the cost of increased file size. If None, defaults to rcParam['animation.
bitrate'].
extra_args : list, optional
List of extra string arguments to be passed to the underlying movie utility. If
None, defaults to rcParams['animation.extra_args']
metadata : Dict[str, str], optional
Dictionary of keys and values for metadata to include in the output file. Some
keys that may be of use include: title, artist, genre, subject, copyright, srcform, comment.
extra_anim : list, optional
Additional Animation objects that should be included in the saved movie
file. These need to be from the same matplotlib.figure.Figure instance.
Also, animation frames will just be simply combined, so there should be a 1:1
correspondence between the frames from the different animations.
savefig_kwargs : dict, optional
Is a dictionary containing keyword arguments to be passed on to the savefig
command which is called repeatedly to save the individual frames.
Notes
fps, codec, bitrate, extra_args, metadata are used to construct a MovieWriter instance and
can only be passed if writer is a string. If they are passed as non-None and writer is a
MovieWriter, a RuntimeError will be raised.
to_html5_video(embed_limit=None)
Returns animation as an HTML5 video tag.
32.3. Helper Classes
679
Matplotlib, Release 2.1.2
This saves the animation as an h264 video, encoded in base64 directly into the HTML5 video
tag. This respects the rc parameters for the writer as well as the bitrate. This also makes use of
the interval to control the speed, and uses the repeat parameter to decide whether to loop.
to_jshtml(fps=None, embed_frames=True, default_mode=None)
Generate HTML representation of the animation
matplotlib.animation.TimedAnimation
class matplotlib.animation.TimedAnimation(fig,
interval=200,
repeat_delay=None,
repeat=True, event_source=None, *args,
**kwargs)
Animation subclass for time-based animation.
A new frame is drawn every interval milliseconds.
Parameters fig : matplotlib.figure.Figure
The figure object that is used to get draw, resize, and any other needed events.
interval : number, optional
Delay between frames in milliseconds. Defaults to 200.
repeat_delay : number, optional
If the animation in repeated, adds a delay in milliseconds before repeating the
animation. Defaults to None.
repeat : bool, optional
Controls whether the animation should repeat when the sequence of frames
is completed. Defaults to True.
blit : bool, optional
Controls whether blitting is used to optimize drawing. Defaults to False.
__init__(fig, interval=200, repeat_delay=None, repeat=True, event_source=None, *args,
**kwargs)
Methods
__init__(fig[, interval, repeat_delay, . . . ])
new_frame_seq()
new_saved_frame_seq()
save(filename[, writer, fps, dpi, codec, . . . ])
to_html5_video([embed_limit])
to_jshtml([fps, embed_frames, default_mode])
680
Creates a new sequence of frame information.
Creates a new sequence of saved/cached frame information.
Saves a movie file by drawing every frame.
Returns animation as an HTML5 video tag.
Generate HTML representation of the animation
Chapter 32. animation module
Matplotlib, Release 2.1.2
32.3.2 Custom Animation classes
sphx_glr_gallery_animation_subplots.py
32.3.3 Writer Registry
A module-level registry is provided to map between the name of the writer and the class to allow a string to
be passed to Animation.save instead of a writer instance.
MovieWriterRegistry
Registry of available writer classes by human readable
name.
matplotlib.animation.MovieWriterRegistry
class matplotlib.animation.MovieWriterRegistry
Registry of available writer classes by human readable name.
__init__()
Methods
__init__()
ensure_not_dirty()
is_available(name)
list()
register(name)
reset_available_writers()
set_dirty()
If dirty, reasks the writers if they are available
Check if given writer is available by name.
Get a list of available MovieWriters.
Decorator for registering a class under a name.
Reset the available state of all registered writers
Sets a flag to re-setup the writers.
ensure_not_dirty()
If dirty, reasks the writers if they are available
is_available(name)
Check if given writer is available by name.
Parameters name : str
Returns available : bool
list()
Get a list of available MovieWriters.
register(name)
Decorator for registering a class under a name.
Example use:
32.3. Helper Classes
681
Matplotlib, Release 2.1.2
@registry.register(name)
class Foo:
pass
reset_available_writers()
Reset the available state of all registered writers
set_dirty()
Sets a flag to re-setup the writers.
32.3.4 Writer Base Classes
To reduce code duplication base classes
AbstractMovieWriter
MovieWriter
FileMovieWriter
Abstract base class for writing movies.
Base class for writing movies.
MovieWriter for writing to individual files and
stitching at the end.
matplotlib.animation.AbstractMovieWriter
class matplotlib.animation.AbstractMovieWriter
Abstract base class for writing movies. Fundamentally, what a MovieWriter does is provide is a way
to grab frames by calling grab_frame().
setup() is called to start the process and finish() is called afterwards.
This class is set up to provide for writing movie frame data to a pipe. saving() is provided as a context
manager to facilitate this process as:
with moviewriter.saving(fig, outfile='myfile.mp4', dpi=100):
# Iterate over frames
moviewriter.grab_frame(**savefig_kwargs)
The use of the context manager ensures that setup() and finish() are performed as necessary.
An instance of a concrete subclass of this class can be given as the writer argument of Animation.
save().
__init__($ self, /, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
Methods
finish ()
Finish any processing for writing the movie.
Continued on next page
682
Chapter 32. animation module
Matplotlib, Release 2.1.2
Table 32.18 – continued from previous page
grab_frame(**savefig_kwargs)
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
Grab the image information from the figure and
save as a movie frame.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
finish()
Finish any processing for writing the movie.
grab_frame(**savefig_kwargs)
Grab the image information from the figure and save as a movie frame.
All keyword arguments in savefig_kwargs are passed on to the savefig command that saves
the figure.
saving(fig, outfile, dpi, *args, **kwargs)
Context manager to facilitate writing the movie file.
*args, **kw are any parameters that should be passed to setup.
setup(fig, outfile, dpi=None)
Perform setup for writing the movie file.
Parameters fig: ‘matplotlib.figure.Figure‘ instance
The figure object that contains the information for frames
outfile: string
The filename of the resulting movie file
dpi: int, optional
The DPI (or resolution) for the file. This controls the size in pixels of the
resulting movie file. Default is fig.dpi.
matplotlib.animation.MovieWriter
class matplotlib.animation.MovieWriter(fps=5,
codec=None,
bitrate=None,
tra_args=None, metadata=None)
Base class for writing movies.
ex-
This class is set up to provide for writing movie frame data to a pipe. See examples for how to use
these classes.
Attributes
frame_format (str) The format used in writing frame data, defaults to ‘rgba’
fig
(Figure) The figure to capture data from. This must be provided by the subclasses.
32.3. Helper Classes
683
Matplotlib, Release 2.1.2
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
__init__(fps=5, codec=None, bitrate=None, extra_args=None, metadata=None)
MovieWriter
Parameters fps: int
Framerate for movie.
codec: string or None, optional
The codec to use. If None (the default) the animation.codec rcParam is
used.
bitrate: int or None, optional
The bitrate for the saved movie file, which is one way to control the output
file size and quality. The default value is None, which uses the animation.
bitrate rcParam. A value of -1 implies that the bitrate should be determined
automatically by the underlying utility.
extra_args: list of strings or None, optional
A list of extra string arguments to be passed to the underlying movie utility. The default is None, which passes the additional arguments in the
animation.extra_args rcParam.
metadata: Dict[str, str] or None
684
Chapter 32. animation module
Matplotlib, Release 2.1.2
A dictionary of keys and values for metadata to include in the output file.
Some keys that may be of use include: title, artist, genre, subject, copyright,
srcform, comment.
Methods
__init__([fps, codec, bitrate, extra_args, . . . ])
bin_path ()
cleanup()
finish ()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
MovieWriter
Returns the binary path to the commandline tool
used by a specific subclass.
Clean-up and collect the process used to write the
movie file.
Finish any processing for writing the movie.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
classmethod bin_path()
Returns the binary path to the commandline tool used by a specific subclass. This is a class
method so that the tool can be looked for before making a particular MovieWriter subclass
available.
cleanup()
Clean-up and collect the process used to write the movie file.
finish()
Finish any processing for writing the movie.
frame_size
A tuple (width, height) in pixels of a movie frame.
grab_frame(**savefig_kwargs)
Grab the image information from the figure and save as a movie frame.
All keyword arguments in savefig_kwargs are passed on to the savefig command that saves
the figure.
classmethod isAvailable()
Check to see if a MovieWriter subclass is actually available by running the commandline tool.
setup(fig, outfile, dpi=None)
Perform setup for writing the movie file.
Parameters fig : matplotlib.figure.Figure
The figure object that contains the information for frames
32.3. Helper Classes
685
Matplotlib, Release 2.1.2
outfile : string
The filename of the resulting movie file
dpi : int, optional
The DPI (or resolution) for the file. This controls the size in pixels of the
resulting movie file. Default is fig.dpi.
matplotlib.animation.FileMovieWriter
class matplotlib.animation.FileMovieWriter(*args, **kwargs)
MovieWriter for writing to individual files and stitching at the end.
This must be sub-classed to be useful.
__init__(*args, **kwargs)
Methods
__init__(*args, **kwargs)
bin_path()
cleanup()
finish ()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi, frame_prefix, . . . ])
Returns the binary path to the commandline tool
used by a specific subclass.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
cleanup()
finish()
frame_format
Format (png, jpeg, etc.) to use for saving the frames, which can be decided by the individual
subclasses.
grab_frame(**savefig_kwargs)
Grab the image information from the figure and save as a movie frame. All keyword arguments
in savefig_kwargs are passed on to the savefig command that saves the figure.
setup(fig, outfile, dpi=None, frame_prefix=’_tmp’, clear_temp=True)
686
Chapter 32. animation module
Matplotlib, Release 2.1.2
Perform setup for writing the movie file.
Parameters fig : matplotlib.figure.Figure
The figure to grab the rendered frames from.
outfile : str
The filename of the resulting movie file.
dpi : number, optional
The dpi of the output file. This, with the figure size, controls the size in pixels
of the resulting movie file. Default is fig.dpi.
frame_prefix : str, optional
The filename prefix to use for temporary files. Defaults to '_tmp'.
clear_temp : bool, optional
If the temporary files should be deleted after stitching the final result. Setting
this to False can be useful for debugging. Defaults to True.
and mixins are provided
AVConvBase
FFMpegBase
ImageMagickBase
Mixin class for avconv output.
Mixin class for FFMpeg output.
Mixin class for ImageMagick output.
matplotlib.animation.AVConvBase
class matplotlib.animation.AVConvBase
Mixin class for avconv output.
To be useful this must be multiply-inherited from with a MovieWriterBase sub-class.
__init__($ self, /, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
args_key = 'animation.avconv_args'
exec_key = 'animation.avconv_path'
matplotlib.animation.FFMpegBase
class matplotlib.animation.FFMpegBase
Mixin class for FFMpeg output.
To be useful this must be multiply-inherited from with a MovieWriterBase sub-class.
32.3. Helper Classes
687
Matplotlib, Release 2.1.2
__init__($ self, /, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
args_key = 'animation.ffmpeg_args'
exec_key = 'animation.ffmpeg_path'
output_args
matplotlib.animation.ImageMagickBase
class matplotlib.animation.ImageMagickBase
Mixin class for ImageMagick output.
To be useful this must be multiply-inherited from with a MovieWriterBase sub-class.
__init__($ self, /, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
Methods
isAvailable()
Check to see if a ImageMagickWriter is actually
available.
args_key = 'animation.convert_args'
delay
exec_key = 'animation.convert_path'
classmethod isAvailable()
Check to see if a ImageMagickWriter is actually available.
Done by first checking the windows registry (if applicable) and then running the commandline
tool.
output_args
See the source code for how to easily implement new MovieWriter classes.
688
Chapter 32. animation module
Matplotlib, Release 2.1.2
32.4 Inheritance Diagrams
matplotlib.animation.ArtistAnimation
matplotlib.animation.Animation
matplotlib.animation.TimedAnimation
matplotlib.animation.FuncAnimation
matplotlib.animation.FFMpegWriter
matplotlib.animation.AVConvWriter
matplotlib.animation.FFMpegBase
matplotlib.animation.AVConvBase
matplotlib.animation.AVConvFileWriter
matplotlib.animation.AbstractMovieWriter
matplotlib.animation.MovieWriter
matplotlib.animation.FileMovieWriter
matplotlib.animation.FFMpegFileWriter
matplotlib.animation.ImageMagickWriter
matplotlib.animation.ImageMagickBase
matplotlib.animation.ImageMagickFileWriter
32.5 Deprecated
MencoderBase
MencoderFileWriter
Deprecated since version 2.0.
MencoderWriter
Deprecated since version 2.0.
32.5.1 matplotlib.animation.MencoderBase
class matplotlib.animation.MencoderBase
__init__($ self, /, *args, **kwargs)
Initialize self. See help(type(self)) for accurate signature.
allowed_metadata = ['name', 'artist', 'genre', 'subject', 'copyright', 'srcform', 'comment
args_key = 'animation.mencoder_args'
exec_key = 'animation.mencoder_path'
32.5. Deprecated
689
Matplotlib, Release 2.1.2
output_args
32.5.2 matplotlib.animation.MencoderFileWriter
class matplotlib.animation.MencoderFileWriter(*args, **kwargs)
Deprecated since version 2.0: Support for mencoder is only partially functional, and will be removed
entirely in 2.2. Please use ffmpeg instead.
__init__(*args, **kwargs)
Deprecated since version 2.0: Support for mencoder is only partially functional, and will be
removed entirely in 2.2. Please use ffmpeg instead.
Methods
__init__(*args, **kwargs)
Deprecated since version 2.0.
bin_path()
Returns the binary path to the commandline tool
used by a specific subclass.
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi, frame_prefix, . . . ])
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
supported_formats = ['png', 'jpeg', 'tga', 'sgi']
32.5.3 matplotlib.animation.MencoderWriter
class matplotlib.animation.MencoderWriter(*args, **kwargs)
Deprecated since version 2.0: Support for mencoder is only partially functional, and will be removed
entirely in 2.2. Please use ffmpeg instead.
__init__(*args, **kwargs)
Deprecated since version 2.0: Support for mencoder is only partially functional, and will be
removed entirely in 2.2. Please use ffmpeg instead.
690
Chapter 32. animation module
Matplotlib, Release 2.1.2
Methods
__init__(*args, **kwargs)
Deprecated since version 2.0.
bin_path()
Returns the binary path to the commandline tool
used by a specific subclass.
Clean-up and collect the process used to write the
movie file.
Finish any processing for writing the movie.
Grab the image information from the figure and
save as a movie frame.
Check to see if a MovieWriter subclass is actually
available by running the commandline tool.
Context manager to facilitate writing the movie
file.
Perform setup for writing the movie file.
cleanup()
finish()
grab_frame(**savefig_kwargs)
isAvailable()
saving(fig, outfile, dpi, *args, **kwargs)
setup(fig, outfile[, dpi])
32.5. Deprecated
691
Matplotlib, Release 2.1.2
692
Chapter 32. animation module
693
Matplotlib, Release 2.1.2
CHAPTER
THIRTYTHREE
ARTIST MODULE
YTick
Tick
XTick
DrawingArea
HPacker
PackerBase
VPacker
OffsetImage
PaddedBox
OffsetBox
TextArea
AnchoredOffsetbox
AnchoredText
AuxTransformBox
TextWithDash
ClabelText
Text
Annotation
Polygon
FancyArrow
FancyBboxPatch
_AnnotationBase
PathPatch
AnnotationBbox
Shadow
Spine
Wedge
Patch
YAArrow
Arc
Figure
Ellipse
Circle
Legend
Arrow
Artist
_AxesBase
Rectangle
Cell
RegularPolygon
CirclePolygon
FancyArrowPatch
ConnectionPatch
Axes
PolarAxes
YAxis
GeoAxes
CustomCell
Line2D
QuiverKey
MollweideAxes
Table
AitoffAxes
Axis
HammerAxes
XAxis
LambertAxes
BboxImage
_ImageBase
FigureImage
PcolorImage
AxesImage
NonUniformImage
Barbs
TriMesh
PolyCollection
BrokenBarHCollection
_CollectionWithSizes
CircleCollection
Quiver
EllipseCollection
PathCollection
LineCollection
RegularPolyCollection
ScalarMappable
Collection
StarPolygonCollection
AsteriskPolygonCollection
PatchCollection
EventCollection
QuadMesh
694
Chapter 33. artist Module
Matplotlib, Release 2.1.2
33.1 Artist class
class matplotlib.artist.Artist
Abstract base class for someone who renders into a FigureCanvas.
33.1.1 Interactive
Artist.add_callback
Artist.format_cursor_data
Artist.get_contains
Artist.get_cursor_data
Artist.get_picker
Artist.hitlist
Artist.mouseover
Artist.pchanged
Artist.pick
Artist.pickable
Artist.remove_callback
Artist.set_contains
Artist.set_picker
Artist.contains
Adds a callback function that will be called whenever
one of the Artist’s properties changes.
Return cursor data string formatted.
Return the _contains test used by the artist, or None
for default.
Get the cursor data for a given event.
Return the picker object used by this artist.
List the children of the artist which contain the mouse
event event.
Fire an event when property changed, calling all of the
registered callbacks.
Process pick event
Return True if Artist is pickable.
Remove a callback based on its id.
Replace the contains test used by this artist.
Set the epsilon for picking used by this artist
Test whether the artist contains the mouse event.
matplotlib.artist.Artist.add_callback
Artist.add_callback(func)
Adds a callback function that will be called whenever one of the Artist’s properties changes.
Returns an id that is useful for removing the callback with remove_callback() later.
matplotlib.artist.Artist.format_cursor_data
Artist.format_cursor_data(data)
Return cursor data string formatted.
matplotlib.artist.Artist.get_contains
Artist.get_contains()
Return the _contains test used by the artist, or None for default.
33.1. Artist class
695
Matplotlib, Release 2.1.2
matplotlib.artist.Artist.get_cursor_data
Artist.get_cursor_data(event)
Get the cursor data for a given event.
matplotlib.artist.Artist.get_picker
Artist.get_picker()
Return the picker object used by this artist.
matplotlib.artist.Artist.hitlist
Artist.hitlist(event)
List the children of the artist which contain the mouse event event.
matplotlib.artist.Artist.mouseover
Artist.mouseover
matplotlib.artist.Artist.pchanged
Artist.pchanged()
Fire an event when property changed, calling all of the registered callbacks.
matplotlib.artist.Artist.pick
Artist.pick(mouseevent)
Process pick event
each child artist will fire a pick event if mouseevent is over the artist and the artist has picker set
matplotlib.artist.Artist.pickable
Artist.pickable()
Return True if Artist is pickable.
matplotlib.artist.Artist.remove_callback
Artist.remove_callback(oid)
Remove a callback based on its id.
See also:
696
Chapter 33. artist Module
Matplotlib, Release 2.1.2
add_callback() For adding callbacks
matplotlib.artist.Artist.set_contains
Artist.set_contains(picker)
Replace the contains test used by this artist. The new picker should be a callable function which
determines whether the artist is hit by the mouse event:
hit, props = picker(artist, mouseevent)
If the mouse event is over the artist, return hit = True and props is a dictionary of properties you want
returned with the contains test.
Parameters picker : callable
matplotlib.artist.Artist.set_picker
Artist.set_picker(picker)
Set the epsilon for picking used by this artist
picker can be one of the following:
• None: picking is disabled for this artist (default)
• A boolean: if True then picking will be enabled and the artist will fire a pick event if the mouse
event is over the artist
• A float: if picker is a number it is interpreted as an epsilon tolerance in points and the artist will
fire off an event if it’s data is within epsilon of the mouse event. For some artists like lines and
patch collections, the artist may provide additional data to the pick event that is generated, e.g.,
the indices of the data within epsilon of the pick event
• A function: if picker is callable, it is a user supplied function which determines whether the
artist is hit by the mouse event:
hit, props = picker(artist, mouseevent)
to determine the hit test. if the mouse event is over the artist, return hit=True and props is a
dictionary of properties you want added to the PickEvent attributes.
Parameters picker : None or bool or float or callable
matplotlib.artist.Artist.contains
Artist.contains(mouseevent)
Test whether the artist contains the mouse event.
33.1. Artist class
697
Matplotlib, Release 2.1.2
Returns the truth value and a dictionary of artist specific details of selection, such as which points are
contained in the pick radius. See individual artists for details.
33.1.2 Margins and Autoscaling
Artist.sticky_edges
x and y sticky edge lists.
matplotlib.artist.Artist.sticky_edges
Artist.sticky_edges
x and y sticky edge lists.
When performing autoscaling, if a data limit coincides with a value in the corresponding sticky_edges
list, then no margin will be added–the view limit “sticks” to the edge. A typical usecase is histograms,
where one usually expects no margin on the bottom edge (0) of the histogram.
This attribute cannot be assigned to; however, the x and y lists can be modified in place as needed.
Examples
>>> artist.sticky_edges.x[:] = (xmin, xmax)
>>> artist.sticky_edges.y[:] = (ymin, ymax)
33.1.3 Clipping
Artist.get_clip_box
Artist.get_clip_on
Artist.get_clip_path
Artist.set_clip_box
Artist.set_clip_on
Artist.set_clip_path
Return artist clipbox
Return whether artist uses clipping
Return artist clip path
Set the artist’s clip Bbox.
Set whether artist uses clipping.
Set the artist’s clip path, which may be:
matplotlib.artist.Artist.get_clip_box
Artist.get_clip_box()
Return artist clipbox
matplotlib.artist.Artist.get_clip_on
Artist.get_clip_on()
Return whether artist uses clipping
698
Chapter 33. artist Module
Matplotlib, Release 2.1.2
matplotlib.artist.Artist.get_clip_path
Artist.get_clip_path()
Return artist clip path
matplotlib.artist.Artist.set_clip_box
Artist.set_clip_box(clipbox)
Set the artist’s clip Bbox.
Parameters clipbox : Bbox
matplotlib.artist.Artist.set_clip_on
Artist.set_clip_on(b)
Set whether artist uses clipping.
When False artists will be visible out side of the axes which can lead to unexpected results.
Parameters b : bool
matplotlib.artist.Artist.set_clip_path
Artist.set_clip_path(path, transform=None)
Set the artist’s clip path, which may be:
• a Patch (or subclass) instance; or
• a Path instance, in which case a Transform instance, which will be applied to the path before
using it for clipping, must be provided; or
• None, to remove a previously set clipping path.
For efficiency, if the path happens to be an axis-aligned rectangle, this method will set the clipping
box to the corresponding rectangle and set the clipping path to None.
ACCEPTS: [(Path , Transform) | Patch | None]
33.1.4 Bulk Properties
Artist.update
Artist.update_from
Update this artist’s properties from the dictionary
prop.
Copy properties from other to self.
Continued on next page
33.1. Artist class
699
Matplotlib, Release 2.1.2
Table 33.4 – continued from previous page
Artist.properties
Artist.set
return a dictionary mapping property name -> value
for all Artist props
A property batch setter.
matplotlib.artist.Artist.update
Artist.update(props)
Update this artist’s properties from the dictionary prop.
matplotlib.artist.Artist.update_from
Artist.update_from(other)
Copy properties from other to self.
matplotlib.artist.Artist.properties
Artist.properties()
return a dictionary mapping property name -> value for all Artist props
matplotlib.artist.Artist.set
Artist.set(**kwargs)
A property batch setter. Pass kwargs to set properties.
33.1.5 Drawing
Artist.draw
Artist.get_animated
Artist.set_animated
Artist.get_agg_filter
Artist.get_alpha
Artist.get_snap
Artist.get_visible
Artist.get_zorder
Artist.set_agg_filter
Artist.set_alpha
Artist.set_sketch_params
Artist.set_snap
Artist.get_rasterized
Artist.get_sketch_params
Derived classes drawing method
Return the artist’s animated state
Set the artist’s animation state.
Return filter function to be used for agg filter.
Return the alpha value used for blending - not supported on all
Returns the snap setting which may be:
Return the artist’s visiblity
Return the artist’s zorder.
Set the agg filter.
Set the alpha value used for blending - not supported
on all backends.
Sets the sketch parameters.
Sets the snap setting which may be:
Return whether the artist is to be rasterized.
Returns the sketch parameters for the artist.
Continued on next page
700
Chapter 33. artist Module
Matplotlib, Release 2.1.2
Table 33.5 – continued from previous page
Artist.set_path_effects
Artist.set_rasterized
Set the path effects.
Force rasterized (bitmap) drawing in vector backend
output.
Artist.zorder
Artist.set_visible
Set the artist’s visibility.
Artist.set_zorder
Set the zorder for the artist.
Artist.get_window_extent
Get the axes bounding box in display space.
Artist.get_path_effects
Artist.get_transformed_clip_path_and_affineReturn the clip path with the non-affine part of its
transformation applied, and the remaining affine part
of its transformation.
matplotlib.artist.Artist.draw
Artist.draw(renderer, *args, **kwargs)
Derived classes drawing method
matplotlib.artist.Artist.get_animated
Artist.get_animated()
Return the artist’s animated state
matplotlib.artist.Artist.set_animated
Artist.set_animated(b)
Set the artist’s animation state.
Parameters b : bool
matplotlib.artist.Artist.get_agg_filter
Artist.get_agg_filter()
Return filter function to be used for agg filter.
matplotlib.artist.Artist.get_alpha
Artist.get_alpha()
Return the alpha value used for blending - not supported on all backends
33.1. Artist class
701
Matplotlib, Release 2.1.2
matplotlib.artist.Artist.get_snap
Artist.get_snap()
Returns the snap setting which may be:
• True: snap vertices to the nearest pixel center
• False: leave vertices as-is
• None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center
Only supported by the Agg and MacOSX backends.
matplotlib.artist.Artist.get_visible
Artist.get_visible()
Return the artist’s visiblity
matplotlib.artist.Artist.get_zorder
Artist.get_zorder()
Return the artist’s zorder.
matplotlib.artist.Artist.set_agg_filter
Artist.set_agg_filter(filter_func)
Set the agg filter.
Parameters filter_func : callable
A filter function, which takes a (m, n, 3) float array and a dpi value, and
returns a (m, n, 3) array.
matplotlib.artist.Artist.set_alpha
Artist.set_alpha(alpha)
Set the alpha value used for blending - not supported on all backends.
Parameters alpha : float
matplotlib.artist.Artist.set_sketch_params
Artist.set_sketch_params(scale=None, length=None, randomness=None)
Sets the sketch parameters.
Parameters scale : float, optional
702
Chapter 33. artist Module
Matplotlib, Release 2.1.2
The amplitude of the wiggle perpendicular to the source line, in pixels. If
scale is None, or not provided, no sketch filter will be provided.
length : float, optional
The length of the wiggle along the line, in pixels (default 128.0)
randomness : float, optional
The scale factor by which the length is shrunken or expanded (default 16.0)
matplotlib.artist.Artist.set_snap
Artist.set_snap(snap)
Sets the snap setting which may be:
• True: snap vertices to the nearest pixel center
• False: leave vertices as-is
• None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center
Only supported by the Agg and MacOSX backends.
Parameters snap : bool or None
matplotlib.artist.Artist.get_rasterized
Artist.get_rasterized()
Return whether the artist is to be rasterized.
matplotlib.artist.Artist.get_sketch_params
Artist.get_sketch_params()
Returns the sketch parameters for the artist.
Returns sketch_params : tuple or None
A 3-tuple with the following elements:
• scale: The amplitude of the wiggle perpendicular to the source line.
• length: The length of the wiggle along the line.
• randomness: The scale factor by which the length is shrunken or expanded.
May return None if no sketch parameters were set.
33.1. Artist class
703
Matplotlib, Release 2.1.2
matplotlib.artist.Artist.set_path_effects
Artist.set_path_effects(path_effects)
Set the path effects.
Parameters path_effects : AbstractPathEffect
matplotlib.artist.Artist.set_rasterized
Artist.set_rasterized(rasterized)
Force rasterized (bitmap) drawing in vector backend output.
Defaults to None, which implies the backend’s default behavior.
Parameters rasterized : bool or None
matplotlib.artist.Artist.zorder
Artist.zorder = 0
matplotlib.artist.Artist.set_visible
Artist.set_visible(b)
Set the artist’s visibility.
Parameters b : bool
matplotlib.artist.Artist.set_zorder
Artist.set_zorder(level)
Set the zorder for the artist. Artists with lower zorder values are drawn first.
Parameters level : float
matplotlib.artist.Artist.get_window_extent
Artist.get_window_extent(renderer)
Get the axes bounding box in display space. Subclasses should override for inclusion in the bounding
box “tight” calculation. Default is to return an empty bounding box at 0, 0.
704
Chapter 33. artist Module
Matplotlib, Release 2.1.2
Be careful when using this function, the results will not update if the artist window extent of the artist
changes. The extent can change due to any changes in the transform stack, such as changing the
axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to
unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.
matplotlib.artist.Artist.get_path_effects
Artist.get_path_effects()
matplotlib.artist.Artist.get_transformed_clip_path_and_affine
Artist.get_transformed_clip_path_and_affine()
Return the clip path with the non-affine part of its transformation applied, and the remaining affine
part of its transformation.
33.1.6 Figure and Axes
Artist.remove
Artist.axes
Artist.set_figure
Artist.get_figure
Artist.is_figure_set
Remove the artist from the figure if possible.
The Axes instance the artist resides in, or None.
Set the Figure instance the artist belongs to.
Return the Figure instance the artist belongs to.
Returns whether the artist is assigned to a Figure.
matplotlib.artist.Artist.remove
Artist.remove()
Remove the artist from the figure if possible. The effect will not be visible until the figure is redrawn,
e.g., with matplotlib.axes.Axes.draw_idle(). Call matplotlib.axes.Axes.relim() to
update the axes limits if desired.
Note: relim() will not see collections even if the collection was added to axes with autolim = True.
Note: there is no support for removing the artist’s legend entry.
matplotlib.artist.Artist.axes
Artist.axes
The Axes instance the artist resides in, or None.
matplotlib.artist.Artist.set_figure
Artist.set_figure(fig)
Set the Figure instance the artist belongs to.
33.1. Artist class
705
Matplotlib, Release 2.1.2
Parameters fig : Figure
matplotlib.artist.Artist.get_figure
Artist.get_figure()
Return the Figure instance the artist belongs to.
matplotlib.artist.Artist.is_figure_set
Artist.is_figure_set()
Returns whether the artist is assigned to a Figure.
33.1.7 Children
Artist.get_children
Artist.findobj
Return a list of the child
:class:`Artist contains.
Find artist objects.
Artist`s this
matplotlib.artist.Artist.get_children
Artist.get_children()
Return a list of the child Artist`s this :class:`Artist contains.
matplotlib.artist.Artist.findobj
Artist.findobj(match=None, include_self=True)
Find artist objects.
Recursively find all Artist instances contained in self.
match can be
• None: return all objects contained in artist.
• function with signature boolean = match(artist) used to filter matches
• class instance: e.g., Line2D. Only return artists of class type.
If include_self is True (default), include self in the list to be checked for a match.
33.1.8 Transform
Artist.set_transform
Set the artist transform.
Continued on next page
706
Chapter 33. artist Module
Matplotlib, Release 2.1.2
Table 33.8 – continued from previous page
Artist.get_transform
Artist.is_transform_set
Return the Transform instance used by this artist.
Returns True if Artist has a transform explicitly set.
matplotlib.artist.Artist.set_transform
Artist.set_transform(t)
Set the artist transform.
Parameters t : Transform
matplotlib.artist.Artist.get_transform
Artist.get_transform()
Return the Transform instance used by this artist.
matplotlib.artist.Artist.is_transform_set
Artist.is_transform_set()
Returns True if Artist has a transform explicitly set.
33.1.9 Units
Artist.convert_xunits
Artist.convert_yunits
Artist.have_units
For artists in an axes, if the xaxis has units support,
For artists in an axes, if the yaxis has units support,
Return True if units are set on the x or y axes
matplotlib.artist.Artist.convert_xunits
Artist.convert_xunits(x)
For artists in an axes, if the xaxis has units support, convert x using xaxis unit type
matplotlib.artist.Artist.convert_yunits
Artist.convert_yunits(y)
For artists in an axes, if the yaxis has units support, convert y using yaxis unit type
matplotlib.artist.Artist.have_units
Artist.have_units()
Return True if units are set on the x or y axes
33.1. Artist class
707
Matplotlib, Release 2.1.2
33.1.10 Metadata
Artist.get_gid
Artist.get_label
Artist.set_gid
Artist.set_label
Artist.get_url
Artist.set_url
Artist.aname
Returns the group id.
Get the label used for this artist in the legend.
Sets the (group) id for the artist.
Set the label to s for auto legend.
Returns the url.
Sets the url for the artist.
matplotlib.artist.Artist.get_gid
Artist.get_gid()
Returns the group id.
matplotlib.artist.Artist.get_label
Artist.get_label()
Get the label used for this artist in the legend.
matplotlib.artist.Artist.set_gid
Artist.set_gid(gid)
Sets the (group) id for the artist.
Parameters gid : str
matplotlib.artist.Artist.set_label
Artist.set_label(s)
Set the label to s for auto legend.
Parameters s : object
s will be converted to a string by calling str (unicode on Py2).
matplotlib.artist.Artist.get_url
Artist.get_url()
Returns the url.
708
Chapter 33. artist Module
Matplotlib, Release 2.1.2
matplotlib.artist.Artist.set_url
Artist.set_url(url)
Sets the url for the artist.
Parameters url : str
matplotlib.artist.Artist.aname
Artist.aname = 'Artist'
33.1.11 Stale
Artist.stale
If the artist is ‘stale’ and needs to be re-drawn for the
output to match the internal state of the artist.
matplotlib.artist.Artist.stale
Artist.stale
If the artist is ‘stale’ and needs to be re-drawn for the output to match the internal state of the artist.
33.2 Functions
allow_rasterization
get
getp
setp
kwdoc
ArtistInspector
Decorator for Artist.draw method.
Return the value of object’s property.
Return the value of object’s property.
Set a property on an artist object.
A helper class to inspect an Artist and return information about it’s settable properties and their current
values.
33.2.1 matplotlib.artist.allow_rasterization
matplotlib.artist.allow_rasterization(draw)
Decorator for Artist.draw method. Provides routines that run before and after the draw call. The
before and after functions are useful for changing artist-dependent renderer attributes or making other
setup function calls, such as starting and flushing a mixed-mode renderer.
33.2. Functions
709
Matplotlib, Release 2.1.2
33.2.2 matplotlib.artist.get
matplotlib.artist.get(obj, property=None)
Return the value of object’s property. property is an optional string for the property you want to
return
Example usage:
getp(obj) # get all the object properties
getp(obj, 'linestyle') # get the linestyle property
obj is a Artist instance, e.g., Line2D or an instance of a Axes or matplotlib.text.Text. If the
property is ‘somename’, this function returns
obj.get_somename()
getp() can be used to query all the gettable properties with getp(obj). Many properties have aliases
for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names
will be listed as:
property or alias = value
e.g.:
linewidth or lw = 2
33.2.3 matplotlib.artist.getp
matplotlib.artist.getp(obj, property=None)
Return the value of object’s property. property is an optional string for the property you want to
return
Example usage:
getp(obj) # get all the object properties
getp(obj, 'linestyle') # get the linestyle property
obj is a Artist instance, e.g., Line2D or an instance of a Axes or matplotlib.text.Text. If the
property is ‘somename’, this function returns
obj.get_somename()
getp() can be used to query all the gettable properties with getp(obj). Many properties have aliases
for shorter typing, e.g. ‘lw’ is an alias for ‘linewidth’. In the output, aliases and full property names
will be listed as:
property or alias = value
e.g.:
linewidth or lw = 2
710
Chapter 33. artist Module
Matplotlib, Release 2.1.2
33.2.4 matplotlib.artist.setp
matplotlib.artist.setp(obj, *args, **kwargs)
Set a property on an artist object.
matplotlib supports the use of setp() (“set property”) and getp() to set and get object properties,
as well as to do introspection on the object. For example, to set the linestyle of a line to be dashed,
you can do:
>>> line, = plot([1,2,3])
>>> setp(line, linestyle='--')
If you want to know the valid types of arguments, you can provide the name of the property you want
to set without a value:
>>> setp(line, 'linestyle')
linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
If you want to see all the properties that can be set, and their possible values, you can do:
>>> setp(line)
... long output listing omitted
You may specify another output file to setp if sys.stdout is not acceptable for some reason using
the file keyword-only argument:
>>> with fopen('output.log') as f:
>>>
setp(line, file=f)
setp() operates on a single instance or a iterable of instances. If you are in query mode introspecting
the possible values, only the first instance in the sequence is used. When actually setting values, all
the instances will be set. e.g., suppose you have a list of two lines, the following will make both lines
thicker and red:
>>>
>>>
>>>
>>>
>>>
x = arange(0,1.0,0.01)
y1 = sin(2*pi*x)
y2 = sin(4*pi*x)
lines = plot(x, y1, x, y2)
setp(lines, linewidth=2, color='r')
setp() works with the MATLAB style string/value pairs or with python kwargs. For example, the
following are equivalent:
>>> setp(lines, 'linewidth', 2, 'color', 'r')
>>> setp(lines, linewidth=2, color='r')
# MATLAB style
# python style
33.2.5 matplotlib.artist.kwdoc
matplotlib.artist.kwdoc(a)
33.2. Functions
711
Matplotlib, Release 2.1.2
33.2.6 matplotlib.artist.ArtistInspector
class matplotlib.artist.ArtistInspector(o)
A helper class to inspect an Artist and return information about it’s settable properties and their
current values.
Initialize the artist inspector with an Artist or iterable of Artists. If an iterable is used, we assume
it is a homogeneous sequence (all Artists are of the same type) and it is your responsibility to make
sure this is so.
__init__(o)
Initialize the artist inspector with an Artist or iterable of Artists. If an iterable is used,
we assume it is a homogeneous sequence (all Artists are of the same type) and it is your
responsibility to make sure this is so.
Methods
__init__(o)
aliased_name(s)
aliased_name_rest(s, target)
get_aliases()
get_setters()
get_valid_values(attr)
is_alias(o)
pprint_getters()
pprint_setters([prop, leadingspace])
pprint_setters_rest([prop, leadingspace])
properties()
Initialize the artist inspector with an Artist or iterable of Artists.
return ‘PROPNAME or alias’ if s has an alias, else
return
return ‘PROPNAME or alias’ if s has an alias, else
return
Get a dict mapping fullname -> alias for each alias
in the ArtistInspector.
Get the attribute strings with setters for object.
Get the legal arguments for the setter associated
with attr.
Return True if method object o is an alias for another function.
Return the getters and actual values as list of
strings.
If prop is None, return a list of strings of all settable
properies and their valid values.
If prop is None, return a list of strings of all settable
properies and their valid values.
return a dictionary mapping property name ->
value
aliased_name(s)
return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME.
e.g., for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’
and for the transform property, which does not, return ‘transform’
aliased_name_rest(s, target)
return ‘PROPNAME or alias’ if s has an alias, else return PROPNAME formatted for ReST
712
Chapter 33. artist Module
Matplotlib, Release 2.1.2
e.g., for the line markerfacecolor property, which has an alias, return ‘markerfacecolor or mfc’
and for the transform property, which does not, return ‘transform’
get_aliases()
Get a dict mapping fullname -> alias for each alias in the ArtistInspector.
e.g., for lines:
{'markerfacecolor': 'mfc',
'linewidth'
: 'lw',
}
get_setters()
Get the attribute strings with setters for object. e.g., for a line, return ['markerfacecolor',
'linewidth', ....].
get_valid_values(attr)
Get the legal arguments for the setter associated with attr.
This is done by querying the docstring of the function set_attr for a line that begins with ACCEPTS:
e.g., for a line linestyle, return “[ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]”
is_alias(o)
Return True if method object o is an alias for another function.
pprint_getters()
Return the getters and actual values as list of strings.
pprint_setters(prop=None, leadingspace=2)
If prop is None, return a list of strings of all settable properies and their valid values.
If prop is not None, it is a valid property name and that property will be returned as a string of
property : valid values.
pprint_setters_rest(prop=None, leadingspace=2)
If prop is None, return a list of strings of all settable properies and their valid values. Format the
output for ReST
If prop is not None, it is a valid property name and that property will be returned as a string of
property : valid values.
properties()
return a dictionary mapping property name -> value
33.2. Functions
713
Matplotlib, Release 2.1.2
714
Chapter 33. artist Module
CHAPTER
THIRTYFOUR
AXES CLASS
class matplotlib.axes.Axes(fig, rect, facecolor=None, frameon=True, sharex=None,
sharey=None, label=”, xscale=None, yscale=None, axisbg=None, **kwargs)
The Axes contains most of the figure elements: Axis, Tick, Line2D, Text, Polygon, etc., and sets
the coordinate system.
The Axes instance supports callbacks through a callbacks attribute which is a CallbackRegistry
instance. The events you can connect to are ‘xlim_changed’ and ‘ylim_changed’ and the callback will
be called with func(ax) where ax is the Axes instance.
Table of Contents
• Plotting
– Basic
– Spans
– Spectral
– Statistics
– Binned
– Contours
– Array
– Unstructured Triangles
– Text and Annotations
– Fields
• Clearing
• Appearance
• Property cycle
• Axis / limits
– Axis Limits and direction
715
Matplotlib, Release 2.1.2
– Axis Labels, title, and legend
– Axis scales
– Autoscaling and margins
– Aspect ratio
– Ticks and tick labels
• Units
• Adding Artists
• Twinning
• Axes Position
• Async/Event based
• Interactive
• Children
• Drawing
• Bulk property manipulation
• General Artist Properties
• Artist Methods
• Projection
• Other
• Inheritance
34.1 Plotting
34.1.1 Basic
Axes.plot
Axes.errorbar
Axes