ENH: Support mixed shading in pcolor/pcolormesh by AbiramiR-27 · Pull Request #31918 · matplotlib/matplotlib

github-actions

Description

Allow specifying shading style individually for x and y axes as a 2-tuple.
Resolve 'auto' individually per axis.
Added validation for 2-tuple configurations in rcsetup.
Added comprehensive tests covering correct resolution, shape checks, and error cases.

PR summary

Currently, pcolor and pcolormesh support coordinate grids that are either the same size as the 2D data array (shading='nearest'), or one larger than the array (shading='flat'). However, it was not possible to plot a dataset where the coordinate grid is defined by cell centers along one dimension and cell edges along the other.

This PR introduces support for mixed shading styles by allowing a 2-tuple of shadings (e.g. shading=('nearest', 'flat') or shading=('flat', 'nearest')). It also updates shading='auto' to automatically resolve to a mixed shading configuration depending on the coordinate and data dimensions.

Implementation Details:

Validation: Updated validation in rcsetup.py via validate_pcolor_shading to support a 2-tuple of values, ensuring that 'gouraud' cannot be mixed with other shading styles (which raises a ValueError).
Grid Generation: In _axes.py: _pcolorargs, the shading parameter is unpacked/normalized. If either dimension has 'nearest' shading, its coordinate centers are interpolated to cell edges, while the other dimension is left as-is if it is already 'flat'. This results in a final rectangular grid of cell corners which is then rendered with 'flat' shading.
Compatibility: Standard single-string shadings ('flat', 'nearest', 'gouraud', 'auto') continue to work exactly as before.

Example usage:

python
import matplotlib.pyplot as plt
import numpy as np

Data shape: 4 rows, 5 columns

Z = np.random.rand(4, 5)

X matches columns (5 centers -> nearest)

X = np.arange(5)

Y matches cell edges (5 edges for 4 rows -> flat)

Y = np.arange(5)
fig, ax = plt.subplots()

Automatically resolves to shading=('nearest', 'flat')

pcm = ax.pcolormesh(X, Y, Z, shading='auto')
plt.show()

closes #31607

AI Disclosure

Antigravity was used to assist in writing parts of the implementation logic and formatting unit tests.

PR checklist

[✓]"closes [ENH]: Mixed shading in pcolor/pcolormesh #31607" is in the body of the PR description to link the related issue
[✓]new and changed code is tested
[]Plotting related features are demonstrated in an example
[]New Features and API Changes are noted with a directive and release note
[✓]Documentation complies with general and docstring guidelines