Merge pull request matplotlib#25258 from dstansby/pow-norm-doc

Document PowerNorm parameters

Author: QuLogic

lib/matplotlib/colors.py

@@ -1214,8 +1214,8 @@ def __init__(self, vmin=None, vmax=None, clip=False):
             are mapped to 0 or 1, whichever is closer, and masked values are
             set to 1.  If ``False`` masked values remain masked.
 
-            Clipping silently defeats the purpose of setting the over, under,
-            and masked colors in a colormap, so it is likely to lead to
+            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``.
 
         Notes
@@ -1775,8 +1775,8 @@ def forward(values: array-like) -> array-like
         are mapped to 0 or 1, whichever is closer, and masked values are
         set to 1.  If ``False`` masked values remain masked.
 
-        Clipping silently defeats the purpose of setting the over, under,
-        and masked colors in a colormap, so it is likely to lead to
+        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``.
     """
 
@@ -1858,9 +1858,34 @@ def linear_width(self, value):
 
 
 class PowerNorm(Normalize):
-    """
+    r"""
     Linearly map a given value to the 0-1 range and then apply
     a power-law normalization over that range.
+
+    Parameters
+    ----------
+    gamma : float
+        Power law exponent.
+    vmin, vmax : float or None
+        If *vmin* and/or *vmax* is not given, they are initialized from the
+        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.
+
+        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``.
+
+    Notes
+    -----
+    The normalization formula is
+
+    .. math::
+
+        \left ( \frac{x - v_{min}}{v_{max}  - v_{min}} \right )^{\gamma}
     """
     def __init__(self, gamma, vmin=None, vmax=None, clip=False):
         super().__init__(vmin, vmax, clip)

lib/matplotlib/tests/test_colors.py

@@ -545,6 +545,9 @@ def test_LogNorm_inverse():
 
 
 def test_PowerNorm():
+    # Check an exponent of 1 gives same results as a normal linear
+    # normalization. Also implicitly checks that vmin/vmax are
+    # automatically initialized from first array input.
     a = np.array([0, 0.5, 1, 1.5], dtype=float)
     pnorm = mcolors.PowerNorm(1)
     norm = mcolors.Normalize()
@@ -561,19 +564,22 @@ def test_PowerNorm():
     # Clip = True
     a = np.array([-0.5, 0, 1, 8, 16], dtype=float)
     expected = [0, 0, 0, 1, 1]
+    # Clip = True when creating the norm
     pnorm = mcolors.PowerNorm(2, vmin=2, vmax=8, clip=True)
     assert_array_almost_equal(pnorm(a), expected)
     assert pnorm(a[0]) == expected[0]
     assert pnorm(a[-1]) == expected[-1]
-
     # Clip = True at call time
-    a = np.array([-0.5, 0, 1, 8, 16], dtype=float)
-    expected = [0, 0, 0, 1, 1]
     pnorm = mcolors.PowerNorm(2, vmin=2, vmax=8, clip=False)
     assert_array_almost_equal(pnorm(a, clip=True), expected)
     assert pnorm(a[0], clip=True) == expected[0]
     assert pnorm(a[-1], clip=True) == expected[-1]
 
+    # Check clip=True preserves masked values
+    a = np.ma.array([5, 2], mask=[True, False])
+    out = pnorm(a, clip=True)
+    assert_array_equal(out.mask, [True, False])
+
 
 def test_PowerNorm_translation_invariance():
     a = np.array([0, 1/2, 1], dtype=float)