Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: re-add api example #26624

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

Closed
wants to merge 1 commit into from
Closed

DOC: re-add api example #26624

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
47 changes: 41 additions & 6 deletions doc/api/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,21 +24,56 @@ use cases.
**Axes interface** (object-based, explicit)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

API:

- `~.pyplot.subplots`: create Figure and Axes
- :mod:`~matplotlib.axes`: add data, limits, labels etc.
- `~.pyplot.subplots` or `~.pyplot.subplot_mosaic`: create Figure and Axes
- `Axes <matplotlib.axes>`: add data, limits, labels etc.
- `.Figure`: for figure-level methods

.. grid-item-card::

**pyplot interface** (function-based, implicit)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

API:

- `matplotlib.pyplot`

.. tab-set::

.. tab-item:: Axes interface

.. plot::
:include-source:
:align: center

x = np.arange(0, 4, 0.05)
y = np.sin(x*np.pi)
# Create a Figure and an Axes:
fig, ax = plt.subplots(figsize=(3,2), layout='constrained')
# Use the Axes to plot and label:
ax.plot(x, y)
ax.set_xlabel('t [s]')
ax.set_ylabel('S [V]')
ax.set_title('Sine wave')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ax.set_title('Sine wave')
ax.set_title('Sine wave (explicit)')

# Change a property of the Figure:
fig.set_facecolor('lightsteelblue')
Comment on lines +46 to +56
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
x = np.arange(0, 4, 0.05)
y = np.sin(x*np.pi)
# Create a Figure and an Axes:
fig, ax = plt.subplots(figsize=(3,2), layout='constrained')
# Use the Axes to plot and label:
ax.plot(x, y)
ax.set_xlabel('t [s]')
ax.set_ylabel('S [V]')
ax.set_title('Sine wave')
# Change a property of the Figure:
fig.set_facecolor('lightsteelblue')
# Create a Figure and an Axes:
fig, ax = plt.subplots(figsize=(3,2), layout='constrained')
# add a plot to the Axes ax
ax.plot(np.sin(np.linspace(0, 2*np.pi))
# label the Axes and x and y Axis
ax.set(xlabel= 't [s]', ylabel = 'S [V]', title ='Sine wave')
# Change the face color of the Figure:
fig.set_facecolor('lightsteelblue')

I think the original is a bit too long and also I think we want to encourage set unless they need the individual properties

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ax.set is pretty obscure as a way to shorten things.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I think we want folks to know about it. I also agree w/ Tim that this should be as short as possible, and probably in a 2 column grid rather than tabs 'cause it's that side by side that really illustrates the difference.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two column is fine, though it looks pretty cramped.

Re ax.set that seems an advanced usage to me, whereas I thought we wanted this to be straightforward? ax.,set also does not allow one to customize anything in the set methods (eg fontsize in title etc), so I'm not sure it should become canonical usage.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of scope here but I think that's a point we're trying to make in all sorts of places - that if you don't need customization we've got this nice method that will do all the things at once, but if you need customization then you've gotta use the specific methods to do so cause we try to scope our functions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a lot of value in the 1:1 mapping between the lines so am very 👎🏻 on changing to use ax.set.

At least for me clicking between the tabs and seeing what does/does not change is way easier to see the differences than trying to scan between two columns.



.. tab-item:: pyplot interface

.. plot::
:include-source:
:align: center

x = np.arange(0, 4, 0.05)
y = np.sin(x*np.pi)
# Create a Figure of a given size:
plt.figure(figsize=(3, 2), layout='constrained')
# plot on a default Axes on the Figure:
plt.plot(x, y)
plt.xlabel('t [s]')
plt.ylabel('S [V]')
plt.title('Sine wave')
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
plt.title('Sine wave')
plt.title('Sine wave (implicit)')

# set a Figure property:
plt.gcf().set_facecolor('lightsteelblue')


.. _api-index:

Expand Down