DOC: new plot gallery #19703

jklymak · 2021-03-14T21:11:52Z

PR Summary

Start on a new simple plot gallery just for plot types. Heavily based on the cheatsheet @rougier, and suggested by @story645

Closes #18277

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

jklymak · 2021-03-14T23:43:53Z

This needs a bit off work to pass but here is the general idea:

https://54955-1385122-gh.circle-artifacts.com/0/doc/build/html/
https://54955-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/index.html

Click on Plot Types

story645 · 2021-03-15T00:38:55Z

My bias is to organize by mark type/base artist - marker, line2d, patch...but that might confuse folk...I'm really liking it on a first pass, but is the plan to keep all the cheatsheat code or simplify to just the data/plot?

timhoffm · 2021-03-15T00:57:17Z

Random thought: A flow-chart approach to organization could also be nice e.g. something like https://twitter.com/jamiejgriffin/status/1179758518427107328

but I don't think one can easily create that.

jklymak · 2021-03-15T01:11:59Z

So, I don't think we should workshop this to death yet.

If we think a third gallery like this is a good idea, then let us add it. We can then discuss how its styled, exactly what is plotted, how it is organized etc after, preferably as PRs on the already existent gallery.

FWIW, I think copying the styling from the cheatsheet is a good strategy to keep the overviews parallel. These all should have links added to them over the next little while, but that is pretty good First-Issue fodder if the scaffolding is in place.

timhoffm · 2021-03-15T22:05:41Z

I like the cheat-sheet style. However, the styling heavily clutters the actual command.

Can we make https://54953-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/A_basic/a_plot.html#sphx-glr-plot-types-a-basic-a-plot-py something like

import matplotlib.pyplot as plt
import numpy as np
plt.style._use_cheatsheet_style()  # style only used for the examples

X = np.linspace(0, 10, 100)
Y = 4 + 2 * np.sin(2 * X)

fig, ax = plt.subplots()
ax.plot(X, Y)

plt.show()

Then again, while the defaults are not as pretty, it would make some sense to show the plots like the users would see them without heavy styling.

jklymak · 2021-03-15T23:35:37Z

The biggest issue isn't particularly the defaults but the labels - they detract from the bare images, hence the manual axes placement. I tried to make the preamble and postamble as similar as possible so they would be easy to change...

timhoffm · 2021-03-16T07:50:28Z

We can't remove the labels using styles, can we?

Oh, maybe make them white/transparent?

Alternatively,

import matplotlib.pyplot as plt
import numpy as np

with plt.style._use_cheatsheet_style():  # style only used for the examples

    X = np.linspace(0, 10, 100)
    Y = 4 + 2 * np.sin(2 * X)

    fig, ax = plt.subplots()
    ax.plot(X, Y)

Or we don't separate figure code and displayed code by using .. plot: and .. code-block::.
At the slight annoyance that code and figure may not be in sync. But anyway the figure is only an illustration.
And I anticipate virtually no changes to the basic API which we need there. So duplication is less critical.
Or we need heavier sphinx machinery with a custom directive.

Thinking of it, 3. seems the reasonable choice.

story645 · 2021-03-16T07:58:01Z

Some version of 3, where the cheatsheet code is used to generate the figure + label for the gallery landing page, but the displayed figure + code on the actual plot page is the default styled bare minimum one? Which I think maybe is more suited to potentially growing the entry to all the configs?

jklymak · 2021-03-16T10:41:02Z

I'm not convinced we should have some complicated solution here. The point of these in my mind is to give the user an idea of what is available and the name so they have. something to google or search the docs for. I don't feel some boilerplate styling around that info on the clicked page is all that distracting from the goal. I also don't know that demonstrating the default style is a particular goal.

Certainly we can add a style to help encapsulate, but I wouldn't let perfect get in the way of good here, particularly if it means hard-to-maintain extra workarounds.

story645 · 2021-03-16T16:24:54Z

My goal w/ this was

make explicit the structure of the data each function takes
illustrate the api of each function

and my experience has been that any extra line of code ends up being a place folks can trip up, especially since lots of users wholesale copy the whole example w/o really sorting out the parts they need.

jklymak · 2021-03-16T17:07:58Z

Encapsulated the style changes in a style sheet. Happy to make private if necessary, but I'm not sure what the point of that would be.

I feel this is an improvement as-is, but if I were doing anything more to it, I'd include "see-also" blocks for each of them to act as an index to the gallery. But again, that can be done after the fact, and is easy for new contributors.

jklymak · 2021-03-16T20:07:04Z

Latest: https://55035-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/index.html

anntzer · 2021-03-16T20:25:30Z

lib/matplotlib/mpl-data/stylelib/cheatsheet_gallery.mplstyle

+axes.grid: True
+axes.axisbelow: True       # grid/ticks are below elements (e.g., lines, text)
+
+xtick.color: 555555


why do you need to set x/ytick rcs?
(also, quite a few other rcs seem to just match the default value?)

Tried to minimize it.

Can't we have fully transparent color for the ticks ? On the gallery, I can see part of them (on the left here for example.

Sure, I've made their length 0

anntzer · 2021-03-16T20:26:20Z

plot_types/A_basic/a_plot.py

+with plt.style.context('cheatsheet_gallery'):
+    fig, ax = plt.subplots()
+
+    ax.plot(X, Y, color="C1", linewidth=2.0)


Any reason for using C1 (orange)? just from the peanut gallery, C0 (blue) may perhaps look better, and it's the default too?

OK, so I tried changing the color order. Guess what - a bunch of artists do not respect the the rcParam when changed in the context manager. i.e. most of the stats ones.

WRT to orange, that is for consistency with the cheatsheet. You can argue with @rougier about what looks better ;-)

OK, the issue with the colororder not sticking was if plt.show() was inside the context manager or outside. Some artists delay assigning the color until draw time. I think we should stomp out any delayed state in the library as it almost always makes things confusing....

I think "C0" might do, it mostly depends on the matplotlib website main color.

anntzer · 2021-03-16T20:27:42Z

plot_types/A_basic/a_plot.py

+    ax.plot(X, Y, color="C1", linewidth=2.0)
+
+    ax.set_xlim(0, 8), ax.set_xticks(np.arange(1, 8))
+    ax.set_ylim(0, 8), ax.set_yticks(np.arange(1, 8))


either ax.set(xlim=(0, 8), xticks=range(1, 8), ylim=(0, 0, yticks=range(1, 8)) or split over 4 lines or at least use a semicolon (a comma happens to work too, but is rather unidiomatic)

did carriage returns.

anntzer · 2021-03-16T20:28:22Z

Some minor nits, but I like this very much.

jklymak · 2021-03-17T05:50:39Z

Blue looks fine: https://55085-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/index.html

But could go back to orange: https://55073-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/index.html

jklymak · 2021-03-17T16:50:24Z

Here is how this looks with no styling (except note I manually specified the colormap in imshow, and manually removed the ticks. Not the end of the world, and I could be convinced that simpler is better if that is the consensus:

rougier · 2021-03-17T17:50:03Z

Aspect should be set to 1 and tick labels could be bigger.

jklymak · 2021-03-17T17:56:08Z

Aspect should be set to 1 and tick labels could be bigger.

What is being proposed is linked here which is almost aspect=1 and has no labels: https://55085-1385122-gh.circle-artifacts.com/0/doc/build/html/plot_types/index.html

This snapshot above was because @story645 was suggesting no styling - so if we go that route, then we get what the default style gives us, or we add a bunch of bespoke code.

timhoffm · 2021-03-17T21:59:36Z

@jklymak I really like what you are doing here! Thanks for taking this on.

I'm undecided concerning styling. The styled version clearly looks better, but has more distracting boilerplate code.

Possibly either one is fine for a start. We can always tune later.

jklymak · 2021-03-17T22:17:36Z

Suggest we go with "looks good" and make simpler if there are complaints of confusion.

QuLogic · 2021-04-01T20:35:13Z

lib/matplotlib/mpl-data/stylelib/cheatsheet_gallery.mplstyle

@@ -0,0 +1,19 @@
+# from the Matplotlib cheatsheet as used in our gallery:


Do we want to make this public then?

We could? Whichever is easiest - I'm not sure about user examples that don't have a public stylesheet....

IMHO it's ok to make the style public. If somebody wants to use that style, that's ok.

Is "cheatsheet_gallery" a good public name? I'm not sure if "cheatsheet" is a helpful term here, in particular also because the style looks a bit like the cheatsheets but is not used there. What about "mpl_plot_gallery"?

I guess it's okay to leave public, but I'm not sure we want to say that it will follow any API guarantees. It's tied very much with out documentation style, which may change at any time.

Well, thats a good point. Happy to do a follow up to fix that...

QuLogic · 2021-04-01T20:35:57Z

plot_types/A_basic/README.rst

@@ -0,0 +1,6 @@
+.. _basic_plots:


Do we want this in the top-level (of the repo, not the docs site) instead of in doc?

The other galleries are at the top level...

plot_types/A_basic/b_scatter.py

plot_types/A_basic/c_bar.py

QuLogic · 2021-04-01T20:42:35Z

plot_types/A_basic/e_step.py

+# plot
+fig, ax = plt.subplots()
+
+ax.step(X, Y, linewidth=2.5)


Weird to have where= in the page title, but not shown.

This is just a gallery, not documentation for the functions. So the title provides useful keywords the user may be interested in, but we aren't necessarily trying to demo those kwargs.

See my proposal above for leaving parameters out of the title and optionally add them to the body.

QuLogic · 2021-04-01T20:46:30Z

plot_types/A_basic/f_pie.py

@@ -0,0 +1,31 @@
+"""
+====================
+pie(X, explode, ...)


Again, explode is not shown.

... as above...

QuLogic · 2021-04-01T20:53:48Z

plot_types/B_arrays/c_contourf.py

+fig, ax = plt.subplots()
+
+plt.contourf(X, Y, Z, levels=levs)
+plt.contour(X, Y, Z, levels=levs, colors="white", linewidths=0.5)


At first, this looked like the bug with alpha and multiple filled contours to me. I don't know if you want to use a different colour for the contours, but I'm not sure which colour matches the theme.

I'm not following this concern.... what is wrong with just adding white contours on top of the contourf?

When I first saw it, I thought it was #4419 and not on purpose.

plot_types/C_stats/a_hist.py

plot_types/C_stats/b_boxplot.py

timhoffm · 2021-04-02T20:10:23Z

plot_types/A_basic/a_plot.py

+"""
+======================
+plot([X], Y, [fmt]...)
+======================
+"""


I'd leave out the parameters in the title. They are a bit cluttered.

We should however add a bit of info inside the example, e.g.

What this plot is. In the simplest case, this is just a repetition of the title line of the function documentation. But one might also give a little more context.

Prominent link to the docs

Optional: You could add the pseudo-signature from the title if you think that is helpful.

Suggested change

"""

======================

plot([X], Y, [fmt]...)

======================

"""

"""

======

plot()

======

"""

.. code-block:: none

plot([X], Y, [fmt]...)

Plot y versus x as lines and/or markers.

Documentation: `matplotlib.axes.Axes.plot()` / `matplotlib.pyplot.plot()`

This was basically copying the cheatsheet, which I think was pretty good. If you would like to simplify it later, and add more info to the main text, I think we could do as follow-ups.

timhoffm · 2021-04-02T20:12:21Z

plot_types/A_basic/e_step.py

@@ -0,0 +1,25 @@
+"""
+=====================
+step(x, y, where=...)


We want to have stairs() as well. Two alternatives:

name this "step-like" and show both here

or make a separate entry and link between the two.

As above, we can add more, or modify as wanted after this is merged.

timhoffm · 2021-04-02T20:13:11Z

plot_types/A_basic/e_step.py

+# plot
+fig, ax = plt.subplots()
+
+ax.step(X, Y, linewidth=2.5)


See my proposal above for leaving parameters out of the title and optionally add them to the body.

timhoffm

Basically, good to go. As discussed there is still room for improvement, but that doesn't have to be part of this PR.

One last request from my side: I don't quite like the letter prefixes in the filenames. I assume that's for sorting? Can we configure that in gallery_order.py instead? Trying to sort by prefix will break if we want to change something later. We'd have to re-index, which breaks links (or needs redirects). Also the prefixes look ugly.

jklymak · 2021-04-03T16:26:40Z

I agree if there is a reasonable way to order gallery entries. I wasn't aware one existed.

timhoffm

This is a solid start. As discussed, there is still room for improvement, but let's make the changes incrementally and not let perfect be the enemy of good.

jklymak added the Documentation/new page label Mar 14, 2021

jklymak force-pushed the doc-new-gallery branch from 7caa11f to 8683873 Compare March 14, 2021 22:36

jklymak marked this pull request as ready for review March 15, 2021 01:37

jklymak added this to the v3.5.0 milestone Mar 15, 2021

jklymak force-pushed the doc-new-gallery branch 3 times, most recently from e864aac to ce3e40e Compare March 16, 2021 17:05

jklymak force-pushed the doc-new-gallery branch 6 times, most recently from 435ac6f to 20fbf36 Compare March 16, 2021 19:24

anntzer reviewed Mar 16, 2021

View reviewed changes

jklymak force-pushed the doc-new-gallery branch from 72f35a4 to a9f82c8 Compare March 16, 2021 21:19

jklymak added 7 commits April 1, 2021 11:27

New doc gallery for plot_types

d49696a

FIX: made style smaller, fixed formatting, changed cycle order

90fad32

FIX: make pcolormesh sample unevenly

42df67e

FIX: make pcolormesh sample unevenly

7b79ba4

Blues

f3a5b27

No context manager

aec15b0

Make ticks invisible

2653170

jklymak force-pushed the doc-new-gallery branch from 48a22ea to 2653170 Compare April 1, 2021 18:27

QuLogic reviewed Apr 1, 2021

View reviewed changes

jklymak force-pushed the doc-new-gallery branch from 04f54f3 to 1f49f88 Compare April 2, 2021 02:14

FIX: review suggestions

b40ed41

jklymak force-pushed the doc-new-gallery branch from 1f49f88 to b40ed41 Compare April 2, 2021 05:15

timhoffm reviewed Apr 2, 2021

View reviewed changes

DOC: rename stylefile

69327fb

timhoffm reviewed Apr 2, 2021

View reviewed changes

jklymak added 2 commits April 4, 2021 15:29

Rename and order

b3b44b1

dedupe some names

6e4c4be

jklymak force-pushed the doc-new-gallery branch from af3c8f7 to 6e4c4be Compare April 4, 2021 23:27

timhoffm approved these changes Apr 5, 2021

View reviewed changes

timhoffm merged commit 183018c into matplotlib:master Apr 5, 2021

jklymak deleted the doc-new-gallery branch April 5, 2021 21:21

pllim mentioned this pull request Apr 9, 2021

matplotlib dev: What happened to figure.dpi ? #19928

Closed

jklymak added this to Done in Chart Types Gallery May 3, 2021

		@@ -0,0 +1,19 @@
		# from the Matplotlib cheatsheet as used in our gallery:

DOC: new plot gallery #19703

DOC: new plot gallery #19703

Conversation

jklymak commented Mar 14, 2021

PR Summary

PR Checklist

jklymak commented Mar 14, 2021 • edited Loading

story645 commented Mar 15, 2021

timhoffm commented Mar 15, 2021

jklymak commented Mar 15, 2021

timhoffm commented Mar 15, 2021

jklymak commented Mar 15, 2021 • edited Loading

timhoffm commented Mar 16, 2021 • edited Loading

story645 commented Mar 16, 2021

jklymak commented Mar 16, 2021 • edited Loading

story645 commented Mar 16, 2021

jklymak commented Mar 16, 2021

jklymak commented Mar 16, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer commented Mar 16, 2021

jklymak commented Mar 17, 2021 • edited Loading

jklymak commented Mar 17, 2021

rougier commented Mar 17, 2021

jklymak commented Mar 17, 2021

timhoffm commented Mar 17, 2021

jklymak commented Mar 17, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm Apr 2, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuLogic Apr 5, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm left a comment

Choose a reason for hiding this comment

jklymak commented Apr 3, 2021

timhoffm left a comment

Choose a reason for hiding this comment

jklymak commented Mar 14, 2021 •

edited

Loading

jklymak commented Mar 15, 2021 •

edited

Loading

timhoffm commented Mar 16, 2021 •

edited

Loading

jklymak commented Mar 16, 2021 •

edited

Loading

jklymak commented Mar 17, 2021 •

edited

Loading

timhoffm Apr 2, 2021 •

edited

Loading

QuLogic Apr 5, 2021 •

edited

Loading