"""

Use this module directly:

import xarray.plot as xplt

Or use the methods on a DataArray or Dataset:

DataArray.plot._____

Dataset.plot._____

"""

import functools

import numpy as np

import pandas as pd

from .facetgrid import _easy_facetgrid

from .utils import (

_add_colorbar,

_assert_valid_xy,

_ensure_plottable,

_infer_interval_breaks,

_infer_xy_labels,

_process_cmap_cbar_kwargs,

_rescale_imshow_rgb,

_resolve_intervals_1dplot,

_resolve_intervals_2dplot,

_update_axes,

get_axis,

import_matplotlib_pyplot,

label_from_attrs,

)

def _infer_line_data(darray, x, y, hue):

ndims = len(darray.dims)

if x is not None and y is not None:

raise ValueError("Cannot specify both x and y kwargs for line plots.")

if x is not None:

_assert_valid_xy(darray, x, "x")

if y is not None:

_assert_valid_xy(darray, y, "y")

if ndims == 1:

huename = None

hueplt = None

huelabel = ""

if x is not None:

xplt = darray[x]

yplt = darray

elif y is not None:

xplt = darray

yplt = darray[y]

else: # Both x & y are None

dim = darray.dims[0]

xplt = darray[dim]

yplt = darray

else:

if x is None and y is None and hue is None:

raise ValueError("For 2D inputs, please specify either hue, x or y.")

if y is None:

if hue is not None:

_assert_valid_xy(darray, hue, "hue")

xname, huename = _infer_xy_labels(darray=darray, x=x, y=hue)

xplt = darray[xname]

if xplt.ndim > 1:

if huename in darray.dims:

otherindex = 1 if darray.dims.index(huename) == 0 else 0

otherdim = darray.dims[otherindex]

yplt = darray.transpose(otherdim, huename, transpose_coords=False)

xplt = xplt.transpose(otherdim, huename, transpose_coords=False)

else:

raise ValueError(

"For 2D inputs, hue must be a dimension"

" i.e. one of " + repr(darray.dims)

)

else:

(xdim,) = darray[xname].dims

(huedim,) = darray[huename].dims

yplt = darray.transpose(xdim, huedim)

else:

yname, huename = _infer_xy_labels(darray=darray, x=y, y=hue)

yplt = darray[yname]

if yplt.ndim > 1:

if huename in darray.dims:

otherindex = 1 if darray.dims.index(huename) == 0 else 0

otherdim = darray.dims[otherindex]

xplt = darray.transpose(otherdim, huename, transpose_coords=False)

yplt = yplt.transpose(otherdim, huename, transpose_coords=False)

else:

raise ValueError(

"For 2D inputs, hue must be a dimension"

" i.e. one of " + repr(darray.dims)

)

else:

(ydim,) = darray[yname].dims

(huedim,) = darray[huename].dims

xplt = darray.transpose(ydim, huedim)

huelabel = label_from_attrs(darray[huename])

hueplt = darray[huename]

return xplt, yplt, hueplt, huelabel

def plot(

darray,

row=None,

col=None,

col_wrap=None,

ax=None,

hue=None,

rtol=0.01,

subplot_kws=None,

**kwargs,

):

"""

Default plot of DataArray using :py:mod:`matplotlib:matplotlib.pyplot`.

Calls xarray plotting function based on the dimensions of

the squeezed DataArray.

=============== ===========================

Dimensions Plotting function

=============== ===========================

1 :py:func:`xarray.plot.line`

2 :py:func:`xarray.plot.pcolormesh`

Anything else :py:func:`xarray.plot.hist`

=============== ===========================

Parameters

----------

darray : DataArray

row : str, optional

If passed, make row faceted plots on this dimension name.

col : str, optional

If passed, make column faceted plots on this dimension name.

hue : str, optional

If passed, make faceted line plots with hue on this dimension name.

col_wrap : int, optional

Use together with ``col`` to wrap faceted plots.

ax : matplotlib axes object, optional

If ``None``, use the current axes. Not applicable when using facets.

rtol : float, optional

Relative tolerance used to determine if the indexes

are uniformly spaced. Usually a small positive number.

subplot_kws : dict, optional

Dictionary of keyword arguments for Matplotlib subplots

(see :py:meth:`matplotlib:matplotlib.figure.Figure.add_subplot`).

**kwargs : optional

Additional keyword arguments for Matplotlib.

See Also

--------

xarray.DataArray.squeeze

"""

darray = darray.squeeze().compute()

plot_dims = set(darray.dims)

plot_dims.discard(row)

plot_dims.discard(col)

plot_dims.discard(hue)

ndims = len(plot_dims)

error_msg = (

"Only 1d and 2d plots are supported for facets in xarray. "

"See the package `Seaborn` for more options."

)

if ndims in [1, 2]:

if row or col:

kwargs["subplot_kws"] = subplot_kws

kwargs["row"] = row

kwargs["col"] = col

kwargs["col_wrap"] = col_wrap

if ndims == 1:

plotfunc = line

kwargs["hue"] = hue

elif ndims == 2:

if hue:

plotfunc = line

kwargs["hue"] = hue

else:

plotfunc = pcolormesh

kwargs["subplot_kws"] = subplot_kws

else:

if row or col or hue:

raise ValueError(error_msg)

plotfunc = hist

kwargs["ax"] = ax

return plotfunc(darray, **kwargs)

# This function signature should not change so that it can use

# matplotlib format strings

def line(

darray,

*args,

row=None,

col=None,

figsize=None,

aspect=None,

size=None,

ax=None,

hue=None,

x=None,

y=None,

xincrease=None,

yincrease=None,

xscale=None,

yscale=None,

xticks=None,

yticks=None,

xlim=None,

ylim=None,

add_legend=True,

_labels=True,

**kwargs,

):

"""

Line plot of DataArray values.

Wraps :py:func:`matplotlib:matplotlib.pyplot.plot`.

Parameters

----------

darray : DataArray

Either 1D or 2D. If 2D, one of ``hue``, ``x`` or ``y`` must be provided.

figsize : tuple, optional

A tuple (width, height) of the figure in inches.

Mutually exclusive with ``size`` and ``ax``.

aspect : scalar, optional

Aspect ratio of plot, so that ``aspect * size`` gives the *width* in

inches. Only used if a ``size`` is provided.

size : scalar, optional

If provided, create a new figure for the plot with the given size:

*height* (in inches) of each plot. See also: ``aspect``.

ax : matplotlib axes object, optional

Axes on which to plot. By default, the current is used.

Mutually exclusive with ``size`` and ``figsize``.

hue : str, optional

Dimension or coordinate for which you want multiple lines plotted.

If plotting against a 2D coordinate, ``hue`` must be a dimension.

x, y : str, optional

Dimension, coordinate or multi-index level for *x*, *y* axis.

Only one of these may be specified.

The other will be used for values from the DataArray on which this

plot method is called.

xscale, yscale : {'linear', 'symlog', 'log', 'logit'}, optional

Specifies scaling for the *x*- and *y*-axis, respectively.

xticks, yticks : array-like, optional

Specify tick locations for *x*- and *y*-axis.

xlim, ylim : array-like, optional

Specify *x*- and *y*-axis limits.

xincrease : None, True, or False, optional

Should the values on the *x* axis be increasing from left to right?

if ``None``, use the default for the Matplotlib function.

yincrease : None, True, or False, optional

Should the values on the *y* axis be increasing from top to bottom?

if ``None``, use the default for the Matplotlib function.

add_legend : bool, optional

Add legend with *y* axis coordinates (2D inputs only).

*args, **kwargs : optional

Additional arguments to :py:func:`matplotlib:matplotlib.pyplot.plot`.

"""

# Handle facetgrids first

if row or col:

allargs = locals().copy()

allargs.update(allargs.pop("kwargs"))

allargs.pop("darray")

return _easy_facetgrid(darray, line, kind="line", **allargs)

ndims = len(darray.dims)

if ndims > 2:

raise ValueError(

"Line plots are for 1- or 2-dimensional DataArrays. "

"Passed DataArray has {ndims} "

"dimensions".format(ndims=ndims)

)

# The allargs dict passed to _easy_facetgrid above contains args

if args == ():

args = kwargs.pop("args", ())

else:

assert "args" not in kwargs

ax = get_axis(figsize, size, aspect, ax)

xplt, yplt, hueplt, hue_label = _infer_line_data(darray, x, y, hue)

# Remove pd.Intervals if contained in xplt.values and/or yplt.values.

xplt_val, yplt_val, x_suffix, y_suffix, kwargs = _resolve_intervals_1dplot(

xplt.values, yplt.values, kwargs

)

xlabel = label_from_attrs(xplt, extra=x_suffix)

ylabel = label_from_attrs(yplt, extra=y_suffix)

_ensure_plottable(xplt_val, yplt_val)

primitive = ax.plot(xplt_val, yplt_val, *args, **kwargs)

if _labels:

if xlabel is not None:

ax.set_xlabel(xlabel)

if ylabel is not None:

ax.set_ylabel(ylabel)

ax.set_title(darray._title_for_slice())

if darray.ndim == 2 and add_legend:

ax.legend(handles=primitive, labels=list(hueplt.values), title=hue_label)

# Rotate dates on xlabels

# Do this without calling autofmt_xdate so that x-axes ticks

# on other subplots (if any) are not deleted.

# https://stackoverflow.com/questions/17430105/autofmt-xdate-deletes-x-axis-labels-of-all-subplots

if np.issubdtype(xplt.dtype, np.datetime64):

for xlabels in ax.get_xticklabels():

xlabels.set_rotation(30)

xlabels.set_ha("right")

_update_axes(ax, xincrease, yincrease, xscale, yscale, xticks, yticks, xlim, ylim)

return primitive

def step(darray, *args, where="pre", drawstyle=None, ds=None, **kwargs):

"""

Step plot of DataArray values.

Similar to :py:func:`matplotlib:matplotlib.pyplot.step`.

Parameters

----------

where : {'pre', 'post', 'mid'}, default: 'pre'

Define where the steps should be placed:

- ``'pre'``: The y value is continued constantly to the left from

every *x* position, i.e. the interval ``(x[i-1], x[i]]`` has the

value ``y[i]``.

- ``'post'``: The y value is continued constantly to the right from

every *x* position, i.e. the interval ``[x[i], x[i+1])`` has the

value ``y[i]``.

- ``'mid'``: Steps occur half-way between the *x* positions.

Note that this parameter is ignored if one coordinate consists of

:py:class:`pandas.Interval` values, e.g. as a result of

:py:func:`xarray.Dataset.groupby_bins`. In this case, the actual

boundaries of the interval are used.

*args, **kwargs : optional

Additional arguments for :py:func:`xarray.plot.line`.

"""

if where not in {"pre", "post", "mid"}:

raise ValueError("'where' argument to step must be 'pre', 'post' or 'mid'")

if ds is not None:

if drawstyle is None:

drawstyle = ds

else:

raise TypeError("ds and drawstyle are mutually exclusive")

if drawstyle is None:

drawstyle = ""

drawstyle = "steps-" + where + drawstyle

return line(darray, *args, drawstyle=drawstyle, **kwargs)

def hist(

darray,

figsize=None,

size=None,

aspect=None,

ax=None,

xincrease=None,

yincrease=None,

xscale=None,

yscale=None,

xticks=None,

yticks=None,

xlim=None,

ylim=None,

**kwargs,

):

"""

Histogram of DataArray.

Wraps :py:func:`matplotlib:matplotlib.pyplot.hist`.

Plots *N*-dimensional arrays by first flattening the array.

Parameters

----------

darray : DataArray

Can have any number of dimensions.

figsize : tuple, optional

A tuple (width, height) of the figure in inches.

Mutually exclusive with ``size`` and ``ax``.

aspect : scalar, optional

Aspect ratio of plot, so that ``aspect * size`` gives the *width* in

inches. Only used if a ``size`` is provided.

size : scalar, optional

If provided, create a new figure for the plot with the given size:

*height* (in inches) of each plot. See also: ``aspect``.

ax : matplotlib axes object, optional

Axes on which to plot. By default, use the current axes.

Mutually exclusive with ``size`` and ``figsize``.

**kwargs : optional

Additional keyword arguments to :py:func:`matplotlib:matplotlib.pyplot.hist`.

"""

ax = get_axis(figsize, size, aspect, ax)

no_nan = np.ravel(darray.values)

no_nan = no_nan[pd.notnull(no_nan)]

primitive = ax.hist(no_nan, **kwargs)

ax.set_title("Histogram")

ax.set_xlabel(label_from_attrs(darray))

_update_axes(ax, xincrease, yincrease, xscale, yscale, xticks, yticks, xlim, ylim)

return primitive

# MUST run before any 2d plotting functions are defined since

# _plot2d decorator adds them as methods here.

class _PlotMethods:

"""

Enables use of xarray.plot functions as attributes on a DataArray.

For example, DataArray.plot.imshow

"""

__slots__ = ("_da",)

def __init__(self, darray):

self._da = darray

def __call__(self, **kwargs):

return plot(self._da, **kwargs)

# we can't use functools.wraps here since that also modifies the name / qualname

__doc__ = __call__.__doc__ = plot.__doc__

__call__.__wrapped__ = plot # type: ignore[attr-defined]

__call__.__annotations__ = plot.__annotations__

@functools.wraps(hist)

def hist(self, ax=None, **kwargs):

return hist(self._da, ax=ax, **kwargs)

@functools.wraps(line)

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

return line(self._da, *args, **kwargs)

@functools.wraps(step)

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

return step(self._da, *args, **kwargs)

def override_signature(f):

def wrapper(func):

func.__wrapped__ = f

return func

return wrapper

def _plot2d(plotfunc):

"""

Decorator for common 2d plotting logic

Also adds the 2d plot method to class _PlotMethods

"""

commondoc = """

Parameters

----------

darray : DataArray

Must be two-dimensional, unless creating faceted plots.

x : str, optional

Coordinate for *x* axis. If ``None``, use ``darray.dims[1]``.

y : str, optional

Coordinate for *y* axis. If ``None``, use ``darray.dims[0]``.

figsize : tuple, optional

A tuple (width, height) of the figure in inches.

Mutually exclusive with ``size`` and ``ax``.

aspect : scalar, optional

Aspect ratio of plot, so that ``aspect * size`` gives the *width* in

inches. Only used if a ``size`` is provided.

size : scalar, optional

If provided, create a new figure for the plot with the given size:

*height* (in inches) of each plot. See also: ``aspect``.

ax : matplotlib axes object, optional

Axes on which to plot. By default, use the current axes.

Mutually exclusive with ``size`` and ``figsize``.

row : string, optional

If passed, make row faceted plots on this dimension name.

col : string, optional

If passed, make column faceted plots on this dimension name.

col_wrap : int, optional

Use together with ``col`` to wrap faceted plots.

xscale, yscale : {'linear', 'symlog', 'log', 'logit'}, optional

Specifies scaling for the *x*- and *y*-axis, respectively.

xticks, yticks : array-like, optional

Specify tick locations for *x*- and *y*-axis.

xlim, ylim : array-like, optional

Specify *x*- and *y*-axis limits.

xincrease : None, True, or False, optional

Should the values on the *x* axis be increasing from left to right?

If ``None``, use the default for the Matplotlib function.

yincrease : None, True, or False, optional

Should the values on the *y* axis be increasing from top to bottom?

If ``None``, use the default for the Matplotlib function.

add_colorbar : bool, optional

Add colorbar to axes.

add_labels : bool, optional

Use xarray metadata to label axes.

norm : matplotlib.colors.Normalize, optional

If ``norm`` has ``vmin`` or ``vmax`` specified, the corresponding

kwarg must be ``None``.

vmin, vmax : float, optional

Values to anchor the colormap, otherwise they are inferred from the

data and other keyword arguments. When a diverging dataset is inferred,

setting one of these values will fix the other by symmetry around

``center``. Setting both values prevents use of a diverging colormap.

If discrete levels are provided as an explicit list, both of these

values are ignored.

cmap : matplotlib colormap name or colormap, optional

The mapping from data values to color space. If not provided, this

will be either be ``'viridis'`` (if the function infers a sequential

dataset) or ``'RdBu_r'`` (if the function infers a diverging dataset).

See :doc:`Choosing Colormaps in Matplotlib <matplotlib:tutorials/colors/colormaps>`

for more information.

If *seaborn* is installed, ``cmap`` may also be a

`seaborn color palette <https://seaborn.pydata.org/tutorial/color_palettes.html>`_.

Note: if ``cmap`` is a seaborn color palette and the plot type

is not ``'contour'`` or ``'contourf'``, ``levels`` must also be specified.

colors : str or array-like of color-like, optional

A single color or a sequence of colors. If the plot type is not ``'contour'``

or ``'contourf'``, the ``levels`` argument is required.

center : float, optional

The value at which to center the colormap. Passing this value implies

use of a diverging colormap. Setting it to ``False`` prevents use of a

diverging colormap.

robust : bool, optional

If ``True`` and ``vmin`` or ``vmax`` are absent, the colormap range is

computed with 2nd and 98th percentiles instead of the extreme values.

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

How to draw arrows extending the colorbar beyond its limits. If not

provided, ``extend`` is inferred from ``vmin``, ``vmax`` and the data limits.

levels : int or array-like, optional

Split the colormap (``cmap``) into discrete color intervals. If an integer

is provided, "nice" levels are chosen based on the data range: this can

imply that the final number of levels is not exactly the expected one.

Setting ``vmin`` and/or ``vmax`` with ``levels=N`` is equivalent to

setting ``levels=np.linspace(vmin, vmax, N)``.

infer_intervals : bool, optional

Only applies to pcolormesh. If ``True``, the coordinate intervals are

passed to pcolormesh. If ``False``, the original coordinates are used

(this can be useful for certain map projections). The default is to

always infer intervals, unless the mesh is irregular and plotted on

a map projection.

subplot_kws : dict, optional

Dictionary of keyword arguments for Matplotlib subplots. Only used

for 2D and faceted plots.

(see :py:meth:`matplotlib:matplotlib.figure.Figure.add_subplot`).

cbar_ax : matplotlib axes object, optional

Axes in which to draw the colorbar.

cbar_kwargs : dict, optional

Dictionary of keyword arguments to pass to the colorbar

(see :meth:`matplotlib:matplotlib.figure.Figure.colorbar`).

**kwargs : optional

Additional keyword arguments to wrapped Matplotlib function.

Returns

-------

artist :

The same type of primitive artist that the wrapped Matplotlib

function returns.

"""

# Build on the original docstring

plotfunc.__doc__ = f"{plotfunc.__doc__}\n{commondoc}"

# plotfunc and newplotfunc have different signatures:

# - plotfunc: (x, y, z, ax, **kwargs)

# - newplotfunc: (darray, x, y, **kwargs)

# where plotfunc accepts numpy arrays, while newplotfunc accepts a DataArray

# and variable names. newplotfunc also explicitly lists most kwargs, so we

# need to shorten it

def signature(darray, x, y, **kwargs):

pass

@override_signature(signature)

@functools.wraps(plotfunc)

def newplotfunc(

darray,

x=None,

y=None,

figsize=None,

size=None,

aspect=None,

ax=None,

row=None,

col=None,

col_wrap=None,

xincrease=True,

yincrease=True,

add_colorbar=None,

add_labels=True,

vmin=None,

vmax=None,

cmap=None,

center=None,

robust=False,

extend=None,

levels=None,

infer_intervals=None,

colors=None,

subplot_kws=None,

cbar_ax=None,

cbar_kwargs=None,

xscale=None,

yscale=None,

xticks=None,

yticks=None,

xlim=None,

ylim=None,

norm=None,

**kwargs,

):

# All 2d plots in xarray share this function signature.

# Method signature below should be consistent.

# Decide on a default for the colorbar before facetgrids

if add_colorbar is None:

add_colorbar = True

if plotfunc.__name__ == "contour" or (

plotfunc.__name__ == "surface" and cmap is None

):

add_colorbar = False

imshow_rgb = plotfunc.__name__ == "imshow" and darray.ndim == (

3 + (row is not None) + (col is not None)

)

if imshow_rgb:

# Don't add a colorbar when showing an image with explicit colors

add_colorbar = False

# Matplotlib does not support normalising RGB data, so do it here.

# See eg. https://github.com/matplotlib/matplotlib/pull/10220

if robust or vmax is not None or vmin is not None:

darray = _rescale_imshow_rgb(darray, vmin, vmax, robust)

vmin, vmax, robust = None, None, False

if subplot_kws is None:

subplot_kws = dict()

if plotfunc.__name__ == "surface" and not kwargs.get("_is_facetgrid", False):

if ax is None:

# TODO: Importing Axes3D is no longer necessary in matplotlib >= 3.2.

# Remove when minimum requirement of matplotlib is 3.2:

from mpl_toolkits.mplot3d import Axes3D # type: ignore # noqa: F401

# delete so it does not end up in locals()

del Axes3D

# Need to create a "3d" Axes instance for surface plots

subplot_kws["projection"] = "3d"

# In facet grids, shared axis labels don't make sense for surface plots

sharex = False

sharey = False

# Handle facetgrids first

if row or col:

allargs = locals().copy()

del allargs["darray"]

del allargs["imshow_rgb"]

allargs.update(allargs.pop("kwargs"))

# Need the decorated plotting function

allargs["plotfunc"] = globals()[plotfunc.__name__]

return _easy_facetgrid(darray, kind="dataarray", **allargs)

plt = import_matplotlib_pyplot()

if (

plotfunc.__name__ == "surface"

and not kwargs.get("_is_facetgrid", False)

and ax is not None

):

import mpl_toolkits # type: ignore

if not isinstance(ax, mpl_toolkits.mplot3d.Axes3D):

raise ValueError(

"If ax is passed to surface(), it must be created with "

'projection="3d"'

)

rgb = kwargs.pop("rgb", None)

if rgb is not None and plotfunc.__name__ != "imshow":

raise ValueError('The "rgb" keyword is only valid for imshow()')

elif rgb is not None and not imshow_rgb:

raise ValueError(

'The "rgb" keyword is only valid for imshow()'

"with a three-dimensional array (per facet)"

)

xlab, ylab = _infer_xy_labels(

darray=darray, x=x, y=y, imshow=imshow_rgb, rgb=rgb

)

xval = darray[xlab]

yval = darray[ylab]

if xval.ndim > 1 or yval.ndim > 1 or plotfunc.__name__ == "surface":

# Passing 2d coordinate values, need to ensure they are transposed the same

# way as darray.

# Also surface plots always need 2d coordinates

xval = xval.broadcast_like(darray)

yval = yval.broadcast_like(darray)

dims = darray.dims

else:

dims = (yval.dims[0], xval.dims[0])

# better to pass the ndarrays directly to plotting functions

xval = xval.values

yval = yval.values

# May need to transpose for correct x, y labels

# xlab may be the name of a coord, we have to check for dim names

if imshow_rgb:

# For RGB[A] images, matplotlib requires the color dimension

# to be last. In Xarray the order should be unimportant, so

# we transpose to (y, x, color) to make this work.

yx_dims = (ylab, xlab)

dims = yx_dims + tuple(d for d in darray.dims if d not in yx_dims)

if dims != darray.dims:

darray = darray.transpose(*dims, transpose_coords=True)

# Pass the data as a masked ndarray too

zval = darray.to_masked_array(copy=False)

# Replace pd.Intervals if contained in xval or yval.

xplt, xlab_extra = _resolve_intervals_2dplot(xval, plotfunc.__name__)

yplt, ylab_extra = _resolve_intervals_2dplot(yval, plotfunc.__name__)

_ensure_plottable(xplt, yplt, zval)

cmap_params, cbar_kwargs = _process_cmap_cbar_kwargs(

plotfunc,

zval.data,

**locals(),

_is_facetgrid=kwargs.pop("_is_facetgrid", False),

)

if "contour" in plotfunc.__name__:

# extend is a keyword argument only for contour and contourf, but

# passing it to the colorbar is sufficient for imshow and

# pcolormesh

kwargs["extend"] = cmap_params["extend"]

kwargs["levels"] = cmap_params["levels"]

# if colors == a single color, matplotlib draws dashed negative

# contours. we lose this feature if we pass cmap and not colors

if isinstance(colors, str):

cmap_params["cmap"] = None

kwargs["colors"] = colors

if "pcolormesh" == plotfunc.__name__:

kwargs["infer_intervals"] = infer_intervals

if "imshow" == plotfunc.__name__ and isinstance(aspect, str):

# forbid usage of mpl strings

raise ValueError("plt.imshow's `aspect` kwarg is not available in xarray")

ax = get_axis(figsize, size, aspect, ax, **subplot_kws)

primitive = plotfunc(

xplt,

yplt,

zval,

ax=ax,

cmap=cmap_params["cmap"],

vmin=cmap_params["vmin"],

vmax=cmap_params["vmax"],

norm=cmap_params["norm"],

**kwargs,

)

# Label the plot with metadata

if add_labels:

ax.set_xlabel(label_from_attrs(darray[xlab], xlab_extra))

ax.set_ylabel(label_from_attrs(darray[ylab], ylab_extra))

ax.set_title(darray._title_for_slice())

if plotfunc.__name__ == "surface":

ax.set_zlabel(label_from_attrs(darray))

if add_colorbar:

if add_labels and "label" not in cbar_kwargs:

cbar_kwargs["label"] = label_from_attrs(darray)

cbar = _add_colorbar(primitive, ax, cbar_ax, cbar_kwargs, cmap_params)

elif cbar_ax is not None or cbar_kwargs:

# inform the user about keywords which aren't used

raise ValueError(

"cbar_ax and cbar_kwargs can't be used with add_colorbar=False."

)

# origin kwarg overrides yincrease

if "origin" in kwargs:

yincrease = None

_update_axes(

ax, xincrease, yincrease, xscale, yscale, xticks, yticks, xlim, ylim

)

# Rotate dates on xlabels

# Do this without calling autofmt_xdate so that x-axes ticks

# on other subplots (if any) are not deleted.

# https://stackoverflow.com/questions/17430105/autofmt-xdate-deletes-x-axis-labels-of-all-subplots

if np.issubdtype(xplt.dtype, np.datetime64):

for xlabels in ax.get_xticklabels():

xlabels.set_rotation(30)

xlabels.set_ha("right")

return primitive

# For use as DataArray.plot.plotmethod

@functools.wraps(newplotfunc)

def plotmethod(

_PlotMethods_obj,

x=None,

y=None,

figsize=None,

size=None,

aspect=None,

ax=None,

row=None,

col=None,

col_wrap=None,

xincrease=True,

yincrease=True,

add_colorbar=None,

add_labels=True,

vmin=None,

vmax=None,

cmap=None,

colors=None,

center=None,

robust=False,

extend=None,

levels=None,

infer_intervals=None,

subplot_kws=None,

cbar_ax=None,

cbar_kwargs=None,

xscale=None,

yscale=None,

xticks=None,

yticks=None,

xlim=None,

ylim=None,

norm=None,

**kwargs,

):

"""

The method should have the same signature as the function.

This just makes the method work on Plotmethods objects,

and passes all the other arguments straight through.

"""

allargs = locals()

allargs["darray"] = _PlotMethods_obj._da

allargs.update(kwargs)

for arg in ["_PlotMethods_obj", "newplotfunc", "kwargs"]:

del allargs[arg]

return newplotfunc(**allargs)

# Add to class _PlotMethods

setattr(_PlotMethods, plotmethod.__name__, plotmethod)

return newplotfunc

@_plot2d

def imshow(x, y, z, ax, **kwargs):

"""

Image plot of 2D DataArray.

Wraps :py:func:`matplotlib:matplotlib.pyplot.imshow`.

While other plot methods require the DataArray to be strictly

two-dimensional, ``imshow`` also accepts a 3D array where some

dimension can be interpreted as RGB or RGBA color channels and

allows this dimension to be specified via the kwarg ``rgb=``.

Unlike :py:func:`matplotlib:matplotlib.pyplot.imshow`, which ignores ``vmin``/``vmax``

for RGB(A) data,

xarray *will* use ``vmin`` and ``vmax`` for RGB(A) data

by applying a single scaling factor and offset to all bands.

Passing ``robust=True`` infers ``vmin`` and ``vmax``

:ref:`in the usual way <robust-plotting>`.

.. note::

This function needs uniformly spaced coordinates to

properly label the axes. Call :py:meth:`DataArray.plot` to check.

The pixels are centered on the coordinates. For example, if the coordinate

value is 3.2, then the pixels for those coordinates will be centered on 3.2.

"""

if x.ndim != 1 or y.ndim != 1:

raise ValueError(

"imshow requires 1D coordinates, try using pcolormesh or contour(f)"

)

# Centering the pixels- Assumes uniform spacing

try:

xstep = (x[1] - x[0]) / 2.0

except IndexError:

# Arbitrary default value, similar to matplotlib behaviour

xstep = 0.1

try:

ystep = (y[1] - y[0]) / 2.0

except IndexError:

ystep = 0.1

left, right = x[0] - xstep, x[-1] + xstep

bottom, top = y[-1] + ystep, y[0] - ystep

defaults = {"origin": "upper", "interpolation": "nearest"}

if not hasattr(ax, "projection"):

# not for cartopy geoaxes

defaults["aspect"] = "auto"

# Allow user to override these defaults

defaults.update(kwargs)

if defaults["origin"] == "upper":

defaults["extent"] = [left, right, bottom, top]

else:

defaults["extent"] = [left, right, top, bottom]

if z.ndim == 3:

# matplotlib imshow uses black for missing data, but Xarray makes

# missing data transparent. We therefore add an alpha channel if

# there isn't one, and set it to transparent where data is masked.

if z.shape[-1] == 3:

alpha = np.ma.ones(z.shape[:2] + (1,), dtype=z.dtype)

if np.issubdtype(z.dtype, np.integer):

alpha *= 255

z = np.ma.concatenate((z, alpha), axis=2)

else:

z = z.copy()

z[np.any(z.mask, axis=-1), -1] = 0

primitive = ax.imshow(z, **defaults)

return primitive

@_plot2d

def contour(x, y, z, ax, **kwargs):

"""

Contour plot of 2D DataArray.

Wraps :py:func:`matplotlib:matplotlib.pyplot.contour`.

"""

primitive = ax.contour(x, y, z, **kwargs)

return primitive

@_plot2d

def contourf(x, y, z, ax, **kwargs):

"""

Filled contour plot of 2D DataArray.

Wraps :py:func:`matplotlib:matplotlib.pyplot.contourf`.

"""

primitive = ax.contourf(x, y, z, **kwargs)

return primitive

@_plot2d

def pcolormesh(x, y, z, ax, infer_intervals=None, **kwargs):

"""

Pseudocolor plot of 2D DataArray.

Wraps :py:func:`matplotlib:matplotlib.pyplot.pcolormesh`.