This module provides a Julia interface to the
Matplotlib plotting library from Python, and
specifically to the matplotlib.pyplot
module.
PyPlot uses the Julia PyCall package to call Matplotlib directly from Julia with little or no overhead (arrays are passed without making a copy).
This package takes advantage of Julia's multimedia I/O API to display plots in any Julia graphical backend, including as inline graphics in IJulia. Alternatively, you can use a Python-based graphical Matplotlib backend to support interactive plot zooming etcetera.
(This PyPlot package replaces an earlier package of the same name by Junfeng Li, which used PyPlot over a ZeroMQ socket with IPython.)
You will need to have the Python Matplotlib library installed on your machine in order to use PyPlot. You can either do inline plotting with IJulia, which doesn't require a GUI backend, or use the Qt, wx, or GTK+ backends of Matplotlib as described below.
Once Matplotlib is installed, then you can just use
Pkg.add("PyPlot")
in Julia to install PyPlot and its dependencies.
MacOS 10.9 comes with Python and Matplotlib, but this version of
Matplotlib only comes with the Cocoa GUI backend, which is not
supported by PyPlot.
So, unless you are running IJulia (which requires you to install
ipython
), you will need a different version of Matplotlib.
For IJulia plots, a working Matplotlib is included as part of the
Anaconda Python distribution
(which also includes ipython
and other IJulia dependencies).
Otherwise, you can use the Homebrew package manager:
brew install python gfortran freetype pyqt
ln -s /usr/local/Cellar/freetype/2.5.3_1/include/freetype2/ /usr/local/include/freetype
export PATH="/usr/local/bin:$PATH"
export PYTHONPATH=/usr/local/lib/python2.7
pip install numpy scipy matplotlib
(You may want to add the two export
commands to your ~/.profile
file so that they
are automatically executed whenever you start a shell.)
Once Matplotlib and PyPlot are installed, and you are using a
graphics-capable Julia environment such as IJulia, you can simply type
using PyPlot
and begin calling functions in the
matplotlib.pyplot API.
For example:
using PyPlot
x = linspace(0,2*pi,1000); y = sin(3*x + 4*cos(2*x));
plot(x, y, color="red", linewidth=2.0, linestyle="--")
title("A sinusoidally modulated sinusoid")
In general, all of the arguments, including keyword arguments, are
exactly the same as in Python. (With minor translations, of course,
e.g. Julia uses true
and nothing
instead of Python's True
and
None
.)
The full matplotlib.pyplot
API is far too extensive to describe here;
see the matplotlib.pyplot documentation for more
information
Only the currently documented matplotlib.pyplot
API is exported. To use
other functions in the module, you can also call matplotlib.pyplot.foo(...)
as plt.foo(...)
. For example, plt.plot(x, y)
also works. (And
the raw PyObject
s for the matplotlib
and pyplot
modules are accessible
as PyPlot.matplotlib
and PyPlot.pltm
, respectively.)
You must also use plt
to access some functions that conflict with
built-in Julia functions. In particular, plt.hist
and plt.xcorr
must be used to access matplotlib.pyplot.hist
and
matplotlib.pyplot.xcorr
, respectively.
If you wish to access all of the PyPlot functions exclusively
through plt.somefunction(...)
, as is conventional in Python, simply
do import PyPlot.plt
instead of using PyPlot
.
You can get the current figure as a Figure
object (a wrapper
around matplotlib.pyplot.Figure
) by calling gcf()
.
The Figure
type supports Julia's multimedia I/O
API,
so you can use display(fig)
to show a fig::PyFigure
and
writemime(io, mime, fig)
to write it to a given mime
type string
(e.g. "image/png"
or "application/pdf"
) that is supported by the
Matplotlib backend.
PyPlot can use any Julia graphics backend capable of displaying PNG,
SVG, or PDF images, such as the IJulia environment. To use a
different backend, simply call pushdisplay
with the desired
Display
; see the Julia multimedia display
API
for more detail.
On the other hand, you may wish to use one of the Python Matplotlib backends to open an interactive window for each plot (for interactive zooming, panning, etcetera). You can do this at any time by running:
pygui(true)
to turn on the Python-based GUI (if possible) for subsequent plots,
while pygui(false)
will return to the Julia backend. Even when a
Python GUI is running, you can display the current figure with the
Julia backend by running display(gcf())
.
If no Julia graphics backend is available when PyPlot is imported, then
pygui(true)
is the default.
Only the wxWidgets,
GTK+, and Qt (via the
PyQt4 or
PySide, Python GUI backends are
supported by PyPlot. (Obviously, you must have installed one of these
toolkits for Python first.) By default, PyPlot picks one of these
when it starts up (based on what you have installed), but you can
force a specific toolkit to be chosen by importing the PyCall module
and using its pygui
function to set a Python backend before
importing PyPlot:
using PyCall
pygui(gui)
using PyPlot
where gui
can currently be one of :wx
, :gtk
, or :qt
.
The PyPlot module also exports some functions and types based on the matplotlib.colors and matplotlib.cm modules to simplify management of color maps (which are used to assign values to colors in various plot types). In particular:
-
ColorMap
: a wrapper around the matplotlib.colors.Colormap type. The following constructors are provided:-
ColorMap{T<:ColorValue}(name::String, c::AbstractVector{T}, n=256, gamma=1.0)
constructs ann
-component colormap by linearly interpolating the colors in the arrayc
ofColorValue
s (from the Color.jl package). If you want aname
to be constructed automatically, callColorMap(c, n=256, gamma=1.0)
instead. -
Even more general color maps may be defined by passing arrays of (x,y0,y1) tuples for the red, green, blue, and (optionally) alpha components, as defined by the matplotlib.colors.LinearSegmentedColormap constructor, via:
ColorMap{T<:Real}(name::String, r::AbstractVector{(T,T,T)}, g::AbstractVector{(T,T,T)}, b::AbstractVector{(T,T,T)}, n=256, gamma=1.0)
orColorMap{T<:Real}(name::String, r::AbstractVector{(T,T,T)}, g::AbstractVector{(T,T,T)}, b::AbstractVector{(T,T,T)}, alpha::AbstractVector{(T,T,T)}, n=256, gamma=1.0)
-
ColorMap(name::String)
returns an existing (registered) colormap, equivalent to matplotlib.cm.get_cmap(name
). -
matplotlib.colors.Colormap
objects returned by Python functions are automatically converted to theColorMap
type.
-
-
get_cmap(name::String)
orget_cmap(name::String, lut::Integer)
call the matplotlib.cm.get_cmap function. -
register_cmap(c::ColorMap)
orregister_cmap(name::String, c::ColorMap)
call the matplotlib.cm.register_cmap function. -
get_cmaps()
returns aVector{ColorMap}
of the currently registered colormaps.
Note that, given an SVG-supporting display environment like IJulia,
ColorMap
and Vector{ColorMap}
objects are displayed graphically;
try get_cmaps()
!
The PyPlot package also imports functions from Matplotlib's
mplot3d toolkit.
Unlike Matplotlib, however, you can create 3d plots directly without
first creating an
Axes3d
object, simply by calling one of: bar3D
, contour3D
, contourf3D
,
plot3D
, plot_surface
, plot_trisurf
, plot_wireframe
, or
scatter3D
(as well as text2D
, text3D
), exactly like the
correspondingly named methods of
Axes3d.
We also export the Matlab-like synonyms surf
for plot_surface
(or
plot_trisurf
for 1d-array arguments) and mesh
for
plot_wireframe
. For example, you can do:
surf(rand(30,40))
to plot a random 30ร40 surface mesh.
You can also explicitly create a subplot with 3d axes via, for
example, subplot(111, projection="3d")
, exactly as in Matplotlib.
The Axes3d
constructor and the
art3d
module are also exported.
Matplotlib allows you to use LaTeX equations in plot
labels, titles, and so on
simply by enclosing the equations in dollar signs ($ ... $
) within
the string. However, typing LaTeX equations in Julia string literals
is awkward because escaping is necessary to prevent Julia from
interpreting the dollar signs and backslashes itself; for example, the
LaTeX equation $\alpha + \beta$
would be the literal string
"\$\\alpha + \\beta\$"
in Julia.
To simplify this, PyPlot provides a new LaTeXString
type which can
be constructed via L"...."
without escaping backslashes or dollar
signs. For example, one can simply write L"$\alpha + \beta$"
for the
abovementioned equation, and thus you can do things like:
title(L"Plot of $\Gamma_3(x)$")
(As an added benefit, a LaTeXString
is
automatically displayed as a rendered equation in IJulia.)
By default, plots in IJulia are sent to the notebook as PNG images. Optionally, you can tell PyPlot to display plots in the browser as SVG images, which have the advantage of being resolution-independent (so that they display without pixellation at high-resolutions, for example if you convert an IJulia notebook to PDF), by running:
PyPlot.svg(true)
This is not the default because SVG plots in the browser are much
slower to display (especially for complex plots) and may display
inaccurately in some browsers with buggy SVG support. The PyPlot.svg()
method returns whether SVG display is currently enabled.
Note that this is entirely separate from manually exporting plots to SVG
or any other format. Regardless of whether PyPlot uses SVG for
browser display, you can export a plot to SVG at any time by using the
Matplotlib
savefig
command, e.g. savefig("plot.svg")
.
This module was written by Steven G. Johnson.