Merge pull request matplotlib#26481 from timhoffm/doc-clip

Clarify behavior of norm clipping

Author: ksunden

lib/matplotlib/colors.py

@@ -1228,13 +1228,18 @@ def __init__(self, vmin=None, vmax=None, clip=False):
             processed; i.e., ``__call__(A)`` calls ``autoscale_None(A)``.
 
         clip : bool, default: False
-            If ``True`` values falling outside the range ``[vmin, vmax]``,
-            are mapped to 0 or 1, whichever is closer, and masked values are
-            set to 1.  If ``False`` masked values remain masked.
+            Determines the behavior for mapping values outside the range
+            ``[vmin, vmax]``.
+
+            If clipping is off, values outside the range ``[vmin, vmax]`` are also
+            transformed linearly, resulting in values outside ``[0, 1]``. For a
+            standard use with colormaps, this behavior is desired because colormaps
+            mark these outside values with specific colors for *over* or *under*.
 
-            Clipping silently defeats the purpose of setting the over and
-            under colors in a colormap, so it is likely to lead to
-            surprises; therefore the default is ``clip=False``.
+            If ``True`` values falling outside the range ``[vmin, vmax]``,
+            are mapped to 0 or 1, whichever is closer. This makes these values
+            indistinguishable from regular boundary values and can lead to
+            misinterpretation of the data.
 
         Notes
         -----
@@ -1330,6 +1335,8 @@ def __call__(self, value, clip=None):
         value
             Data to normalize.
         clip : bool, optional
+            See the description of the parameter *clip* in `.Normalize`.
+
             If ``None``, defaults to ``self.clip`` (which defaults to
             ``False``).
 
@@ -1524,9 +1531,18 @@ def __init__(self, vcenter=0, halfrange=None, clip=False):
             Defaults to the largest absolute difference to *vcenter* for
             the values in the dataset.
         clip : bool, default: False
+            Determines the behavior for mapping values outside the range
+            ``[vmin, vmax]``.
+
+            If clipping is off, values outside the range ``[vmin, vmax]`` are also
+            transformed, resulting in values outside ``[0, 1]``. For a
+            standard use with colormaps, this behavior is desired because colormaps
+            mark these outside values with specific colors for *over* or *under*.
+
             If ``True`` values falling outside the range ``[vmin, vmax]``,
-            are mapped to 0 or 1, whichever is closer, and masked values are
-            set to 1.  If ``False`` masked values remain masked.
+            are mapped to 0 or 1, whichever is closer. This makes these values
+            indistinguishable from regular boundary values and can lead to
+            misinterpretation of the data.
 
         Examples
         --------
@@ -1799,13 +1815,18 @@ def forward(values: array-like) -> array-like
         processed; i.e., ``__call__(A)`` calls ``autoscale_None(A)``.
 
     clip : bool, default: False
-        If ``True`` values falling outside the range ``[vmin, vmax]``,
-        are mapped to 0 or 1, whichever is closer, and masked values are
-        set to 1.  If ``False`` masked values remain masked.
+        Determines the behavior for mapping values outside the range
+        ``[vmin, vmax]``.
+
+        If clipping is off, values outside the range ``[vmin, vmax]`` are also
+        transformed by the function, resulting in values outside ``[0, 1]``. For a
+        standard use with colormaps, this behavior is desired because colormaps
+        mark these outside values with specific colors for *over* or *under*.
 
-        Clipping silently defeats the purpose of setting the over and
-        under colors in a colormap, so it is likely to lead to
-        surprises; therefore the default is ``clip=False``.
+        If ``True`` values falling outside the range ``[vmin, vmax]``,
+        are mapped to 0 or 1, whichever is closer. This makes these values
+        indistinguishable from regular boundary values and can lead to
+        misinterpretation of the data.
     """
 
 
@@ -1899,13 +1920,18 @@ class PowerNorm(Normalize):
         minimum and maximum value, respectively, of the first input
         processed; i.e., ``__call__(A)`` calls ``autoscale_None(A)``.
     clip : bool, default: False
-        If ``True`` values falling outside the range ``[vmin, vmax]``,
-        are mapped to 0 or 1, whichever is closer, and masked values
-        remain masked.
+        Determines the behavior for mapping values outside the range
+        ``[vmin, vmax]``.
+
+        If clipping is off, values outside the range ``[vmin, vmax]`` are also
+        transformed by the power function, resulting in values outside ``[0, 1]``. For
+        a standard use with colormaps, this behavior is desired because colormaps
+        mark these outside values with specific colors for *over* or *under*.
 
-        Clipping silently defeats the purpose of setting the over and under
-        colors, so it is likely to lead to surprises; therefore the default
-        is ``clip=False``.
+        If ``True`` values falling outside the range ``[vmin, vmax]``,
+        are mapped to 0 or 1, whichever is closer. This makes these values
+        indistinguishable from regular boundary values and can lead to
+        misinterpretation of the data.
 
     Notes
     -----