Module « matplotlib.pyplot »

Fonction pcolormesh - module matplotlib.pyplot

Signature de la fonction pcolormesh

def pcolormesh(*args, alpha=None, norm=None, cmap=None, vmin=None, vmax=None, shading=None, antialiased=False, data=None, **kwargs) 

Description

pcolormesh.__doc__

Create a pseudocolor plot with a non-regular rectangular grid.

Call signature::

    pcolormesh([X, Y,] C, **kwargs)

*X* and *Y* can be used to specify the corners of the quadrilaterals.

.. hint::

   `~.Axes.pcolormesh` is similar to `~.Axes.pcolor`. It is much faster
   and preferred in most cases. For a detailed discussion on the
   differences see :ref:`Differences between pcolor() and pcolormesh()
   <differences-pcolor-pcolormesh>`.

Parameters
----------
C : 2D array-like
    The color-mapped values.

X, Y : array-like, optional
    The coordinates of the corners of quadrilaterals of a pcolormesh::

        (X[i+1, j], Y[i+1, j])       (X[i+1, j+1], Y[i+1, j+1])
                              +-----+
                              |     |
                              +-----+
            (X[i, j], Y[i, j])       (X[i, j+1], Y[i, j+1])

    Note that the column index corresponds to the x-coordinate, and
    the row index corresponds to y. For details, see the
    :ref:`Notes <axes-pcolormesh-grid-orientation>` section below.

    If ``shading='flat'`` the dimensions of *X* and *Y* should be one
    greater than those of *C*, and the quadrilateral is colored due
    to the value at ``C[i, j]``.  If *X*, *Y* and *C* have equal
    dimensions, a warning will be raised and the last row and column
    of *C* will be ignored.

    If ``shading='nearest'`` or ``'gouraud'``, the dimensions of *X*
    and *Y* should be the same as those of *C* (if not, a ValueError
    will be raised).  For ``'nearest'`` the color ``C[i, j]`` is
    centered on ``(X[i, j], Y[i, j])``.  For ``'gouraud'``, a smooth
    interpolation is caried out between the quadrilateral corners.

    If *X* and/or *Y* are 1-D arrays or column vectors they will be
    expanded as needed into the appropriate 2D arrays, making a
    rectangular grid.

cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
    A Colormap instance or registered colormap name. The colormap
    maps the *C* values to colors.

norm : `~matplotlib.colors.Normalize`, optional
    The Normalize instance scales the data values to the canonical
    colormap range [0, 1] for mapping to colors. By default, the data
    range is mapped to the colorbar range using linear scaling.

vmin, vmax : float, default: None
    The colorbar range. If *None*, suitable min/max values are
    automatically chosen by the `~.Normalize` instance (defaults to
    the respective min/max values of *C* in case of the default linear
    scaling).
    It is deprecated to use *vmin*/*vmax* when *norm* is given.

edgecolors : {'none', None, 'face', color, color sequence}, optional
    The color of the edges. Defaults to 'none'. Possible values:

    - 'none' or '': No edge.
    - *None*: :rc:`patch.edgecolor` will be used. Note that currently
      :rc:`patch.force_edgecolor` has to be True for this to work.
    - 'face': Use the adjacent face color.
    - A color or sequence of colors will set the edge color.

    The singular form *edgecolor* works as an alias.

alpha : float, default: None
    The alpha blending value, between 0 (transparent) and 1 (opaque).

shading : {'flat', 'nearest', 'gouraud', 'auto'}, optional
    The fill style for the quadrilateral; defaults to
    'flat' or :rc:`pcolor.shading`. Possible values:

    - 'flat': A solid color is used for each quad. The color of the
      quad (i, j), (i+1, j), (i, j+1), (i+1, j+1) is given by
      ``C[i, j]``. The dimensions of *X* and *Y* should be
      one greater than those of *C*; if they are the same as *C*,
      then a deprecation warning is raised, and the last row
      and column of *C* are dropped.
    - 'nearest': Each grid point will have a color centered on it,
      extending halfway between the adjacent grid centers.  The
      dimensions of *X* and *Y* must be the same as *C*.
    - 'gouraud': Each quad will be Gouraud shaded: The color of the
      corners (i', j') are given by ``C[i', j']``. The color values of
      the area in between is interpolated from the corner values.
      The dimensions of *X* and *Y* must be the same as *C*. When
      Gouraud shading is used, *edgecolors* is ignored.
    - 'auto': Choose 'flat' if dimensions of *X* and *Y* are one
      larger than *C*.  Choose 'nearest' if dimensions are the same.

    See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
    for more description.

snap : bool, default: False
    Whether to snap the mesh to pixel boundaries.

rasterized: bool, optional
    Rasterize the pcolormesh when drawing vector graphics.  This can
    speed up rendering and produce smaller files for large data sets.
    See also :doc:`/gallery/misc/rasterization_demo`.

Returns
-------
`matplotlib.collections.QuadMesh`

Other Parameters
----------------
**kwargs
    Additionally, the following arguments are allowed. They are passed
    along to the `~matplotlib.collections.QuadMesh` constructor:

Properties:
    agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
    alpha: array-like or scalar or None
    animated: bool
    antialiased or aa or antialiaseds: bool or list of bools
    array: ndarray or None
    capstyle: `.CapStyle` or {'butt', 'projecting', 'round'}
    clim: (vmin: float, vmax: float)
    clip_box: `.Bbox`
    clip_on: bool
    clip_path: Patch or (Path, Transform) or None
    cmap: `.Colormap` or str or None
    color: color or list of rgba tuples
    contains: unknown
    edgecolor or ec or edgecolors: color or list of colors or 'face'
    facecolor or facecolors or fc: color or list of colors
    figure: `.Figure`
    gid: str
    hatch: {'/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
    in_layout: bool
    joinstyle: `.JoinStyle` or {'miter', 'round', 'bevel'}
    label: object
    linestyle or dashes or linestyles or ls: str or tuple or list thereof
    linewidth or linewidths or lw: float or list of floats
    norm: `.Normalize` or None
    offset_position: unknown
    offsets: (N, 2) or (2,) array-like
    path_effects: `.AbstractPathEffect`
    picker: None or bool or float or callable
    pickradius: float
    rasterized: bool
    sketch_params: (scale: float, length: float, randomness: float)
    snap: bool or None
    transform: `.Transform`
    url: str
    urls: list of str or None
    visible: bool
    zorder: float

See Also
--------
pcolor : An alternative implementation with slightly different
    features. For a detailed discussion on the differences see
    :ref:`Differences between pcolor() and pcolormesh()
    <differences-pcolor-pcolormesh>`.
imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a
    faster alternative.

Notes
-----
**Masked arrays**

*C* may be a masked array. If ``C[i, j]`` is masked, the corresponding
quadrilateral will be transparent. Masking of *X* and *Y* is not
supported. Use `~.Axes.pcolor` if you need this functionality.

.. _axes-pcolormesh-grid-orientation:

**Grid orientation**

The grid orientation follows the standard matrix convention: An array
*C* with shape (nrows, ncolumns) is plotted with the column number as
*X* and the row number as *Y*.

.. _differences-pcolor-pcolormesh:

**Differences between pcolor() and pcolormesh()**

Both methods are used to create a pseudocolor plot of a 2D array
using quadrilaterals.

The main difference lies in the created object and internal data
handling:
While `~.Axes.pcolor` returns a `.PolyCollection`, `~.Axes.pcolormesh`
returns a `.QuadMesh`. The latter is more specialized for the given
purpose and thus is faster. It should almost always be preferred.

There is also a slight difference in the handling of masked arrays.
Both `~.Axes.pcolor` and `~.Axes.pcolormesh` support masked arrays
for *C*. However, only `~.Axes.pcolor` supports masked arrays for *X*
and *Y*. The reason lies in the internal handling of the masked values.
`~.Axes.pcolor` leaves out the respective polygons from the
PolyCollection. `~.Axes.pcolormesh` sets the facecolor of the masked
elements to transparent. You can see the difference when using
edgecolors. While all edges are drawn irrespective of masking in a
QuadMesh, the edge between two adjacent masked quadrilaterals in
`~.Axes.pcolor` is not drawn as the corresponding polygons do not
exist in the PolyCollection.

Another difference is the support of Gouraud shading in
`~.Axes.pcolormesh`, which is not available with `~.Axes.pcolor`.

.. note::
    In addition to the above described arguments, this function can take
    a *data* keyword argument. If such a *data* argument is given,
    every other argument can also be string ``s``, which is
    interpreted as ``data[s]`` (unless this raises an exception).

    Objects passed as **data** must support item access (``data[s]``) and
    membership test (``s in data``).