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://math.jacobs-university.de/oliver --------------------------------------------------------------------- ------------------------------------------------------------------------------ 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
