DOC: switch pylab example `mri_with_eeg.py` to OO interface + cosmetick fixes #7192

afvincent · 2016-09-28T09:12:52Z

The first commit switch the script to pyplot OO interface. The next ones perform some minor cosmetick adjustements, either in the plot layout or the doctsrings and the comments.

If the added MultipleLocator is too much, then I think that at least one should not force negative xticks as former l. 32 did: they are no negative values in the MRI data.

Additional remark: I am not a big fan of the

if 1:  # <Description>

blocks. I wonder if simple

"""
<Description>
"""

would not be as well OK visually and more semantically correct.

NelleV · 2016-09-28T15:51:28Z

examples/pylab_examples/mri_with_eeg.py

+# NB: one uses "if 1:" to break up the different regions of code visually
+fig = plt.figure("MRI_with_EEG")
+
+if 1:   # Load the data


I really dislike this syntay. Can we get rid of this? It is using python code for documentation purposes.
Having comments should be enough to break the different regions of the code visually.

I pushed a new commit (d06e572) that get rid of this idiom.

NelleV · 2016-09-28T16:07:38Z

examples/pylab_examples/mri_with_eeg.py

-    ax2.set_yticklabels(['PG3', 'PG5', 'PG7', 'PG9'])
-
-    ax2.set_xlabel('Time (s)')
+"""


I am sorry, but I still don't like this. This is also python code, meant for a specific purpose. Can you switch to comments?

Kojoley · 2016-09-28T23:19:26Z

@afvincent @NelleV maybe it is better to convert these branches to functions like def plot_xxx(ax):?

NelleV · 2016-09-29T03:31:26Z

@Kojoley that would make the example slightly harder to follow. I am pretty sure it would be quite easy to make the blocks stand out just with comments and approrpiate blank lines. We have many examples that are more complex than this one in the documentation, and are yet very readable.

afvincent · 2016-09-30T08:57:28Z

@Kojoley In this particular case, I am not sure that converting everything into functions is worth the extra overhead, as there is nothing really repeating itself among the different parts of the script.

@NelleV I switched to simple comment lines: I hope it is closer to what you had in mind.

By the way, here is what the picture looks like with this PR:

See here for the current picture: http://matplotlib.org/devdocs/examples/pylab_examples/mri_with_eeg.html. The differences are about the upper right panel (it had a useless negative x-axis part and the x-label was hidden by the lower panel).

NelleV · 2016-09-30T16:42:07Z

That looks really cool :)

QuLogic

A few minor things.

QuLogic · 2016-09-30T21:05:35Z

examples/pylab_examples/mri_with_eeg.py

+ax1 = fig.add_subplot(2, 2, 2)
+im = np.ravel(im)
+im = im[np.nonzero(im)]  # Ignore the background
+im = im / (2**15)  # Normalize


So this is how it was originally, but I'm not sure if it's right. The intensities go over 1 and a uint16 should have a maximum of 2**16, but maybe this just how MRIs are defined? I don't know, but it seems odd.

ping @matthew-brett our resident expert on MRI :)

I agree that this normalization seemed weird to me too but I did not feel comfortable changing it to (2**16 - 1) as I do not know anything about MRI. PS: anyway, currently there are no units for the MRI...

QuLogic · 2016-09-30T21:05:48Z

examples/pylab_examples/mri_with_eeg.py

+numSamples, numRows = 800, 4
+eegfile = cbook.get_sample_data('eeg.dat', asfileobj=False)
+print('Loading EEG %s' % eegfile)
+data = np.fromstring(open(eegfile, 'rb').read(), float)


Leaky open; can use np.fromfile(eegfile, float) instead

QuLogic · 2016-09-30T21:09:22Z

examples/pylab_examples/mri_with_eeg.py

+fig = plt.figure("MRI_with_EEG")
+
+# Load the MRI data (256x256 16 bit integers)
+dfile = cbook.get_sample_data('s1045.ima.gz')


This file should be closed.

get_sample_data should probably be deprecated and replaced with something with a sane interface.
In any case, python will close that file automatically at the end of the script without problems considering it is a read-only file.

afvincent · 2016-10-01T10:47:44Z

While waiting for more info on what to do about the normalization, the commit c8388f9 takes care of the leaky open that were present.

afvincent · 2016-10-01T10:56:45Z

@NelleV Looking at the files in the pylab_examples, there is another (simpler) example mri_demo.py with issues similar to mri_with_eeg.py (incomplete OO interface, not close file, room for docstring improvement, etc.). As I would not like to mess with the "[MRG + 1]" and GH "approved review" process,should I open a new dedicated PR or is it possible to add a "corrected" version of mri_demo.py to the current PR?

NelleV · 2016-10-01T15:38:35Z

Either is fine to me. I can also review it and readapt my +1 whether the patch seems satisfying or not.

I have started on the integration of sphinx-gallery yesterday, so I may have new specific requests on how to document examples (It is basically a docstring with a title, and a description - nothing fancy).

efiring · 2016-10-01T17:00:31Z

examples/pylab_examples/mri_with_eeg.py

+"""Displays a set of subplots with an MRI image, its intensity histogram and
+some EEG traces.
+
+NB: ones uses the imshow command instead of pcolor which *is much faster*.


Delete this comment line. Even mentioning pcolor here is confusing. I suspect the line dates back to the very earliest days, when imshow was first added to mpl.

You were right (see 6721163). I have removed it.

…_eeg.py

afvincent · 2016-10-02T10:11:09Z

Finally I have normalized the MRI data in mri_with_eeg.py with the np.uint16 max value (dfc9cca) and adjusted the x-ticks and x-label accordingly. If somebody more in this field says it was a mistake, I will reverse it.

Currently, it looks like

@NelleV The next two commits (db3d206 and 96ff817) fix the similar example (mri_demo.py) in a similar fashion to the MRI subplot in mri_with_eeg.py. If the docstrings of these two examples have to be enhanced, just let me know.

Edit: added a picture.

NelleV · 2016-10-02T16:04:09Z

@afvincent I am not happy with what sphinx-gallery requires (there is a small incoherence IMO between the way you write a title) so I am opening a bug on the sphinx-gallery issue tracker.
Basically, it requires a title and a description unless the title is written in rst format, ie:

=====
title
=====

If the title is written in rst format, then sphinx-gallery also displays it as the figure name in the gallery (instead of the file name as it is right now in our gallery).
If you are up to write a docstring like the following, that'd be awesome but it requires some work of understanding why the plot has been added to the gallery, etc
https://github.com/sphinx-gallery/sphinx-gallery/blob/master/examples/just_code.py

Last element, we'll have to rename examples that plot a figure into plot_something.py for sphinx-gallery to display the plot in the gallery. So you can either start doing it in this PR, or I'll do a batch rename later on.

NelleV · 2016-10-02T16:24:04Z

Never mind… It does seem to require a header and a text at all times. I don't know how I manage to compile the documentation before…

efiring · 2016-10-02T18:31:38Z

It's a little late, but I will raise the question anyway: is there any point in keeping mri_demo, given that its contents are repeated in mri_with_eeg?

NelleV · 2016-10-02T22:29:36Z

@efiring That's an excellent questions. I've going through the examples lately, and there are a lot of repeats with slight variations. Writing up a bit of documentation on these examples will probably help identifying duplicates and reduce our examples size.

tacaswell · 2016-10-03T23:01:10Z

I really wish that the old comments got folded again 😞

DOC: switch pylab example `mri_with_eeg.py` to OO interface + cosmetic fixes

tacaswell · 2016-10-03T23:05:03Z

Backported to v2.x as 17fab80

afvincent added 4 commits September 28, 2016 10:24

DOC: switch to pyplot OO interface

86bf335

DOC: cosmetick adjustements (tight_layout, labels and comments)

330a807

Replace (unfortunate) manual xticks with example of MultipleLocator

2d65280

DOC: correct statement in docstring

0c204d2

afvincent added the Documentation label Sep 28, 2016

afvincent added this to the 2.0.1 (next bug fix release) milestone Sep 28, 2016

mdboom added the status: needs review label Sep 28, 2016

NelleV reviewed Sep 28, 2016

View reviewed changes

Switch to triple quotes comment blocks as visual separators

d06e572

NelleV reviewed Sep 28, 2016

View reviewed changes

DOC: structure blocks of code with only a top real comment line

f5da34f

NelleV approved these changes Sep 30, 2016

View reviewed changes

NelleV changed the title ~~DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes~~ [MRG+1] DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes Sep 30, 2016

QuLogic reviewed Sep 30, 2016

View reviewed changes

Close files or use safer access functions

c8388f9

efiring reviewed Oct 1, 2016

View reviewed changes

afvincent added 4 commits October 2, 2016 10:59

Remove top comment 'pcolor vs imshow'

38d92b5

Normalize intensity values in [0, 1] and adjust x-ticks

dfc9cca

Add a top dosctring and perform small cleaning/fixing ops to mri_with…

db3d206

…_eeg.py

Switch mri_demo.py to OO interface

96ff817

NelleV added the MEP: MEP12 gallery and examples improvements label Oct 3, 2016

tacaswell merged commit b1bab75 into matplotlib:master Oct 3, 2016

tacaswell removed the status: needs review label Oct 3, 2016

tacaswell added a commit that referenced this pull request Oct 3, 2016

Merge pull request #7192 from afvincent/doc_pylab_examples_mri_with_eeg

17fab80

DOC: switch pylab example `mri_with_eeg.py` to OO interface + cosmetic fixes

QuLogic changed the title ~~[MRG+1] DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes~~ DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes Oct 15, 2016

QuLogic modified the milestones: 2.0.1 (next bug fix release), 2.0 (style change major release) Dec 7, 2016

Uh oh!

DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes #7192

DOC: switch pylab example mri_with_eeg.py to OO interface + cosmetick fixes #7192

Uh oh!

Conversation

afvincent commented Sep 28, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afvincent Sep 28, 2016 • 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!

Kojoley commented Sep 28, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NelleV commented Sep 29, 2016

Uh oh!

afvincent commented Sep 30, 2016

Uh oh!

NelleV commented Sep 30, 2016

Uh oh!

QuLogic 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!

afvincent commented Oct 1, 2016

Uh oh!

afvincent commented Oct 1, 2016

Uh oh!

NelleV commented Oct 1, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afvincent commented Oct 2, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NelleV commented Oct 2, 2016

Uh oh!

NelleV commented Oct 2, 2016

Uh oh!

efiring commented Oct 2, 2016

Uh oh!

NelleV commented Oct 2, 2016

Uh oh!

tacaswell commented Oct 3, 2016

Uh oh!

tacaswell commented Oct 3, 2016

Uh oh!

Uh oh!

DOC: switch pylab example `mri_with_eeg.py` to OO interface + cosmetick fixes #7192

DOC: switch pylab example `mri_with_eeg.py` to OO interface + cosmetick fixes #7192

afvincent Sep 28, 2016 •

edited

Loading

Kojoley commented Sep 28, 2016 •

edited

Loading

afvincent commented Oct 2, 2016 •

edited

Loading