MEP12

Table of Contents

• Status
• Branches and Pull requests
• Abstract
• Detailed description
• Implementation
  • Gallery sections
  • Clean up guidelines
    • Additional suggestions
• Backward compatibility
• Alternatives
  • Alternate gallery sections
  • Tags

.. author:: Tony S Yu

Status

Discussion

Branches and Pull requests

None so far.

Abstract

Reorganizing the matplotlib plot gallery would greatly simplify navigation of the gallery. In addition, examples should be cleaned-up and simplified for clarity.

Detailed description

The matplotlib gallery was recently set up to split examples up into sections. As discussed in that PR [1], the current example sections (api, pylab_examples) aren't terribly useful to users: New sections in the gallery would help users find relevant examples.

These sections would also guide a cleanup of the examples: Initially, all the current examples would remain and be listed under their current directories. Over time, these examples could be cleaned up and moved into one of the new sections.

This process allows users to easily identify examples that need to be cleaned up; i.e. anything in the api and pylab_examples directories.

Implementation

1. Create new gallery sections.
2. Clean up examples and move them to the new gallery sections (over the course of many PRs and with the help of many users/developers).

Gallery sections

The naming of sections is critical and will guide the clean-up effort. The following is a list of proposed sections:

• plotting (minimal code to use core plotting functions---i.e., all first-class plotting functions in the pyplot namespace)
• text and annotation
• spines, subplots, and axes
• specialty (e.g., sankey, radar, tornado)
• showcase (plots with tweaks to make them publication-quality)
• reference (e.g., 'show_colormaps.py', 'artist_demo.py', 'annotation_demo2.py', 'anatomy of a matplotlib plot' mentioned in PR #524 [2]).
• separate sections for toolboxes (already exists)

These names are certainly up for debate. In addition, the plotting section may be too general, as discussed below (see Alternate gallery sections).

Clean up guidelines

The current examples in the api and pylab_examples sections of the gallery would remain in those directories until they are cleaned up. After clean-up, they would be moved to one of the new gallery sections described above. "Clean-up" should involve:

• PEP8 clean-ups
• Commented-out code should be removed.
• Add introductory sentence or paragraph in the main docstring.
• Replace uses of pylab interface with pyplot (+ numpy, etc.).
• Each example should focus on a specific feature (excluding showcase examples, which will show more "polished" plots). Tweaking unrelated to that feature should be removed.

Use of pylab should be demonstrated/discussed on a dedicated help page instead of the gallery examples.

Additional suggestions

• Rename the example to clarify it's purpose. For example, the most basic demo of imshow might be imshow_demo.py, and one demonstrating different interpolation settings would be imshow_demo_interpolation.py (not imshow_demo2.py).

• Split up examples that try to do too much.

• Delete examples that don't show anything new.

• Some examples exercise esoteric features for unit testing. These tweaks should be moved out of the gallery to an example in the unit directory located in the root directory of the package.

• Use consistent imports. In particular:

  import numpy as np

  import matplotlib.pyplot as plt

  Avoid importing specific functions from these modules (e.g. from numpy import sin)

• Use plt.subplots (note trailing "s") in preference over plt.subplot.

• Remove shebang line, e.g.:

  #!/usr/bin/env python

Note: When moving an existing example, you should search for references to that example. For example, the API documentation for axes.py and pyplot.py may use these examples to generate plots. Use your favorite search tool (e.g., grep, ack, grin, pss) to search the matplotlib package.

Backward compatibility

The website for each Matplotlib version is readily accessible, so users who want to refer to old examples can still do so.

Alternatives

Alternate gallery sections

Instead of a section named plotting, it might be useful to use a finer-grained classification; for example:

• lines, bars, and markers
• shapes and collections
• images, contours, and fields
• pie and polar charts

See the following mailing list thread for more discussion on gallery organization: [3]. Also, here are a couple of alternate plot galleries for comparison/inspiration: [4], [5], [6].

Tags

Tagging examples will also help users search the example gallery. Although tags would be a big win for users with specific goals, the plot gallery will remain the entry point to these examples, and sections could really help users navigate the gallery. Thus, tags are complementary to this reorganization.

[1]	http://github.com/matplotlib/matplotlib/pull/714

[2]	http://github.com/matplotlib/matplotlib/issues/524

[3]	http://matplotlib.1069221.n5.nabble.com/Matplotlib-gallery-td762.html#a33379091

[4]	http://www.loria.fr/~rougier/teaching/matplotlib/

[5]	http://www.gigawiz.com/aagraphs.html

[6]	http://www.loria.fr/~rougier/coding/gallery/