matplotlib.pyplot

Pyplot function overview

pyplot

matplotlib.pyplot is a state-based interface to matplotlib.

matplotlib.pyplot.plotting()[source]

Function

Description

acorr

Plot the autocorrelation of x.

angle_spectrum

Plot the angle spectrum.

annotate

Annotate the point xy with text text.

arrow

Add an arrow to the Axes.

autoscale

Autoscale the axis view to the data (toggle).

axes

Add an axes to the current figure and make it the current axes.

axhline

Add a horizontal line across the axis.

axhspan

Add a horizontal span (rectangle) across the Axes.

axis

Convenience method to get or set some axis properties.

axline

Add an infinitely long straight line.

axvline

Add a vertical line across the Axes.

axvspan

Add a vertical span (rectangle) across the Axes.

bar

Make a bar plot.

bar_label

Label a bar plot.

barbs

Plot a 2D field of barbs.

barh

Make a horizontal bar plot.

box

Turn the axes box on or off on the current axes.

boxplot

Draw a box and whisker plot.

broken_barh

Plot a horizontal sequence of rectangles.

cla

Clear the current axes.

clabel

Label a contour plot.

clf

Clear the current figure.

clim

Set the color limits of the current image.

close

Close a figure window.

cohere

Plot the coherence between x and y.

colorbar

Add a colorbar to a plot.

contour

Plot contour lines.

contourf

Plot filled contours.

csd

Plot the cross-spectral density.

delaxes

Remove an Axes (defaulting to the current axes) from its figure.

draw

Redraw the current figure.

draw_if_interactive

Redraw the current figure if in interactive mode.

errorbar

Plot y versus x as lines and/or markers with attached errorbars.

eventplot

Plot identical parallel lines at the given positions.

figimage

Add a non-resampled image to the figure.

figlegend

Place a legend on the figure.

fignum_exists

Return whether the figure with the given id exists.

figtext

Add text to figure.

figure

Create a new figure, or activate an existing figure.

fill

Plot filled polygons.

fill_between

Fill the area between two horizontal curves.

fill_betweenx

Fill the area between two vertical curves.

findobj

Find artist objects.

gca

Get the current Axes, creating one if necessary.

gcf

Get the current figure.

gci

Get the current colorable artist.

get

Return the value of an Artist's property, or print all of them.

get_figlabels

Return a list of existing figure labels.

get_fignums

Return a list of existing figure numbers.

getp

Return the value of an Artist's property, or print all of them.

grid

Configure the grid lines.

hexbin

Make a 2D hexagonal binning plot of points x, y.

hist

Plot a histogram.

hist2d

Make a 2D histogram plot.

hlines

Plot horizontal lines at each y from xmin to xmax.

imread

Read an image from a file into an array.

imsave

Save an array as an image file.

imshow

Display data as an image, i.e., on a 2D regular raster.

install_repl_displayhook

Install a repl display hook so that any stale figure are automatically redrawn when control is returned to the repl.

ioff

Disable interactive mode.

ion

Enable interactive mode.

isinteractive

Return whether plots are updated after every plotting command.

legend

Place a legend on the Axes.

locator_params

Control behavior of major tick locators.

loglog

Make a plot with log scaling on both the x and y axis.

magnitude_spectrum

Plot the magnitude spectrum.

margins

Set or retrieve autoscaling margins.

matshow

Display an array as a matrix in a new figure window.

minorticks_off

Remove minor ticks from the axes.

minorticks_on

Display minor ticks on the axes.

new_figure_manager

Create a new figure manager instance.

pause

Run the GUI event loop for interval seconds.

pcolor

Create a pseudocolor plot with a non-regular rectangular grid.

pcolormesh

Create a pseudocolor plot with a non-regular rectangular grid.

phase_spectrum

Plot the phase spectrum.

pie

Plot a pie chart.

plot

Plot y versus x as lines and/or markers.

plot_date

Plot coercing the axis to treat floats as dates.

polar

Make a polar plot.

psd

Plot the power spectral density.

quiver

Plot a 2D field of arrows.

quiverkey

Add a key to a quiver plot.

rc

Set the current rcParams.

rc_context

Return a context manager for temporarily changing rcParams.

rcdefaults

Restore the rcParams from Matplotlib's internal default style.

rgrids

Get or set the radial gridlines on the current polar plot.

savefig

Save the current figure.

sca

Set the current Axes to ax and the current Figure to the parent of ax.

scatter

A scatter plot of y vs.

sci

Set the current image.

semilogx

Make a plot with log scaling on the x axis.

semilogy

Make a plot with log scaling on the y axis.

set_cmap

Set the default colormap, and applies it to the current image if any.

set_loglevel

Set Matplotlib's root logger and root logger handler level, creating the handler if it does not exist yet.

setp

Set one or more properties on an Artist, or list allowed values.

show

Display all open figures.

specgram

Plot a spectrogram.

spy

Plot the sparsity pattern of a 2D array.

stackplot

Draw a stacked area plot.

stairs

A stepwise constant function as a line with bounding edges or a filled plot.

stem

Create a stem plot.

step

Make a step plot.

streamplot

Draw streamlines of a vector flow.

subplot

Add an Axes to the current figure or retrieve an existing Axes.

subplot2grid

Create a subplot at a specific location inside a regular grid.

subplot_mosaic

Build a layout of Axes based on ASCII art or nested lists.

subplot_tool

Launch a subplot tool window for a figure.

subplots

Create a figure and a set of subplots.

subplots_adjust

Adjust the subplot layout parameters.

suptitle

Add a centered suptitle to the figure.

switch_backend

Close all open figures and set the Matplotlib backend.

table

Add a table to an Axes.

text

Add text to the Axes.

thetagrids

Get or set the theta gridlines on the current polar plot.

tick_params

Change the appearance of ticks, tick labels, and gridlines.

ticklabel_format

Configure the ScalarFormatter used by default for linear axes.

tight_layout

Adjust the padding between and around subplots.

title

Set a title for the Axes.

tricontour

Draw contour lines on an unstructured triangular grid.

tricontourf

Draw contour regions on an unstructured triangular grid.

tripcolor

Create a pseudocolor plot of an unstructured triangular grid.

triplot

Draw a unstructured triangular grid as lines and/or markers.

twinx

Make and return a second axes that shares the x-axis.

twiny

Make and return a second axes that shares the y-axis.

uninstall_repl_displayhook

Uninstall the Matplotlib display hook.

violinplot

Make a violin plot.

vlines

Plot vertical lines at each x from ymin to ymax.

xcorr

Plot the cross correlation between x and y.

xkcd

Turn on xkcd sketch-style drawing mode.

xlabel

Set the label for the x-axis.

xlim

Get or set the x limits of the current axes.

xscale

Set the x-axis scale.

xticks

Get or set the current tick locations and labels of the x-axis.

ylabel

Set the label for the y-axis.

ylim

Get or set the y-limits of the current axes.

yscale

Set the y-axis scale.

yticks

Get or set the current tick locations and labels of the y-axis.

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 Choosing Colormaps in Matplotlib tutorial.

matplotlib.pyplot.colormaps()[source]

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

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 colormaps which are the recommended colormaps for sequential data:

Colormap

Description

inferno

perceptually uniform shades of black-red-yellow

magma

perceptually uniform shades of black-red-white

plasma

perceptually uniform shades of blue-red-yellow

viridis

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 differently-colored endpoints):

Colormap

Description

BrBG

brown, white, blue-green

PiYG

pink, white, yellow-green

PRGn

purple, white, green

PuOr

orange, white, purple

RdBu

red, white, blue

RdGy

red, white, gray

RdYlBu

red, yellow, blue

RdYlGn

red, yellow, green

Spectral

red, orange, yellow, green, blue

ColorBrewer Sequential (luminance decreases monotonically):

Colormap

Description

Blues

white to dark blue

BuGn

white, light blue, dark green

BuPu

white, light blue, dark purple

GnBu

white, light green, dark blue

Greens

white to dark green

Greys

white to black (not linear)

Oranges

white, orange, dark brown

OrRd

white, orange, dark red

PuBu

white, light purple, dark blue

PuBuGn

white, light purple, dark green

PuRd

white, light purple, dark red

Purples

white to dark purple

RdPu

white, pink, dark purple

Reds

white to dark red

YlGn

light yellow, dark green

YlGnBu

light yellow, light green, dark blue

YlOrBr

light yellow, orange, dark brown

YlOrRd

light yellow, orange, dark red

ColorBrewer Qualitative:

(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

sequential linearly-increasing shades of red-orange-yellow

bone

sequential increasing black-white colormap with a tinge of blue, to emulate X-ray film

cool

linearly-decreasing shades of cyan-magenta

copper

sequential increasing shades of black-copper

flag

repetitive red-white-blue-black pattern (not cyclic at endpoints)

gray

sequential linearly-increasing black-to-white grayscale

hot

sequential black-red-yellow-white, to emulate blackbody radiation from an object at increasing temperatures

jet

a spectral map with dark endpoints, blue-cyan-yellow-red; based on a fluid-jet simulation by NCSA 1

pink

sequential increasing pastel black-pink-white, meant for sepia tone colorization of photographs

prism

repetitive red-yellow-green-blue-purple-...-green pattern (not cyclic at endpoints)

spring

linearly-increasing shades of magenta-yellow

summer

sequential linearly-increasing shades of green-yellow

winter

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:

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 Research 2

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

A set of cyclic colormaps:

Colormap

Description

hsv

red-yellow-green-cyan-blue-magenta-red, formed by changing the hue component in the HSV color space

twilight

perceptually uniform shades of white-blue-black-red-white

twilight_shifted

perceptually uniform shades of black-blue-white-red-black

Other miscellaneous schemes:

Colormap

Description

afmhot

sequential black-orange-yellow-white blackbody spectrum, commonly used in atomic force microscopy

brg

blue-red-green

bwr

diverging blue-white-red

coolwarm

diverging blue-gray-red, meant to avoid issues with 3D shading, color blindness, and ordering of colors 3

CMRmap

"Default colormaps on color images often reproduce to confusing grayscale images. The proposed colormap maintains an aesthetically pleasing color image that automatically reproduces to a monotonic grayscale with discrete, quantifiable saturation levels." 4

cubehelix

Unlike most other color schemes cubehelix was designed by D.A. Green to be monotonically increasing in terms of perceived brightness. Also, when printed 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.

gnuplot

gnuplot's traditional pm3d scheme (black-blue-red-yellow)

gnuplot2

sequential color printable as gray (black-blue-violet-yellow-white)

ocean

green-blue-white

rainbow

spectral purple-blue-green-yellow-orange-red colormap with diverging luminance

seismic

diverging blue-white-red

nipy_spectral

black-purple-blue-green-yellow-red-white spectrum, originally from the Neuroimaging in Python project

terrain

mapmaker's colors, blue-green-yellow-brown-white, originally from IGOR Pro

turbo

Spectral map (purple-blue-green-yellow-orange-red) with a bright center and darker endpoints. A smoother alternative to jet.

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

identical to gray

gist_yarg

identical to gray_r

binary

identical to gray_r

Footnotes

1

Rainbow colormaps, jet in particular, are considered a poor choice for scientific visualization by many researchers: Rainbow Color Map (Still) Considered Harmful

2

Resembles "BkBlAqGrYeOrReViWh200" from NCAR Command Language. See Color Table Gallery

3

See Diverging Color Maps for Scientific Visualization by Kenneth Moreland.

4

See A Color Map for Effective Black-and-White Rendering of Color-Scale Images by Carey Rappaport