matplotlib
diff --git a/‎doc/users/explain/api_interfaces.rst
Lines changed: 73 additions & 100 deletions b/‎doc/users/explain/api_interfaces.rst
Lines changed: 73 additions & 100 deletions
@@ -4,39 +4,39 @@
 Matplotlib Application Interfaces (APIs)
 ========================================
 
-Python is a flexible language allowing different design choices when
-creating an application programming interface (API).  Matplotlib
-has seen two of these over the years (or more, depending on how you
-count).  In addition, external libraries have their own interfaces to
-Matplotlib.  This means that code snippets across the internet are written
-using different interfaces, often leading to confusion.  The three major
-interfaces are:
-
-- an explicit interface that uses methods on a Figure or Axes object to
-  create other Artists, and build a visualization step by step in an
-  `imperative <https://en.wikipedia.org/wiki/Imperative_programming>`_
-  manner.
-- an implicit interface that keeps track of the last Figure and Axes
-  created, and adds Artists to the object it thinks the user wants. This
-  interface is also imperative.
-- a number of downstream libraries offer a
-  `declarative <https://en.wikipedia.org/wiki/Declarative_programming>`_
-  interface, usually where a data object has a ``plot`` method implemented
-  that will plot the data.
+Matplotlib has two major application interfaces, or styles of using the library:
+
+- An explicit "Axes" interface that uses methods on a Figure or Axes object to
+  create other Artists, and build a visualization step by step.  This has also
+  been called an "object-oriented" interface.
+- An implicit "pyplot" interface that keeps track of the last Figure and Axes
+  created, and adds Artists to the object it thinks the user wants.
+
+In addition, a number of downstream libraries (like `pandas` and `xarray`)
+offer a ``plot`` method implemented directly on their data classes so that
+users can call ``data.plot()``.
+
+The difference between these interfaces can be a bit confusing, particularly
+given snippets on the web that use one or the other, or sometimes multiple
+interfaces in the same example.  Here we attempt to point out how the "pyplot"
+and downstream interfaces relate to the explicit "Axes" interface to help users
+better navigate the library.
+
+
+Native Matplotlib interfaces
+----------------------------
 
 The explicit "Axes" interface
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The "Axes" interface is how Matplotlib is implemented, and many customizations
-and fine-tuning end up needing to be done at this level.  So even if you
-prefer the higher-level interfaces, it is very useful to understand that this
-interface exists, and how to access it.
+and fine-tuning end up being done at this level.
 
-In general, using it is as easy as instantiating an instance of a
-`~.matplotlib.figure.Figure` class (``fig`` below), using an
-`~.Figure.add_axes` method (or similar) on that object to create an
-`~.matplotlib.axes.Axes` object (``ax`` below), and then calling drawing methods
-on the Axes (``plot`` in this example):
+This interface works by instantiating an instance of a
+`~.matplotlib.figure.Figure` class (``fig`` below), using a method
+`~.Figure.subplots` method (or similar) on that object to create one or more
+`~.matplotlib.axes.Axes` objects (``ax`` below), and then calling drawing
+methods on the Axes (``plot`` in this example):
 
 .. plot::
    :include-source:
@@ -45,35 +45,21 @@ on the Axes (``plot`` in this example):
     import matplotlib.pyplot as plt
 
     fig = plt.figure()
-    ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
-    l = ax.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])
-Note that ``plot`` itself also returns an object that can be subsequently
-manipulated.
+    ax = fig.subplots()
+    ax.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])
 
 We call this an "explicit" interface because each object is explicitly
-referenced, and used to make the next object.  Keeping handles to the
-objects is very flexible, and allows us to customize the objects after
-they are created, but before they are displayed.
-
-This is also an example of an "imperative" interface because the user tells
-Matplotlib what to do each step of the way.  Of course Matplotlib has defaults
-for many things (line widths, fonts, colors, etc.), but this interface tells
-Matplotlib how to compose the visualization.  Of course this paradigm is not
-pure, in that ``fig.add_axes()`` encapsulates creating many of the objects on
-an Axes (spines, labels, ticks) and ``ax.plot()`` encapsulates creating a
-line plot.  But it is much more "imperative" than something like
-``data.plot()`` as we will see below.
+referenced, and used to make the next object.  Keeping references to the objects
+is very flexible, and allows us to customize the objects after they are created,
+but before they are displayed.
 
 
 The implicit "pyplot" interface
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The "pyplot" interface arose from Matlab, where one would just call
-``plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])`` and a figure with axes would be
-created for you.  The `~.matplotlib.pyplot` module shadows most of the
+The `~.matplotlib.pyplot` module shadows most of the
 `~.matplotlib.axes.Axes` plotting methods to give the equivalent of
-the above:
+the above, where the creation of the Figure and Axes is done for the user:
 
 .. plot::
    :include-source:
@@ -84,20 +70,10 @@ the above:
     plt.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])
 
 This can be convenient, particularly when doing interactive work or simple
-scripts - it saves at least a line of typing, and saves the user from having
-to think about figure and axes creation.  However, for more complicated scripts
-it can be at more of a disadvantage - imagine you want to loop through a number
-of variables and plot them on separate Axes, it is often more straight-forward
-to create the Axes beforehand.  It can also become ambiguous when you have
-multiple Figures or Axes which one is being acted on.  In general the
-Matplotlib project recommends using the explicit interface, at least for code
-you want to share or preserve.
-
-Whichever interface you choose, it is helpful to decode what is happening
-in the pyplot interface.  Matplotib retains a list of Figures, and each Figure
-retains a list of Axes on the figure.  The most recent figure can be retrieved
-with `~.pyplot.gcf` and the most recent Axes with `~.pyplot.gca`.  So for a more
-complicated example:
+scripts.  A reference to the current Figure can be retrieved using
+`~.pyplot.gcf` and to the current Axes by `~.pyplot.gca`.  The `~.pyplot` module
+retains a list of Figures, and each Figure retains a list of Axes on the figure
+for the user so that the following are all equivalent:
 
 .. plot::
     :include-source:
@@ -127,7 +103,7 @@ is equivalent to
     ax = plt.gca()
     ax.plot([3, 2, 1], [0, 0.5, 0.2])
 
-which in the explict interface would be:
+In the explicit interface, this would be:
 
 .. plot::
     :include-source:
@@ -139,22 +115,16 @@ which in the explict interface would be:
     axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
     axs[1].plot([3, 2, 1], [0, 0.5, 0.2])
 
-The "pyplot" interface creates and uses all the same objects, that the "Axes"
-interface does, but it implicitly keeps track of the current Figure
-(``plt.gcf()``) and Axes (``plt.gca()``) for the user, and uses those Figures
-and Axes for any "pyplot" plotting methods until another Axes or Figure is
-selected.
-
 Why be explicit?
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
-What happens if you have to backtrack, and operate on an old axes? One that
-is not referenced by ``plt.gca()``.  Of course you can do this, the simplest
-way is to call ``subplot`` again with the same arguments.  However, that quickly
-becomes inelegant.  You can also peer into the Figure object and get its list
-of Axes, however, that can be misleading (colorbars are axes too!). The best
-solution is probably to save a handle to every axes you create, but if you
-do that, why not simply create the axes at the start?
+What happens if you have to backtrack, and operate on an old axes that is not
+referenced by ``plt.gca()``?  One simple way is to call ``subplot`` again with
+the same arguments.  However, that quickly becomes inelegant.  You can also
+inspect the Figure object and get its list of Axes objects, however, that can be
+misleading (colorbars are Axes too!). The best solution is probably to save a
+handle to every Axes you create, but if you do that, why not simply create the
+all the Axes objects at the start?
 
 The first approach is to call ``plt.subplot`` again:
 
@@ -199,7 +169,7 @@ The second is to save a handle:
         plt.sca(axs[i])
         plt.xlabel('Boo')
 
-But the recommended way would be to just be explicit from the outset:
+However, the recommended way would be to be explicit from the outset:
 
 .. plot::
     :include-source:
@@ -215,18 +185,14 @@ But the recommended way would be to just be explicit from the outset:
         axs[i].set_xlabel('Boo')
 
 
-The declarative "Data" interface
---------------------------------
-
-Matplotlib does not implement this interface natively.  However, it is seen
-in `pandas`, `xarray`, and
-other third-party libraries.  These interfaces are "declarative" in that
-the data object is told to plot itself, and then it uses Matplotlib behind
-the scenes to create the visualization.
+Third-party library "Data-object" interfaces
+--------------------------------------------
 
-For illustrative purposes, a downstream library may implement a simple
-data container that has ``x`` and ``y`` data stored together, and then
-impliments a ``plot`` method as so:
+Some third party libraries have chosen to implement plotting for their data
+objects, e.g. `data.plot()`, is seen in `pandas`, `xarray`, and other
+third-party libraries.  For illustrative purposes, a downstream library may
+implement a simple data container that has ``x`` and ``y`` data stored together,
+and then implements a ``plot`` method:
 
 .. plot::
     :include-source:
@@ -258,16 +224,16 @@ impliments a ``plot`` method as so:
 
 So the library can hide all the nitty-gritty from the user, and can make a
 visualization appropriate to the data type, often with good labels, choices of
-colormaps, and other nice features.
+colormaps, and other convenient features.
 
 In the above, however, we may not have liked the title the library provided.
-Thankfully, they pass us back the axes object from the ``plot()`` method, and
-understanding the explicit Axes interface, we could manually manipulate it
-``ax.set_title('My preferred title')``.
+Thankfully, they pass us back the Axes from the ``plot()`` method, and
+understanding the explicit Axes interface, we could call:
+``ax.set_title('My preferred title')`` to customize the title.
 
-Many libraries also allow ``plot`` to take an optional *ax* argument.
-This allows us to place the visualization in an Axes of our explicit
-choice.
+Many libraries also allow their ``plot`` methods to accept an optional *ax*
+argument. This allows us to place the visualization in an Axes that we have
+placed and perhaps customized.
 
 Summary
 -------
@@ -289,9 +255,10 @@ the implicit "pyplot" interface.
     interface chosen.
 
 Similarly, the declarative interfaces provided by partner libraries use the
-objects accessible by the Axes interface, and often accept these as arguments
+objects accessible by the "Axes" interface, and often accept these as arguments
 or pass them back from methods.  It is usually essential to use the explicit
-"Axes" interface to perform any customization of the initial visualization.
+"Axes" interface to perform any customization of the default visualization, or
+to unpack the data into numpy arrays and pass directly to Matplotlib.
 
 Appendix: "Axes" interface with data structures
 -----------------------------------------------
@@ -309,4 +276,10 @@ Most `~.axes.Axes` methods allow yet another API addressing by passing a
     fig, ax = plt.subplots()
     ax.plot(x='x1', y='y1', data=data)
 
+Appendix: "pylab" interface
+---------------------------
 
+There is one further interface that is highly discouraged, and that is to
+basically do `from matplotlib.pyplot import *`.  This allows users to simply
+call `plot(x, y)`.  While convenient, this can lead to obvious problems if the
+user unwittingly names a variable the same name as a pyplot method.