Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit f6f9149

Browse filesBrowse files
timhoffmtimhoffm
committed
Improve docstring of Axes.pcolormesh
1 parent 1966a7a commit f6f9149
Copy full SHA for f6f9149

File tree

Expand file treeCollapse file tree

1 file changed

+137
-53
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+137
-53
lines changed

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+137-53Lines changed: 137 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -5326,18 +5326,21 @@ def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
53265326
the respective min/max values of *C* in case of the default linear
53275327
scaling).
53285328
5329-
edgecolors : {'none', None, color, color sequence}, optional
5329+
edgecolors : {'none', None, 'face', color, color sequence}, optional
53305330
The color of the edges. Defaults to 'none'. Possible values:
53315331
53325332
- 'none' or '': No edge.
53335333
- *None*: :rc:`patch.edgecolor` will be used. Note that currently
53345334
:rc:`patch.force_edgecolor` has to be True for this to work.
5335+
- 'face': Use the adjacent face color.
53355336
- An mpl color or sequence of colors will set the edge color.
53365337
53375338
The singular form *edgecolor* works as an alias.
53385339
53395340
alpha : scalar, optional, default: None
5340-
The alpha blending value, between 0 (transparent) and 1 (opaque).
5341+
The alpha blending value of the face color, between 0 (transparent)
5342+
and 1 (opaque). Note: The edgecolor is currently not affected by
5343+
this.
53415344
53425345
snap : bool, optional, default: False
53435346
Whether to snap the mesh to pixel boundaries.
@@ -5502,79 +5505,160 @@ def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
55025505
def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
55035506
vmax=None, shading='flat', antialiased=False, **kwargs):
55045507
"""
5505-
Plot a quadrilateral mesh.
5508+
Create a pseudocolor plot with a non-regular rectangular grid.
55065509
5507-
Call signatures::
5510+
Call signature::
55085511
5509-
pcolormesh(C)
5510-
pcolormesh(X, Y, C)
5511-
pcolormesh(C, **kwargs)
5512+
pcolor([X, Y,] C, **kwargs)
55125513
5513-
Create a pseudocolor plot of a 2-D array.
5514+
*X* and *Y* can be used to specify the corners of the quadrilaterals.
55145515
5515-
pcolormesh is similar to :func:`~matplotlib.pyplot.pcolor`,
5516-
but uses a different mechanism and returns a different
5517-
object; pcolor returns a
5518-
:class:`~matplotlib.collections.PolyCollection` but pcolormesh
5519-
returns a
5520-
:class:`~matplotlib.collections.QuadMesh`. It is much faster,
5521-
so it is almost always preferred for large arrays.
5516+
.. note::
55225517
5523-
*C* may be a masked array, but *X* and *Y* may not. Masked
5524-
array support is implemented via *cmap* and *norm*; in
5525-
contrast, :func:`~matplotlib.pyplot.pcolor` simply does not
5526-
draw quadrilaterals with masked colors or vertices.
5518+
``pcolormesh()`` is similar to :func:`~Axes.pcolor`. It's much
5519+
faster and preferred in most cases. For a detailed discussion on
5520+
the differences see
5521+
:ref:`Differences between pcolor() and pcolormesh()
5522+
<differences-pcolor-pcolormesh>`.
55275523
5528-
Other Parameters
5529-
----------------
5530-
cmap : Colormap, optional
5531-
A :class:`matplotlib.colors.Colormap` instance. If ``None``, use
5532-
rc settings.
5524+
Parameters
5525+
----------
5526+
C : array_like
5527+
A scalar 2-D array. The values will be color-mapped.
55335528
5534-
norm : Normalize, optional
5535-
A :class:`matplotlib.colors.Normalize` instance is used to
5536-
scale luminance data to 0,1. If ``None``, defaults to
5537-
:func:`normalize`.
5529+
X, Y : array_like, optional
5530+
The coordinates of the quadrilateral corners. The quadrilateral
5531+
for ``C[i,j]`` has corners at::
55385532
5539-
vmin, vmax : scalar, optional
5540-
*vmin* and *vmax* are used in conjunction with *norm* to
5541-
normalize luminance data. If either is ``None``, it is autoscaled
5542-
to the respective min or max of the color array *C*.
5543-
If not ``None``, *vmin* or *vmax* passed in here override any
5544-
pre-existing values supplied in the *norm* instance.
5533+
(X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1])
5534+
+--------+
5535+
| C[i,j] |
5536+
+--------+
5537+
(X[i, j], Y[i, j]) (X[i, j+1], Y[i, j+1]),
55455538
5546-
shading : [ 'flat' | 'gouraud' ], optional
5547-
'flat' indicates a solid color for each quad. When
5548-
'gouraud', each quad will be Gouraud shaded. When gouraud
5549-
shading, *edgecolors* is ignored.
5539+
Note that the column index corresponds to the
5540+
x-coordinate, and the row index corresponds to y. For
5541+
details, see the :ref:`Notes <axes-pcolormesh-grid-orientation>`
5542+
section below.
55505543
5551-
edgecolors : string, color, color sequence, optional
5552-
- If ``None``, the rc setting is used by default.
5553-
- If ``'None'``, edges will not be visible.
5554-
- If ``'face'``, edges will have the same color as the faces.
5544+
The dimensions of *X* and *Y* should be one greater than those of
5545+
*C*. Alternatively, *X*, *Y* and *C* may have equal dimensions, in
5546+
which case the last row and column of *C* will be ignored.
55555547
5556-
An mpl color or sequence of colors will also set the edge color.
5548+
If *X* and/or *Y* are 1-D arrays or column vectors they will be
5549+
expanded as needed into the appropriate 2-D arrays, making a
5550+
rectangular grid.
55575551
5558-
alpha : scalar, optional
5559-
Alpha blending value. Must be between 0 and 1.
5552+
cmap : str or `~matplotlib.colors.Colormap`, optional
5553+
A Colormap instance or registered colormap name. The colormap
5554+
maps the *C* values to colors. Defaults to :rc:`image.cmap`.
5555+
5556+
norm : `~matplotlib.colors.Normalize`, optional
5557+
The Normalize instance scales the data values to the canonical
5558+
colormap range [0, 1] for mapping to colors. By default, the data
5559+
range is mapped to the colorbar range using linear scaling.
5560+
5561+
vmin, vmax : scalar, optional, default: None
5562+
The colorbar range. If *None*, suitable min/max values are
5563+
automatically chosen by the `~.Normalize` instance (defaults to
5564+
the respective min/max values of *C* in case of the default linear
5565+
scaling).
5566+
5567+
edgecolors : {'none', None, 'face', color, color sequence}, optional
5568+
The color of the edges. Defaults to 'none'. Possible values:
5569+
5570+
- 'none' or '': No edge.
5571+
- *None*: :rc:`patch.edgecolor` will be used. Note that currently
5572+
:rc:`patch.force_edgecolor` has to be True for this to work.
5573+
- 'face': Use the adjacent face color.
5574+
- An mpl color or sequence of colors will set the edge color.
5575+
5576+
The singular form *edgecolor* works as an alias.
5577+
5578+
alpha : scalar, optional, default: None
5579+
The alpha blending value, between 0 (transparent) and 1 (opaque).
5580+
5581+
shading : {'flat', 'gouraud'}, optional
5582+
The fill style, Possible values:
5583+
5584+
- 'flat': A solid color is used for each quad. The color of the
5585+
quad (i, j), (i+1, j), (i, j+1), (i+1, j+1) is given by
5586+
``C[i,j]``.
5587+
- 'gouraud': Each quad will be Gouraud shaded: The color of the
5588+
corners (i', j') are given by ``C[i',j']``. The color values of
5589+
the area in between is interpolated from the corner values.
5590+
When Gouraud shading is used, *edgecolors* is ignored.
5591+
5592+
snap : bool, optional, default: False
5593+
Whether to snap the mesh to pixel boundaries.
55605594
55615595
Returns
55625596
-------
5563-
matplotlib.collections.QuadMesh
5597+
mesh : `matplotlib.collections.QuadMesh`
5598+
5599+
Other Parameters
5600+
----------------
5601+
**kwargs
5602+
Additionally, the following arguments are allowed. They are passed
5603+
along to the `~matplotlib.collections.QuadMesh` constructor:
5604+
5605+
%(QuadMesh)s
5606+
55645607
55655608
See Also
55665609
--------
5567-
matplotlib.pyplot.pcolor :
5568-
For an explanation of the grid orientation
5569-
(:ref:`Grid Orientation <axes-pcolor-grid-orientation>`)
5570-
and the expansion of 1-D *X* and/or *Y* to 2-D arrays.
5610+
pcolor : An alternative implementation with slightly different
5611+
features. For a detailed discussion on the differences see
5612+
:ref:`Differences between pcolor() and pcolormesh()
5613+
<differences-pcolor-pcolormesh>`.
5614+
imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a
5615+
faster alternative.
55715616
55725617
Notes
55735618
-----
5574-
kwargs can be used to control the
5575-
:class:`matplotlib.collections.QuadMesh` properties:
55765619
5577-
%(QuadMesh)s
5620+
**Masked arrays**
5621+
5622+
*C* may be a masked array. If ``C[i, j]`` is masked, the corresponding
5623+
quadrilateral will be transparent. Masking of *X* and *Y* is not
5624+
supported. Use `~.Axes.pcolor` if you need this functionality.
5625+
5626+
.. _axes-pcolormesh-grid-orientation:
5627+
5628+
**Grid orientation**
5629+
5630+
The grid orientation follows the standard matrix convention: An array
5631+
*C* with shape (nrows, ncolumns) is plotted with the column number as
5632+
*X* and the row number as *Y*.
5633+
5634+
.. _differences-pcolor-pcolormesh:
5635+
5636+
**Differences between pcolor() and pcolormesh()**
5637+
5638+
Both methods are used to create a pseudocolor plot of a 2-D array
5639+
using quadrilaterals.
5640+
5641+
The main difference lies in the created object and internal data
5642+
handling:
5643+
While `~.Axes.pcolor` returns a `.PolyCollection`, `~.Axes.pcolormesh`
5644+
returns a `.QuadMesh`. The latter is more specialized for the given
5645+
purpose and thus is faster. It should almost always be preferred.
5646+
5647+
There is also a slight difference in the handling of masked arrays.
5648+
Both `~.Axes.pcolor` and `~.Axes.pcolormesh` support masked arrays
5649+
for *C*. However, only `~.Axes.pcolor` supports masked arrays for *X*
5650+
and *Y*. The reason lies in the internal handling of the masked values.
5651+
`~.Axes.pcolor` leaves out the respective polygons from the
5652+
PolyCollection. `~.Axes.pcolormesh` sets the facecolor of the masked
5653+
elements to transparent. You can see the difference when using
5654+
edgecolors. While all edges are drawn irrespective of masking in a
5655+
QuadMesh, the edge between two adjacent masked quadrilaterals in
5656+
`~.Axes.pcolor` is not drawn as the corresponding polygons do not
5657+
exist in the PolyCollection.
5658+
5659+
Another difference is the support of Gouraud shading in
5660+
`~.Axes.pcolormesh`, which is not available with `~.Axes.pcolor`.
5661+
55785662
"""
55795663
shading = shading.lower()
55805664
kwargs.setdefault('edgecolors', 'None')

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.