DOC: Clarify description and add examples in colors.Normalize (#26915)

stevezhang1999 · web-flow · commit 93cab2e64252 · 2023-09-28T02:43:26.000+02:00
Co-authored-by: Zihao Yang zihaoyng@gmail.com
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1215,36 +1215,55 @@ def reversed(self, name=None):
 
 class Normalize:
     """
-    A class which, when called, linearly normalizes data into the
-    ``[0.0, 1.0]`` interval.
+    A class which, when called, maps values within the interval
+    ``[vmin, vmax]`` linearly to the interval ``[0.0, 1.0]``. The mapping of
+    values outside ``[vmin, vmax]`` depends on *clip*.
+
+    Examples
+    --------
+    ::
+
+        x = [-2, -1, 0, 1, 2]
+
+        norm = mpl.colors.Normalize(vmin=-1, vmax=1, clip=False)
+        norm(x)  # [-0.5, 0., 0.5, 1., 1.5]
+        norm = mpl.colors.Normalize(vmin=-1, vmax=1, clip=True)
+        norm(x)  # [0., 0., 0.5, 1., 1.]
+
+    See Also
+    --------
+    :ref:`colormapnorms`
     """
 
     def __init__(self, vmin=None, vmax=None, clip=False):
         """
         Parameters
         ----------
         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)``.
+            Values within the range ``[vmin, vmax]`` from the input data will be
+            linearly mapped to ``[0, 1]``. If either *vmin* or *vmax* is not
+            provided, they default to the minimum and maximum values of the input,
+            respectively.
+
 
         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 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*.
+            If *clip* is ``False``, values outside ``[vmin, vmax]`` are also transformed
+            linearly, leading to results 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. This makes these values
+            If *clip* is ``True``, values outside ``[vmin, vmax]`` are set to 0 or 1,
+            depending on which boundary they're closer to. This makes these values
             indistinguishable from regular boundary values and can lead to
             misinterpretation of the data.
 
+
         Notes
         -----
-        Returns 0 if ``vmin == vmax``.
+        If ``vmin == vmax``, input data will be mapped to 0.
         """
         self._vmin = _sanitize_extrema(vmin)
         self._vmax = _sanitize_extrema(vmax)
@@ -1298,6 +1317,11 @@ def process_value(value):
 
         *value* can be a scalar or sequence.
 
+        Parameters
+        ----------
+        value
+            Data to normalize.
+
         Returns
         -------
         result : masked array
@@ -1328,8 +1352,7 @@ def process_value(value):
 
     def __call__(self, value, clip=None):
         """
-        Normalize *value* data in the ``[vmin, vmax]`` interval into the
-        ``[0.0, 1.0]`` interval and return it.
+        Normalize the data and return the normalized data.
 
         Parameters
         ----------
@@ -1375,6 +1398,15 @@ def __call__(self, value, clip=None):
         return result
 
     def inverse(self, value):
+        """
+        Maps the normalized value (i.e., index in the colormap) back to image
+        data value.
+
+        Parameters
+        ----------
+        value
+            Normalized value.
+        """
         if not self.scaled():
             raise ValueError("Not invertible until both vmin and vmax are set")
         (vmin,), _ = self.process_value(self.vmin)
@@ -1396,7 +1428,7 @@ def autoscale(self, A):
         self._changed()
 
     def autoscale_None(self, A):
-        """If vmin or vmax are not set, use the min/max of *A* to set them."""
+        """If *vmin* or *vmax* are not set, use the min/max of *A* to set them."""
         A = np.asanyarray(A)
 
         if isinstance(A, np.ma.MaskedArray):
@@ -1410,7 +1442,7 @@ def autoscale_None(self, A):
             self.vmax = A.max()
 
     def scaled(self):
-        """Return whether vmin and vmax are set."""
+        """Return whether *vmin* and *vmax* are both set."""
         return self.vmin is not None and self.vmax is not None
 
 
