matplotlib · jklymak · Feb 3, 2022 · Dec 7, 2021 · Jan 25, 2022
diff --git a/doc/conf.py b/doc/conf.py
@@ -162,6 +162,7 @@ def _check_dependencies():
     'python': ('https://docs.python.org/3/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
     'tornado': ('https://www.tornadoweb.org/en/stable/', None),
+    'xarray': ('https://xarray.pydata.org/en/stable/', None),
 }
 
 

diff --git a/doc/users/explain/api_interfaces.rst b/doc/users/explain/api_interfaces.rst
@@ -0,0 +1,288 @@
+.. _api_interfaces:
+
+========================================
+Matplotlib Application Interfaces (APIs)
+========================================
+
+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()``.
+
+.. _xarray: https://xarray.pydata.org
+
+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 being done at this level.
+
+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:
+   :align: center
+
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    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 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 `~.matplotlib.pyplot` module shadows most of the
+`~.matplotlib.axes.Axes` plotting methods to give the equivalent of
+the above, where the creation of the Figure and Axes is done for the user:
+
+.. plot::
+   :include-source:
+   :align: center
+
+    import matplotlib.pyplot as plt
+
+    plt.plot([1, 2, 3, 4], [0, 0.5, 1, 0.2])
+
+This can be convenient, particularly when doing interactive work or simple
+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:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    plt.subplot(1, 2, 1)
+    plt.plot([1, 2, 3], [0, 0.5, 0.2])
+
+    plt.subplot(1, 2, 2)
+    plt.plot([3, 2, 1], [0, 0.5, 0.2])
+
+is equivalent to:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    plt.subplot(1, 2, 1)
+    ax = plt.gca()
+    ax.plot([1, 2, 3], [0, 0.5, 0.2])
+
+    plt.subplot(1, 2, 2)
+    ax = plt.gca()
+    ax.plot([3, 2, 1], [0, 0.5, 0.2])
+
+In the explicit interface, this would be:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    fig, axs = plt.subplots(1, 2)
+    axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
+    axs[1].plot([3, 2, 1], [0, 0.5, 0.2])
+
+Why be explicit?
+^^^^^^^^^^^^^^^^
+
+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:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    plt.subplot(1, 2, 1)
+    plt.plot([1, 2, 3], [0, 0.5, 0.2])
+
+    plt.subplot(1, 2, 2)
+    plt.plot([3, 2, 1], [0, 0.5, 0.2])
+
+    plt.suptitle('Implicit Interface: re-call subplot')
+
+    for i in range(1, 3):
+        plt.subplot(1, 2, i)
+        plt.xlabel('Boo')
+
+The second is to save a handle:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    axs = []
+    ax = plt.subplot(1, 2, 1)
+    axs += [ax]
+    plt.plot([1, 2, 3], [0, 0.5, 0.2])
+
+    ax = plt.subplot(1, 2, 2)
+    axs += [ax]
+    plt.plot([3, 2, 1], [0, 0.5, 0.2])
+
+    plt.suptitle('Implicit Interface: save handles')
+
+    for i in range(2):
+        plt.sca(axs[i])
+        plt.xlabel('Boo')
+
+However, the recommended way would be to be explicit from the outset:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    fig, axs = plt.subplots(1, 2)
+    axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
+    axs[1].plot([3, 2, 1], [0, 0.5, 0.2])
+    fig.suptitle('Explicit Interface')
+    for i in range(2):
+        axs[i].set_xlabel('Boo')
+
+
+Third-party library "Data-object" interfaces
+--------------------------------------------
+
+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:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    # supplied by downstream library:
+    class DataContainer:
+
+        def __init__(self, x, y):
+            """
+            Proper docstring here!
+            """
+            self._x = x
+            self._y = y
+
+        def plot(self, ax=None, **kwargs):
+            if ax is None:
+                ax = plt.gca()
+            ax.plot(self._x, self._y, **kwargs)
+            ax.set_title('Plotted from DataClass!')
+            return ax
+
+
+    # what the user usually calls:
+    data = DataContainer([0, 1, 2, 3], [0, 0.2, 0.5, 0.3])
+    data.plot()
+
+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 convenient features.
+
+In the above, however, we may not have liked the title the library provided.
+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 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
+-------
+
+Overall, it is useful to understand the explicit "Axes" interface since it is
+the most flexible and underlies the other interfaces.  A user can usually
+figure out how to drop down to the explicit interface and operate on the
+underlying objects.  While the explicit interface can be a bit more verbose
+to setup, complicated plots will often end up simpler than trying to use
+the implicit "pyplot" interface.
+
+.. note::
+
+    It is sometimes confusing to people that we import ``pyplot`` for both
+    interfaces.  Currently, the ``pyplot`` module implements the "pyplot"
+    interface, but it also provides top-level Figure and Axes creation
+    methods, and ultimately spins up the graphical user interface, if one
+    is being used.  So ``pyplot`` is still needed regardless of the
+    interface chosen.
+
+Similarly, the declarative interfaces provided by partner libraries use the
+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 default visualization, or
+to unpack the data into NumPy arrays and pass directly to Matplotlib.
+
+Appendix: "Axes" interface with data structures
+-----------------------------------------------
+
+Most `~.axes.Axes` methods allow yet another API addressing by passing a
+*data* object to the method and specifying the arguments as strings:
+
+.. plot::
+    :include-source:
+    :align: center
+
+    import matplotlib.pyplot as plt
+
+    data = {'xdat': [0, 1, 2, 3], 'ydat': [0, 0.2, 0.4, 0.1]}
+    fig, ax = plt.subplots(figsize=(2, 2))
+    ax.plot('xdat', 'ydat', 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.
diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst
@@ -8,6 +8,7 @@ Explanations
 .. toctree::
     :maxdepth: 2
 
+    api_interfaces.rst
     backends.rst
     interactive.rst
     fonts.rst