import functools

import itertools

import logging

import math

from numbers import Integral, Number, Real

import re

import numpy as np

import matplotlib as mpl

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

import matplotlib.cbook as cbook

import matplotlib.collections as mcoll

import matplotlib.colorizer as mcolorizer

import matplotlib.colors as mcolors

import matplotlib.contour as mcontour

import matplotlib.dates # noqa: F401, Register date unit converter as side effect.

import matplotlib.image as mimage

import matplotlib.inset as minset

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, _docstring, _preprocess_data

from matplotlib.axes._base import (

_AxesBase, _TransformedBoundsLocator, _process_plot_format)

from matplotlib.axes._secondary_axes import SecondaryAxis

from matplotlib.container import BarContainer, ErrorbarContainer, StemContainer

from matplotlib.transforms import _ScaledRotation

_log = logging.getLogger(__name__)

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

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

def _make_axes_method(func):

"""

Patch the qualname for functions that are directly added to Axes.

Some Axes functionality is defined in functions in other submodules.

These are simply added as attributes to Axes. As a result, their

``__qualname__`` is e.g. only "table" and not "Axes.table". This

function fixes that.

Note that the function itself is patched, so that

``matplotlib.table.table.__qualname__` will also show "Axes.table".

However, since these functions are not intended to be standalone,

this is bearable.

"""

func.__qualname__ = f"Axes.{func.__name__}"

return func

@_docstring.interpd

class Axes(_AxesBase):

"""

An Axes object encapsulates all the elements of an individual (sub-)plot in

a figure.

It contains most of the (sub-)plot elements: `~.axis.Axis`,

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

and sets the coordinate system.

Like all visible elements in a figure, Axes is an `.Artist` subclass.

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.

.. note::

As a user, you do not instantiate Axes directly, but use Axes creation

methods instead; e.g. from `.pyplot` or `.Figure`:

`~.pyplot.subplots`, `~.pyplot.subplot_mosaic` or `.Figure.add_axes`.

"""

### 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

.. admonition:: Discouraged

The use of *fontdict* is discouraged. Parameters should be passed as

individual keyword arguments or using dictionary-unpacking

``set_title(..., **fontdict)``.

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 location for the title (1.0 is the top). If

None (the default) and :rc:`axes.titley` is also None, 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 : `~matplotlib.text.Text` properties

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

of valid text properties.

"""

if loc is None:

loc = mpl.rcParams['axes.titlelocation']

if y is None:

y = mpl.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': mpl.rcParams['axes.titlesize'],

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

'verticalalignment': 'baseline',

'horizontalalignment': loc.lower()}

titlecolor = mpl.rcParams['axes.titlecolor']

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

default["color"] = titlecolor

if pad is None:

pad = mpl.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._internal_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.interpd

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

"""

Place a legend on the Axes.

Call signatures::

legend()

legend(handles, labels)

legend(handles=handles)

legend(labels)

The call signatures correspond to the following 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()

.. note::

Specific artists can be excluded from the automatic legend element

selection by using a label starting with an underscore, "_".

A string starting with an underscore is the default label for all

artists, so calling `.Axes.legend` without any arguments and

without setting the labels manually will result in a ``UserWarning``

and an empty legend being drawn.

**2. Explicitly listing the artists and labels 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'])

**3. Explicitly listing the artists in the legend**

This is similar to 2, but the labels are taken from the artists'

label properties. Example::

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

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

ax.legend(handles=[line1, line2])

**4. Labeling existing plot elements**

.. admonition:: Discouraged

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.

To make a legend for all artists on an Axes, call this function with

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

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

ax.plot([5, 6, 7])

ax.legend(['First line', 'Second line'])

Parameters

----------

handles : list of (`.Artist` or tuple 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.

If an entry contains a tuple, then the legend handler for all Artists in the

tuple will be placed alongside a single label.

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_axes)s

See Also

--------

.Figure.legend

Notes

-----

Some artists are not supported by this function. See

:ref:`legend_guide` for details.

Examples

--------

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

"""

handles, labels, kwargs = mlegend._parse_legend_args([self], *args, **kwargs)

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.

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.

projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', \

'polar', 'rectilinear', str}, optional

The projection type of the inset `~.axes.Axes`. *str* is the name

of a custom projection, see `~matplotlib.projections`. The default

None results in a 'rectilinear' projection.

polar : bool, default: False

If True, equivalent to projection='polar'.

axes_class : subclass type of `~.axes.Axes`, optional

The `.axes.Axes` subclass that is instantiated. This parameter

is incompatible with *projection* and *polar*. See

:ref:`axisartist_users-guide-index` for examples.

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 inset Axes class.

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

fig = self.get_figure(root=False)

projection_class, pkw = fig._process_projection_requirements(**kwargs)

inset_ax = projection_class(fig, bounds, zorder=zorder, **pkw)

# 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.interpd

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

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

zorder=None, **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], optional

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

and height. If not set, the bounds will be calculated from the

data limits of *inset_ax*, which must be supplied.

inset_ax : `.Axes`, optional

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 : :mpltype:`color`, default: 'none'

Facecolor of the rectangle.

edgecolor : :mpltype:`color`, default: '0.5'

Color of the rectangle and color of the connecting lines.

alpha : float or None, default: 0.5

Transparency of the rectangle and connector lines. If not

``None``, this overrides any alpha value included in the

*facecolor* and *edgecolor* parameters.

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

-------

inset_indicator : `.inset.InsetIndicator`

An artist which contains

inset_indicator.rectangle : `.Rectangle`

The indicator frame.

inset_indicator.connectors : 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.

.. versionchanged:: 3.10

Previously the rectangle and connectors tuple were returned.

"""

# 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')

indicator_patch = minset.InsetIndicator(

bounds, inset_ax=inset_ax,

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

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

self.add_artist(indicator_patch)

return indicator_patch

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

-------

inset_indicator : `.inset.InsetIndicator`

An artist which contains

inset_indicator.rectangle : `.Rectangle`

The indicator frame.

inset_indicator.connectors : 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.

.. versionchanged:: 3.10

Previously the rectangle and connectors tuple were returned.

"""

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

@_docstring.interpd

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

"""

Add a second x-axis to this `~.axes.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()

To add a secondary axis relative to your data, you can pass a transform

to the new axis.

.. plot::

fig, ax = plt.subplots()

ax.plot(range(0, 5), range(-1, 4))

# Pass 'ax.transData' as a transform to place the axis

# relative to your data at y=0

secax = ax.secondary_xaxis(0, transform=ax.transData)

"""

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

raise ValueError('secondary_xaxis location must be either '

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

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

transform, **kwargs)

self.add_child_axes(secondary_ax)

return secondary_ax

@_docstring.interpd

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

"""

Add a second y-axis to this `~.axes.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')

To add a secondary axis relative to your data, you can pass a transform

to the new axis.

.. plot::

fig, ax = plt.subplots()

ax.plot(range(0, 5), range(-1, 4))

# Pass 'ax.transData' as a transform to place the axis

# relative to your data at x=3

secax = ax.secondary_yaxis(3, transform=ax.transData)

"""

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

raise ValueError('secondary_yaxis location must be either '

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

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

transform, **kwargs)

self.add_child_axes(secondary_ax)

return secondary_ax

@_docstring.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,

with a default ``horizontalalignment`` on the ``left`` and

``verticalalignment`` at the ``baseline``. See

:doc:`/gallery/text_labels_and_annotations/text_alignment`.

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

.. admonition:: Discouraged

The use of *fontdict* is discouraged. Parameters should be passed as

individual keyword arguments or using dictionary-unpacking

``text(..., **fontdict)``.

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)

if t.get_clip_path() is None:

t.set_clip_path(self.patch)

self._add_text(t)

return t

@_docstring.interpd

def annotate(self, text, xy, xytext=None, xycoords='data', textcoords=None,

arrowprops=None, annotation_clip=None, **kwargs):

# Signature must match Annotation. This is verified in

# test_annotate_signature().

a = mtext.Annotation(text, xy, xytext=xytext, xycoords=xycoords,

textcoords=textcoords, arrowprops=arrowprops,

annotation_clip=annotation_clip, **kwargs)

a.set_transform(mtransforms.IdentityTransform())

if kwargs.get('clip_on', False) and a.get_clip_path() is None:

a.set_clip_path(self.patch)

self._add_text(a)

return a

annotate.__doc__ = mtext.Annotation.__init__.__doc__

#### Lines and spans

@_docstring.interpd

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

"""

Add a horizontal line spanning the whole or fraction of the Axes.

Note: If you want to set x-limits in data coordinates, use

`~.Axes.hlines` instead.

Parameters

----------

y : float, default: 0

y position in :ref:`data coordinates <coordinate-systems>`.

xmin : float, default: 0

The start x-position in :ref:`axes coordinates <coordinate-systems>`.

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

The end x-position in :ref:`axes coordinates <coordinate-systems>`.

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`

A `.Line2D` specified via two points ``(xmin, y)``, ``(xmax, y)``.

Its transform is set such that *x* is in

:ref:`axes coordinates <coordinate-systems>` and *y* is in

:ref:`data coordinates <coordinate-systems>`.

This is still a generic line and the horizontal character is only

realized through using identical *y* values for both points. Thus,

if you want to change the *y* value later, you have to provide two

values ``line.set_ydata([3, 3])``.

Other Parameters

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

**kwargs

Valid keyword arguments are `.Line2D` properties, except for

'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)

l.get_path()._interpolation_steps = mpl.axis.GRIDLINE_INTERPOLATION_STEPS

if scaley:

self._request_autoscale_view("y")

return l

@_docstring.interpd

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

"""

Add a vertical line spanning the whole or fraction of the Axes.

Note: If you want to set y-limits in data coordinates, use

`~.Axes.vlines` instead.

Parameters

----------

x : float, default: 0

x position in :ref:`data coordinates <coordinate-systems>`.

ymin : float, default: 0

The start y-position in :ref:`axes coordinates <coordinate-systems>`.

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

top of the plot.

ymax : float, default: 1

The end y-position in :ref:`axes coordinates <coordinate-systems>`.

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

top of the plot.

Returns

-------

`~matplotlib.lines.Line2D`

A `.Line2D` specified via two points ``(x, ymin)``, ``(x, ymax)``.

Its transform is set such that *x* is in

:ref:`data coordinates <coordinate-systems>` and *y* is in

:ref:`axes coordinates <coordinate-systems>`.

This is still a generic line and the vertical character is only

realized through using identical *x* values for both points. Thus,

if you want to change the *x* value later, you have to provide two

values ``line.set_xdata([3, 3])``.

Other Parameters

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

**kwargs

Valid keyword arguments are `.Line2D` properties, except for

'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)

l.get_path()._interpolation_steps = mpl.axis.GRIDLINE_INTERPOLATION_STEPS

if scalex:

self._request_autoscale_view("x")

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.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

-------

`.AxLine`

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"_child{len(self._children)}")

self._children.append(line)

line._remove_method = self._children.remove

self.update_datalim(datalim)

self._request_autoscale_view()

return line

@_docstring.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.