Add consistency check for PathCollection sizes and edgecolors (#28833)

BrunoWolf03 · BrunoWolf03 · commit 0aea4447b39e · 2025-06-04T11:44:54.000-03:00
This patch adds a check_consistency() method to PathCollection,
which emits a warning if the number of sizes or edgecolors does not
match the number of paths. The check is invoked during the draw()
call to ensure it happens after all data is set.

Also adds a unit test that triggers the warning for mismatched sizes.
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -1131,6 +1131,45 @@ def __init__(self, paths, sizes=None, **kwargs):
 
     def get_paths(self):
         return self._paths
+    
+    def check_consistency(self):
+        """
+        Emit warnings if the lengths of certain properties do not match
+        the number of paths.
+
+        This method checks whether the lengths of `sizes` and `edgecolors`
+        are either 1 or equal to the number of paths in the collection.
+        If not, a warning is issued.
+
+        This is useful for identifying potential bugs or silent mismatches
+        in collection properties when plotting, especially when properties
+        are expected to be applied per-path.
+
+        Notes
+        -----
+        - This method does not raise an error, only a warning.
+        - It is recommended to call this at draw-time to ensure properties
+        have been fully set.
+
+        Warnings
+        --------
+        UserWarning
+            If the number of sizes or edgecolors does not match the number
+            of paths and is not a singleton (length 1).
+
+        Examples
+        --------
+        >>> paths = [Path(...), Path(...), Path(...)]
+        >>> pc = PathCollection(paths, sizes=[10, 20])  # 3 paths, 2 sizes
+        >>> pc.check_consistency()
+        UserWarning: Number of sizes does not match number of paths.
+        """
+        n_paths = len(self.get_paths())
+        if self._sizes is not None and len(self._sizes) not in (1, n_paths):
+            warnings.warn("Number of sizes does not match number of paths.")
+        if self._edgecolors is not None and len(self._edgecolors) not in (1, n_paths):
+            warnings.warn("Number of edgecolors does not match number of paths.")
+
 
     def legend_elements(self, prop="colors", num="auto",
                         fmt=None, func=lambda x: x, **kwargs):
@@ -1271,6 +1310,21 @@ def legend_elements(self, prop="colors", num="auto",
             labels.append(l)
 
         return handles, labels
+    
+    def draw(self, renderer):
+        """
+        Draw the collection using the given renderer.
+
+        This override adds consistency checks before delegating
+        to the base implementation.
+
+        Parameters
+        ----------
+        renderer : RendererBase instance
+        The renderer to use for drawing.
+        """
+        self.check_consistency()
+        return super().draw(renderer)
 
 
 class PolyCollection(_CollectionWithSizes):
diff --git a/lib/matplotlib/tests/test_collections.py b/lib/matplotlib/tests/test_collections.py
@@ -16,10 +16,10 @@
 import matplotlib.path as mpath
 import matplotlib.transforms as mtransforms
 from matplotlib.collections import (Collection, LineCollection,
-                                    EventCollection, PolyCollection)
+                                    EventCollection, PolyCollection, PathCollection)
 from matplotlib.collections import FillBetweenPolyCollection
 from matplotlib.testing.decorators import check_figures_equal, image_comparison
-
+from matplotlib.path import Path
 
 @pytest.fixture(params=["pcolormesh", "pcolor"])
 def pcfunc(request):
@@ -1533,3 +1533,12 @@ def mock_draw_path_collection(self, gc, master_transform, paths, all_transforms,
     ax.add_collection(coll)
 
     plt.draw()
+
+def test_pathcollection_size_mismatch_warning():
+
+    paths = [Path([(0, 0), (1, 0), (0.5, 1)]) for _ in range(5)]
+    fig, ax = plt.subplots()
+    with pytest.warns(UserWarning, match="Number of sizes does not match"):
+        pc = PathCollection(paths, sizes=[10, 20])
+        ax.add_collection(pc)
+        fig.canvas.draw()  
