My 2 cents: I find "tabular and linear data" quite odd and partly wrong. I don't think many of our users think in that category. This first section is on basic/fundamental/most common/simple plots. Not more not less. FWIW "Basic" is an ok description (and I cannot come up with something better). Note that plotly also uses the term "basic": https://plotly.com/python/

Releated: IMHO this should focus on the plot type (either visual or semantic), not that much on the input data - even though certain input data types suggest certain visualizations.

Releated: IMHO this should focus on the plot type (either visual or semantic), not that much on the input data

But the input data structure determines the plot type...otherwise the structured and unstructured grid plots should all be together since they're all different types of heatmaps, contour plots, and quivers and barbs are basically specialized scatters...

The reason the plots for tabular data structures get grouped together as "basic" is because those are the first plots folks tend to make/first type of data folks work w/. (ETA: Grammer of Graphics presupposes table as fundamental structure for viz data).

I don't love that plotly calls it basic either...

Eta: if we were actually gonna show just the most basic plot types, that's
a bar chart, scatter chart, line chart, and heat map. Most everything else is kind of a derivative/specialization of those. (ETA: Semiology of Graphics, Chapter 2 is the fundamental properties of graphics and how to combine them and you basically get these 4).

I don't like basic because the current section headings are a mix of the semantic properties, computational properties, data, aesthetics and subjective assessment of the "fundementalness" of the chart. I'm proposing here to focus 'em all to the data side, I can instead focus em all to the chart type side (and then I'd combine the two gridded data sections).

• Basic
• Plots of arrays and fields
• Statistics plots
• Unstructured coordinates
• 3D

I also really like the python graph galleries approach of just the pictures:

I conceptualize plot types by dimensionality, and that is the general division in the gallery.

• x versus y plots (plot, scatter, bar, pie),
• gridded x, y, Z plots (pcolor(mesh), imshow, contour, quiver (Z1, Z2)),
• unstructured x, y, z plots (tricontour, tripcolor)

where, x, y, and z are 1-D arrays (though of course we often accept higher dimensions, but just as a convenience to repeat the plot N times) and Z is a 2-D array.

There are 3-D analogs to many of those, but should be in a separate subsection as they are now.

Statistical plots are separate, and I don't think will fit in to any reasonable division, because they are generally composed of the fundamental plots but have a computational front end to them.

Of course in the above, x and y can come from any sort of structure the user likes, be it a dictionary, xarray, pandas DataFrame. But from Matplotlib's point of view we only deal with array-like (lists, or numpy arrays or things that can convert to such).

x versus y plots (plot, scatter, bar, pie),
where, x, y, and z are 1-D arrays (though of course we often accept higher

The point I'm trying to make is that this is the implementation choice mpl made for plotting data with a tabular structure - rows of 0D (discrete) items or points/observations sampled on a 1D line and each column/variable passed in separately .

The arrays are 1D, but the data can be 0D or 1D and I really don't want to ID the section by data container shape even if that's the most technically correct.

I really don't want to ID the section by data container shape even if that's the most technically correct.

Data shape is the most important constraint when plotting data - there is no point in trying to use contour on y vs x data, and if you have gridded Z vs x, y data, then you need to drop either x or y to use plot. ID-ing by data shape makes the most sense to me, but 🤷 ...

there is no point in trying to use contour on y vs x data, and if you have gridded Z vs x, y data, then you need to drop either x or y to use plot

Because data shape is being used as a proxy for the underlying topology (structure) of the data. The actual shape of the array (or that the array is the data container we're using to hold the data) is the wrong thing to focus on b/c the same $N \times M$ array can be passed into plot and here pcolormesh and it will not break:

ds = xr.open_dataset('air.mon.mean.nc')
Z = ds.sel(time='2021-01-01', lon=slice(360-126, 360-55), lat=slice(55, 20)).to_array().squeeze()
xy = ds.sel(time=slice('2020-01-01', '2022-01-01'),  lon=slice(360-95, 360-55), lat=slice(45, 35)).to_dataframe()
xyt = xy.pivot_table(columns=['lat', 'lon'], index = 'time', values='air')

fig, axd = plt.subplot_mosaic([['map_map', 'map_time', 'map_time'], ['time_map', 'time_time', 'time_time']], figsize=(15,5))

axd['map_map'].pcolormesh(Z[::-1], cmap='coolwarm')
axd['map_time'].plot(Z)

axd['time_map'].pcolormesh(xyt[::-1], cmap='coolwarm')
axd['time_time'].plot(xyt)

@story645

if you have gridded Z vs x, y data, then you need to drop either x or y to use plot.

In the above you have dropped x information from the line plots. The fact it doesn't break is a convenience we allow, not fundamental to the plotting method.

I mean this in all earnestness - I'm so confused about how this conversation is going that I can't tell if I've been too in the weeds in this stuff and so I'm poorly explaining my baseline or if I'm dropping a lot of middle or if I'm just being really unclear or what.

We all agree that plot assumes 1D continuity input and that imshow assumes 2D continuity - that's is viz 101 stuff.

In the above you have dropped x information from the line plots.

This is the point I'm trying to make - that I didn't actively drop anything but that the function implicitly dropped it due to the assumptions it makes about what an $N\times M$ array holds:

• pcolormesh assumes the $N\times M$ array is a grid of Z points
• plot assumes the $N \times M$ array is a list of lists: $[y_{1} = (y_{11}, \cdots, y_{1n}),\ \cdots \ y_{n} = (y_{n1}, \cdots, y_{nn})]$

Going one level back up, the reason I do not want to use array is b/c of term overload. Array in matplotlib is our core data object/current data model and it's too easy to conflate data container with data structure. Basically, np.Array can hold either a list of time series or an image, and neither np.Array object will throw an error if passed into either plot or pcolormesh.

The image is wrong because the structure of the data stored in that np.Array doesn't match the assumptions of the function - plot assumes it's getting a list of ys and x is unimportant , pcolormesh assumes it's getting a grid - not because of the value in np.Array.shape . I figure since we're using shape as a proxy for structure, we'd be better of being more explicit by talking about structure directly.

This is the point I'm trying to make - that I didn't actively drop anything but that the function implicitly dropped it due to the assumptions it makes about what an NxM array holds.

And my point is that if you start with x, y, and Z, and do plot(y, Z) you have actively dropped x. Your plot method no longer knows anything about x because it never saw x.

In your example, you have chosen to forget about the co-ordinates altogether, which is usually a very bad idea and leads to practical, and apparently conceptual, problems.

Your plot method no longer knows anything about x because it never saw x.

plot and imshow got the exact same input plot(Z) and imshow(Z) and it's an implementation choice which dimension plot treats as x and which it treats as distinct lines.

you have chosen to forget about the co-ordinates altogether

I passed in the exact same data to two functions. What I'd like to make clearer in this PR is what assumptions about the structure of their input these different families of functions are making such that passing in the same data will cause it to be read differently depending on the plot type.

Yes like "line plot != heatmap" but what I'm getting at here is giving a bit more guidance on what the data structure looks like for each. The reason for that is that one of the goals of this page is to orient (especially new) users to the plots matplotib can make & it's modeled on the excel "chart types here's what we recommend for what we see". The major reason for including the signatures is to highlight the assumed/implied structure of the data & I just want to push that one level up.

@story645 plot(Z) is a convenience for plot(np.arange(N), Z) and loses all co-ordindate information. (Indeed in your first line plot the x axis is flipped, and clearly does not represent degrees latitude).

At the risk of repeating myself,

• x versus y plots (plot, scatter, bar, pie),
• gridded x, y, Z plots (pcolor(mesh), imshow, contour, quiver (Z1, Z2)),
• unstructured x, y, z plots (tricontour, tripcolor)

The point is that pcolormesh(x, y, Z) retains the x and y information. plot(y, Z) drops the x co-ordinate information. That is the fundamental difference between the first category and the second two - the first category of functions only have one coordinate (y in this case), the second and third categories have two coordinates (x and y).

x versus y plots (plot, scatter, bar, pie)

pie doesn't have a y but it's also not in this section..and going back to the very beginning of this thread, this x versus y is b/c of the underlying assumption of a tabular structure (x_i, y_i) for i in table index.

• x versus y plots (plot, scatter, bar, pie),
• gridded x, y, Z plots (pcolor(mesh), imshow, contour, quiver (Z1, Z2)),
• unstructured x, y, z plots (tricontour, tripcolor)

I don't think we're far apart here. What I'm trying to get at is basically Munzner's taxonomy of data types

Switched to pairwise and moved tabular into framing. the stats plots are all distribution plots which means it's the structure, but I kept stats in the title cause I figured otherwise I'd confuse folk. Switched coordinate x,y to i,j to differentiated from data x,y.

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout v3.7.x
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -x -m1 54f16125df8338a1e3784bdd489cc0488ac6ffe9

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #26328: [DOC]: improve consistency of plot types gallery'

4. Push to a named branch:

git push YOURFORK v3.7.x:auto-backport-of-pr-26328-on-v3.7.x

5. Create a PR against branch v3.7.x, I would have named this PR:

"Backport PR #26328 on branch v3.7.x ([DOC]: improve consistency of plot types gallery)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

Thanks for the review! It was helpful not just here but in my general "wait how do I describe data?" struggles.

There's a big conflict on gallery sorting order, so I won't backport this.