DOC: use OO-ish interface in image, contour, field examples #10865

phobson · 2018-03-22T20:00:14Z

PR Summary

Basic clean up of pyplot ambiguity in some rather complex examples.

PR Checklist

Code is PEP 8 compliant
Documentation is sphinx and numpydoc compliant

jklymak

I think this is great. A couple of minor quibbles that are totally take-it-or-leave-it. I've not gone through and actually checked that all the examples still render OK. Presumably you've done that...

jklymak · 2018-03-23T16:31:26Z

examples/images_contours_and_fields/contour_image.py

@@ -34,13 +34,11 @@
 norm = cm.colors.Normalize(vmax=abs(Z).max(), vmin=-abs(Z).max())
 cmap = cm.PRGn

-fig = plt.figure()
+fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(nrows=2, ncols=2)


I'm not a huge fan of this syntax, versus just fig, axs = and then setting ax = axs[row, col]. But not a show-stopper at all.

I'm with you on that. We do it both ways. And while I think consistency is good, maybe showing options are important too

I'm not huge fan of putting arrays in variable names (ax1, ax2, ax3, ax4) rather than just the type (ax[0]). The former is so much harder to change later on, so I'm not sure we should actually be promoting it. If the row/column nature is a problem, you can always do ax = ax.flatten(). My $0.02.

jklymak · 2018-03-23T16:32:08Z

examples/images_contours_and_fields/contour_label_demo.py


 # Basic contour plot
-CS = plt.contour(X, Y, Z)
+CS1 = ax1.contour(X, Y, Z)


Why not reuse CS?

My thought (which is behind e.g., fig1, ax1 as well) is that I want it to be completely clear to a totally "n00b" (to programming, python, or matplotlib) that we're starting over and working on something new.

jklymak · 2018-03-23T16:33:43Z

examples/images_contours_and_fields/interpolation_methods.py

@@ -34,6 +34,6 @@

 for ax, interp_method in zip(axes.flat, methods):
    ax.imshow(grid, interpolation=interp_method, cmap='viridis')
-    ax.set_title(interp_method)
+    ax.set_title(str(interp_method))


I don't think you need the str here. set_title does that as well...

When I looked at the rendered page, the None plot has no title, but in the current docs, is does have a title that says "None"

Oh, yes, I guess None might have a different meaning. Fair enough

jklymak · 2018-03-23T16:34:32Z

examples/images_contours_and_fields/triinterp_demo.py

@@ -29,33 +29,31 @@
 interp_cubic_min_E = mtri.CubicTriInterpolator(triang, z, kind='min_E')
 zi_cubic_min_E = interp_cubic_min_E(xi, yi)

+# Set up the figure
+fig, axes = plt.subplots(nrows=2, ncols=2)


Not a fan of axes becuase of the plural/singular ambiguity....

super minor - I'd only change if someone else has serious issues...

timhoffm · 2018-03-25T23:24:39Z

examples/images_contours_and_fields/barb_demo.py

@@ -22,24 +22,21 @@
 data = np.array(data, dtype=[('x', np.float32), ('y', np.float32),
                             ('u', np.float32), ('v', np.float32)])

+fig, axes1 = plt.subplots(nrows=2, ncols=2)


Since fig, doesn't have a number, axes1 shouldn't either.

I propose to decide on one canonical way of writing the second argument: axs vs. axes. Both seem to be used. I slightly tend to axs in the sense of multiple ax. Since Axes and Axis are both class names axes may just too easily be misinterpreted as multiple Axis or a single Axes instance.

So proposed value here is axs.

timhoffm · 2018-03-25T23:38:32Z

examples/images_contours_and_fields/specgram_demo.py

-plt.subplot(212, sharex=ax1)
-Pxx, freqs, bins, im = plt.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900)
+fig, (ax1, ax2) = plt.subplots(nrows=2)
+line, = ax1.plot(t, x)


line is not used afterwards, so it should be left out. Same with the return values on the following line.

I'm going to push back on this a bit. My gut feeling is that users -- especially new users -- are more likely to read these example than the docstrings.

So I think we should use this examples to be as explicit as possible about what each method is doing.

There are a lot of questions on SO along the lines of "how do I get an artist that's on my plot". While, there's a decent way to do that after the fact, I think it'd be nice to get users in the habbit of capturing things sooner rather than searching for them later.

I'm 100% with you that users are learning from the examples. Therefore a big 👍 for updating the examples.

My conclusion from learning by example is that the examples should be similar to real-world uses. I fear that if all the examples had line = ax.plot(x, y), you'll find a lot of people having exactly that in their scripts, even if they don't use line at all - at least that's my experience with less-experienced users.

I'm fine, if you want to keep the return values on specgram(). That's what the example is about. If so, it would be good to move the related comment from a few lines above directly to the function call. Something like:

Pxx, freqs, bins, im = ax2.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900) # returned values: # - Pxx: the periodograms # - freqs: the frequency vector # - bins: the centers of the time bins # - im: the matplotlib.image.AxesImage instance representing the data in the plot

However, since this is not about plot(), I wouldn't add the unused line.

Well said. I'm on aboard.

timhoffm · 2018-03-26T23:45:16Z

examples/images_contours_and_fields/specgram_demo.py

+fig, (ax1, ax2) = plt.subplots(nrows=2)
+ax1.plot(t, x)
+Pxx, freqs, bins, im = ax2.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900)
+# The `specgram` method returns 4 objects. They are:


Unfortunately sphinx references don't work in code comments. See the resulting file.

I'll leave it up to you, if you want to keep it anyway.

phobson · 2018-03-26T23:58:51Z

Oh yeah. I wasn't trying to sphinx format. that was just habit.

…

On Mon, Mar 26, 2018 at 4:45 PM, Tim Hoffmann ***@***.***> wrote: ***@***.**** approved this pull request. ------------------------------ In examples/images_contours_and_fields/specgram_demo.py <#10865 (comment)> : > Fs = int(1.0 / dt) # the sampling frequency -# Pxx is the segments x freqs array of instantaneous power, freqs is -# the frequency vector, bins are the centers of the time bins in which -# the power is computed, and im is the matplotlib.image.AxesImage -# instance - -ax1 = plt.subplot(211) -plt.plot(t, x) -plt.subplot(212, sharex=ax1) -Pxx, freqs, bins, im = plt.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900) +fig, (ax1, ax2) = plt.subplots(nrows=2) +ax1.plot(t, x) +Pxx, freqs, bins, im = ax2.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900) +# The `specgram` method returns 4 objects. They are: Unfortunately sphinx references don't work in code comments. See the resulting file <https://8320-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/gallery/images_contours_and_fields/specgram_demo.html#sphx-glr-gallery-images-contours-and-fields-specgram-demo-py> . I'll leave it up to you, if you want to keep it anyway. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#10865 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABHCoxDqM-kOFA2t9Fo6qxdcuguUK0SIks5tiX2fgaJpZM4S3s7h> .

DOC: use OO-ish interface in image, contour, field examples This removes change to lib/matplotlib/axes/_base.py in PR matplotlib#10865 and commit ad3a303

phobson added Documentation status: work in progress labels Mar 22, 2018

phobson force-pushed the ooify-more-examples branch from 9b63ed5 to 5c61b95 Compare March 23, 2018 15:17

phobson added status: needs review and removed status: work in progress labels Mar 23, 2018

phobson changed the title ~~(WIP) DOC: use OO-ish interface in image, contour, field examples~~ DOC: use OO-ish interface in image, contour, field examples Mar 23, 2018

jklymak approved these changes Mar 23, 2018

View reviewed changes

timhoffm reviewed Mar 25, 2018

View reviewed changes

DOC: use OO-ish interface in img/contour examples

ec5e886

phobson force-pushed the ooify-more-examples branch from fb2ea82 to ec5e886 Compare March 26, 2018 22:50

timhoffm approved these changes Mar 26, 2018

View reviewed changes

timhoffm removed the status: needs review label Mar 26, 2018

jklymak merged commit ad3a303 into matplotlib:master Mar 27, 2018

phobson deleted the ooify-more-examples branch April 30, 2018 21:25

tacaswell added this to the v3.0 milestone Jun 28, 2018

Uh oh!

DOC: use OO-ish interface in image, contour, field examples #10865

DOC: use OO-ish interface in image, contour, field examples #10865

Uh oh!

Conversation

phobson commented Mar 22, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

jklymak left a comment

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!

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!

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!

phobson commented Mar 26, 2018 via email

Uh oh!

Uh oh!

phobson commented Mar 22, 2018 •

edited

Loading