
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "gallery/images_contours_and_fields/pcolormesh_grids.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_gallery_images_contours_and_fields_pcolormesh_grids.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_gallery_images_contours_and_fields_pcolormesh_grids.py:


============================
pcolormesh grids and shading
============================

`.axes.Axes.pcolormesh` and `~.axes.Axes.pcolor` have a few options for
how grids are laid out and the shading between the grid points.

Generally, if *Z* has shape *(M, N)* then the grid *X* and *Y* can be
specified with either shape *(M+1, N+1)* or *(M, N)*, depending on the
argument for the ``shading`` keyword argument.  Note that below we specify
vectors *x* as either length N or N+1 and *y* as length M or M+1, and
`~.axes.Axes.pcolormesh` internally makes the mesh matrices *X* and *Y* from
the input vectors.

.. GENERATED FROM PYTHON SOURCE LINES 17-22

.. code-block:: default


    import matplotlib
    import matplotlib.pyplot as plt
    import numpy as np








.. GENERATED FROM PYTHON SOURCE LINES 23-31

Flat Shading
------------

The grid specification with the least assumptions is ``shading='flat'``
and if the grid is one larger than the data in each dimension, i.e. has shape
*(M+1, N+1)*.  In that case *X* and *Y* specify the corners of quadrilaterals
that are colored with the values in *Z*. Here we specify the edges of the
*(3, 5)* quadrilaterals with *X* and *Y* that are *(4, 6)*.

.. GENERATED FROM PYTHON SOURCE LINES 31-53

.. code-block:: default


    nrows = 3
    ncols = 5
    Z = np.arange(nrows * ncols).reshape(nrows, ncols)
    x = np.arange(ncols + 1)
    y = np.arange(nrows + 1)

    fig, ax = plt.subplots()
    ax.pcolormesh(x, y, Z, shading='flat', vmin=Z.min(), vmax=Z.max())


    def _annotate(ax, x, y, title):
        # this all gets repeated below:
        X, Y = np.meshgrid(x, y)
        ax.plot(X.flat, Y.flat, 'o', color='m')
        ax.set_xlim(-0.7, 5.2)
        ax.set_ylim(-0.7, 3.2)
        ax.set_title(title)

    _annotate(ax, x, y, "shading='flat'")





.. image:: /gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_grids_001.png
    :alt: shading='flat'
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 54-62

Flat Shading, same shape grid
-----------------------------

Often, however, data is provided where *X* and *Y* match the shape of *Z*.
As of Matplotlib v3.3, ``shading='flat'`` is deprecated when this is the
case, a warning is raised, and the last row and column of *Z* are dropped.
This dropping of the last row and column is what Matplotlib did silently
previous to v3.3, and is compatible with what Matlab does.

.. GENERATED FROM PYTHON SOURCE LINES 62-69

.. code-block:: default


    x = np.arange(ncols)  # note *not* ncols + 1 as before
    y = np.arange(nrows)
    fig, ax = plt.subplots()
    ax.pcolormesh(x, y, Z, shading='flat', vmin=Z.min(), vmax=Z.max())
    _annotate(ax, x, y, "shading='flat': X, Y, C same shape")




.. image:: /gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_grids_002.png
    :alt: shading='flat': X, Y, C same shape
    :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    /build/matplotlib-eAPYn3/matplotlib-3.3.4/examples/images_contours_and_fields/pcolormesh_grids.py:66: MatplotlibDeprecationWarning: shading='flat' when X and Y have the same dimensions as C is deprecated since 3.3.  Either specify the corners of the quadrilaterals with X and Y, or pass shading='auto', 'nearest' or 'gouraud', or set rcParams['pcolor.shading'].  This will become an error two minor releases later.
      ax.pcolormesh(x, y, Z, shading='flat', vmin=Z.min(), vmax=Z.max())




.. GENERATED FROM PYTHON SOURCE LINES 70-80

Nearest Shading, same shape grid
--------------------------------

Usually, dropping a row and column of data is not what the user means when
they make *X*, *Y* and *Z* all the same shape.  For this case, Matplotlib
allows ``shading='nearest'`` and centers the colored quadrilaterals on the
grid points.

If a grid that is not the correct shape is passed with ``shading='nearest'``
an error is raised.

.. GENERATED FROM PYTHON SOURCE LINES 80-85

.. code-block:: default


    fig, ax = plt.subplots()
    ax.pcolormesh(x, y, Z, shading='nearest', vmin=Z.min(), vmax=Z.max())
    _annotate(ax, x, y, "shading='nearest'")




.. image:: /gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_grids_003.png
    :alt: shading='nearest'
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 86-92

Auto Shading
------------

It's possible that the user would like the code to automatically choose which
to use, in this case ``shading='auto'`` will decide whether to use 'flat' or
'nearest' shading based on the shapes of *X*, *Y* and *Z*.

.. GENERATED FROM PYTHON SOURCE LINES 92-106

.. code-block:: default


    fig, axs = plt.subplots(2, 1, constrained_layout=True)
    ax = axs[0]
    x = np.arange(ncols)
    y = np.arange(nrows)
    ax.pcolormesh(x, y, Z, shading='auto', vmin=Z.min(), vmax=Z.max())
    _annotate(ax, x, y, "shading='auto'; X, Y, Z: same shape (nearest)")

    ax = axs[1]
    x = np.arange(ncols + 1)
    y = np.arange(nrows + 1)
    ax.pcolormesh(x, y, Z, shading='auto', vmin=Z.min(), vmax=Z.max())
    _annotate(ax, x, y, "shading='auto'; X, Y one larger than Z (flat)")




.. image:: /gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_grids_004.png
    :alt: shading='auto'; X, Y, Z: same shape (nearest), shading='auto'; X, Y one larger than Z (flat)
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 107-113

Gouraud Shading
---------------

`Gouraud shading <https://en.wikipedia.org/wiki/Gouraud_shading>`_ can also
be specified, where the color in the quadrilaterals is linearly interpolated
between the grid points.  The shapes of *X*, *Y*, *Z* must be the same.

.. GENERATED FROM PYTHON SOURCE LINES 113-121

.. code-block:: default


    fig, ax = plt.subplots(constrained_layout=True)
    x = np.arange(ncols)
    y = np.arange(nrows)
    ax.pcolormesh(x, y, Z, shading='gouraud', vmin=Z.min(), vmax=Z.max())
    _annotate(ax, x, y, "shading='gouraud'; X, Y same shape as Z")

    plt.show()



.. image:: /gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_grids_005.png
    :alt: shading='gouraud'; X, Y same shape as Z
    :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 122-128

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

References
""""""""""

The use of the following functions and methods is shown in this example:

.. GENERATED FROM PYTHON SOURCE LINES 129-132

.. code-block:: default


    matplotlib.axes.Axes.pcolormesh
    matplotlib.pyplot.pcolormesh




.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    <function pcolormesh at 0x7f73be827d30>




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  3.706 seconds)


.. _sphx_glr_download_gallery_images_contours_and_fields_pcolormesh_grids.py:


.. only :: html

 .. container:: sphx-glr-footer
    :class: sphx-glr-footer-example



  .. container:: sphx-glr-download sphx-glr-download-python

     :download:`Download Python source code: pcolormesh_grids.py <pcolormesh_grids.py>`



  .. container:: sphx-glr-download sphx-glr-download-jupyter

     :download:`Download Jupyter notebook: pcolormesh_grids.ipynb <pcolormesh_grids.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    Keywords: matplotlib code example, codex, python plot, pyplot
    `Gallery generated by Sphinx-Gallery
    <https://sphinx-gallery.readthedocs.io>`_
