matplotlib.axes.Axes.plot#

Axes.plot(*args, scalex=True, scaley=True, data=None, **kwargs)[source]#

Plot y versus x as lines and/or markers.

Call signatures:

plot([x], y, [fmt], *, data=None, **kwargs)
plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

The coordinates of the points or line nodes are given by x, y.

The optional parameter fmt is a convenient way for defining basic formatting like color, marker and linestyle. It's a shortcut string notation described in the Notes section below.

>>> plot(x, y)        # plot x and y using default line style and color
>>> plot(x, y, 'bo')  # plot x and y using blue circle markers
>>> plot(y)           # plot y using x as index array 0..N-1
>>> plot(y, 'r+')     # ditto, but with red plusses

You can use Line2D properties as keyword arguments for more control on the appearance. Line properties and fmt can be mixed. The following two calls yield identical results:

>>> plot(x, y, 'go--', linewidth=2, markersize=12)
>>> plot(x, y, color='green', marker='o', linestyle='dashed',
...      linewidth=2, markersize=12)

When conflicting with fmt, keyword arguments take precedence.

Plotting labelled data

There's a convenient way for plotting objects with labelled data (i.e. data that can be accessed by index obj['y']). Instead of giving the data in x and y, you can provide the object in the data parameter and just give the labels for x and y:

>>> plot('xlabel', 'ylabel', data=obj)

All indexable objects are supported. This could e.g. be a dict, a pandas.DataFrame or a structured numpy array.

Plotting multiple sets of data

There are various ways to plot multiple sets of data.

  • The most straight forward way is just to call plot multiple times. Example:

    >>> plot(x1, y1, 'bo')
    >>> plot(x2, y2, 'go')
    
  • If x and/or y are 2D arrays a separate data set will be drawn for every column. If both x and y are 2D, they must have the same shape. If only one of them is 2D with shape (N, m) the other must have length N and will be used for every data set m.

    Example:

    >>> x = [1, 2, 3]
    >>> y = np.array([[1, 2], [3, 4], [5, 6]])
    >>> plot(x, y)
    

    is equivalent to:

    >>> for col in range(y.shape[1]):
    ...     plot(x, y[:, col])
    
  • The third way is to specify multiple sets of [x], y, [fmt] groups:

    >>> plot(x1, y1, 'g^', x2, y2, 'g-')
    

    In this case, any additional keyword argument applies to all datasets. Also, this syntax cannot be combined with the data parameter.

By default, each line is assigned a different style specified by a 'style cycle'. The fmt and line property parameters are only necessary if you want explicit deviations from these defaults. Alternatively, you can also change the style cycle using rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'])).

Parameters:
x, yarray-like or scalar

The horizontal / vertical coordinates of the data points. x values are optional and default to range(len(y)).

Commonly, these parameters are 1D arrays.

They can also be scalars, or two-dimensional (in that case, the columns represent separate data sets).

These arguments cannot be passed as keywords.

fmtstr, optional

A format string, e.g. 'ro' for red circles. See the Notes section for a full description of the format strings.

Format strings are just an abbreviation for quickly setting basic line properties. All of these and more can also be controlled by keyword arguments.

This argument cannot be passed as keyword.

dataindexable object, optional

An object with labelled data. If given, provide the label names to plot in x and y.

Note

Technically there's a slight ambiguity in calls where the second label is a valid fmt. plot('n', 'o', data=obj) could be plt(x, y) or plt(y, fmt). In such cases, the former interpretation is chosen, but a warning is issued. You may suppress the warning by adding an empty format string plot('n', 'o', '', data=obj).

Returns:
list of Line2D

A list of lines representing the plotted data.

Other Parameters:
scalex, scaleybool, default: True

These parameters determine if the view limits are adapted to the data limits. The values are passed on to autoscale_view.

**kwargsLine2D properties, optional

kwargs are used to specify properties like a line label (for auto legends), linewidth, antialiasing, marker face color. Example:

>>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
>>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')

If you specify multiple lines with one plot call, the kwargs apply to all those lines. In case the label object is iterable, each element is used as labels for each set of data.

Here is a list of available Line2D properties:

Property

Description

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

scalar or None

animated

bool

antialiased or aa

bool

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

color or c

color

dash_capstyle

CapStyle or {'butt', 'projecting', 'round'}

dash_joinstyle

JoinStyle or {'miter', 'round', 'bevel'}

dashes

sequence of floats (on/off ink in points) or (None, None)

data

(2, N) array or two 1D arrays

drawstyle or ds

{'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default'

figure

Figure

fillstyle

{'full', 'left', 'right', 'bottom', 'top', 'none'}

gapcolor

color or None

gid

str

in_layout

bool

label

object

linestyle or ls

{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

linewidth or lw

float

marker

marker style string, Path or MarkerStyle

markeredgecolor or mec

color

markeredgewidth or mew

float

markerfacecolor or mfc

color

markerfacecoloralt or mfcalt

color

markersize or ms

float

markevery

None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool]

mouseover

bool

path_effects

list of AbstractPathEffect

picker

float or callable[[Artist, Event], tuple[bool, dict]]

pickradius

float

rasterized

bool

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

solid_capstyle

CapStyle or {'butt', 'projecting', 'round'}

solid_joinstyle

JoinStyle or {'miter', 'round', 'bevel'}

transform

unknown

url

str

visible

bool

xdata

1D array

ydata

1D array

zorder

float

See also

scatter

XY scatter plot with markers of varying size and/or color ( sometimes also called bubble chart).

Notes

Format Strings

A format string consists of a part for color, marker and line:

fmt = '[marker][line][color]'

Each of them is optional. If not provided, the value from the style cycle is used. Exception: If line is given, but no marker, the data will be a line without markers.

Other combinations such as [color][marker][line] are also supported, but note that their parsing may be ambiguous.

Markers

character

description

'.'

point marker

','

pixel marker

'o'

circle marker

'v'

triangle_down marker

'^'

triangle_up marker

'<'

triangle_left marker

'>'

triangle_right marker

'1'

tri_down marker

'2'

tri_up marker

'3'

tri_left marker

'4'

tri_right marker

'8'

octagon marker

's'

square marker

'p'

pentagon marker

'P'

plus (filled) marker

'*'

star marker

'h'

hexagon1 marker

'H'

hexagon2 marker

'+'

plus marker

'x'

x marker

'X'

x (filled) marker

'D'

diamond marker

'd'

thin_diamond marker

'|'

vline marker

'_'

hline marker

Line Styles

character

description

'-'

solid line style

'--'

dashed line style

'-.'

dash-dot line style

':'

dotted line style

Example format strings:

'b'    # blue markers with default shape
'or'   # red circles
'-g'   # green solid line
'--'   # dashed line with default color
'^k:'  # black triangle_up markers connected by a dotted line

Colors

The supported color abbreviations are the single letter codes

character

color

'b'

blue

'g'

green

'r'

red

'c'

cyan

'm'

magenta

'y'

yellow

'k'

black

'w'

white

and the 'CN' colors that index into the default property cycle.

If the color is the only part of the format string, you can additionally use any matplotlib.colors spec, e.g. full names ('green') or hex strings ('#008000').

Examples using matplotlib.axes.Axes.plot#

Plotting categorical variables

Plotting categorical variables

Cross spectral density (CSD)

Cross spectral density (CSD)

Curve with error band

Curve with error band

EventCollection Demo

EventCollection Demo

Fill Between and Alpha

Fill Between and Alpha

Filling the area between lines

Filling the area between lines

Fill Betweenx Demo

Fill Betweenx Demo

Customizing dashed line styles

Customizing dashed line styles

Lines with a ticked patheffect

Lines with a ticked patheffect

Marker reference

Marker reference

Markevery Demo

Markevery Demo

Mapping marker properties to multivariate data

Mapping marker properties to multivariate data

Power spectral density (PSD)

Power spectral density (PSD)

Simple Plot

Simple Plot

Shade regions defined by a logical mask using fill_between

Shade regions defined by a logical mask using fill_between

Step Demo

Step Demo

Creating a timeline with lines, dates, and text

Creating a timeline with lines, dates, and text

hlines and vlines

hlines and vlines

Contour Corner Mask

Contour Corner Mask

Contour plot of irregularly spaced data

Contour plot of irregularly spaced data

pcolormesh grids and shading

pcolormesh grids and shading

Spectrogram

Spectrogram

Triinterp Demo

Triinterp Demo

Aligning Labels

Aligning Labels

Programmatically controlling subplot adjustment

Programmatically controlling subplot adjustment

Axes box aspect

Axes box aspect

Axes Demo

Axes Demo

Controlling view limits using margins and sticky_edges

Controlling view limits using margins and sticky_edges

Axes Props

Axes Props

axhspan Demo

axhspan Demo

Broken Axis

Broken Axis

Resizing axes with constrained layout

Resizing axes with constrained layout

Resizing axes with tight layout

Resizing axes with tight layout

Figure labels: suptitle, supxlabel, supylabel

Figure labels: suptitle, supxlabel, supylabel

Invert Axes

Invert Axes

Secondary Axis

Secondary Axis

Sharing axis limits and views

Sharing axis limits and views

Figure subfigures

Figure subfigures

Multiple subplots

Multiple subplots

Creating multiple subplots using plt.subplots

Creating multiple subplots using plt.subplots

Plots with different scales

Plots with different scales

Boxplots

Boxplots

Some features of the histogram (hist) function

Some features of the histogram (hist) function

Polar plot

Polar plot

Polar legend

Polar legend

Accented text

Accented text

Align y-labels

Align y-labels

Scale invariant angle label

Scale invariant angle label

Annotate Transform

Annotate Transform

Annotating a plot

Annotating a plot

Annotating Plots

Annotating Plots

Annotation Polar

Annotation Polar

Composing Custom Legends

Composing Custom Legends

Date tick labels

Date tick labels

AnnotationBbox demo

AnnotationBbox demo

Labeling ticks using engineering notation

Labeling ticks using engineering notation

Annotation arrow style reference

Annotation arrow style reference

Legend using pre-defined labels

Legend using pre-defined labels

Legend Demo

Legend Demo

Mathtext

Mathtext

Math fontfamily

Math fontfamily

Multiline

Multiline

Rendering math equations using TeX

Rendering math equations using TeX

Text Commands

Text Commands

Text Rotation Relative To Line

Text Rotation Relative To Line

Title positioning

Title positioning

Text watermark

Text watermark

Color Demo

Color Demo

Color by y-value

Color by y-value

Selecting individual colors from a colormap

Selecting individual colors from a colormap

Ellipse with orientation arrow demo

Ellipse with orientation arrow demo

PathPatch object

PathPatch object

Bezier Curve

Bezier Curve

Dark background style sheet

Dark background style sheet

FiveThirtyEight style sheet

FiveThirtyEight style sheet

ggplot style sheet

ggplot style sheet

Multiple lines using pyplot

Multiple lines using pyplot

Axes with a fixed physical size

Axes with a fixed physical size

Parasite Simple

Parasite Simple

Simple Axisline4

Simple Axisline4

Axis line styles

Axis line styles

Parasite Axes demo

Parasite Axes demo

Parasite axis demo

Parasite axis demo

Custom spines with axisartist

Custom spines with axisartist

Simple Axisline

Simple Axisline

Anatomy of a figure

Anatomy of a figure

Integral as the area under a curve

Integral as the area under a curve

Stock prices over 32 years

Stock prices over 32 years

XKCD

XKCD

Decay

Decay

The Bayes update

The Bayes update

The double pendulum problem

The double pendulum problem

Multiple axes animation

Multiple axes animation

Animated 3D random walk

Animated 3D random walk

Animated line plot

Animated line plot

MATPLOTLIB UNCHAINED

MATPLOTLIB UNCHAINED

Mouse move and click events

Mouse move and click events

Cross-hair cursor

Cross-hair cursor

Data browser

Data browser

Keypress event

Keypress event

Legend picking

Legend picking

Looking Glass

Looking Glass

Path editor

Path editor

Pick event demo

Pick event demo

Pick event demo 2

Pick event demo 2

Resampling Data

Resampling Data

Timers

Timers

Changing colors of lines intersecting a box

Changing colors of lines intersecting a box

Custom projection

Custom projection

Patheffect Demo

Patheffect Demo

SVG Filter Line

SVG Filter Line

TickedStroke patheffect

TickedStroke patheffect

Zorder Demo

Zorder Demo

Plot 2D data on 3D plot

Plot 2D data on 3D plot

3D box surface plot

3D box surface plot

Parametric curve

Parametric curve

Lorenz attractor

Lorenz attractor

2D and 3D axes in same figure

2D and 3D axes in same figure

Asinh Demo

Asinh Demo

Loglog Aspect

Loglog Aspect

Scales

Scales

Symlog Demo

Symlog Demo

Anscombe's quartet

Anscombe's quartet

Ishikawa Diagram

Ishikawa Diagram

Radar chart (aka spider or star chart)

Radar chart (aka spider or star chart)

Spines

Spines

Spine placement

Spine placement

Multiple y-axis with Spines

Multiple y-axis with Spines

Centered spines with arrows

Centered spines with arrows

Centering labels between ticks

Centering labels between ticks

Formatting date ticks using ConciseDateFormatter

Formatting date ticks using ConciseDateFormatter

Date Demo Convert

Date Demo Convert

Custom tick formatter for time series

Custom tick formatter for time series

Date Precision and Epochs

Date Precision and Epochs

Dollar ticks

Dollar ticks

Major and minor ticks

Major and minor ticks

Multilevel (nested) ticks

Multilevel (nested) ticks

Set default y-axis tick labels on the right

Set default y-axis tick labels on the right

Setting tick labels from a list of values

Setting tick labels from a list of values

Move x-axis tick labels to the top

Move x-axis tick labels to the top

Evans test

Evans test

CanvasAgg demo

CanvasAgg demo

Annotated cursor

Annotated cursor

Buttons

Buttons

Check buttons

Check buttons

Cursor

Cursor

Multicursor

Multicursor

Rectangle and ellipse selectors

Rectangle and ellipse selectors

Slider

Slider

Snapping Sliders to Discrete Values

Snapping Sliders to Discrete Values

Span Selector

Span Selector

Textbox

Textbox

Annotate Explain

Annotate Explain

Connection styles for annotations

Connection styles for annotations

Nested GridSpecs

Nested GridSpecs

PGF fonts

PGF fonts

PGF texsystem

PGF texsystem

Simple Annotate01

Simple Annotate01

Simple Legend01

Simple Legend01

Simple Legend02

Simple Legend02

Artist tutorial

Artist tutorial

plot(x, y)

plot(x, y)

fill_between(x, y1, y2)

fill_between(x, y1, y2)

tricontour(x, y, z)

tricontour(x, y, z)

tricontourf(x, y, z)

tricontourf(x, y, z)

tripcolor(x, y, z)

tripcolor(x, y, z)

Quick start guide

Quick start guide

Animations using Matplotlib

Animations using Matplotlib

Faster rendering by using blitting

Faster rendering by using blitting

Styling with cycler

Styling with cycler

Path Tutorial

Path Tutorial

Transformations Tutorial

Transformations Tutorial

Legend guide

Legend guide

Constrained layout guide

Constrained layout guide

Tight layout guide

Tight layout guide

Arranging multiple Axes in a Figure

Arranging multiple Axes in a Figure

Autoscaling Axis

Autoscaling Axis

Axis scales

Axis scales

Axis ticks

Axis ticks

Specifying colors

Specifying colors

Text in Matplotlib

Text in Matplotlib

Annotations

Annotations