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

[Marcel O. <m.o...@ja...>]

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.o...@ja...
Campus Ring 1                                   ol...@me... 
28759 Bremen, Germany         http://math.jacobs-university.de/oliver
---------------------------------------------------------------------