-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
DOC: Add patches and link to transformations in quickstart guide #25911
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.
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
base: main
Are you sure you want to change the base?
Conversation
Thanks, nit you can take or leave, ping me to merge |
Done, thanks! |
Is failing flake :/ |
c60a173
to
b758c88
Compare
I think I got it now 😅 |
|
||
# %% | ||
# Patches | ||
# ======= |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems good, but is this really the best place for it within this document? Nothing nearby seems related? Maybe put near annotations?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was arbitrary, I am definitely happy to move if there are more appropriate places. I wanted to give it a menu entry as this was mentioned in the original issue (#9967)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would actually go back a step and have the quick-start guide have a section on plotting methods in general that could include patches. Probably with a link to Plot Types to make it short.
I think more detailed commentary belongs in https://matplotlib.org/devdocs/users/explain/artists/index.html.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you suggest a new section at that page, or adding a new "Concept: Patches" page? I think I can definitely see the latter - sounds like a nice addition. I'm wondering if we want to have both - a quick mention at the quickstart and a more elaborate document under the page you mentioned? I have no strong feelings either way
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think a quick mention that maybe contextualizes/signposts which artists to look at for what? Something like if we don't have the plot type you need, see Markerstyle for points, LineArtist/LineCollection for lines, patches for regions and AxesImage for images, Contour and Quiver for ... and Artist tutorial to understand all the things?.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If it was just me, I'd add to quick-start a very short section on plot-types, and include patches as a special case of lower level plot types that need add_artist
. I'd add a section in user/explain/artists on "Patches". We may want to rename user/explain/artists to make it more clear this refers to plot elements, but not sure what that name would be.
Here's a second take. It probably needs some copy editing and the patches page might need expanding, but is this organization better? |
# type you need, it may still be possible to create the visualization you want | ||
# by combining existing Artists and plot elements. | ||
# | ||
# * To manipulate and customize points, see :class:`~.markers.MarkerStyle` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is a reasonable place for this. But not a fan of this almost exhaustive list of Artists, under plot types. Maybe just link the Artists page and have a few examples? eg
Matplotlib plotting methods return a variety of :ref:`Artists <users_artists>` that allow customization of the plot elements. For example, `~.matplotlib.axes.Axes.plot` returns a :class:`~.lines.Line2D` object and `~.matplotlib.axes.Axes.scatter` returns a :class:`~.collections.LineCollection`.
and maybe include a short snippet example.
Co-authored-by: hannah <[email protected]>
Also creates a Patches under the Artists explanations.
c0659d4
to
26d4c99
Compare
Sorry it took me so long - let me know if this is too much! |
Not sure how to address the linting errors; didactically it is better to keep the imports here, and I'm not sure how to avoid the escaping error in the LaTeX symbol... Will investigate. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the flake8 import complaints, you could just add an exception here:
Line 33 in 48e2891
per-file-ignores = |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So on the one hand I'm sorry if I've managed to contradict an older review of mine, on the other I think 'explain that things return objects` might be a good scope to stick with.
# Plot types | ||
# ========== | ||
# | ||
# For an overview of the different types of plot you can create with Matplotlib, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
# For an overview of the different types of plot you can create with Matplotlib, | |
# For an overview of the different types of plots you can create with Matplotlib, |
# by combining existing :ref:`Artists <users_artists>` and customizing plot | ||
# elements. For example, `~.matplotlib.axes.Axes.plot` returns a | ||
# :class:`~.lines.Line2D` object and `~.matplotlib.axes.Axes.scatter` returns a | ||
# :class:`~.collections.LineCollection`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this would benefit from a little more context setting: this is what I'm showing you and why-otherwise there's no info here that they're not getting from the comments and code. Also honestly most folks should probably just use plot, axhline, and axhspan to achieve this:
# by combining existing :ref:`Artists <users_artists>` and customizing plot | |
# elements. For example, `~.matplotlib.axes.Axes.plot` returns a | |
# :class:`~.lines.Line2D` object and `~.matplotlib.axes.Axes.scatter` returns a | |
# :class:`~.collections.LineCollection`. | |
# For example, Matplotlib does not provide a method to automatically annotate a distribution plot. Instead, you can create this visualization by combining a the `~.matplotlib.axes.Axes.plot` method to draw the distrubtion, the `~.matplotlib.axes.Axes.axvline` method to draw the mean, and `~matplotlib.axes.Axes.axhspan` to shade the standard deviation region. |
But I like your idea of highlighting the returns objects, and maybe run w/ that the same way we do axes - basically folks almost never call the axes constructor, but modify the object all the time.
So like after
#Plot the data
x = np.array([3, 4, 9, 8, 9, 8, 0, 8, 4, 8])
fig, ax = plt.subplots()
# Computing the mean and standard deviation of the data
mean = np.mean(x)
std = np.std(x)
ln_data, = ax.plot(x, label='Data')
ln_mean = ax.axhline(mean, color='red', label='Mean')
ln_std = ax.axhspan(mean-std, mean+std, alpha=0.1, label=r'$\sigma$')
ax.legend()
give some examples of using the object methods:
ln_data.set_color('orange')
ln_mean.set_linestyle(':')
ln_std.set_hatch('oo')
and maybe end this section w/ a lead in "and for information on creating artists from their constructors, see the artist tutorial'
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This makes sense, but what I'm failing to do here is connect this example with the patches - looking at it I don't see patches (of course I know they are used internally, but I would like to expose that somehow to the reader so they understand where they come up). I'm not even sure if this is possible though, so I'm accepting the suggestions and we can maybe think of something later. I think I'm personally also failing to connect the concepts here so I may very well be missing the link :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure if this is what you mean, but ax.hspan
returns a Polygon, which is why ln_std has a set_hatch method, because hatches are 2D texture. Linestyles are 1d texture and here applied to the other line2d object ln_mean.
Which then maybe the call and response form is better:
#line2d
ln_data, = ax.plot(x, label='Data')
ln_data.set_color('orange')
ln_mean = ax.axhline(mean, color='red', label='Mean')
ln_mean.set_linestyle(':')
#polygon
ln_std = ax.axhspan(mean-std, mean+std, alpha=0.1, label=r'$\sigma$')
ln_std.set_hatch('oo')
Little less obvious why you'd do this, but maybe the return object pattern is clearer? Not trying to hold up the PR, but I think like even a comment that axhspan returns polygons (patches) may do the trick?
Co-authored-by: hannah <[email protected]>
Hi folks, I am unsure of what to do this. Feel free to close if you think this is not useful. Thanks! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the guidance on how to customize is good, I like the lead in to how to customize, and it's good for patches to get a page we can flesh out later. If nobody has any objections, I'll merge in a day or so.
@@ -111,6 +111,45 @@ | |||
# Artists are drawn to the **canvas**. Most Artists are tied to an Axes; such | |||
# an Artist cannot be shared by multiple Axes, or moved from one to another. | |||
# | |||
# .. _plot_types_quickstart: | |||
# | |||
# Plot types |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
# Plot types | |
# Custom plot types |
I think that's what this section is really about, or making custom plot types
As the author of #9967, I feel obliged to give my thoughts. Since I currently don't have the time to go into this topic, please take or leave my comments and do whatever you think is appropriate to improve the docs. I'm not quite convinced that "Quick start" is the right place for patches. They don't belong to the fundamental aspects I would teach someone to get started (but the same holds for other things in "Quick start". We may have a scope issue there. Also I suppose this doesn't close #9967. That issue was thought more technical and fundamental ("how does matplotlib work"), which cannot/should not be addressed by an addition "Quick start" ("How to use matplotlib"). |
I agree w/ you that the quick start guide could do w/ some reorg and better scoping. I also think if we did that scoping, it would be good to have "quick start: what do you need to know about artists to move past the basics?" section near the end that would give the conceptual underpinning to unlock the rest of the docs and that's kinda where this patches stuff really fits in. For artists (not quick start) I think it'd be good to have a section or page for each of the classes that map to a bertin mark/geometry/topology - so like pathcollection, Line2d/Linecollection, patch, AxesImage, etc - for folks who want to build new plot types. So this is a start for that. For #9967, I think maybe something like https://ggplot2.tidyverse.org/reference/index.html may also be a good direction to move the quickstart guide towards or the user guide landing page. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm fine with @story645 's wording suggestion or not.
Although, reading @timhoffm 's last comment I'm going to hold off merging and move this out of the 3.10 milestone. |
I agree that this does not fit well into the Quick-Start guide, and should probably be moved to Users Guide under Artitsts. |
PR summary
Closes #9967
From the current quickstart and user guide contents, I think this is what was missing to close the above issue. To address #9967 (comment), I also added a link to the quickstart in the main User guide landing page.
PR checklist