Skip to content

Commit

Permalink
Merge pull request matplotlib#11327 from matplotlib/auto-backport-of-…
Browse files Browse the repository at this point in the history 
…pr-11317-on-v2.2.x

Backport PR matplotlib#11317 on branch v2.2.x
  • Loading branch information
@jklymak
jklymak authored May 29, 2018
2 parents ecba68a + e0895b2 commit 89fc4e4
Showing 1 changed file with 74 additions and 81 deletions.
155 changes: 74 additions & 81 deletions lib/matplotlib/axes/_axes.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5596,62 +5596,73 @@ def _pcolorargs(funcname, *args, **kw):
@docstring.dedent_interpd
def pcolor(self, *args, **kwargs):
"""
Create a pseudocolor plot of a 2-D array.
Create a pseudocolor plot with a non-regular rectangular grid.
Call signatures::
Call signature::
pcolor([X, Y,] C, **kwargs)
*X* and *Y* can be used to specify the corners of the quadrilaterals.
pcolor(C, **kwargs)
pcolor(X, Y, C, **kwargs)
.. hint::
pcolor can be very slow for large arrays; consider
using the similar but much faster
:func:`~matplotlib.pyplot.pcolormesh` instead.
``pcolor()`` can be very slow for large arrays. In most
cases you should use the the similar but much faster
`~.Axes.pcolormesh` instead. See there for a discussion of the
differences.
Parameters
----------
C : array_like
An array of color values.
A scalar 2-D array. The values will be color-mapped.
X, Y : array_like, optional
If given, specify the (x, y) coordinates of the colored
quadrilaterals; the quadrilateral for ``C[i,j]`` has corners at::
The coordinates of the quadrilateral corners. The quadrilateral
for ``C[i,j]`` has corners at::
(X[i, j], Y[i, j]),
(X[i, j+1], Y[i, j+1]),
(X[i+1, j], Y[i+1, j]),
(X[i+1, j+1], Y[i+1, j+1])
Ideally the dimensions of ``X`` and ``Y`` should be one greater
than those of ``C``; if the dimensions are the same, then the last
row and column of ``C`` will be ignored.
(X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1])
+--------+
| C[i,j] |
+--------+
(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:`Grid Orientation
<axes-pcolor-grid-orientation>` section below.
x-coordinate, and the row index corresponds to y. For
details, see the :ref:`Notes <axes-pcolor-grid-orientation>`
section below.
If either or both of ``X`` and ``Y`` are 1-D arrays or column
vectors, they will be expanded as needed into the appropriate 2-D
arrays, making a rectangular grid.
The dimensions of *X* and *Y* should be one greater than those of
*C*. Alternatively, *X*, *Y* and *C* may have equal dimensions, in
which case the last row and column of *C* will be ignored.
cmap : `~matplotlib.colors.Colormap`, optional, default: None
If `None`, default to rc settings.
If *X* and/or *Y* are 1-D arrays or column vectors they will be
expanded as needed into the appropriate 2-D arrays, making a
rectangular grid.
cmap : str or `~matplotlib.colors.Colormap`, optional
A Colormap instance or registered colormap name. The colormap
maps the *C* values to colors. Defaults to :rc:`image.cmap`.
norm : `matplotlib.colors.Normalize`, optional, default: None
An instance is used to scale luminance data to (0, 1).
If `None`, defaults to :func:`normalize`.
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 : scalar, optional, default: None
``vmin`` and ``vmax`` are used in conjunction with ``norm`` to
normalize luminance data. If either is `None`, it is autoscaled to
the respective min or max of the color array ``C``. If not `None`,
``vmin`` or ``vmax`` passed in here override any pre-existing
values supplied in the ``norm`` instance.
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).
edgecolors : {'none', None, 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.
- An mpl color or sequence of colors will set the edge color.
edgecolors : {None, 'none', color, color sequence}
If None, the rc setting is used by default.
If 'none', edges will not be visible.
An mpl color or sequence of colors will set the edge color.
The singular form *edgecolor* works as an alias.
alpha : scalar, optional, default: None
The alpha blending value, between 0 (transparent) and 1 (opaque).
Expand All @@ -5666,72 +5677,54 @@ def pcolor(self, *args, **kwargs):
Other Parameters
----------------
antialiaseds : bool, optional, default: False
The default ``antialiaseds`` is False if the default
``edgecolors="none"`` is used. This eliminates artificial lines
The default *antialiaseds* is False if the default
*edgecolors*\ ="none" is used. This eliminates artificial lines
at patch boundaries, and works regardless of the value of alpha.
If ``edgecolors`` is not "none", then the default ``antialiaseds``
If *edgecolors* is not "none", then the default *antialiaseds*
is taken from :rc:`patch.antialiased`, which defaults to True.
Stroking the edges may be preferred if ``alpha`` is 1, but will
Stroking the edges may be preferred if *alpha* is 1, but will
cause artifacts otherwise.
**kwargs :
Any unused keyword arguments are passed along to the
`~matplotlib.collections.PolyCollection` constructor:
Additionally, the following arguments are allowed. They are passed
along to the `~matplotlib.collections.PolyCollection` constructor:
%(PolyCollection)s
See Also
--------
pcolormesh : for an explanation of the differences between
pcolor and pcolormesh.
imshow : If *X* and *Y* are each equidistant, `~.Axes.imshow` can be a
faster alternative.
Notes
-----
.. _axes-pcolor-grid-orientation:
``X``, ``Y`` and ``C`` may be masked arrays. If either C[i, j], or one
of the vertices surrounding C[i,j] (``X`` or ``Y`` at [i, j], [i+1, j],
[i, j+1], [i+1, j+1]) is masked, nothing is plotted.
The grid orientation follows the MATLAB convention: an array ``C`` with
shape (nrows, ncolumns) is plotted with the column number as ``X`` and
the row number as ``Y``, increasing up; hence it is plotted the way the
array would be printed, except that the ``Y`` axis is reversed. That
is, ``C`` is taken as ``C`` (y, x).
Similarly for :func:`meshgrid`::
x = np.arange(5)
y = np.arange(3)
X, Y = np.meshgrid(x, y)
**Masked arrays**
is equivalent to::
*X*, *Y* and *C* may be masked arrays. If either ``C[i, j]``, or one
of the vertices surrounding ``C[i,j]`` (*X* or *Y* at
``[i, j], [i+1, j], [i, j+1], [i+1, j+1]``) is masked, nothing is
plotted.
X = array([[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4]])
Y = array([[0, 0, 0, 0, 0],
[1, 1, 1, 1, 1],
[2, 2, 2, 2, 2]])
so if you have::
C = rand(len(x), len(y))
.. _axes-pcolor-grid-orientation:
then you need to transpose C::
**Grid orientation**
pcolor(X, Y, C.T)
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*.
or::
**Handling of pcolor() end-cases**
pcolor(C.T)
``pcolor()`` displays all columns of *C* if *X* and *Y* are not
specified, or if *X* and *Y* have one more column than *C*.
If *X* and *Y* have the same number of columns as *C* then the last
column of *C* is dropped. Similarly for the rows.
MATLAB :func:`pcolor` always discards the last row and column of ``C``,
but Matplotlib displays the last row and column if ``X`` and ``Y`` are
not specified, or if ``X`` and ``Y`` have one more row and column than
``C``.
Note: This behavior is different from MATLAB's ``pcolor()``, which
always discards the last row and column of *C*.
"""

if not self._hold:
Expand Down

0 comments on commit 89fc4e4

Please sign in to comment.