Skip to content

DOC: Add section on translating between Axes and pyplot interface #29272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 11, 2024
+45 −0
Merged

DOC: Add section on translating between Axes and pyplot interface #29272

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions galleries/users_explain/figure/api_interfaces.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?
^^^^^^^^^^^^^^^^

Expand Down
Loading