Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. We also ask that you please finish addressing any review comments on this PR and wait for it to be merged (or closed) before opening a new one, as it can be a valuable learning experience to go through the review process.

You can also join us on gitter for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

We strive to be a welcoming and open project. Please follow our Code of Conduct.

I realized I forgot to run boilerplate.py to update pyplot.py, which is why some tests were failing. Ive just amended the commit and pushed the updated branch!

New docs:

Thank you for the review and suggestion. I updated that part to use f-strings.

If you want to be completely parallel you could have "flat-gouraud" and "nearest-gouraud" and then have "gouraud" be like "auto" and just do the right thing.

If you want to be completely parallel you could have "flat-gouraud" and "nearest-gouraud" and then have "gouraud" be like "auto" and just do the right thing.

Hm, while this would be structurally the same, the naming would be a bit awkward. "flat" stems from the idea that there is a constant value across the quadrilateral. "nearest" meas "take the color from the nearest grid node. Both do not rhyme with a continous shading that gouraud implies. I believe if we want more consistent naming we would need to rethink the the whole set of names "constant" and "gouraud" would be the automatic ones (and discourage "auto" in favor of "constant"). Not sure about the grid-specific ones; maybe "nodes-constant", "centered-condstant", "nodes-gouraud", "centered-gouraud".
There is also a slight semantic difference in that the gouraud variants define the colors at exactly the points and interpolate in between, whereas the constants can be interpreted either as directly meaning the whole area "the quadrilateral has as constant value" or as defining the color on a single point ("color at the quadrilateral center") and filling with constant extrapolation.

It's a bit the question whether we want to advertize/encourage automatic response to the shape constallations, or whether we prefer explicit specification that the data points are meant to be on the grid nodes or the quadrilateral centers.

Fair enough, that is awkward.

Just to review the context of the original changes: the old behaviour of flat if x and y matched the shape of Z was intolerable: it dropped a row and column of Z and shifted the data over by half a cell in x and y. Yet I'd bet the amount of data that is stored that way outnumbers data where x and y are the borders of the cell by 100:1. So matplotlib (and Matlab still) were actively dropping data and changing its spatial phase without even warning the user.

Here the problem is less, and the opposite. Occasional users who have x and y having one ore element than Z in each dimension cannot make a plot. I think we should just help those users by automatically plotting the data at the centres, and maybe emiting a warning. But I'm fine if we want to have a different named option to allow this.

Thanks for the feedback. Ive made the suggested changes and pushed everything. I noticed however that several automated tests are failing. I’m not sure if these are related to my changes or unrelated.

We still need to make a decision. On whether automatic behavior based on the grid vs data shape is desired and should be the default (in which case gouraud should cover both).

I've originally been in favor of dedicated names for all the use cases to have the analogy with 'nearest' and 'flat' and force an explicit decision on how you want to render your data. But can see the appeal of an automatic setting so that "it just works".

I suspect the majority of users do not bother passing “flat” or “nearest” to the shading parameter but just leave it to “auto”. Could we deprecate those options for shading and introduce a new parameter that distinguishes whether x,y represent “centers” or “corners” for those who really want to nail it down? So we end up with something like

• shading = “box”, “gouraud” (default “box”)
• locations = “centers”, “corners”, “auto” (default “auto”)

From the discussion so far, it seems there are two main approaches being considered:

1. Extend gouraud with automatic handling

• keep the current grid semantics
• gouraud expects X, Y and Z to have the same shape
• add support for the gouraud case where X and Y are one dimension larger than Z, by automatically converting them.
  • possibly emit a warning

2. Introduce centered-gouraud

• introduce data semantics

• gouraud expects data at the corners of quadrilaterals, requiring X, Y and Z to have the same shape

• centered-gouraud expects data at the centers of quadrilaterals, and therefore X and Y to be one dimension larger than Z

• pcolormesh now provides both discrete and continuous shading for each data semantics:

  	discrete	continuous
  data at corners	"nearest"	"gouraud"
  data at centers	"flat"	"centered-gouraud"

  Switching is defined within the same data semantics:

  • nearest $\leftrightarrow$ gouraud
  • flat $\leftrightarrow$ centered-gouraud

Another approach suggested by @rcomer:

3. Separate rendering style from data semantics

• introduce data semantics explicitly

  • add a parameter like location = 'centers' | 'corners' | 'auto'

• change shading to describe the rendering style

  • e.g. shading = 'discrete' | 'continuous'

• for example:

  Z = np.arange(nrows * ncols).reshape(nrows, ncols)
  x = np.arange(ncols)
  y = np.arange(nrows)
  
  _, ax = plt.subplots()
  
  # ax.pcolormesh(x, y, Z, shading='nearest') would be equivalent to:
  ax.pcolormesh(x, y, Z, shading='discrete', location='corners')
  
  # ax.pcolormesh(x, y, Z, shading='gouraud') would be equivalent to:
  ax.pcolormesh(x, y, Z, shading='continuous', location='corners')
  
  x = np.arange(ncols + 1)
  y = np.arange(nrows + 1)
  
  # ax.pcolormesh(x, y, Z, shading='flat') would be equivalent to:
  ax.pcolormesh(x, y, Z, shading='discrete', location='centers')
  
  # ax.pcolormesh(x, y, Z, shading='centered-gouraud') would be equivalent to:
  ax.pcolormesh(x, y, Z, shading='continuous', location='centers')

My current implementation follows approach 2.

I’m happy to adapt the PR depending on the preferred direction.

I like @rcomer's suggestion of using two keyword parameters to decouple the shading type from the location type. That said, I'm not a fan of calling the option 'box' (and I'm even less of a fan of 'discrete'/'continuous'). How about 'step' (a la the histtype option) to go alongside 'gouraud'?

If locations="auto" is the default would anybody really bother to set this to a more specific value? I doubt that. The only reason could be that you want to make sure that the data is plotted as desired, which actually means it's has a specific structure. But that could be checked on the data shapes up-front. I suspect such a parameter wound not be of practical use and we could always add that later.

Then, I'm rather tempted to aim at shading : {'constant', 'gouraud'}, default: 'constant' with additional backward compatibility of keeping 'nearest', 'flat' and making 'constant' a synonym for the current 'auto'.

In theory, we could alternatively promote 'nearest' or 'flat' to the general one if you feel that naming would be much better. It's only slightly weirder than promoting 'grouraud'.

I agree 'flat' and 'nearest' are bad terms for Gouraud.

Given that, I'd vote for 1) above - just fix the data for the user, and emit a warning if it has been fixed. I think this case will be very rare, and a user who wants to suppress the warning can supply the properly shaped data. That way the toggle is auto/gouraud. I can't imagine a case where someone would be mad that they didn't get an error here.

About your shading: {'constant', 'gouraud'} idea @timhoffm, just to clarify:

• Does this mean that constant would support both cases where X, Y have the same shape as Z, and where they are one dimension larger?
• And similarly for gouraud, would it be extended to handle both shapes?

Regarding this PR, I’m thinking of proceeding with approach 1, extending gouraud to handle the (n+1, m+1) case with a warning.

The shading simplification idea seems like a great improvement. I’d be happy to either include it in this PR if that is preferred, or work on it in another PR.

Yes, 'constant' and 'gouraud' would handle both cases and automatically decide what to do.

Regarding this PR, I’m thinking of proceeding with approach 1, extending gouraud to handle the (n+1, m+1) case with a warning.

Yes, but without the warning. If we have an automatism, that's intended behavior, so a warning is not justified (in the same way that "auto" does not warn).

Let's focus this PR on the implementation. We can have a follow-up to discuss whether and how to evolve the API.

Understood, thanks for the clarification. In the meantime I noticed two minor things in the docstrings that could maybe be improved.

I'd still suggest a warning as we are dropping data (the coords of the cell edges in favour of the midpoints). "Auto" doesn't drop anything.

I suppose the warning depends on how this automatic handling is intended to be presented, whether it is a fallback for incompatible grids one larger than C, or an extension of gouraud to support that same case (and therefore needing to update user documentation (specifically this example).

Given that it was mentioned that this case is not very common, i think it makes sense to go with a warning.

Updated the implementation to handle grids one larger than C in gouraud shading.

I would have a problem with if the only way to use centered Gouraud shading always produces a warning. A regular feature must always be usable without a warning.

In addition, this mustn’t be a „fallback for incompatible grids“. An automatism is only justified if every outcome is expected for the respective inputs, i.e. we must be able to assume that the user knows whether their data is to be on the grid nodes or centers. If we cannot, doing something with a warning is the wrong approach. Instead we then cannot do the automatism, but would have to resort to two targeted shading variants that the user would have to specify explicitly.

Understood, thanks.

Updated the implementation following the discussion: extended gouraud to support data defined at the centers without a warning.

Added and updated docs (including the two fixes in the pcolormesh API docs I pointed out above), added tests, and included a What's New entry.

New docs: