Improve docstring of Axes.pcolor #11317

timhoffm · 2018-05-26T18:59:12Z

PR Summary

As part of #10148: Docstring update for Axes.pcolor.

anntzer · 2018-05-26T19:42:44Z

lib/matplotlib/axes/_axes.py


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


does numpydoc not support lower-level headings?

Masked arrays ~~~~~~~~~~~~~

(dunno)

Nope. If you try this, numpydoc simply swallows the lower-level headings.

I think structuring with bold paragraphs is the best one can do.

anntzer · 2018-05-26T19:43:11Z

lib/matplotlib/axes/_axes.py

+        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.
+


as there's no heading there I'm not sure this anchor is correct (see above re lower headings)

This does work the id is attached to the paragraph:

<p id="axes-pcolor-grid-orientation"><strong>Grid orientation</strong></p>

anntzer · 2018-05-26T19:44:54Z

lib/matplotlib/axes/_axes.py

@@ -5268,62 +5268,69 @@ def _pcolorargs(funcname, *args, allmatch=False):
    def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
               vmax=None, **kwargs):
        """
-        Create a pseudocolor plot of a 2-D array.
+        Create a pseudocolor plot of a 2-D array using quadrilaterals.


Not convinced "using quadrilaterals" really helps here (and yes I know how pcolor is implemented).

I think we need some sort of addition to differentiate it from imshow and matshow. A better wording is welcome.

Its explained below - I think the differentiation is useful. OTOH to me the main difference w/ imshow is that the lateral and vertical spacing can be non-even (as opposed to distorted grids.)

Alternatively I could do "Create a pseudocolor plot with a non-regular rectangular grid." Is that more helpful?

I like that wording!

jklymak · 2018-05-27T18:01:09Z

lib/matplotlib/axes/_axes.py

@@ -5268,62 +5268,69 @@ def _pcolorargs(funcname, *args, allmatch=False):
    def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
               vmax=None, **kwargs):
        """
-        Create a pseudocolor plot of a 2-D array.
+        Create a pseudocolor plot of a 2-D array using quadrilaterals.


Its explained below - I think the differentiation is useful. OTOH to me the main difference w/ imshow is that the lateral and vertical spacing can be non-even (as opposed to distorted grids.)

jklymak · 2018-05-27T18:01:32Z

lib/matplotlib/axes/_axes.py

-        pcolor can be very slow for large arrays; consider
-        using the similar but much faster
-        :func:`~matplotlib.pyplot.pcolormesh` instead.
+        *X* and *Y* can be used to specify the corners of the quadrilatals.


Typo: quadrilaterals

jklymak · 2018-05-27T18:03:58Z

lib/matplotlib/axes/_axes.py

@@ -5338,39 +5345,46 @@ def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
        Other Parameters
        ----------------
        antialiaseds : bool, optional, default: False


wow, is this really the parameter name? Thats terrible!

Yes, we have this pluralization scheme in some places, see e.g. LineCollection: colors, edgecolors, antialiaseds, ... Not really great and IMO not really necessary to pluralize, but it's the way it is now.

jklymak · 2018-05-27T18:09:28Z

lib/matplotlib/axes/_axes.py

-        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).
+        The grid orientation follows the MATLAB convention: an array *C* with


I don't particularly like this note, and find it confusing as written. Can we improve it while here?

""" An array *C* with shape (nrows, columns) is plotted with the column number *X* and the row number as *Y*. """

suffices in my opinion. I don't understand why anyone would think that y[j] doesn't correspond to C[j, i] so the only ambiguous orientation is if C is organized as C[j, i] or C[i, j].

Significantly shortend to:

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.

Removed also the whole example stuff as it's more confusing than helpflul.

jklymak · 2018-05-27T18:21:17Z

lib/matplotlib/axes/_axes.py

-        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``.
+        **Difference to MATLAB pcolor()**


again:

Handling of pcolor end-cases

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.

jklymak · 2018-05-27T20:34:26Z

lib/matplotlib/axes/_axes.py

@@ -5268,62 +5268,69 @@ def _pcolorargs(funcname, *args, allmatch=False):
    def pcolor(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
               vmax=None, **kwargs):
        """
-        Create a pseudocolor plot of a 2-D array.
+        Create a pseudocolor plot of a 2-D array using quadrilaterals.


I like that wording!

timhoffm · 2018-05-28T21:49:07Z

@meeseeksdev backport to v2.2.x

jklymak · 2018-05-28T21:49:58Z

...we aren't backporting *.py files...

The only changes to be backported to 2.2.N-doc are changes to doc, examples, 
or tutorials. Any changes to lib or src should not be backported to this branch.

timhoffm · 2018-05-28T21:54:12Z

That does only hold for the branch v2.2-doc. I'm quite strongly for backporting pure docstring updates to 2.2.x. It will be around for quite some time and definitively deserves the docstring improvements.

We can discuss if I should backport this to v2.2.x or v2.2-doc. But I really want to backport this somehow.

jklymak · 2018-05-28T21:59:35Z

I'm not at all the final say on these things, so please feel free to argue up the chain... But I think 2.2.x is just for regressions and other important bug fixes. I don't think we want to also be merging in a bunch of doc string changes. I agree they are hugely helpful, but folks have managed to muddle through with the old docs so I personally don't think its critical that they be backported. But I don't actually do the backporting...

…n-v2.2.x Backport PR #11317 on branch v2.2.x

jklymak · 2018-05-29T13:45:24Z

lib/matplotlib/axes/_axes.py

-            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


I can't run the tests wth this line: SyntaxError: invalid escape sequence \

Strange. This is the recommended way:

Use a backslash escaped space to work around that: thisis\ *one*\ word.

The docs itself look fine:
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.pcolor.html?highlight=pcolor#matplotlib.axes.Axes.pcolor

Why is the test inspecting the docstring at all? Do we have some doctests somewhere that need to be run?

Its a syntax error for me on one machine, but not on another. Grrrr. Maybe I have a messed up install on the other machine (which I can't access right now, of course).

Appending a r""" docstring """ makes it work again on the other machine.

@timhoffm The recommended way you cite is for Sphinx, while @jklymak's error is coming from Python. The backslash escape for Sphinx is on the text that it sees, which is either a reST file or a docstring (extracted to a reST file by auto-something), but in order to place the backslash in the docstring, you also need to escape it for Python. So you need to double-escape or make it a raw string.

As to why @jklymak only sees it on one machine, maybe it's tests.py vs pytest? The former turns these deprecation warnings into errors. Also, the warnings are only raised on Python 3.6+.

Ahh. Thanks @QuLogic : python tests.py does not work and gives the Syntax Error. py.test works. Thats what I get for just hitting ^R for the last time I ran the tests - obviously on one machine I mentally upgraded to py.test and the other I haven't 😉...

timhoffm force-pushed the doc-axes-pcolor branch from f7c5599 to 9a8fde5 Compare May 26, 2018 19:37

anntzer reviewed May 26, 2018

View reviewed changes

jklymak approved these changes May 27, 2018

View reviewed changes

timhoffm force-pushed the doc-axes-pcolor branch from 9a8fde5 to 246cd9c Compare May 27, 2018 18:47

jklymak approved these changes May 27, 2018

View reviewed changes

Improve docstring of Axes.pcolor

1104393

timhoffm force-pushed the doc-axes-pcolor branch from 246cd9c to 1104393 Compare May 27, 2018 22:13

anntzer added this to the v3.0 milestone May 28, 2018

anntzer merged commit 22bc89c into matplotlib:master May 28, 2018

timhoffm deleted the doc-axes-pcolor branch May 28, 2018 21:23

lumberbot-app bot pushed a commit that referenced this pull request May 28, 2018

Backport PR #11317: Improve docstring of Axes.pcolor

e0895b2

lumberbot-app bot mentioned this pull request May 28, 2018

Backport PR #11317 on branch v2.2.x #11327

Merged

jklymak added a commit that referenced this pull request May 29, 2018

Merge pull request #11327 from matplotlib/auto-backport-of-pr-11317-o…

89fc4e4

…n-v2.2.x Backport PR #11317 on branch v2.2.x

QuLogic modified the milestones: v3.0, v2.2.3 May 29, 2018

jklymak reviewed May 29, 2018

View reviewed changes

timhoffm mentioned this pull request May 30, 2018

Improve docstring of Axes.pcolormesh #11344

Merged

Uh oh!

Improve docstring of Axes.pcolor #11317

Improve docstring of Axes.pcolor #11317

Uh oh!

Conversation

timhoffm commented May 26, 2018

PR Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm May 27, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm May 27, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm commented May 28, 2018

Uh oh!

jklymak commented May 28, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timhoffm commented May 28, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak commented May 28, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuLogic May 29, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

timhoffm May 27, 2018 •

edited

Loading

timhoffm May 27, 2018 •

edited

Loading

jklymak commented May 28, 2018 •

edited

Loading

timhoffm commented May 28, 2018 •

edited

Loading

QuLogic May 29, 2018 •

edited

Loading