matplotlib.pyplot.subplot #

matplotlib.pyplot.subplot(*args,**kwargs)[source]#

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

This is a wrapper ofFigure.add_subplot which provides additionalbehavior when working with the implicit API (see the notes section).

Call signatures:

subplot(nrows,ncols,index,**kwargs)subplot(pos,**kwargs)subplot(**kwargs)subplot(ax)

Parameters:

*argsint, (int, int,index), orSubplotSpec, default: (1, 1, 1)

The position of the subplot described by one of

Three integers (nrows,ncols,index). The subplot will take theindex position on a grid withnrows rows andncols columns.index starts at 1 in the upper left corner and increases to theright.index can also be a two-tuple specifying the (first,last) indices (1-based, and includinglast) of the subplot, e.g.,fig.add_subplot(3,1,(1,2)) makes a subplot that spans theupper 2/3 of the figure.
A 3-digit integer. The digits are interpreted as if given separatelyas three single-digit integers, i.e.fig.add_subplot(235) is thesame asfig.add_subplot(2,3,5). Note that this can only be usedif there are no more than 9 subplots.
ASubplotSpec.

projection{None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, optional

The projection type of the subplot (Axes).str is the nameof a custom projection, seeprojections. The defaultNone results in a 'rectilinear' projection.

polarbool, default: False

If True, equivalent to projection='polar'.

sharex, shareyAxes, optional

Share the x or yaxis with sharex and/or sharey. Theaxis will have the same limits, ticks, and scale as the axis of theshared Axes.

labelstr

A label for the returned Axes.

Returns:

Axes: The Axes of the subplot. The returned Axes can actually be an instanceof a subclass, such asprojections.polar.PolarAxes for polarprojections.

Other Parameters:

**kwargs

This method also takes the keyword arguments for the returned Axesbase class; except for thefigure argument. The keyword argumentsfor the rectilinear base classAxes can be found inthe following table but there might also be other keywordarguments if another projection is used.

Property	Description
`adjustable`	{'box', 'datalim'}
`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`	float or None
`anchor`	(float, float) or {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
`animated`	bool
`aspect`	{'auto', 'equal'} or float
`autoscale_on`	bool
`autoscalex_on`	unknown
`autoscaley_on`	unknown
`axes_locator`	Callable[[Axes, Renderer], Bbox]
`axisbelow`	bool or 'line'
`box_aspect`	float or None
`clip_box`	`BboxBase` or None
`clip_on`	bool
`clip_path`	Patch or (Path, Transform) or None
`facecolor` or`fc`	color
`figure`	`Figure` or`SubFigure`
`forward_navigation_events`	bool or "auto"
`frame_on`	bool
`gid`	str
`in_layout`	bool
`label`	object
`mouseover`	bool
`navigate`	bool
`navigate_mode`	unknown
`path_effects`	list of`AbstractPathEffect`
`picker`	None or bool or float or callable
`position`	[left, bottom, width, height] or`Bbox`
`prop_cycle`	`Cycler`
`rasterization_zorder`	float or None
`rasterized`	bool
`sketch_params`	(scale: float, length: float, randomness: float)
`snap`	bool or None
`subplotspec`	unknown
`title`	str
`transform`	`Transform`
`url`	str
`visible`	bool
`xbound`	(lower: float, upper: float)
`xinverted`	unknown
`xlabel`	str
`xlim`	(left: float, right: float)
`xmargin`	float greater than -0.5
`xscale`	unknown
`xticklabels`	unknown
`xticks`	unknown
`ybound`	(lower: float, upper: float)
`yinverted`	unknown
`ylabel`	str
`ylim`	(bottom: float, top: float)
`ymargin`	float greater than -0.5
`yscale`	unknown
`yticklabels`	unknown
`yticks`	unknown
`zorder`	float

See also

Figure.add_subplot
pyplot.subplots
pyplot.axes
Figure.subplots

Notes

Changed in version 3.8:In versions prior to 3.8, any preexisting Axes that overlap with the new Axesbeyond sharing a boundary was deleted. Deletion does not happen in morerecent versions anymore. UseAxes.remove explicitly if needed.

If you do not want this behavior, use theFigure.add_subplot methodor thepyplot.axes function instead.

If nokwargs are passed and there exists an Axes in the locationspecified byargs then that Axes will be returned rather than a newAxes being created.

Ifkwargs are passed and there exists an Axes in the locationspecified byargs, the projection type is the same, and thekwargs match with the existing Axes, then the existing Axes isreturned. Otherwise a new Axes is created with the specifiedparameters. We save a reference to thekwargs which we usefor this comparison. If any of the values inkwargs aremutable we will not detect the case where they are mutated.In these cases we suggest usingFigure.add_subplot and theexplicit Axes API rather than the implicit pyplot API.

Examples

plt.subplot(221)# equivalent but more generalax1=plt.subplot(2,2,1)# add a subplot with no frameax2=plt.subplot(222,frameon=False)# add a polar subplotplt.subplot(223,projection='polar')# add a red subplot that shares the x-axis with ax1plt.subplot(224,sharex=ax1,facecolor='red')# delete ax2 from the figureplt.delaxes(ax2)# add ax2 to the figure againplt.subplot(ax2)# make the first Axes "current" againplt.subplot(221)