import functools

import itertools

import logging

import math

from numbers import Integral, Number

import numpy as np

from numpy import ma

import matplotlib.category # Register category unit converter as side-effect.

import matplotlib.cbook as cbook

import matplotlib.collections as mcoll

import matplotlib.colors as mcolors

import matplotlib.contour as mcontour

import matplotlib.dates # Register date unit converter as side-effect.

import matplotlib.docstring as docstring

import matplotlib.image as mimage

import matplotlib.legend as mlegend

import matplotlib.lines as mlines

import matplotlib.markers as mmarkers

import matplotlib.mlab as mlab

import matplotlib.patches as mpatches

import matplotlib.path as mpath

import matplotlib.quiver as mquiver

import matplotlib.stackplot as mstack

import matplotlib.streamplot as mstream

import matplotlib.table as mtable

import matplotlib.text as mtext

import matplotlib.ticker as mticker

import matplotlib.transforms as mtransforms

import matplotlib.tri as mtri

import matplotlib.units as munits

from matplotlib import _api, _preprocess_data, rcParams

from matplotlib.axes._base import (

_AxesBase, _TransformedBoundsLocator, _process_plot_format)

from matplotlib.axes._secondary_axes import SecondaryAxis

from matplotlib.container import BarContainer, ErrorbarContainer, StemContainer

_log = logging.getLogger(__name__)

# The axes module contains all the wrappers to plotting functions.

# All the other methods should go in the _AxesBase class.

class Axes(_AxesBase):

"""

The `Axes` contains most of the figure elements: `~.axis.Axis`,

`~.axis.Tick`, `~.lines.Line2D`, `~.text.Text`, `~.patches.Polygon`, etc.,

and sets the coordinate system.

The `Axes` instance supports callbacks through a callbacks attribute which

is a `~.cbook.CallbackRegistry` instance. The events you can connect to

are 'xlim_changed' and 'ylim_changed' and the callback will be called with

func(*ax*) where *ax* is the `Axes` instance.

Attributes

----------

dataLim : `.Bbox`

The bounding box enclosing all data displayed in the Axes.

viewLim : `.Bbox`

The view limits in data coordinates.

"""

### Labelling, legend and texts

def get_title(self, loc="center"):

"""

Get an Axes title.

Get one of the three available Axes titles. The available titles

are positioned above the Axes in the center, flush with the left

edge, and flush with the right edge.

Parameters

----------

loc : {'center', 'left', 'right'}, str, default: 'center'

Which title to return.

Returns

-------

str

The title text string.

"""

titles = {'left': self._left_title,

'center': self.title,

'right': self._right_title}

title = _api.check_getitem(titles, loc=loc.lower())

return title.get_text()

def set_title(self, label, fontdict=None, loc=None, pad=None, *, y=None,

**kwargs):

"""

Set a title for the Axes.

Set one of the three available Axes titles. The available titles

are positioned above the Axes in the center, flush with the left

edge, and flush with the right edge.

Parameters

----------

label : str

Text to use for the title

fontdict : dict

A dictionary controlling the appearance of the title text,

the default *fontdict* is::

{'fontsize': rcParams['axes.titlesize'],

'fontweight': rcParams['axes.titleweight'],

'color': rcParams['axes.titlecolor'],

'verticalalignment': 'baseline',

'horizontalalignment': loc}

loc : {'center', 'left', 'right'}, default: :rc:`axes.titlelocation`

Which title to set.

y : float, default: :rc:`axes.titley`

Vertical Axes loation for the title (1.0 is the top). If

None (the default), y is determined automatically to avoid

decorators on the Axes.

pad : float, default: :rc:`axes.titlepad`

The offset of the title from the top of the Axes, in points.

Returns

-------

`.Text`

The matplotlib text instance representing the title

Other Parameters

----------------

**kwargs : `.Text` properties

Other keyword arguments are text properties, see `.Text` for a list

of valid text properties.

"""

if loc is None:

loc = rcParams['axes.titlelocation']

if y is None:

y = rcParams['axes.titley']

if y is None:

y = 1.0

else:

self._autotitlepos = False

kwargs['y'] = y

titles = {'left': self._left_title,

'center': self.title,

'right': self._right_title}

title = _api.check_getitem(titles, loc=loc.lower())

default = {

'fontsize': rcParams['axes.titlesize'],

'fontweight': rcParams['axes.titleweight'],

'verticalalignment': 'baseline',

'horizontalalignment': loc.lower()}

titlecolor = rcParams['axes.titlecolor']

if not cbook._str_lower_equal(titlecolor, 'auto'):

default["color"] = titlecolor

if pad is None:

pad = rcParams['axes.titlepad']

self._set_title_offset_trans(float(pad))

title.set_text(label)

title.update(default)

if fontdict is not None:

title.update(fontdict)

title.update(kwargs)

return title

def get_legend_handles_labels(self, legend_handler_map=None):

"""

Return handles and labels for legend

``ax.legend()`` is equivalent to ::

h, l = ax.get_legend_handles_labels()

ax.legend(h, l)

"""

# pass through to legend.

handles, labels = mlegend._get_legend_handles_labels(

[self], legend_handler_map)

return handles, labels

@docstring.dedent_interpd

def legend(self, *args, **kwargs):

"""

Place a legend on the Axes.

Call signatures::

legend()

legend(labels)

legend(handles, labels)

The call signatures correspond to these three different ways to use

this method:

**1. Automatic detection of elements to be shown in the legend**

The elements to be added to the legend are automatically determined,

when you do not pass in any extra arguments.

In this case, the labels are taken from the artist. You can specify

them either at artist creation or by calling the

:meth:`~.Artist.set_label` method on the artist::

ax.plot([1, 2, 3], label='Inline label')

ax.legend()

or::

line, = ax.plot([1, 2, 3])

line.set_label('Label via method')

ax.legend()

Specific lines can be excluded from the automatic legend element

selection by defining a label starting with an underscore.

This is default for all artists, so calling `.Axes.legend` without

any arguments and without setting the labels manually will result in

no legend being drawn.

**2. Labeling existing plot elements**

To make a legend for lines which already exist on the Axes

(via plot for instance), simply call this function with an iterable

of strings, one for each legend item. For example::

ax.plot([1, 2, 3])

ax.legend(['A simple line'])

Note: This call signature is discouraged, because the relation between

plot elements and labels is only implicit by their order and can

easily be mixed up.

**3. Explicitly defining the elements in the legend**

For full control of which artists have a legend entry, it is possible

to pass an iterable of legend artists followed by an iterable of

legend labels respectively::

ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])

Parameters

----------

handles : sequence of `.Artist`, optional

A list of Artists (lines, patches) to be added to the legend.

Use this together with *labels*, if you need full control on what

is shown in the legend and the automatic mechanism described above

is not sufficient.

The length of handles and labels should be the same in this

case. If they are not, they are truncated to the smaller length.

labels : list of str, optional

A list of labels to show next to the artists.

Use this together with *handles*, if you need full control on what

is shown in the legend and the automatic mechanism described above

is not sufficient.

Returns

-------

`~matplotlib.legend.Legend`

Other Parameters

----------------

%(_legend_kw_doc)s

See Also

--------

.Figure.legend

Notes

-----

Some artists are not supported by this function. See

:doc:`/tutorials/intermediate/legend_guide` for details.

Examples

--------

.. plot:: gallery/text_labels_and_annotations/legend.py

"""

handles, labels, extra_args, kwargs = mlegend._parse_legend_args(

[self],

*args,

**kwargs)

if len(extra_args):

raise TypeError('legend only accepts two non-keyword arguments')

self.legend_ = mlegend.Legend(self, handles, labels, **kwargs)

self.legend_._remove_method = self._remove_legend

return self.legend_

def _remove_legend(self, legend):

self.legend_ = None

def inset_axes(self, bounds, *, transform=None, zorder=5, **kwargs):

"""

Add a child inset Axes to this existing Axes.

Warnings

--------

This method is experimental as of 3.0, and the API may change.

Parameters

----------

bounds : [x0, y0, width, height]

Lower-left corner of inset Axes, and its width and height.

transform : `.Transform`

Defaults to `ax.transAxes`, i.e. the units of *rect* are in

Axes-relative coordinates.

zorder : number

Defaults to 5 (same as `.Axes.legend`). Adjust higher or lower

to change whether it is above or below data plotted on the

parent Axes.

**kwargs

Other keyword arguments are passed on to the child `.Axes`.

Returns

-------

ax

The created `~.axes.Axes` instance.

Examples

--------

This example makes two inset Axes, the first is in Axes-relative

coordinates, and the second in data-coordinates::

fig, ax = plt.subplots()

ax.plot(range(10))

axin1 = ax.inset_axes([0.8, 0.1, 0.15, 0.15])

axin2 = ax.inset_axes(

[5, 7, 2.3, 2.3], transform=ax.transData)

"""

if transform is None:

transform = self.transAxes

kwargs.setdefault('label', 'inset_axes')

# This puts the rectangle into figure-relative coordinates.

inset_locator = _TransformedBoundsLocator(bounds, transform)

bounds = inset_locator(self, None).bounds

inset_ax = Axes(self.figure, bounds, zorder=zorder, **kwargs)

# this locator lets the axes move if in data coordinates.

# it gets called in `ax.apply_aspect() (of all places)

inset_ax.set_axes_locator(inset_locator)

self.add_child_axes(inset_ax)

return inset_ax

@docstring.dedent_interpd

def indicate_inset(self, bounds, inset_ax=None, *, transform=None,

facecolor='none', edgecolor='0.5', alpha=0.5,

zorder=4.99, **kwargs):

"""

Add an inset indicator to the Axes. This is a rectangle on the plot

at the position indicated by *bounds* that optionally has lines that

connect the rectangle to an inset Axes (`.Axes.inset_axes`).

Warnings

--------

This method is experimental as of 3.0, and the API may change.

Parameters

----------

bounds : [x0, y0, width, height]

Lower-left corner of rectangle to be marked, and its width

and height.

inset_ax : `.Axes`

An optional inset Axes to draw connecting lines to. Two lines are

drawn connecting the indicator box to the inset Axes on corners

chosen so as to not overlap with the indicator box.

transform : `.Transform`

Transform for the rectangle coordinates. Defaults to

`ax.transAxes`, i.e. the units of *rect* are in Axes-relative

coordinates.

facecolor : color, default: 'none'

Facecolor of the rectangle.

edgecolor : color, default: '0.5'

Color of the rectangle and color of the connecting lines.

alpha : float, default: 0.5

Transparency of the rectangle and connector lines.

zorder : float, default: 4.99

Drawing order of the rectangle and connector lines. The default,

4.99, is just below the default level of inset Axes.

**kwargs

Other keyword arguments are passed on to the `.Rectangle` patch:

%(Rectangle_kwdoc)s

Returns

-------

rectangle_patch : `.patches.Rectangle`

The indicator frame.

connector_lines : 4-tuple of `.patches.ConnectionPatch`

The four connector lines connecting to (lower_left, upper_left,

lower_right upper_right) corners of *inset_ax*. Two lines are

set with visibility to *False*, but the user can set the

visibility to True if the automatic choice is not deemed correct.

"""

# to make the axes connectors work, we need to apply the aspect to

# the parent axes.

self.apply_aspect()

if transform is None:

transform = self.transData

kwargs.setdefault('label', '_indicate_inset')

x, y, width, height = bounds

rectangle_patch = mpatches.Rectangle(

(x, y), width, height,

facecolor=facecolor, edgecolor=edgecolor, alpha=alpha,

zorder=zorder, transform=transform, **kwargs)

self.add_patch(rectangle_patch)

connects = []

if inset_ax is not None:

# connect the inset_axes to the rectangle

for xy_inset_ax in [(0, 0), (0, 1), (1, 0), (1, 1)]:

# inset_ax positions are in axes coordinates

# The 0, 1 values define the four edges if the inset_ax

# lower_left, upper_left, lower_right upper_right.

ex, ey = xy_inset_ax

if self.xaxis.get_inverted():

ex = 1 - ex

if self.yaxis.get_inverted():

ey = 1 - ey

xy_data = x + ex * width, y + ey * height

p = mpatches.ConnectionPatch(

xyA=xy_inset_ax, coordsA=inset_ax.transAxes,

xyB=xy_data, coordsB=self.transData,

arrowstyle="-", zorder=zorder,

edgecolor=edgecolor, alpha=alpha)

connects.append(p)

self.add_patch(p)

# decide which two of the lines to keep visible....

pos = inset_ax.get_position()

bboxins = pos.transformed(self.figure.transSubfigure)

rectbbox = mtransforms.Bbox.from_bounds(

*bounds

).transformed(transform)

x0 = rectbbox.x0 < bboxins.x0

x1 = rectbbox.x1 < bboxins.x1

y0 = rectbbox.y0 < bboxins.y0

y1 = rectbbox.y1 < bboxins.y1

connects[0].set_visible(x0 ^ y0)

connects[1].set_visible(x0 == y1)

connects[2].set_visible(x1 == y0)

connects[3].set_visible(x1 ^ y1)

return rectangle_patch, tuple(connects) if connects else None

def indicate_inset_zoom(self, inset_ax, **kwargs):

"""

Add an inset indicator rectangle to the Axes based on the axis

limits for an *inset_ax* and draw connectors between *inset_ax*

and the rectangle.

Warnings

--------

This method is experimental as of 3.0, and the API may change.

Parameters

----------

inset_ax : `.Axes`

Inset Axes to draw connecting lines to. Two lines are

drawn connecting the indicator box to the inset Axes on corners

chosen so as to not overlap with the indicator box.

**kwargs

Other keyword arguments are passed on to `.Axes.indicate_inset`

Returns

-------

rectangle_patch : `.patches.Rectangle`

Rectangle artist.

connector_lines : 4-tuple of `.patches.ConnectionPatch`

Each of four connector lines coming from the rectangle drawn on

this axis, in the order lower left, upper left, lower right,

upper right.

Two are set with visibility to *False*, but the user can

set the visibility to *True* if the automatic choice is not deemed

correct.

"""

xlim = inset_ax.get_xlim()

ylim = inset_ax.get_ylim()

rect = (xlim[0], ylim[0], xlim[1] - xlim[0], ylim[1] - ylim[0])

return self.indicate_inset(rect, inset_ax, **kwargs)

@docstring.dedent_interpd

def secondary_xaxis(self, location, *, functions=None, **kwargs):

"""

Add a second x-axis to this Axes.

For example if we want to have a second scale for the data plotted on

the xaxis.

%(_secax_docstring)s

Examples

--------

The main axis shows frequency, and the secondary axis shows period.

.. plot::

fig, ax = plt.subplots()

ax.loglog(range(1, 360, 5), range(1, 360, 5))

ax.set_xlabel('frequency [Hz]')

def invert(x):

# 1/x with special treatment of x == 0

x = np.array(x).astype(float)

near_zero = np.isclose(x, 0)

x[near_zero] = np.inf

x[~near_zero] = 1 / x[~near_zero]

return x

# the inverse of 1/x is itself

secax = ax.secondary_xaxis('top', functions=(invert, invert))

secax.set_xlabel('Period [s]')

plt.show()

"""

if location in ['top', 'bottom'] or isinstance(location, Number):

secondary_ax = SecondaryAxis(self, 'x', location, functions,

**kwargs)

self.add_child_axes(secondary_ax)

return secondary_ax

else:

raise ValueError('secondary_xaxis location must be either '

'a float or "top"/"bottom"')

@docstring.dedent_interpd

def secondary_yaxis(self, location, *, functions=None, **kwargs):

"""

Add a second y-axis to this Axes.

For example if we want to have a second scale for the data plotted on

the yaxis.

%(_secax_docstring)s

Examples

--------

Add a secondary Axes that converts from radians to degrees

.. plot::

fig, ax = plt.subplots()

ax.plot(range(1, 360, 5), range(1, 360, 5))

ax.set_ylabel('degrees')

secax = ax.secondary_yaxis('right', functions=(np.deg2rad,

np.rad2deg))

secax.set_ylabel('radians')

"""

if location in ['left', 'right'] or isinstance(location, Number):

secondary_ax = SecondaryAxis(self, 'y', location,

functions, **kwargs)

self.add_child_axes(secondary_ax)

return secondary_ax

else:

raise ValueError('secondary_yaxis location must be either '

'a float or "left"/"right"')

@docstring.dedent_interpd

def text(self, x, y, s, fontdict=None, **kwargs):

"""

Add text to the Axes.

Add the text *s* to the Axes at location *x*, *y* in data coordinates.

Parameters

----------

x, y : float

The position to place the text. By default, this is in data

coordinates. The coordinate system can be changed using the

*transform* parameter.

s : str

The text.

fontdict : dict, default: None

A dictionary to override the default text properties. If fontdict

is None, the defaults are determined by `.rcParams`.

Returns

-------

`.Text`

The created `.Text` instance.

Other Parameters

----------------

**kwargs : `~matplotlib.text.Text` properties.

Other miscellaneous text parameters.

%(Text_kwdoc)s

Examples

--------

Individual keyword arguments can be used to override any given

parameter::

>>> text(x, y, s, fontsize=12)

The default transform specifies that text is in data coords,

alternatively, you can specify text in axis coords ((0, 0) is

lower-left and (1, 1) is upper-right). The example below places

text in the center of the Axes::

>>> text(0.5, 0.5, 'matplotlib', horizontalalignment='center',

... verticalalignment='center', transform=ax.transAxes)

You can put a rectangular box around the text instance (e.g., to

set a background color) by using the keyword *bbox*. *bbox* is

a dictionary of `~matplotlib.patches.Rectangle`

properties. For example::

>>> text(x, y, s, bbox=dict(facecolor='red', alpha=0.5))

"""

effective_kwargs = {

'verticalalignment': 'baseline',

'horizontalalignment': 'left',

'transform': self.transData,

'clip_on': False,

**(fontdict if fontdict is not None else {}),

**kwargs,

}

t = mtext.Text(x, y, text=s, **effective_kwargs)

t.set_clip_path(self.patch)

self._add_text(t)

return t

@_api.rename_parameter("3.3", "s", "text")

@docstring.dedent_interpd

def annotate(self, text, xy, *args, **kwargs):

a = mtext.Annotation(text, xy, *args, **kwargs)

a.set_transform(mtransforms.IdentityTransform())

if 'clip_on' in kwargs:

a.set_clip_path(self.patch)

self._add_text(a)

return a

annotate.__doc__ = mtext.Annotation.__init__.__doc__

#### Lines and spans

@docstring.dedent_interpd

def axhline(self, y=0, xmin=0, xmax=1, **kwargs):

"""

Add a horizontal line across the axis.

Parameters

----------

y : float, default: 0

y position in data coordinates of the horizontal line.

xmin : float, default: 0

Should be between 0 and 1, 0 being the far left of the plot, 1 the

far right of the plot.

xmax : float, default: 1

Should be between 0 and 1, 0 being the far left of the plot, 1 the

far right of the plot.

Returns

-------

`~matplotlib.lines.Line2D`

Other Parameters

----------------

**kwargs

Valid keyword arguments are `.Line2D` properties, with the

exception of 'transform':

%(Line2D_kwdoc)s

See Also

--------

hlines : Add horizontal lines in data coordinates.

axhspan : Add a horizontal span (rectangle) across the axis.

axline : Add a line with an arbitrary slope.

Examples

--------

* draw a thick red hline at 'y' = 0 that spans the xrange::

>>> axhline(linewidth=4, color='r')

* draw a default hline at 'y' = 1 that spans the xrange::

>>> axhline(y=1)

* draw a default hline at 'y' = .5 that spans the middle half of

the xrange::

>>> axhline(y=.5, xmin=0.25, xmax=0.75)

"""

self._check_no_units([xmin, xmax], ['xmin', 'xmax'])

if "transform" in kwargs:

raise ValueError("'transform' is not allowed as a keyword "

"argument; axhline generates its own transform.")

ymin, ymax = self.get_ybound()

# Strip away the units for comparison with non-unitized bounds.

yy, = self._process_unit_info([("y", y)], kwargs)

scaley = (yy < ymin) or (yy > ymax)

trans = self.get_yaxis_transform(which='grid')

l = mlines.Line2D([xmin, xmax], [y, y], transform=trans, **kwargs)

self.add_line(l)

self._request_autoscale_view(scalex=False, scaley=scaley)

return l

@docstring.dedent_interpd

def axvline(self, x=0, ymin=0, ymax=1, **kwargs):

"""

Add a vertical line across the Axes.

Parameters

----------

x : float, default: 0

x position in data coordinates of the vertical line.

ymin : float, default: 0

Should be between 0 and 1, 0 being the bottom of the plot, 1 the

top of the plot.

ymax : float, default: 1

Should be between 0 and 1, 0 being the bottom of the plot, 1 the

top of the plot.

Returns

-------

`~matplotlib.lines.Line2D`

Other Parameters

----------------

**kwargs

Valid keyword arguments are `.Line2D` properties, with the

exception of 'transform':

%(Line2D_kwdoc)s

See Also

--------

vlines : Add vertical lines in data coordinates.

axvspan : Add a vertical span (rectangle) across the axis.

axline : Add a line with an arbitrary slope.

Examples

--------

* draw a thick red vline at *x* = 0 that spans the yrange::

>>> axvline(linewidth=4, color='r')

* draw a default vline at *x* = 1 that spans the yrange::

>>> axvline(x=1)

* draw a default vline at *x* = .5 that spans the middle half of

the yrange::

>>> axvline(x=.5, ymin=0.25, ymax=0.75)

"""

self._check_no_units([ymin, ymax], ['ymin', 'ymax'])

if "transform" in kwargs:

raise ValueError("'transform' is not allowed as a keyword "

"argument; axvline generates its own transform.")

xmin, xmax = self.get_xbound()

# Strip away the units for comparison with non-unitized bounds.

xx, = self._process_unit_info([("x", x)], kwargs)

scalex = (xx < xmin) or (xx > xmax)

trans = self.get_xaxis_transform(which='grid')

l = mlines.Line2D([x, x], [ymin, ymax], transform=trans, **kwargs)

self.add_line(l)

self._request_autoscale_view(scalex=scalex, scaley=False)

return l

@staticmethod

def _check_no_units(vals, names):

# Helper method to check that vals are not unitized

for val, name in zip(vals, names):

if not munits._is_natively_supported(val):

raise ValueError(f"{name} must be a single scalar value, "

f"but got {val}")

@docstring.dedent_interpd

def axline(self, xy1, xy2=None, *, slope=None, **kwargs):

"""

Add an infinitely long straight line.

The line can be defined either by two points *xy1* and *xy2*, or

by one point *xy1* and a *slope*.

This draws a straight line "on the screen", regardless of the x and y

scales, and is thus also suitable for drawing exponential decays in

semilog plots, power laws in loglog plots, etc. However, *slope*

should only be used with linear scales; It has no clear meaning for

all other scales, and thus the behavior is undefined. Please specify

the line using the points *xy1*, *xy2* for non-linear scales.

The *transform* keyword argument only applies to the points *xy1*,

*xy2*. The *slope* (if given) is always in data coordinates. This can

be used e.g. with ``ax.transAxes`` for drawing grid lines with a fixed

slope.

Parameters

----------

xy1, xy2 : (float, float)

Points for the line to pass through.

Either *xy2* or *slope* has to be given.

slope : float, optional

The slope of the line. Either *xy2* or *slope* has to be given.

Returns

-------

`.Line2D`

Other Parameters

----------------

**kwargs

Valid kwargs are `.Line2D` properties

%(Line2D_kwdoc)s

See Also

--------

axhline : for horizontal lines

axvline : for vertical lines

Examples

--------

Draw a thick red line passing through (0, 0) and (1, 1)::

>>> axline((0, 0), (1, 1), linewidth=4, color='r')

"""

if slope is not None and (self.get_xscale() != 'linear' or

self.get_yscale() != 'linear'):

raise TypeError("'slope' cannot be used with non-linear scales")

datalim = [xy1] if xy2 is None else [xy1, xy2]

if "transform" in kwargs:

# if a transform is passed (i.e. line points not in data space),

# data limits should not be adjusted.

datalim = []

line = mlines._AxLine(xy1, xy2, slope, **kwargs)

# Like add_line, but correctly handling data limits.

self._set_artist_props(line)

if line.get_clip_path() is None:

line.set_clip_path(self.patch)

if not line.get_label():

line.set_label(f"_line{len(self.lines)}")

self.lines.append(line)

line._remove_method = self.lines.remove

self.update_datalim(datalim)

self._request_autoscale_view()

return line

@docstring.dedent_interpd

def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):

"""

Add a horizontal span (rectangle) across the Axes.

The rectangle spans from *ymin* to *ymax* vertically, and, by default,

the whole x-axis horizontally. The x-span can be set using *xmin*

(default: 0) and *xmax* (default: 1) which are in axis units; e.g.

``xmin = 0.5`` always refers to the middle of the x-axis regardless of

the limits set by `~.Axes.set_xlim`.

Parameters

----------

ymin : float

Lower y-coordinate of the span, in data units.

ymax : float

Upper y-coordinate of the span, in data units.

xmin : float, default: 0

Lower x-coordinate of the span, in x-axis (0-1) units.

xmax : float, default: 1

Upper x-coordinate of the span, in x-axis (0-1) units.

Returns

-------

`~matplotlib.patches.Polygon`

Horizontal span (rectangle) from (xmin, ymin) to (xmax, ymax).

Other Parameters

----------------

**kwargs : `~matplotlib.patches.Polygon` properties

%(Polygon_kwdoc)s

See Also

--------

axvspan : Add a vertical span across the Axes.

"""

# Strip units away.

self._check_no_units([xmin, xmax], ['xmin', 'xmax'])

(ymin, ymax), = self._process_unit_info([("y", [ymin, ymax])], kwargs)

verts = (xmin, ymin), (xmin, ymax), (xmax, ymax), (xmax, ymin)

p = mpatches.Polygon(verts, **kwargs)

p.set_transform(self.get_yaxis_transform(which="grid"))

self.add_patch(p)

self._request_autoscale_view(scalex=False)

return p

@docstring.dedent_interpd

def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):

"""

Add a vertical span (rectangle) across the Axes.

The rectangle spans from *xmin* to *xmax* horizontally, and, by

default, the whole y-axis vertically. The y-span can be set using

*ymin* (default: 0) and *ymax* (default: 1) which are in axis units;

e.g. ``ymin = 0.5`` always refers to the middle of the y-axis

regardless of the limits set by `~.Axes.set_ylim`.

Parameters

----------

xmin : float

Lower x-coordinate of the span, in data units.

xmax : float

Upper x-coordinate of the span, in data units.

ymin : float, default: 0

Lower y-coordinate of the span, in y-axis units (0-1).

ymax : float, default: 1

Upper y-coordinate of the span, in y-axis units (0-1).

Returns

-------

`~matplotlib.patches.Polygon`

Vertical span (rectangle) from (xmin, ymin) to (xmax, ymax).

Other Parameters

----------------

**kwargs : `~matplotlib.patches.Polygon` properties

%(Polygon_kwdoc)s

See Also

--------

axhspan : Add a horizontal span across the Axes.

Examples

--------

Draw a vertical, green, translucent rectangle from x = 1.25 to

x = 1.55 that spans the yrange of the Axes.

>>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)

"""

# Strip units away.

self._check_no_units([ymin, ymax], ['ymin', 'ymax'])

(xmin, xmax), = self._process_unit_info([("x", [xmin, xmax])], kwargs)

verts = [(xmin, ymin), (xmin, ymax), (xmax, ymax), (xmax, ymin)]

p = mpatches.Polygon(verts, **kwargs)

p.set_transform(self.get_xaxis_transform(which="grid"))

self.add_patch(p)

self._request_autoscale_view(scaley=False)

return p

@_preprocess_data(replace_names=["y", "xmin", "xmax", "colors"],

label_namer="y")

def hlines(self, y, xmin, xmax, colors=None, linestyles='solid',

label='', **kwargs):

"""

Plot horizontal lines at each *y* from *xmin* to *xmax*.

Parameters

----------

y : float or array-like

y-indexes where to plot the lines.

xmin, xmax : float or array-like

Respective beginning and end of each line. If scalars are

provided, all lines will have same length.

colors : list of colors, default: :rc:`lines.color`

linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional