diff --git a/galleries/users_explain/figure/api_interfaces.rst b/galleries/users_explain/figure/api_interfaces.rst
index 177e516cdaa0..981359dbee0b 100644
--- a/galleries/users_explain/figure/api_interfaces.rst
+++ b/galleries/users_explain/figure/api_interfaces.rst
@@ -121,6 +121,51 @@ In the explicit interface, this would be:
axs[0].plot([1, 2, 3], [0, 0.5, 0.2])
axs[1].plot([3, 2, 1], [0, 0.5, 0.2])
+Translating between the Axes interface and the pyplot interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You may find either interface in existing code, and unfortunately sometimes even
+mixtures. This section describes the patterns for specific operations in both
+interfaces and how to translate from one to the other.
+
+- Creating figures is the same for both interfaces: Use the respective `.pyplot`
+ functions ``plt.figure()``, ``plt.subplots()``, ``plt.subplot_mosaic()``.
+ For the Axes interface, you typically store the created Figure (and possibly
+ Axes) in variables for later use. When using the pyplot interface, these
+ values are typically not stored. Example:
+
+ - Axes: ``fig, ax = plt.subplots()``
+ - pyplot: ``plt.subplots()``
+
+- "Plotting" functions, i.e. functions that add data, are named the same and
+ have identical parameters on the Axes and in pyplot. Example:
+
+ - Axes: ``ax.plot(x, y)``
+ - pyplot: ``plt.plot(x, y)``
+
+- Functions that retrieve properties are named like the property in pyplot
+ and are prefixed with ``get_`` on the Axes. Example:
+
+ - Axes: ``label = ax.get_xlabel()``
+ - pyplot: ``label = plt.xlabel()``
+
+- Functions that set properties like the property in pyplot and are prefixed with
+ ``set_`` on the Axes. Example:
+
+ - Axes: ``ax.set_xlabel("time")``
+ - pyplot: ``plt.xlabel("time")``
+
+Here is a short summary of the examples again as a side-by-side comparison:
+
+================== ============================ ========================
+Operation Axes interface pyplot interface
+================== ============================ ========================
+Creating figures ``fig, ax = plt.subplots()`` ``plt.subplots()``
+Plotting data ``ax.plot(x, y)`` ``plt.plot(x, y)``
+Getting properties ``label = ax.get_xlabel()`` ``label = plt.xlabel()``
+Setting properties ``ax.set_xlabel("time")`` ``plt.xlabel("time")``
+================== ============================ ========================
+
+
Why be explicit?
^^^^^^^^^^^^^^^^
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy