From 49aa235fc63706dc145128dd13fdf139b9d5bc6e Mon Sep 17 00:00:00 2001 From: Zachary Moon Date: Tue, 18 May 2021 11:25:42 -0400 Subject: [PATCH] Clean up and enhance plot method docstrings (#5285) Co-authored-by: Mathias Hauser --- doc/conf.py | 2 +- doc/whats-new.rst | 3 + xarray/plot/dataset_plot.py | 111 +++++++++------- xarray/plot/plot.py | 244 +++++++++++++++++++----------------- 4 files changed, 203 insertions(+), 157 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index a87713fb293..7e7c63ca165 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -144,7 +144,7 @@ "hashable": ":term:`hashable `", # matplotlib terms "color-like": ":py:func:`color-like `", - "matplotlib colormap name": ":doc:matplotlib colormap name ", + "matplotlib colormap name": ":doc:`matplotlib colormap name `", "matplotlib axes object": ":py:class:`matplotlib axes object `", "colormap": ":py:class:`colormap `", # objects without namespace diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 2606ac7b171..a9f234d08d4 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -52,6 +52,9 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Clean up and enhance docstrings for the :py:class:`DataArray.plot` and ``Dataset.plot.*`` + families of methods (:pull:`5285`). + By `Zach Moon `_. - Explanation of deprecation cycles and how to implement them added to contributors guide. (:pull:`5289`) diff --git a/xarray/plot/dataset_plot.py b/xarray/plot/dataset_plot.py index 55a48009f0d..c1aedd570bc 100644 --- a/xarray/plot/dataset_plot.py +++ b/xarray/plot/dataset_plot.py @@ -196,46 +196,56 @@ def _dsplot(plotfunc): ds : Dataset x, y : str - Variable names for x, y axis. + Variable names for the *x* and *y* grid positions. u, v : str, optional - Variable names for quiver or streamplot plots only + Variable names for the *u* and *v* velocities + (in *x* and *y* direction, respectively; quiver/streamplot plots only). hue: str, optional - Variable by which to color scattered points or arrows - hue_style: str, optional - Can be either 'discrete' (legend) or 'continuous' (color bar). + Variable by which to color scatter points or arrows. + hue_style: {'continuous', 'discrete'}, optional + How to use the ``hue`` variable: + + - ``'continuous'`` -- continuous color scale + (default for numeric ``hue`` variables) + - ``'discrete'`` -- a color for each unique value, using the default color cycle + (default for non-numeric ``hue`` variables) markersize: str, optional - scatter only. Variable by which to vary size of scattered points. - size_norm: optional - Either None or 'Norm' instance to normalize the 'markersize' variable. + Variable by which to vary the size of scattered points (scatter plot only). + size_norm: matplotlib.colors.Normalize or tuple, optional + Used to normalize the ``markersize`` variable. + If a tuple is passed, the values will be passed to + :py:class:`matplotlib:matplotlib.colors.Normalize` as arguments. + Default: no normalization (``vmin=None``, ``vmax=None``, ``clip=False``). scale: scalar, optional Quiver only. Number of data units per arrow length unit. Use this to control the length of the arrows: larger values lead to - smaller arrows - add_guide: bool, optional - Add a guide that depends on hue_style - - for "discrete", build a legend. - This is the default for non-numeric `hue` variables. - - for "continuous", build a colorbar + smaller arrows. + add_guide: bool, optional, default: True + Add a guide that depends on ``hue_style``: + + - ``'continuous'`` -- build a colorbar + - ``'discrete'`` -- build a legend row : str, optional - If passed, make row faceted plots on this dimension name + If passed, make row faceted plots on this dimension name. col : str, optional - If passed, make column faceted plots on this dimension name + If passed, make column faceted plots on this dimension name. col_wrap : int, optional - Use together with ``col`` to wrap faceted plots + Use together with ``col`` to wrap faceted plots. ax : matplotlib axes object, optional - If None, uses the current axis. Not applicable when using facets. + If ``None``, use the current axes. Not applicable when using facets. subplot_kws : dict, optional - Dictionary of keyword arguments for matplotlib subplots. Only applies - to FacetGrid plotting. + Dictionary of keyword arguments for Matplotlib subplots + (see :py:meth:`matplotlib:matplotlib.figure.Figure.add_subplot`). + Only applies to FacetGrid plotting. aspect : scalar, optional - Aspect ratio of plot, so that ``aspect * size`` gives the width in + 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``. - norm : ``matplotlib.colors.Normalize`` instance, optional - If the ``norm`` has vmin or vmax specified, the corresponding kwarg - must be None. + If provided, create a new figure for the plot with the given size: + *height* (in inches) of each plot. See also: ``aspect``. + 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, @@ -243,15 +253,20 @@ def _dsplot(plotfunc): ``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 : str or colormap, optional + cmap : matplotlib colormap name or colormap, optional The mapping from data values to color space. Either a - matplotlib colormap name or object. If not provided, this will - be either ``viridis`` (if the function infers a sequential - dataset) or ``RdBu_r`` (if the function infers a diverging - dataset). When `Seaborn` is installed, ``cmap`` may also be a - `seaborn` color palette. If ``cmap`` is seaborn color palette, + Matplotlib colormap name or object. If not provided, this will + be either ``'viridis'`` (if the function infers a sequential + dataset) or ``'RdBu_r'`` (if the function infers a diverging + dataset). + See :doc:`Choosing Colormaps in Matplotlib ` + for more information. + + If *seaborn* is installed, ``cmap`` may also be a + `seaborn color palette `_. + Note: if ``cmap`` is a seaborn color palette, ``levels`` must also be specified. - colors : color-like or list of color-like, optional + colors : str or array-like of color-like, optional A single color or a list of colors. The ``levels`` argument is required. center : float, optional @@ -259,19 +274,19 @@ def _dsplot(plotfunc): 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 + 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 + 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 list-like object, optional - Split the colormap (cmap) into discrete color intervals. If an integer + 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)``. **kwargs : optional - Additional keyword arguments to matplotlib + Additional keyword arguments to wrapped Matplotlib function. """ # Build on the original docstring @@ -463,9 +478,11 @@ def plotmethod( @_dsplot -def scatter(ds, x, y, ax, u, v, **kwargs): +def scatter(ds, x, y, ax, **kwargs): """ Scatter Dataset data variables against each other. + + Wraps :py:func:`matplotlib:matplotlib.pyplot.scatter`. """ if "add_colorbar" in kwargs or "add_legend" in kwargs: @@ -482,6 +499,10 @@ def scatter(ds, x, y, ax, u, v, **kwargs): size_norm = kwargs.pop("size_norm", None) size_mapping = kwargs.pop("size_mapping", None) # set by facetgrid + # Remove `u` and `v` so they don't get passed to `ax.scatter` + kwargs.pop("u", None) + kwargs.pop("v", None) + # need to infer size_mapping with full dataset data = _infer_scatter_data(ds, x, y, hue, markersize, size_norm, size_mapping) @@ -519,7 +540,10 @@ def scatter(ds, x, y, ax, u, v, **kwargs): @_dsplot def quiver(ds, x, y, ax, u, v, **kwargs): - """Quiver plot with Dataset variables.""" + """Quiver plot of Dataset variables. + + Wraps :py:func:`matplotlib:matplotlib.pyplot.quiver`. + """ import matplotlib as mpl if x is None or y is None or u is None or v is None: @@ -548,7 +572,10 @@ def quiver(ds, x, y, ax, u, v, **kwargs): @_dsplot def streamplot(ds, x, y, ax, u, v, **kwargs): - """Quiver plot with Dataset variables.""" + """Plot streamlines of Dataset variables. + + Wraps :py:func:`matplotlib:matplotlib.pyplot.streamplot`. + """ import matplotlib as mpl if x is None or y is None or u is None or v is None: diff --git a/xarray/plot/plot.py b/xarray/plot/plot.py index e6eb7ecbe0b..f530427562a 100644 --- a/xarray/plot/plot.py +++ b/xarray/plot/plot.py @@ -124,14 +124,14 @@ def plot( **kwargs, ): """ - Default plot of DataArray using matplotlib.pyplot. + Default plot of DataArray using :py:mod:`matplotlib:matplotlib.pyplot`. Calls xarray plotting function based on the dimensions of - darray.squeeze() + 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` @@ -141,23 +141,27 @@ def plot( ---------- darray : DataArray row : str, optional - If passed, make row faceted plots on this dimension name + If passed, make row faceted plots on this dimension name. col : str, optional - If passed, make column faceted plots on this dimension name + 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 + 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.Axes, optional - If None, uses the current axis. Not applicable when using facets. + 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. + Dictionary of keyword arguments for Matplotlib subplots + (see :py:meth:`matplotlib:matplotlib.figure.Figure.add_subplot`). **kwargs : optional - Additional keyword arguments to matplotlib + Additional keyword arguments for Matplotlib. + See Also + -------- + xarray.DataArray.squeeze """ darray = darray.squeeze().compute() @@ -226,48 +230,50 @@ def line( **kwargs, ): """ - Line plot of DataArray index against values + Line plot of DataArray values. - Wraps :func:`matplotlib:matplotlib.pyplot.plot` + Wraps :py:func:`matplotlib:matplotlib.pyplot.plot`. Parameters ---------- darray : DataArray - Must be 1 dimensional + 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 + 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``. + 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 - Axis on which to plot this figure. By default, use the current axis. + Axes on which to plot. By default, the current is used. Mutually exclusive with ``size`` and ``figsize``. - hue : string, optional + 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 : string, optional - Dimension, coordinate or MultiIndex level for x, y axis. + x, y : str, optional + Dimension, coordinate or multi-index level for *x*, *y* axis. Only one of these may be specified. - The other coordinate plots values from the DataArray on which this + 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-axes respectively - xticks, yticks : Specify tick locations for x- and y-axes - xlim, ylim : Specify x- and y-axes limits + 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 axes be increasing from left to right? - if None, use the default for the matplotlib function. + 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 axes be increasing from top to bottom? - if None, use the default for the matplotlib function. + 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). + Add legend with *y* axis coordinates (2D inputs only). *args, **kwargs : optional - Additional arguments to matplotlib.pyplot.plot + Additional arguments to :py:func:`matplotlib:matplotlib.pyplot.plot`. """ # Handle facetgrids first if row or col: @@ -332,29 +338,29 @@ def line( def step(darray, *args, where="pre", drawstyle=None, ds=None, **kwargs): """ - Step plot of DataArray index against values + Step plot of DataArray values. - Similar to :func:`matplotlib:matplotlib.pyplot.step` + Similar to :py:func:`matplotlib:matplotlib.pyplot.step`. Parameters ---------- - where : {"pre", "post", "mid"}, default: "pre" + where : {'pre', 'post', 'mid'}, default: 'pre' Define where the steps should be placed: - - "pre": The y value is continued constantly to the left from + - ``'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 + - ``'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. + - ``'mid'``: Steps occur half-way between the *x* positions. Note that this parameter is ignored if one coordinate consists of - :py:func:`pandas.Interval` values, e.g. as a result 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 following :py:func:`xarray.plot.line` + 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'") @@ -388,30 +394,30 @@ def hist( **kwargs, ): """ - Histogram of DataArray + Histogram of DataArray. - Wraps :func:`matplotlib:matplotlib.pyplot.hist` + Wraps :py:func:`matplotlib:matplotlib.pyplot.hist`. - Plots N dimensional arrays by first flattening the array. + Plots *N*-dimensional arrays by first flattening the array. Parameters ---------- darray : DataArray - Can be any dimension + 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 + 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.Axes, optional - Axis on which to plot this figure. By default, use the current axis. + 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 matplotlib.pyplot.hist + Additional keyword arguments to :py:func:`matplotlib:matplotlib.pyplot.hist`. """ ax = get_axis(figsize, size, aspect, ax) @@ -482,100 +488,108 @@ def _plot2d(plotfunc): Parameters ---------- darray : DataArray - Must be 2 dimensional, unless creating faceted plots - x : string, optional - Coordinate for x axis. If None use darray.dims[1] - y : string, optional - Coordinate for y axis. If None use darray.dims[0] + 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 + 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``. + 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 - Axis on which to plot this figure. By default, use the current axis. + 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 + If passed, make row faceted plots on this dimension name. col : string, optional - If passed, make column faceted plots on this dimension name + 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-axes respectively - xticks, yticks : Specify tick locations for x- and y-axes - xlim, ylim : Specify x- and y-axes limits + 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 axes be increasing from left to right? - if None, use the default for the matplotlib function. + 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 axes be increasing from top to bottom? - if None, use the default for the matplotlib function. + 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 - Adds colorbar to axis + Add colorbar to axes. add_labels : bool, optional - Use xarray metadata to label axes - norm : ``matplotlib.colors.Normalize`` instance, optional - If the ``norm`` has vmin or vmax specified, the corresponding kwarg - must be None. - vmin, vmax : floats, 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 object, optional + 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). - When `Seaborn` is installed, ``cmap`` may also be a `seaborn` - color palette. If ``cmap`` is seaborn color palette and the plot type - is not ``contour`` or ``contourf``, ``levels`` must also be specified. - colors : discrete colors to plot, optional - A single color or a list of colors. If the plot type is not ``contour`` - or ``contourf``, the ``levels`` argument is required. + 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 ` + for more information. + + If *seaborn* is installed, ``cmap`` may also be a + `seaborn color palette `_. + 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 + 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 + 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 list-like object, optional - Split the colormap (cmap) into discrete color intervals. If an integer + 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 + 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 FacetGrid plots. - cbar_ax : matplotlib Axes, 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. + Dictionary of keyword arguments to pass to the colorbar + (see :meth:`matplotlib:matplotlib.figure.Figure.colorbar`). **kwargs : optional - Additional arguments to wrapped matplotlib function + Additional keyword arguments to wrapped Matplotlib function. Returns ------- artist : - The same type of primitive artist that the wrapped matplotlib - function returns + The same type of primitive artist that the wrapped Matplotlib + function returns. """ # Build on the original docstring @@ -882,26 +896,28 @@ def plotmethod( @_plot2d def imshow(x, y, z, ax, **kwargs): """ - Image plot of 2d DataArray using matplotlib.pyplot + Image plot of 2D DataArray. - Wraps :func:`matplotlib:matplotlib.pyplot.imshow` + 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 matplotlib, Xarray can apply ``vmin`` and ``vmax`` to RGB or RGBA - data, by applying a single scaling factor and offset to all bands. + 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 `. .. note:: This function needs uniformly spaced coordinates to - properly label the axes. Call DataArray.plot() to check. + properly label the axes. Call :py:meth:`DataArray.plot` to check. - The pixels are centered on the coordinates values. Ie, if the coordinate - value is 3.2 then the pixels for those coordinates will be centered on 3.2. + 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: @@ -957,9 +973,9 @@ def imshow(x, y, z, ax, **kwargs): @_plot2d def contour(x, y, z, ax, **kwargs): """ - Contour plot of 2d DataArray + Contour plot of 2D DataArray. - Wraps :func:`matplotlib:matplotlib.pyplot.contour` + Wraps :py:func:`matplotlib:matplotlib.pyplot.contour`. """ primitive = ax.contour(x, y, z, **kwargs) return primitive @@ -968,9 +984,9 @@ def contour(x, y, z, ax, **kwargs): @_plot2d def contourf(x, y, z, ax, **kwargs): """ - Filled contour plot of 2d DataArray + Filled contour plot of 2D DataArray. - Wraps :func:`matplotlib:matplotlib.pyplot.contourf` + Wraps :py:func:`matplotlib:matplotlib.pyplot.contourf`. """ primitive = ax.contourf(x, y, z, **kwargs) return primitive @@ -979,9 +995,9 @@ def contourf(x, y, z, ax, **kwargs): @_plot2d def pcolormesh(x, y, z, ax, infer_intervals=None, **kwargs): """ - Pseudocolor plot of 2d DataArray + Pseudocolor plot of 2D DataArray. - Wraps :func:`matplotlib:matplotlib.pyplot.pcolormesh` + Wraps :py:func:`matplotlib:matplotlib.pyplot.pcolormesh`. """ # decide on a default for infer_intervals (GH781) @@ -1029,9 +1045,9 @@ def pcolormesh(x, y, z, ax, infer_intervals=None, **kwargs): @_plot2d def surface(x, y, z, ax, **kwargs): """ - Surface plot of 2d DataArray + Surface plot of 2D DataArray. - Wraps :func:`matplotlib:mpl_toolkits.mplot3d.axes3d.plot_surface` + Wraps :py:meth:`matplotlib:mpl_toolkits.mplot3d.axes3d.Axes3D.plot_surface`. """ primitive = ax.plot_surface(x, y, z, **kwargs) return primitive