matplotlib.axes.Axes.scatter#

Axes.scatter(x, y, s=None, c=None, *, marker=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, edgecolors=None, colorizer=None, plotnonfinite=False, data=None, **kwargs)[source]#

A scatter plot of y vs. x with varying marker size and/or color.

Parameters:
x, yfloat or array-like, shape (n, )

The data positions.

sfloat or array-like, shape (n, ), optional

The marker size in points**2 (typographic points are 1/72 in.). Default is rcParams['lines.markersize'] ** 2.

The linewidth and edgecolor can visually interact with the marker size, and can lead to artifacts if the marker size is smaller than the linewidth.

If the linewidth is greater than 0 and the edgecolor is anything but 'none', then the effective size of the marker will be increased by half the linewidth because the stroke will be centered on the edge of the shape.

To eliminate the marker edge either set linewidth=0 or edgecolor='none'.

carray-like or list of color or color, optional

The marker colors. Possible values:

  • A scalar or sequence of n numbers to be mapped to colors using cmap and norm.

  • A 2D array in which the rows are RGB or RGBA.

  • A sequence of colors of length n.

  • A single color format string.

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. If you want to specify the same RGB or RGBA value for all points, use a 2D array with a single row. Otherwise, value-matching will have precedence in case of a size matching with x and y.

If you wish to specify a single color for all points prefer the color keyword argument.

Defaults to None. In that case the marker color is determined by the value of color, facecolor or facecolors. In case those are not specified or None, the marker color is determined by the next color of the Axes' current "shape and fill" color cycle. This cycle defaults to rcParams["axes.prop_cycle"] (default: cycler('color', ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'])).

markerMarkerStyle, default: rcParams["scatter.marker"] (default: 'o')

The marker style. marker can be either an instance of the class or the text shorthand for a particular marker. See matplotlib.markers for more information about marker styles.

cmapstr or Colormap, default: rcParams["image.cmap"] (default: 'viridis')

The Colormap instance or registered colormap name used to map scalar data to colors.

This parameter is ignored if c is RGB(A).

normstr or Normalize, optional

The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1.

If given, this can be one of the following:

This parameter is ignored if c is RGB(A).

vmin, vmaxfloat, optional

When using scalar data and no explicit norm, vmin and vmax define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data. It is an error to use vmin/vmax when a norm instance is given (but using a str norm name together with vmin/vmax is acceptable).

This parameter is ignored if c is RGB(A).

alphafloat, default: None

The alpha blending value, between 0 (transparent) and 1 (opaque).

linewidthsfloat or array-like, default: rcParams["lines.linewidth"] (default: 1.5)

The linewidth of the marker edges. Note: The default edgecolors is 'face'. You may want to change this as well.

edgecolors{'face', 'none', None} or color or list of color, default: rcParams["scatter.edgecolors"] (default: 'face')

The edge color of the marker. Possible values:

  • 'face': The edge color will always be the same as the face color.

  • 'none': No patch boundary will be drawn.

  • A color or sequence of colors.

For non-filled markers, edgecolors is ignored. Instead, the color is determined like with 'face', i.e. from c, colors, or facecolors.

colorizerColorizer or None, default: None

The Colorizer object used to map color to data. If None, a Colorizer object is created from a norm and cmap.

This parameter is ignored if c is RGB(A).

plotnonfinitebool, default: False

Whether to plot points with nonfinite c (i.e. inf, -inf or nan). If True the points are drawn with the bad colormap color (see Colormap.set_bad).

Returns:
PathCollection
Other Parameters:
dataindexable object, optional

If given, the following parameters also accept a string s, which is interpreted as data[s] if s is a key in data:

x, y, s, linewidths, edgecolors, c, facecolor, facecolors, color

**kwargsPathCollection 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

array-like or float or None

animated

bool

antialiased or aa or antialiaseds

bool or list of bools

array

array-like or None

capstyle

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

clim

(vmin: float, vmax: float)

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

cmap

Colormap or str or None

color

color or list of RGBA tuples

edgecolor or ec or edgecolors

color or list of color or 'face'

facecolor or facecolors or fc

color or list of color

figure

Figure or SubFigure

gid

str

hatch

{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}

hatch_linewidth

unknown

in_layout

bool

joinstyle

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

label

object

linestyle or dashes or linestyles or ls

str or tuple or list thereof

linewidth or linewidths or lw

float or list of floats

mouseover

bool

norm

Normalize or str or None

offset_transform or transOffset

Transform

offsets

(N, 2) or (2,) array-like

path_effects

list of AbstractPathEffect

paths

unknown

picker

None or bool or float or callable

pickradius

float

rasterized

bool

sizes

numpy.ndarray or None

sketch_params

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

snap

bool or None

transform

Transform

url

str

urls

list of str or None

visible

bool

zorder

float

See also

plot

To plot scatter plots when markers are identical in size and color.

Notes

  • The plot function will be faster for scatterplots where markers don't vary in size or color.

  • Any or all of x, y, s, and c may be masked arrays, in which case all masks will be combined and only unmasked points will be plotted.

  • Fundamentally, scatter works with 1D arrays; x, y, s, and c may be input as N-D arrays, but within scatter they will be flattened. The exception is c, which will be flattened only if its size matches the size of x and y.

Examples using matplotlib.axes.Axes.scatter#

Rain simulation

Rain simulation

Animated scatter saved as GIF

Animated scatter saved as GIF

Align histogram to scatter plot using locatable Axes

Align histogram to scatter plot using locatable Axes

floating_axes features

floating_axes features

Named color sequences

Named color sequences

Pick event demo

Pick event demo

Zoom modifies other Axes

Zoom modifies other Axes

Advanced quiver and quiverkey functions

Advanced quiver and quiverkey functions

Multicolored lines

Multicolored lines

Scatter Demo2

Scatter Demo2

Scatter plot with histograms

Scatter plot with histograms

Scatter plot with a legend

Scatter plot with a legend

Plotting with keywords

Plotting with keywords

Zorder Demo

Zorder Demo

Plot 2D data on 3D plot

Plot 2D data on 3D plot

3D scatterplot

3D scatterplot

Scatter plot on polar axis

Scatter plot on polar axis

Asinh scale

Asinh scale

Scatter plot

Scatter plot

Plot a confidence ellipse of a two-dimensional dataset

Plot a confidence ellipse of a two-dimensional dataset

Violin plot customization

Violin plot customization

Axes box aspect

Axes box aspect

Axis label position

Axis label position

Legend Demo

Legend Demo

Automatically setting tick positions

Automatically setting tick positions

Unit handling

Unit handling

Select indices from a collection using polygon selector

Select indices from a collection using polygon selector

scatter(xs, ys, zs)

scatter(xs, ys, zs)

scatter(x, y)

scatter(x, y)

Animations using Matplotlib

Animations using Matplotlib

Plotting dates and strings

Plotting dates and strings

Choosing Colormaps in Matplotlib

Choosing Colormaps in Matplotlib

Quick start guide

Quick start guide

Annotations

Annotations