Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Marcel Oliver]

Tony Yu writes:
 > MEP 12 outlines the reorganization of the example gallery and
 > subsequent clean up of the examples:
 > 
 > https://github.com/matplotlib/matplotlib/wiki/MEP12

Dear all,

thanks for this initiative.  As a user who has done a fair amount of
tweaking for publication-quality graphics, but who cannot claim to
have a deep understanding of the overall architecture of matplotlib,
the gallery has long been on my radar as something in need of
improvement.  I believe that the MEP goes in the right direction, but
I could see some more radical changes as well.

Independent of ordering by topic, I see three categories of examples:

1. API documentation/illustration of basic functionality
2. HOWTO: task driven examples (how to create a certain type of graph,
   how to perform a certain useful tweak)
3. Showcases (complete projects of typically higher complexity than
   the above, code could also contain substantial sections which are
   related to data-generation, preparation, or simulation)

For the category 1 examples, the examples are really part of the API
documentation and the gallery is just a thumbnail view which makes it
easier to use eye-ball navigation through the matplotlib
documentation.  I believe this is already how it works today, but it's
not really clear from the structure of the gallery.  The category 1
examples should be clearly recognizable as views into a more
comprehensive document and also given some structure (by stating
function/methods to whose documentation they are attached, for
example, and/or by the categories outlined in the MEP).

For the category 2 examples, one needs to think in terms of the
workflow.  This will likely need to grow as new tasks and problems
come to peoples attention, so just a very superficial selection of
topics which have come across in my own work:

- How do I change the text size of the legend (or of labels, etc.)
- How do I make matplotlib use only one marker symbol in the legend
  (because each symbols refers not to a graph of something, but to a
  unique point in the graph)
- How to I plot labels and ticks on both sides (or top and bottom) of
  the coordinate system?
- How do I use (and properly label) a logarithmically scaled color
  scale?
- How can I label the axes in imshow logarithmically?
- How do I produce a QQ-plot?
- How do I produce figures such that the font size, when included into
  a TeX document, matches the font size of the text?
- How do I mask invalid regions in imshow()?  

Here, I believe it would be important that the examples are
accompanied by explanatory text.  Sometimes these tricks are obvious
from the code itself, but sometimes a more high-level explanation
would really help a lot.

For category 3, I would only take examples of exceptional quality, and
also, if possible, with explanation of the task, of solution
strategies, and possibly references to publications where the output
has appeared (on wikipedia, there seem to be a good number of high
quality plots which appear to come from matplotlib but which do not
have source code attached, so some cross-linking could be worthwhile).

The last item of concern to me is the quality of gallery pictures.
While there are excellent examples, most have more or less glaring
deficiencies.  Some issues appear to point to bugs or at least
limitations of matplotlib itself.  What is absolutely necessary is a
very critical review.  Let me just pick a more or less randomly chosen
gallery item, sankey_demo_basics.py:

- Annotations run into each other, into the flow graph, and into the
  coordinate frame
- Distance of annotations to flow graph inconsistent and often too
  small
- About half way between the label "0.6" and "0.15", the boundary of
  the flow graph appears to be double-printed with a slightly thicker
  line.
- On the third plot, the flow graph seems down-shifted and the legend
  is cramped

I could easily come up with similar lists of very many of the other
graphs (in fact, I might even volunteer to do this systematically if
there is a process on how to file and document such observations so
that the effort could not get lost).

Another effort should be to remove redundancy, the question should
always be "is this the best way to demonstrate this feature", if there
is a better way, the inferior one should be removed.  The gallery has
already reached a size where finding things is difficult, so the
overall growth should be in quality, not in quantity.

Just my 2 cents...  As I said, I would be willing to help out mainly
with reviewing.

Regards,
Marcel


-
Marcel Oliver Phone: +49-421-200-3212   
School of Engineering and Science   Fax: +49-421-200-3103
Jacobs University   m.oli...@jacobs-university.de
Campus Ring 1   oli...@member.ams.org 
28759 Bremen, Germany http://ma

Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Michael Droettboom]

On 12/11/2012 07:16 PM, Thomas Kluyver wrote:
On 11 December 2012 23:07, Tony Yu > wrote:


You suggest keeping the old examples around in some dark
corner. Is there some advantage you envision for doing this?
I'd just as soon remove them.  Note that the documentation on
the website is now versioned, so the examples that shipped
with 1.2.0 will remain live and unchanged indefinitely.  If a
user wants the older gallery it should just be there under
matplotlib.org/1.2 .


I noted that old examples could either be kept in a dark corner,
or deleted. I'm actually strongly in favor of deleting, especially
since the website is versioned (nice---I didn't know this). I was
afraid some people would be resistant to deleting, but I'm happy
to hear that you prefer it. I'll make this preference clearer in
the MEP.


I haven't had time to consider all the details of this proposal, but 
I'd like to advise against overzealous deletion. For those of us less 
familiar with matplotlib's API, a pretty standard approach is to scan 
through the examples gallery for the plot that looks most like the one 
we want, copy the code and tweak it into what we need. So a big 
gallery is very useful.
I don't think Tony was suggesting deleting many of the examples -- only 
deleting any old stuff after reorganization of what we already have.


I was suggesting deleting a few examples that really aren't useful to 
end users, and are really just unit tests (predating our unit test 
framework).  The sort of thing I was suggesting deleting are:


http://matplotlib.org/examples/api/donut_demo.html

which is really a unit test.  It's highly unlikely the user would create 
those shapes directly, and if they were we have the dolphin demo which 
makes more sense from an end user perspective.


There are also examples that are sort of developer oriented that should 
probably just be updated to be less so, for example:


http://matplotlib.org/examples/api/clippath_demo.html

It's perfectly reasonable code, but seems strange that it's clipped off 
to the corner which I think makes it less useful as an example.


Of course, that doesn't mean it should grow ad infinitum, and I'm sure 
you'll use good judgement on this. I just wanted to check you were 
aware of this use case.




Absolutely.  I think that's a major use case for the gallery.

Cheers,
Mike


Best wishes,
Thomas


--
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Paul Hobson]

On Wed, Dec 12, 2012 at 5:59 AM, Michael Droettboom  wrote:

>
> http://matplotlib.org/examples/api/clippath_demo.html
>
> It's perfectly reasonable code, but seems strange that it's clipped off to
> the corner which I think makes it less useful as an example.
>
>
If I understand correctly, you're proposing that that such an example would
be deleted after a more practical example was available to replace it?

While I'm 100% in favor of "cleaning out the closet", I used this exact
example two days ago to clip a depressed groundwater surface to a landfill
boundary :)
--
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Michael Droettboom]

On 12/12/2012 01:17 PM, Paul Hobson wrote:


On Wed, Dec 12, 2012 at 5:59 AM, Michael Droettboom > wrote:



http://matplotlib.org/examples/api/clippath_demo.html

It's perfectly reasonable code, but seems strange that it's
clipped off to the corner which I think makes it less useful as an
example.


If I understand correctly, you're proposing that that such an example 
would be deleted after a more practical example was available to 
replace it?


While I'm 100% in favor of "cleaning out the closet", I used this 
exact example two days ago to clip a depressed groundwater surface to 
a landfill boundary :)
I'm suggesting updating it to be even more useful, and to make the 
thumbnail image more illustrative of the technique that it demonstrates.


Mike
--
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Re: [matplotlib-devel] MEP12: Reorganize example gallery and clean up examples

[Marcel Oliver]

Paul Hobson writes:
 > On Wed, Dec 12, 2012 at 5:59 AM, Michael Droettboom  wrote:
 > 
 > http://matplotlib.org/examples/api/clippath_demo.html
 >
 > It's perfectly reasonable code, but seems strange that it's
 > clipped off to the corner which I think makes it less useful as
 > an example.
 > 
 > If I understand correctly, you're proposing that that such an
 > example would be deleted after a more practical example was
 > available to replace it?
 > 
 > While I'm 100% in favor of "cleaning out the closet", I used this exact
 > example two days ago to clip a depressed groundwater surface to a landfill
 > boundary :)

There is one small issue with the example: If one is using imshow on
random pixel data, there is not reason to use bilinear interpolation
(which is what imshow defaults to).  "nearest" is the only reasonable
choice.  

I know this sounds pedantic, but it irks me as a numerical analyst...

--Marcel

--
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

[matplotlib-devel] attaching images to github issues

[Darren Dale]

Hurray! https://github.com/blog/1347-issue-attachments

--
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d
___
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel