#!/usr/bin/env python3

"""

The second-level axes subclass used for all proplot figures.

Implements plotting method overrides.

"""

import contextlib

import inspect

import itertools

import re

import sys

from numbers import Integral

import matplotlib.artist as martist

import matplotlib.axes as maxes

import matplotlib.cbook as cbook

import matplotlib.cm as mcm

import matplotlib.collections as mcollections

import matplotlib.colors as mcolors

import matplotlib.contour as mcontour

import matplotlib.image as mimage

import matplotlib.lines as mlines

import matplotlib.patches as mpatches

import matplotlib.ticker as mticker

import numpy as np

import numpy.ma as ma

from .. import colors as pcolors

from .. import constructor, utils

from ..config import rc

from ..internals import ic # noqa: F401

from ..internals import (

_get_aliases,

_not_none,

_pop_kwargs,

_pop_params,

_pop_props,

context,

docstring,

guides,

inputs,

warnings,

)

from . import base

try:

from cartopy.crs import PlateCarree

except ModuleNotFoundError:

PlateCarree = object

__all__ = ['PlotAxes']

# Constants

# NOTE: Increased from native linewidth of 0.25 matplotlib uses for grid box edges.

# This is half of rc['patch.linewidth'] of 0.6. Half seems like a nice default.

EDGEWIDTH = 0.3

# Data argument docstrings

_args_1d_docstring = """

*args : {y} or {x}, {y}

The data passed as positional or keyword arguments. Interpreted as follows:

* If only `{y}` coordinates are passed, try to infer the `{x}` coordinates

from the `~pandas.Series` or `~pandas.DataFrame` indices or the

`~xarray.DataArray` coordinates. Otherwise, the `{x}` coordinates

are ``np.arange(0, {y}.shape[0])``.

* If the `{y}` coordinates are a 2D array, plot each column of data in succession

(except where each column of data represents a statistical distribution, as with

``boxplot``, ``violinplot``, or when using ``means=True`` or ``medians=True``).

* If any arguments are `pint.Quantity`, auto-add the pint unit registry

to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`.

A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.

"""

_args_1d_multi_docstring = """

*args : {y}2 or {x}, {y}2, or {x}, {y}1, {y}2

The data passed as positional or keyword arguments. Interpreted as follows:

* If only `{y}` coordinates are passed, try to infer the `{x}` coordinates from

the `~pandas.Series` or `~pandas.DataFrame` indices or the `~xarray.DataArray`

coordinates. Otherwise, the `{x}` coordinates are ``np.arange(0, {y}2.shape[0])``.

* If only `{x}` and `{y}2` coordinates are passed, set the `{y}1` coordinates

to zero. This draws elements originating from the zero line.

* If both `{y}1` and `{y}2` are provided, draw elements between these points. If

either are 2D, draw elements by iterating over each column.

* If any arguments are `pint.Quantity`, auto-add the pint unit registry

to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`.

A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.

"""

_args_2d_docstring = """

*args : {z} or x, y, {z}

The data passed as positional or keyword arguments. Interpreted as follows:

* If only {zvar} coordinates are passed, try to infer the `x` and `y` coordinates

from the `~pandas.DataFrame` indices and columns or the `~xarray.DataArray`

coordinates. Otherwise, the `y` coordinates are ``np.arange(0, y.shape[0])``

and the `x` coordinates are ``np.arange(0, y.shape[1])``.

* For ``pcolor`` and ``pcolormesh``, calculate coordinate *edges* using

`~proplot.utils.edges` or `~proplot.utils.edges2d` if *centers* were provided.

For all other methods, calculate coordinate *centers* if *edges* were provided.

* If the `x` or `y` coordinates are `pint.Quantity`, auto-add the pint unit registry

to matplotlib's unit registry using `~pint.UnitRegistry.setup_matplotlib`. If the

{zvar} coordinates are `pint.Quantity`, pass the magnitude to the plotting

command. A `pint.Quantity` embedded in an `xarray.DataArray` is also supported.

"""

docstring._snippet_manager['plot.args_1d_y'] = _args_1d_docstring.format(x='x', y='y')

docstring._snippet_manager['plot.args_1d_x'] = _args_1d_docstring.format(x='y', y='x')

docstring._snippet_manager['plot.args_1d_multiy'] = _args_1d_multi_docstring.format(x='x', y='y') # noqa: E501

docstring._snippet_manager['plot.args_1d_multix'] = _args_1d_multi_docstring.format(x='y', y='x') # noqa: E501

docstring._snippet_manager['plot.args_2d'] = _args_2d_docstring.format(z='z', zvar='`z`') # noqa: E501

docstring._snippet_manager['plot.args_2d_flow'] = _args_2d_docstring.format(z='u, v', zvar='`u` and `v`') # noqa: E501

# Shared docstrings

_args_1d_shared_docstring = """

data : dict-like, optional

A dict-like dataset container (e.g., `~pandas.DataFrame` or

`~xarray.Dataset`). If passed, each data argument can optionally

be a string `key` and the arrays used for plotting are retrieved

with ``data[key]``. This is a `native matplotlib feature

<https://matplotlib.org/stable/gallery/misc/keyword_plotting.html>`__.

autoformat : bool, default: :rc:`autoformat`

Whether the `x` axis labels, `y` axis labels, axis formatters, axes titles,

legend titles, and colorbar labels are automatically configured when a

`~pandas.Series`, `~pandas.DataFrame`, `~xarray.DataArray`, or `~pint.Quantity`

is passed to the plotting command. Formatting of `pint.Quantity`

unit strings is controlled by :rc:`unitformat`.

"""

_args_2d_shared_docstring = """

%(plot.args_1d_shared)s

transpose : bool, default: False

Whether to transpose the input data. This should be used when

passing datasets with column-major dimension order ``(x, y)``.

Otherwise row-major dimension order ``(y, x)`` is expected.

order : {'C', 'F'}, default: 'C'

Alternative to `transpose`. ``'C'`` corresponds to the default C-cyle

row-major ordering (equivalent to ``transpose=False``). ``'F'`` corresponds

to Fortran-style column-major ordering (equivalent to ``transpose=True``).

globe : bool, default: False

For `proplot.axes.GeoAxes` only. Whether to enforce global

coverage. When set to ``True`` this does the following:

#. Interpolates input data to the North and South poles by setting the data

values at the poles to the mean from latitudes nearest each pole.

#. Makes meridional coverage "circular", i.e. the last longitude coordinate

equals the first longitude coordinate plus 360\N{DEGREE SIGN}.

#. When basemap is the backend, cycles 1D longitude vectors to fit within

the map edges. For example, if the central longitude is 90\N{DEGREE SIGN},

the data is shifted so that it spans -90\N{DEGREE SIGN} to 270\N{DEGREE SIGN}.

"""

docstring._snippet_manager['plot.args_1d_shared'] = _args_1d_shared_docstring

docstring._snippet_manager['plot.args_2d_shared'] = _args_2d_shared_docstring

# Auto colorbar and legend docstring

_guide_docstring = """

colorbar : bool, int, or str, optional

If not ``None``, this is a location specifying where to draw an

*inset* or *outer* colorbar from the resulting object(s). If ``True``,

the default :rc:`colorbar.loc` is used. If the same location is

used in successive plotting calls, object(s) will be added to the

existing colorbar in that location (valid for colorbars built from lists

of artists). Valid locations are shown in in `~proplot.axes.Axes.colorbar`.

colorbar_kw : dict-like, optional

Extra keyword args for the call to `~proplot.axes.Axes.colorbar`.

legend : bool, int, or str, optional

Location specifying where to draw an *inset* or *outer* legend from the

resulting object(s). If ``True``, the default :rc:`legend.loc` is used.

If the same location is used in successive plotting calls, object(s)

will be added to existing legend in that location. Valid locations

are shown in `~proplot.axes.Axes.legend`.

legend_kw : dict-like, optional

Extra keyword args for the call to `~proplot.axes.Axes.legend`.

"""

docstring._snippet_manager['plot.guide'] = _guide_docstring

# Misc shared 1D plotting docstrings

_inbounds_docstring = """

inbounds : bool, default: :rc:`axes.inbounds`

Whether to restrict the default `y` (`x`) axis limits to account for only

in-bounds data when the `x` (`y`) axis limits have been locked.

See also :rcraw:`axes.inbounds` and :rcraw:`cmap.inbounds`.

"""

_error_means_docstring = """

mean, means : bool, default: False

Whether to plot the means of each column for 2D `{y}` coordinates. Means

are calculated with `numpy.nanmean`. If no other arguments are specified,

this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots).

median, medians : bool, default: False

Whether to plot the medians of each column for 2D `{y}` coordinates. Medians

are calculated with `numpy.nanmedian`. If no other arguments arguments are

specified, this also sets ``barstd=True`` (and ``boxstd=True`` for violin plots).

"""

_error_bars_docstring = """

bars : bool, default: None

Shorthand for `barstd`, `barstds`.

barstd, barstds : bool, float, or 2-tuple of float, optional

Valid only if `mean` or `median` is ``True``. Standard deviation multiples for

*thin error bars* with optional whiskers (i.e., caps). If scalar, then +/- that

multiple is used. If ``True``, the default standard deviation range of +/-3 is used.

barpctile, barpctiles : bool, float, or 2-tuple of float, optional

Valid only if `mean` or `median` is ``True``. As with `barstd`, but instead

using percentiles for the error bars. If scalar, that percentile range is

used (e.g., ``90`` shows the 5th to 95th percentiles). If ``True``, the default

percentile range of 0 to 100 is used.

bardata : array-like, optional

Valid only if `mean` and `median` are ``False``. If shape is 2 x N, these

are the lower and upper bounds for the thin error bars. If shape is N, these

are the absolute, symmetric deviations from the central points.

boxes : bool, default: None

Shorthand for `boxstd`, `boxstds`.

boxstd, boxstds, boxpctile, boxpctiles, boxdata : optional

As with `barstd`, `barpctile`, and `bardata`, but for *thicker error bars*

representing a smaller interval than the thin error bars. If `boxstds` is

``True``, the default standard deviation range of +/-1 is used. If `boxpctiles`

is ``True``, the default percentile range of 25 to 75 is used (i.e., the

interquartile range). When "boxes" and "bars" are combined, this has the

effect of drawing miniature box-and-whisker plots.

capsize : float, default: :rc:`errorbar.capsize`

The cap size for thin error bars in points.

barz, barzorder, boxz, boxzorder : float, default: 2.5

The "zorder" for the thin and thick error bars.

barc, barcolor, boxc, boxcolor \

: color-spec, default: :rc:`boxplot.whiskerprops.color`

Colors for the thin and thick error bars.

barlw, barlinewidth, boxlw, boxlinewidth \

: float, default: :rc:`boxplot.whiskerprops.linewidth`

Line widths for the thin and thick error bars, in points. The default for boxes

is 4 times :rcraw:`boxplot.whiskerprops.linewidth`.

boxm, boxmarker : bool or marker-spec, default: 'o'

Whether to draw a small marker in the middle of the box denoting

the mean or median position. Ignored if `boxes` is ``False``.

boxms, boxmarkersize : size-spec, default: ``(2 * boxlinewidth) ** 2``

The marker size for the `boxmarker` marker in points ** 2.

boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor : color-spec, default: 'w'

Color, face color, and edge color for the `boxmarker` marker.

"""

_error_shading_docstring = """

shade : bool, default: None

Shorthand for `shadestd`.

shadestd, shadestds, shadepctile, shadepctiles, shadedata : optional

As with `barstd`, `barpctile`, and `bardata`, but using *shading* to indicate

the error range. If `shadestds` is ``True``, the default standard deviation

range of +/-2 is used. If `shadepctiles` is ``True``, the default

percentile range of 10 to 90 is used.

fade : bool, default: None

Shorthand for `fadestd`.

fadestd, fadestds, fadepctile, fadepctiles, fadedata : optional

As with `shadestd`, `shadepctile`, and `shadedata`, but for an additional,

more faded, *secondary* shaded region. If `fadestds` is ``True``, the default

standard deviation range of +/-3 is used. If `fadepctiles` is ``True``,

the default percentile range of 0 to 100 is used.

shadec, shadecolor, fadec, fadecolor : color-spec, default: None

Colors for the different shaded regions. The parent artist color is used by default.

shadez, shadezorder, fadez, fadezorder : float, default: 1.5

The "zorder" for the different shaded regions.

shadea, shadealpha, fadea, fadealpha : float, default: 0.4, 0.2

The opacity for the different shaded regions.

shadelw, shadelinewidth, fadelw, fadelinewidth : float, default: :rc:`patch.linewidth`.

The edge line width for the shading patches.

shdeec, shadeedgecolor, fadeec, fadeedgecolor : float, default: 'none'

The edge color for the shading patches.

shadelabel, fadelabel : bool or str, optional

Labels for the shaded regions to be used as separate legend entries. To toggle

labels "on" and apply a *default* label, use e.g. ``shadelabel=True``. To apply

a *custom* label, use e.g. ``shadelabel='label'``. Otherwise, the shading is

drawn underneath the line and/or marker in the legend entry.

"""

docstring._snippet_manager['plot.inbounds'] = _inbounds_docstring

docstring._snippet_manager['plot.error_means_y'] = _error_means_docstring.format(y='y')

docstring._snippet_manager['plot.error_means_x'] = _error_means_docstring.format(y='x')

docstring._snippet_manager['plot.error_bars'] = _error_bars_docstring

docstring._snippet_manager['plot.error_shading'] = _error_shading_docstring

# Color docstrings

_cycle_docstring = """

cycle : cycle-spec, optional

The cycle specifer, passed to the `~proplot.constructor.Cycle` constructor.

If the returned cycler is unchanged from the current cycler, the axes

cycler will not be reset to its first position. To disable property cycling

and just use black for the default color, use ``cycle=False``, ``cycle='none'``,

or ``cycle=()`` (analogous to disabling ticks with e.g. ``xformatter='none'``).

To restore the default property cycler, use ``cycle=True``.

cycle_kw : dict-like, optional

Passed to `~proplot.constructor.Cycle`.

"""

_cmap_norm_docstring = """

cmap : colormap-spec, default: \

:rc:`cmap.sequential` or :rc:`cmap.diverging`

The colormap specifer, passed to the `~proplot.constructor.Colormap` constructor

function. If :rcraw:`cmap.autodiverging` is ``True`` and the normalization

range contains negative and positive values then :rcraw:`cmap.diverging` is used.

Otherwise :rcraw:`cmap.sequential` is used.

cmap_kw : dict-like, optional

Passed to `~proplot.constructor.Colormap`.

c, color, colors : color-spec or sequence of color-spec, optional

The color(s) used to create a `~proplot.colors.DiscreteColormap`.

If not passed, `cmap` is used.

norm : norm-spec, default: \

`~matplotlib.colors.Normalize` or `~proplot.colors.DivergingNorm`

The data value normalizer, passed to the `~proplot.constructor.Norm`

constructor function. If `discrete` is ``True`` then 1) this affects the default

level-generation algorithm (e.g. ``norm='log'`` builds levels in log-space) and

2) this is passed to `~proplot.colors.DiscreteNorm` to scale the colors before they

are discretized (if `norm` is not already a `~proplot.colors.DiscreteNorm`).

If :rcraw:`cmap.autodiverging` is ``True`` and the normalization range contains

negative and positive values then `~proplot.colors.DivergingNorm` is used.

Otherwise `~matplotlib.colors.Normalize` is used.

norm_kw : dict-like, optional

Passed to `~proplot.constructor.Norm`.

extend : {'neither', 'both', 'min', 'max'}, default: 'neither'

Direction for drawing colorbar "extensions" indicating

out-of-bounds data on the end of the colorbar.

discrete : bool, default: :rc:`cmap.discrete`

If ``False``, then `~proplot.colors.DiscreteNorm` is not applied to the

colormap. Instead, for non-contour plots, the number of levels will be

roughly controlled by :rcraw:`cmap.lut`. This has a similar effect to

using `levels=large_number` but it may improve rendering speed. Default is

``True`` only for contouring commands like `~proplot.axes.Axes.contourf`

and pseudocolor commands like `~proplot.axes.Axes.pcolor`.

sequential, diverging, cyclic, qualitative : bool, default: None

Boolean arguments used if `cmap` is not passed. Set these to ``True``

to use the default :rcraw:`cmap.sequential`, :rcraw:`cmap.diverging`,

:rcraw:`cmap.cyclic`, and :rcraw:`cmap.qualitative` colormaps.

The `diverging` option also applies `~proplot.colors.DivergingNorm`

as the default continuous normalizer.

"""

docstring._snippet_manager['plot.cycle'] = _cycle_docstring

docstring._snippet_manager['plot.cmap_norm'] = _cmap_norm_docstring

# Levels docstrings

# NOTE: In some functions we only need some components

_vmin_vmax_docstring = """

vmin, vmax : float, optional

The minimum and maximum color scale values used with the `norm` normalizer.

If `discrete` is ``False`` these are the absolute limits, and if `discrete`

is ``True`` these are the approximate limits used to automatically determine

`levels` or `values` lists at "nice" intervals. If `levels` or `values` were

already passed as lists, these are ignored, and `vmin` and `vmax` are set to

the minimum and maximum of the lists. If `robust` was passed, the default `vmin`

and `vmax` are some percentile range of the data values. Otherwise, the default

`vmin` and `vmax` are the minimum and maximum of the data values.

"""

_manual_levels_docstring = """

N

Shorthand for `levels`.

levels : int or sequence of float, default: :rc:`cmap.levels`

The number of level edges or a sequence of level edges. If the former, `locator`

is used to generate this many level edges at "nice" intervals. If the latter,

the levels should be monotonically increasing or decreasing (note decreasing

levels fail with ``contour`` plots).

values : int or sequence of float, default: None

The number of level centers or a sequence of level centers. If the former,

`locator` is used to generate this many level centers at "nice" intervals.

If the latter, levels are inferred using `~proplot.utils.edges`.

This will override any `levels` input.

"""

_auto_levels_docstring = """

robust : bool, float, or 2-tuple, default: :rc:`cmap.robust`

If ``True`` and `vmin` or `vmax` were not provided, they are

determined from the 2nd and 98th data percentiles rather than the

minimum and maximum. If float, this percentile range is used (for example,

``90`` corresponds to the 5th to 95th percentiles). If 2-tuple of float,

these specific percentiles should be used. This feature is useful

when your data has large outliers.

inbounds : bool, default: :rc:`cmap.inbounds`

If ``True`` and `vmin` or `vmax` were not provided, when axis limits

have been explicitly restricted with `~matplotlib.axes.Axes.set_xlim`

or `~matplotlib.axes.Axes.set_ylim`, out-of-bounds data is ignored.

See also :rcraw:`cmap.inbounds` and :rcraw:`axes.inbounds`.

locator : locator-spec, default: `matplotlib.ticker.MaxNLocator`

The locator used to determine level locations if `levels` or `values` were not

already passed as lists. Passed to the `~proplot.constructor.Locator` constructor.

Default is `~matplotlib.ticker.MaxNLocator` with `levels` integer levels.

locator_kw : dict-like, optional

Keyword arguments passed to `matplotlib.ticker.Locator` class.

symmetric : bool, default: False

If ``True``, the normalization range or discrete colormap levels are

symmetric about zero.

positive : bool, default: False

If ``True``, the normalization range or discrete colormap levels are

positive with a minimum at zero.

negative : bool, default: False

If ``True``, the normaliation range or discrete colormap levels are

negative with a minimum at zero.

nozero : bool, default: False

If ``True``, ``0`` is removed from the level list. This is mainly useful for

single-color `~matplotlib.axes.Axes.contour` plots.

"""

docstring._snippet_manager['plot.vmin_vmax'] = _vmin_vmax_docstring

docstring._snippet_manager['plot.levels_manual'] = _manual_levels_docstring

docstring._snippet_manager['plot.levels_auto'] = _auto_levels_docstring

# Labels docstrings

_label_docstring = """

label, value : float or str, optional

The single legend label or colorbar coordinate to be used for

this plotted element. Can be numeric or string. This is generally

used with 1D positional arguments.

"""

_labels_1d_docstring = """

%(plot.label)s

labels, values : sequence of float or sequence of str, optional

The legend labels or colorbar coordinates used for each plotted element.

Can be numeric or string, and must match the number of plotted elements.

This is generally used with 2D positional arguments.

"""

_labels_2d_docstring = """

label : str, optional

The legend label to be used for this object. In the case of

contours, this is paired with the the central artist in the artist

list returned by `matplotlib.contour.ContourSet.legend_elements`.

labels : bool, optional

Whether to apply labels to contours and grid boxes. The text will be

white when the luminance of the underlying filled contour or grid box

is less than 50 and black otherwise.

labels_kw : dict-like, optional

Ignored if `labels` is ``False``. Extra keyword args for the labels.

For contour plots, this is passed to `~matplotlib.axes.Axes.clabel`.

Otherwise, this is passed to `~matplotlib.axes.Axes.text`.

formatter, fmt : formatter-spec, optional

The `~matplotlib.ticker.Formatter` used to format number labels.

Passed to the `~proplot.constructor.Formatter` constructor.

formatter_kw : dict-like, optional

Keyword arguments passed to `matplotlib.ticker.Formatter` class.

precision : int, optional

The maximum number of decimal places for number labels generated

with the default formatter `~proplot.ticker.Simpleformatter`.

"""

docstring._snippet_manager['plot.label'] = _label_docstring

docstring._snippet_manager['plot.labels_1d'] = _labels_1d_docstring

docstring._snippet_manager['plot.labels_2d'] = _labels_2d_docstring

# Negative-positive colors

_negpos_docstring = """

negpos : bool, default: False

Whether to shade {objects} where ``{pos}`` with `poscolor`

and where ``{neg}`` with `negcolor`. If ``True`` this

function will return a length-2 silent list of handles.

negcolor, poscolor : color-spec, default: :rc:`negcolor`, :rc:`poscolor`

Colors to use for the negative and positive {objects}. Ignored if

`negpos` is ``False``.

"""

docstring._snippet_manager['plot.negpos_fill'] = _negpos_docstring.format(

objects='patches', neg='y2 < y1', pos='y2 >= y1'

)

docstring._snippet_manager['plot.negpos_lines'] = _negpos_docstring.format(

objects='lines', neg='ymax < ymin', pos='ymax >= ymin'

)

docstring._snippet_manager['plot.negpos_bar'] = _negpos_docstring.format(

objects='bars', neg='height < 0', pos='height >= 0'

)

# Plot docstring

_plot_docstring = """

Plot standard lines.

Parameters

----------

%(plot.args_1d_{y})s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.line)s

%(plot.error_means_{y})s

%(plot.error_bars)s

%(plot.error_shading)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.plot`.

See also

--------

PlotAxes.plot

PlotAxes.plotx

matplotlib.axes.Axes.plot

"""

docstring._snippet_manager['plot.plot'] = _plot_docstring.format(y='y')

docstring._snippet_manager['plot.plotx'] = _plot_docstring.format(y='x')

# Step docstring

# NOTE: Internally matplotlib implements step with thin wrapper of plot

_step_docstring = """

Plot step lines.

Parameters

----------

%(plot.args_1d_{y})s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.line)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.step`.

See also

--------

PlotAxes.step

PlotAxes.stepx

matplotlib.axes.Axes.step

"""

docstring._snippet_manager['plot.step'] = _step_docstring.format(y='y')

docstring._snippet_manager['plot.stepx'] = _step_docstring.format(y='x')

# Stem docstring

_stem_docstring = """

Plot stem lines.

Parameters

----------

%(plot.args_1d_{y})s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(plot.inbounds)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.stem`.

"""

docstring._snippet_manager['plot.stem'] = _stem_docstring.format(y='x')

docstring._snippet_manager['plot.stemx'] = _stem_docstring.format(y='x')

# Lines docstrings

_lines_docstring = """

Plot {orientation} lines.

Parameters

----------

%(plot.args_1d_multi{y})s

%(plot.args_1d_shared)s

Other parameters

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

stack, stacked : bool, default: False

Whether to "stack" lines from successive columns of {y} data

or plot lines on top of each other.

%(plot.cycle)s

%(artist.line)s

%(plot.negpos_lines)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.{prefix}lines`.

See also

--------

PlotAxes.vlines

PlotAxes.hlines

matplotlib.axes.Axes.vlines

matplotlib.axes.Axes.hlines

"""

docstring._snippet_manager['plot.vlines'] = _lines_docstring.format(

y='y', prefix='v', orientation='vertical'

)

docstring._snippet_manager['plot.hlines'] = _lines_docstring.format(

y='x', prefix='h', orientation='horizontal'

)

# Scatter docstring

_parametric_docstring = """

Plot a parametric line.

Parameters

----------

%(plot.args_1d_y)s

c, color, colors, values, labels : sequence of float, str, or color-spec, optional

The parametric coordinate(s). These can be passed as a third positional

argument or as a keyword argument. If they are float, the colors will be

determined from `norm` and `cmap`. If they are strings, the color values

will be ``np.arange(len(colors))`` and eventual colorbar ticks will

be labeled with the strings. If they are colors, they are used for the

line segments and `cmap` is ignored -- for example, ``colors='blue'``

makes a monochromatic "parametric" line.

interp : int, default: 0

Interpolate to this many additional points between the parametric

coordinates. This can be increased to make the color gradations

between a small number of coordinates appear "smooth".

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cmap_norm)s

%(plot.vmin_vmax)s

%(plot.inbounds)s

scalex, scaley : bool, optional

Whether the view limits are adapted to the data limits. The values are

passed on to `~matplotlib.axes.Axes.autoscale_view`.

%(plot.label)s

%(plot.guide)s

**kwargs

Valid `~matplotlib.collections.LineCollection` properties.

Returns

-------

`~matplotlib.collections.LineCollection`

The parametric line. See `this matplotlib example \

<https://matplotlib.org/stable/gallery/lines_bars_and_markers/multicolored_line>`__.

See also

--------

PlotAxes.plot

PlotAxes.plotx

matplotlib.collections.LineCollection

"""

docstring._snippet_manager['plot.parametric'] = _parametric_docstring

# Scatter function docstring

_scatter_docstring = """

Plot markers with flexible keyword arguments.

Parameters

----------

%(plot.args_1d_{y})s

s, size, ms, markersize : float or array-like or unit-spec, optional

The marker size area(s). If this is an array matching the shape of `x` and `y`,

the units are scaled by `smin` and `smax`. If this contains unit string(s), it

is processed by `~proplot.utils.units` and represents the width rather than area.

c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors \

: array-like or color-spec, optional

The marker color(s). If this is an array matching the shape of `x` and `y`,

the colors are generated using `cmap`, `norm`, `vmin`, and `vmax`. Otherwise,

this should be a valid matplotlib color.

smin, smax : float, optional

The minimum and maximum marker size area in units ``points ** 2``. Ignored

if `absolute_size` is ``True``. Default value for `smin` is ``1`` and for

`smax` is the square of :rc:`lines.markersize`.

area_size : bool, default: True

Whether the marker sizes `s` are scaled by area or by radius. The default

``True`` is consistent with matplotlib. When `absolute_size` is ``True``,

the `s` units are ``points ** 2`` if `area_size` is ``True`` and ``points``

if `area_size` is ``False``.

absolute_size : bool, default: True or False

Whether `s` should be taken to represent "absolute" marker sizes in units

``points`` or ``points ** 2`` or "relative" marker sizes scaled by `smin`

and `smax`. Default is ``True`` if `s` is scalar and ``False`` if `s` is

array-like or `smin` or `smax` were passed.

%(plot.vmin_vmax)s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cmap_norm)s

%(plot.levels_manual)s

%(plot.levels_auto)s

%(plot.cycle)s

lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths \

: float or sequence, optional

The marker edge width(s).

edgecolors, markeredgecolor, markeredgecolors \

: color-spec or sequence, optional

The marker edge color(s).

%(plot.error_means_{y})s

%(plot.error_bars)s

%(plot.error_shading)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.scatter`.

See also

--------

PlotAxes.scatter

PlotAxes.scatterx

matplotlib.axes.Axes.scatter

"""

docstring._snippet_manager['plot.scatter'] = _scatter_docstring.format(y='y')

docstring._snippet_manager['plot.scatterx'] = _scatter_docstring.format(y='x')

# Bar function docstring

_bar_docstring = """

Plot individual, grouped, or stacked bars.

Parameters

----------

%(plot.args_1d_{y})s

width : float or array-like, default: 0.8

The width(s) of the bars. Can be passed as a third positional argument. If

`absolute_width` is ``True`` (the default) these are in units relative to the

{x} coordinate step size. Otherwise these are in {x} coordinate units.

{bottom} : float or array-like, default: 0

The coordinate(s) of the {bottom} edge of the bars.

Can be passed as a fourth positional argument.

absolute_width : bool, default: False

Whether to make the `width` units *absolute*. If ``True``,

this restores the default matplotlib behavior.

stack, stacked : bool, default: False

Whether to "stack" bars from successive columns of {y}

data or plot bars side-by-side in groups.

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.patch)s

%(plot.negpos_bar)s

%(axes.edgefix)s

%(plot.error_means_{y})s

%(plot.error_bars)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.bar{suffix}`.

See also

--------

PlotAxes.bar

PlotAxes.barh

matplotlib.axes.Axes.bar

matplotlib.axes.Axes.barh

"""

docstring._snippet_manager['plot.bar'] = _bar_docstring.format(

x='x', y='y', bottom='bottom', suffix=''

)

docstring._snippet_manager['plot.barh'] = _bar_docstring.format(

x='y', y='x', bottom='left', suffix='h'

)

# Area plot docstring

_fill_docstring = """

Plot individual, grouped, or overlaid shading patches.

Parameters

----------

%(plot.args_1d_multi{y})s

stack, stacked : bool, default: False

Whether to "stack" area patches from successive columns of {y}

data or plot area patches on top of each other.

%(plot.args_1d_shared)s

Other parameters

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

where : ndarray, optional

A boolean mask for the points that should be shaded.

See `this matplotlib example \

<https://matplotlib.org/stable/gallery/pyplots/whats_new_98_4_fill_between.html>`__.

%(plot.cycle)s

%(artist.patch)s

%(plot.negpos_fill)s

%(axes.edgefix)s

%(plot.inbounds)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.fill_between{suffix}`.

See also

--------

PlotAxes.area

PlotAxes.areax

PlotAxes.fill_between

PlotAxes.fill_betweenx

matplotlib.axes.Axes.fill_between

matplotlib.axes.Axes.fill_betweenx

"""

docstring._snippet_manager['plot.fill_between'] = _fill_docstring.format(

x='x', y='y', suffix=''

)

docstring._snippet_manager['plot.fill_betweenx'] = _fill_docstring.format(

x='y', y='x', suffix='x'

)

# Box plot docstrings

_boxplot_docstring = """

Plot {orientation} boxes and whiskers with a nice default style.

Parameters

----------

%(plot.args_1d_{y})s

%(plot.args_1d_shared)s

Other parameters

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

fill : bool, default: True

Whether to fill the box with a color.

mean, means : bool, default: False

If ``True``, this passes ``showmeans=True`` and ``meanline=True`` to

`matplotlib.axes.Axes.boxplot`. Adds mean lines alongside the median.

%(plot.cycle)s

%(artist.patch_black)s

m, marker, ms, markersize : float or str, optional

Marker style and size for the 'fliers', i.e. outliers. See the

``boxplot.flierprops`` `~matplotlib.rcParams` settings.

meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles \

: str, optional

Line style for the mean and median lines drawn across the box.

See the ``boxplot.meanprops`` and ``boxplot.medianprops``

`~matplotlib.rcParams` settings.

boxc, capc, whiskerc, flierc, meanc, medianc, \

boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor \

boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors \

: color-spec or sequence, optional

Color of various boxplot components. If a sequence, should be the same length as

the number of boxes. These are shorthands so you don't have to pass e.g. a

`boxprops` dictionary keyword. See the ``boxplot.boxprops``, ``boxplot.capprops``,

``boxplot.whiskerprops``, ``boxplot.flierprops``, ``boxplot.meanprops``, and

``boxplot.medianprops`` `~matplotlib.rcParams` settings.

boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, \

meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, \

caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths \

: float, optional

Line width of various boxplot components. These are shorthands so

you don't have to pass e.g. a `boxprops` dictionary keyword.

See the ``boxplot.boxprops``, ``boxplot.capprops``, ``boxplot.whiskerprops``,

``boxplot.flierprops``, ``boxplot.meanprops``, and ``boxplot.medianprops``

`~matplotlib.rcParams` settings.

%(plot.labels_1d)s

**kwargs

Passed to `matplotlib.axes.Axes.boxplot`.

See also

--------

PlotAxes.boxes

PlotAxes.boxesh

PlotAxes.boxplot

PlotAxes.boxploth

matplotlib.axes.Axes.boxplot

"""

docstring._snippet_manager['plot.boxplot'] = _boxplot_docstring.format(

y='y', orientation='vertical'

)

docstring._snippet_manager['plot.boxploth'] = _boxplot_docstring.format(

y='x', orientation='horizontal'

)

# Violin plot docstrings

_violinplot_docstring = """

Plot {orientation} violins with a nice default style matching

`this matplotlib example \

<https://matplotlib.org/stable/gallery/statistics/customized_violin.html>`__.

Parameters

----------

%(plot.args_1d_{y})s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.patch_black)s

%(plot.labels_1d)s

showmeans, showmedians : bool, optional

Interpreted as ``means=True`` and ``medians=True`` when passed.

showextrema : bool, optional

Interpreted as ``barpctiles=True`` when passed (i.e. shows minima and maxima).

%(plot.error_bars)s

**kwargs

Passed to `matplotlib.axes.Axes.violinplot`.

See also

--------

PlotAxes.violin

PlotAxes.violinh

PlotAxes.violinplot

PlotAxes.violinploth

matplotlib.axes.Axes.violinplot

"""

docstring._snippet_manager['plot.violinplot'] = _violinplot_docstring.format(

y='y', orientation='vertical'

)

docstring._snippet_manager['plot.violinploth'] = _violinplot_docstring.format(

y='x', orientation='horizontal'

)

# 1D histogram docstrings

_hist_docstring = """

Plot {orientation} histograms.

Parameters

----------

%(plot.args_1d_{y})s

bins : int or sequence of float, optional

The bin count or exact bin edges.

%(plot.weights)s

histtype : {{'bar', 'barstacked', 'step', 'stepfilled'}}, optional

The histogram type. See `matplotlib.axes.Axes.hist` for details.

width, rwidth : float, default: 0.8 or 1

The bar width(s) for bar-type histograms relative to the bin size. Default

is ``0.8`` for multiple columns of unstacked data and ``1`` otherwise.

stack, stacked : bool, optional

Whether to "stack" successive columns of {y} data for bar-type histograms

or show side-by-side in groups. Setting this to ``False`` is equivalent to

``histtype='bar'`` and to ``True`` is equivalent to ``histtype='barstacked'``.

fill, filled : bool, optional

Whether to "fill" step-type histograms or just plot the edges. Setting

this to ``False`` is equivalent to ``histtype='step'`` and to ``True``

is equivalent to ``histtype='stepfilled'``.

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.patch)s

%(axes.edgefix)s

%(plot.labels_1d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.hist`.

See also

--------

PlotAxes.hist

PlotAxes.histh

matplotlib.axes.Axes.hist

"""

_weights_docstring = """

weights : array-like, optional

The weights associated with each point. If string this

can be retrieved from `data` (see below).

"""

docstring._snippet_manager['plot.weights'] = _weights_docstring

docstring._snippet_manager['plot.hist'] = _hist_docstring.format(

y='x', orientation='vertical'

)

docstring._snippet_manager['plot.histh'] = _hist_docstring.format(

y='x', orientation='horizontal'

)

# 2D histogram docstrings

_hist2d_docstring = """

Plot a {descrip}.

standard 2D histogram.

Parameters

----------

%(plot.args_1d_y)s{bins}

%(plot.weights)s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cmap_norm)s

%(plot.vmin_vmax)s

%(plot.levels_manual)s

%(plot.levels_auto)s

%(plot.labels_2d)s

%(plot.guide)s

**kwargs

Passed to `~matplotlib.axes.Axes.{command}`.

See also

--------

PlotAxes.hist2d

PlotAxes.hexbin

matplotlib.axes.Axes.{command}

"""

_bins_docstring = """

bins : int or 2-tuple of int, or array-like or 2-tuple of array-like, optional

The bin count or exact bin edges for each dimension or both dimensions.

""".rstrip()

docstring._snippet_manager['plot.hist2d'] = _hist2d_docstring.format(

command='hist2d', descrip='standard 2D histogram', bins=_bins_docstring

)

docstring._snippet_manager['plot.hexbin'] = _hist2d_docstring.format(

command='hexbin', descrip='2D hexagonally binned histogram', bins=''

)

# Pie chart docstring

_pie_docstring = """

Plot a pie chart.

Parameters

----------

%(plot.args_1d_y)s

%(plot.args_1d_shared)s

Other parameters

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

%(plot.cycle)s

%(artist.patch)s