Repository navigation
[Doc]: Define: User Guide > Plotting data #31496
Description
Activity
Secondary goals (added benefit): to be defined, if any
Understand how individual plotting functions work. I think understanding that/how the functions are mostly paramterizations of the underlying artists helps folks transfer between the functions w/ relative ease. I feel like the sticking point in many of the community support type questions is lack of this type of understanding.
I think this is a little awkward, in that there is no current description of User Guide which is the same TOC level of Plot Types. I've attempted to add a short one (similar in size to the other descriptions) 2bb91bb
If we then want to go down and scope out each section that is fine though I think the goal of each section is relatively self-explanatory, and if they are not, we should consider why that is. The goal of a "plotting data" section inside the Users Guide is simply: "a narrative overview.explanation of how users can make different data visualizations using Matplotlib".
I think understanding that/how the functions are mostly paramterizations of the underlying artists helps folks transfer between the functions w/ relative ease.
That may be a bit much. I would phrase it like this
-
Common knowledge: plotting functions can be customized through keyword arguments
-
Advanced knowledge: plotting functions create Artists (and add them to the Axes). The Artists can be customized via Artist properties. kwargs forward to the artist properties so can be used to define the Artist properties on creation. Alternatively, Artist properties an be modified later through the setters.
-
is in the scope of Plottting data and several concrete examples will be used to illustrate how to configure important aspects of the plot type.
-
Is an explanation topic that should be handled seprately (and pulled out of https://matplotlib.org/stable/users/explain/quick_start.html#styling-artists be cause that's definitely knowledge beyond quick-start).
-
I think this is a little awkward, in that there is no current description of User Guide which is the same TOC level of Plot Types.
It is. But that's because "User Guide" much broader and less well defined than the other three topics. Im looking bottom-up at the scope of the page at hand, and here "Plotting data" is of interest. In which broader structure it is integreated is a discussion we can have independently/later as long as we are clear what "Plotting data" should do. xref #29124 (comment)
Thank you, @timhoffm !
After reading the discussion I have a suggestion that you folks can take or leave, but that I think would be useful.
The Matplotlib documentation is actually fairly complete, but it is mostly reflecting the library structure - which plot types do we have, what kind of stuff we can do, here are examples of different things you can try. For the User Guide specifically, I think this is the wrong approach: I think the user guide should be focused on who the reader is.
As an example of how to do that, I would cite writing User Stories or Learner Profiles. Both concepts are very related and could help us identify effectively which gaps we have in the docs. I have a feeling we will mostly find out the gaps are in the clicks, not on the content. That is, the content is there, but readers have no "happy path" to get to that content.
- Here are a few examples of User Stories we used for the NumPy website: User stories - tracking issue numpy/numpy.org#42
- Here are some Learner Profiles used by a RSE course: https://rse.shef.ac.uk/hpc-intro-tuos-citc/learner-profiles/index.html
- Here are some Learner Profiles used by the Carpentries: https://swcarpentry.github.io/r-novice-inflammation/profiles.html
Of course, there is no way we can write up all possible user/learner profiles, but we can potentially figure out a few clusters of users and how they would approach the user guide for information.
I understand the spirit of the original PR, and I wonder if merging a condensed version of it with the Plot Types gallery might work as an entry point for some user profiles?
Reacted by Tim Hoffmann and hannah@melissawm This sounds great, and I think it'd be cool to have a running thread like that. I wonder if User stories are an excellent basis for re-invigorating the Tutorials section? Certainly collecting some could be a great way to gain insight. I also think good stories can and should also inspire the Users Guide.
Nonetheless, I still think the current User Guide, as it is structured, has a significant hole in that it never shows the user how to use Matplotlib to plot data. Its less of a catch-all then it used to be (https://matplotlib.org/3.3.4/users/index.html), but I wouldn't consider it finished without this section.
Thanks @melissawm user stories / learner profiles are a great idea.
I also agree with @jklymak that there is a hole in our docs (or rather a missing place) concerning how to generate different types of plots. Details explained here - sorry for the mess with the split discussion, I'd rather keep it here.
The idea of somehow merging with the "Plot types" gallery as also reasonable. "Plot Types" are rather a hollow shell right now. They are mostly without content and just a gallery for ease of generation. They could equally or even better be the overview page generated in another way and the tiles directly linking to the respective function. The individual gallery pages do not hold content other than the link. The code how to genereate the specific visualization of the thumbnail is not relevant and rather distracting. Or putting it the other way round, we could also put the "Plotting data" content into the "Plot types" pages / Link "Plotting types" to plotting data in user guide.
Or putting it the other way round, we could also put the "Plotting data" content into the "Plot types" pages / Link "Plotting types" to plotting data in user guide.
I like the top level plot type examples as the minimal example focused on the structure of the data so think we should keep that. ETA: b/c that tends to get lost in all our other examples and I (probably in agreement w/ Jody) agree that it is really important for folks to know this.
I'd love for the rest of the page to do what the pie example is doing - visually explore/provide an example of each parameter. It's kind of visual API doc, but that's what I think folks need to know most about plotting. ETA: this format also provides proper slots for a lot of what's coming across to me as digressions in #29124
ETA#?: if we like this approach, it's (probably ?) fairly easy to split up Jody's current PR to provide a starter for the functions he's written about so this section is seeded. And I'm happy to rework into visual API format. And it's such a structured format that it's relatively easy to sprint on/tackle in an organized manner.
ETA: which yes then, inline with I think #4 #31496 (comment), the artist discussion I'm proposing goes in a restructured artist section
also yes I completely agree w/ @melissawm that we should do user stories. As a start, it'd be awesome if we could push out the docs survey (it's waiting on steering council feedback) to get a better feel for our users' expectations.
Reacted by Melissa Weber Mendonça- marked DOC: User's Guide needs section for contouring and pcolor-like plots #7116 as a duplicate of this issue
on Jul 23, 2026
Documentation Link
No response
Problem
#29124 aims to add a section "Plotting data" to the user guide. In #29124 (comment) I requested to define the purpose, structure and content of that section, because I'm afraid without that, the section will not converge to a consistent or intended state.
To not just complain about what is missing, I sketich an initial suggestion below.
Suggested improvement
In a first step, I would like to define the goal of "Plotting data". As an example to guide where I'm trying to go, I state my interpertation of the goals of "Plot types"
Goal of Plot types
Primary goal (reason for existence): Overview of the types of visualizations, The user can browse the images and see what kind of visualizations matplotlib is capable of.
Secondary goals (added benefit):
Now here is my interpretation for "Plotting data"
Goal of Plotting data
Primary goal (reason for existence): Explain how individual plotting functions are used.
Secondary goals (added benefit): to be defined, if any
Please disuss this
After we have agreed on that, we can justify/define the structure (should we group by type of data or have a plain list of plotting functions), and content guidelines. as is done in https://matplotlib.org/devdocs/devel/document.html#plot-types-guidelines