Apply suggestions from code review

scottshambaugh · scottshambaugh · commit f58042336c33 · 2025-01-28T10:43:29.000-07:00
Co-authored-by: Elliott Sales de Andrade &lt;quantum.analyst@gmail.com&gt;

Docstrings and typos

Code review updates

varname

varname
diff --git a/doc/users/next_whats_new/depthshading_improvement.rst b/doc/users/next_whats_new/depthshading_improvement.rst
@@ -6,16 +6,19 @@ items could lead to sudden and unexpected changes in transparency as the plot
 orientation changed.
 
 Now, the behavior has been made smooth and predictable. A new parameter
-``depthshade_minalpha`` has also been added to allow users to set the minimum
+*depthshade_minalpha* has also been added to allow users to set the minimum
 transparency level. Depth-shading is an option for Patch3DCollections and
 Path3DCollections, including 3D scatter plots.
 
-The default values for ``depthshade`` and ``depthshade_minalpha`` are now also
+The default values for *depthshade* and *depthshade_minalpha* are now also
 controlled via rcParams, with values of ``True`` and ``0.3`` respectively.
 
 A simple example:
 
 .. plot::
+    :include-source: true
+    :alt: 3D scatter plot with depth shading
+
     import matplotlib.pyplot as plt
 
     fig = plt.figure()
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -15,7 +15,7 @@
 
 from matplotlib import (
     _api, artist, cbook, colors as mcolors, lines, text as mtext,
-    path as mpath, rcParams)
+    path as mpath, _val_or_rc)
 from matplotlib.collections import (
     Collection, LineCollection, PolyCollection, PatchCollection, PathCollection)
 from matplotlib.patches import Patch
@@ -646,31 +646,36 @@ def __init__(
         :class:`~matplotlib.collections.PatchCollection`. In addition,
         keywords *zs=0* and *zdir='z'* are available.
 
-        The keyword argument *depthshade* is available to
-        indicate whether or not to shade the patches in order to
-        give the appearance of depth (default is *True*).
-        This is typically desired in scatter plots.
-
-        *depthshade_minalpha* sets the minimum alpha value applied by
-        depth-shading.
+        Parameters
+        ----------
+        zs : float or array of floats
+            The location or locations to place the patches in the collection
+            along the *zdir* axis.
+        zdir : {'x', 'y', 'z'}
+            Plane to plot patches orthogonal to.
+            All patches must have the same direction.
+            See `.get_dir_vector` for a description of the values.
+        depthshade : bool, default: :rc:`axes3d.depthshade`
+            Whether to shade the patches in order to give the appearance of
+            depth.
+        depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
+            Sets the minimum alpha value used by depth-shading.
+        axlim_clip : bool, default: False
+            Whether to hide patches with a vertex outside the axes view limits.
+        kwargs :
+            Additional keyword arguments are the same as for
+            :class:`~matplotlib.collections.PatchCollection`.
         """
-        if depthshade is None:
-            depthshade = rcParams['axes3d.depthshade']
-        if depthshade_minalpha is None:
-            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
-        self._depthshade = depthshade
-        self._depthshade_minalpha = depthshade_minalpha
+        self._depthshade = _val_or_rc(depthshade, 'axes3d.depthshade')
+        self._depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                               'axes3d.depthshade_minalpha')
         super().__init__(*args, **kwargs)
         self.set_3d_properties(zs, zdir, axlim_clip)
 
     def get_depthshade(self):
         return self._depthshade
 
-    def set_depthshade(
-        self,
-        depthshade,
-        depthshade_minalpha=None,
-    ):
+    def set_depthshade(self, depthshade, depthshade_minalpha=None):
         """
         Set whether depth shading is performed on collection members.
 
@@ -679,14 +684,12 @@ def set_depthshade(
         depthshade : bool
             Whether to shade the patches in order to give the appearance of
             depth.
-        depthshade_minalpha : float, default: None
+        depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
             Sets the minimum alpha value used by depth-shading.
-            If None, use the value from rcParams['axes3d.depthshade_minalpha'].
         """
-        if depthshade_minalpha is None:
-            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
-        self._depthshade_minalpha = depthshade_minalpha
+        self._depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                               'axes3d.depthshade_minalpha')
         self.stale = True
 
     def set_sort_zpos(self, val):
@@ -743,11 +746,7 @@ def do_3d_projection(self):
 
     def _maybe_depth_shade_and_sort_colors(self, color_array):
         color_array = (
-            _zalpha(
-                color_array,
-                self._vzs,
-                min_alpha=self._depthshade_minalpha,
-            )
+            _zalpha(color_array, self._vzs, min_alpha=self._depthshade_minalpha)
             if self._vzs is not None and self._depthshade
             else color_array
         )
@@ -776,18 +775,12 @@ def _get_data_scale(X, Y, Z):
     X, Y, Z : masked arrays
         The data to estimate the scale of.
     """
-    # Account for empty datasets. Assume that X Y and Z have the same number
-    # of elements.
-    if not np.ma.count(X):
+    # Account for empty datasets.
+    if not np.ma.count(X) or not np.ma.count(Y) or not np.ma.count(Z):
         return 0
 
     # Estimate the scale using the RSS of the ranges of the dimensions
-    # Note that we don't use np.ma.ptp() because we otherwise get a build
-    # warning about handing empty arrays.
-    ptp_x = X.max() - X.min()
-    ptp_y = Y.max() - Y.min()
-    ptp_z = Z.max() - Z.min()
-    return np.sqrt(ptp_x ** 2 + ptp_y ** 2 + ptp_z ** 2)
+    return np.sqrt(np.ma.ptp(X) ** 2 + np.ma.ptp(Y) ** 2 + np.ma.ptp(Z) ** 2)
 
 
 class Path3DCollection(PathCollection):
@@ -815,20 +808,29 @@ def __init__(
         :class:`~matplotlib.collections.PathCollection`. In addition,
         keywords *zs=0* and *zdir='z'* are available.
 
-        Also, the keyword argument *depthshade* is available to
-        indicate whether or not to shade the patches in order to
-        give the appearance of depth (default is *True*).
-        This is typically desired in scatter plots.
-
-        *depthshade_minalpha* sets the minimum alpha value applied by
-        depth-shading.
+        Parameters
+        ----------
+        zs : float or array of floats
+            The location or locations to place the paths in the collection
+            along the *zdir* axis.
+        zdir : {'x', 'y', 'z'}
+            Vector to plot paths orthogonal to.
+            All paths must have the same direction.
+            See `.get_dir_vector` for a description of the values.
+        depthshade : bool, default: :rc:`axes3d.depthshade`
+            Whether to shade the paths in order to give the appearance of
+            depth.
+        depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
+            Sets the minimum alpha value used by depth-shading.
+        axlim_clip : bool, default: False
+            Whether to hide paths with a vertex outside the axes view limits.
+        kwargs :
+            Additional keyword arguments are the same as for
+            :class:`~matplotlib.collections.PathCollection`.
         """
-        if depthshade is None:
-            depthshade = rcParams['axes3d.depthshade']
-        if depthshade_minalpha is None:
-            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
-        self._depthshade = depthshade
-        self._depthshade_minalpha = depthshade_minalpha
+        self._depthshade = _val_or_rc(depthshade, 'axes3d.depthshade')
+        self._depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                               'axes3d.depthshade_minalpha')
         self._in_draw = False
         super().__init__(*args, **kwargs)
         self.set_3d_properties(zs, zdir, axlim_clip)
@@ -854,7 +856,7 @@ def set_3d_properties(self, zs, zdir, axlim_clip=False):
             The location or locations to place the paths in the collection
             along the *zdir* axis.
         zdir : {'x', 'y', 'z'}
-            Plane to plot paths orthogonal to.
+            Vector to plot paths orthogonal to.
             All paths must have the same direction.
             See `.get_dir_vector` for a description of the values.
         axlim_clip : bool, default: False
@@ -907,11 +909,7 @@ def set_linewidth(self, lw):
     def get_depthshade(self):
         return self._depthshade
 
-    def set_depthshade(
-        self,
-        depthshade,
-        depthshade_minalpha=None,
-    ):
+    def set_depthshade(self, depthshade, depthshade_minalpha=None):
         """
         Set whether depth shading is performed on collection members.
 
@@ -920,13 +918,12 @@ def set_depthshade(
         depthshade : bool
             Whether to shade the patches in order to give the appearance of
             depth.
-        depthshade_minalpha : float
+        depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
             Sets the minimum alpha value used by depth-shading.
         """
-        if depthshade_minalpha is None:
-            depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
         self._depthshade = depthshade
-        self._depthshade_minalpha = depthshade_minalpha
+        self._depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                               'axes3d.depthshade_minalpha')
         self.stale = True
 
     def do_3d_projection(self):
@@ -989,15 +986,15 @@ def _maybe_depth_shade_and_sort_colors(self, color_array):
                 color_array,
                 self._vzs,
                 min_alpha=self._depthshade_minalpha,
-                _data_scale=self._data_scale,
+                data_scale=self._data_scale,
             )
 
         # Adjust the order of the color_array using the _z_markers_idx,
         # which has been sorted by z-depth
         if len(color_array) > 1:
             color_array = color_array[self._z_markers_idx]
 
-        return mcolors.to_rgba_array(color_array)
+        return mcolors.to_rgba_array(color_array, self._alpha)
 
     def get_facecolor(self):
         return self._maybe_depth_shade_and_sort_colors(super().get_facecolor())
@@ -1017,7 +1014,7 @@ def patch_collection_2d_to_3d(
     zdir="z",
     depthshade=None,
     axlim_clip=False,
-    *args,
+    *,
     depthshade_minalpha=None,
 ):
     """
@@ -1035,12 +1032,10 @@ def patch_collection_2d_to_3d(
     zdir : {'x', 'y', 'z'}
         The axis in which to place the patches. Default: "z".
         See `.get_dir_vector` for a description of the values.
-    depthshade : bool, default: None
+    depthshade : bool, default: :rc:`axes3d.depthshade`
         Whether to shade the patches to give a sense of depth.
-        If None, use the value from rcParams['axes3d.depthshade'].
-    depthshade_minalpha : float, default: None
+    depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
         Sets the minimum alpha value used by depth-shading.
-        If None, use the value from rcParams['axes3d.depthshade_minalpha'].
     axlim_clip : bool, default: False
         Whether to hide patches with a vertex outside the axes view limits.
     """
@@ -1049,12 +1044,9 @@ def patch_collection_2d_to_3d(
         col._offset_zordered = None
     elif isinstance(col, PatchCollection):
         col.__class__ = Patch3DCollection
-    if depthshade is None:
-        depthshade = rcParams['axes3d.depthshade']
-    if depthshade_minalpha is None:
-        depthshade_minalpha = rcParams['axes3d.depthshade_minalpha']
     col._depthshade = depthshade
-    col._depthshade_minalpha = depthshade_minalpha
+    col._depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                          'axes3d.depthshade_minalpha')
     col._in_draw = False
     col.set_3d_properties(zs, zdir, axlim_clip)
 
@@ -1395,12 +1387,7 @@ def rotate_axes(xs, ys, zs, zdir):
         return xs, ys, zs
 
 
-def _zalpha(
-    colors,
-    zs,
-    min_alpha=0.3,
-    _data_scale=None,
-):
+def _zalpha(colors, zs, min_alpha=0.3, data_scale=None):
     """Modify the alphas of the color list according to depth."""
 
     if len(colors) == 0 or len(zs) == 0:
@@ -1409,13 +1396,13 @@ def _zalpha(
     # Alpha values beyond the range 0-1 inclusive make no sense, so clip them
     min_alpha = np.clip(min_alpha, 0, 1)
 
-    if _data_scale is None or _data_scale == 0:
+    if data_scale is None or data_scale == 0:
         # Don't scale the alpha values since we have no valid data scale for reference
         sats = np.ones_like(zs)
 
     else:
         # Deeper points have an increasingly transparent appearance
-        sats = np.clip(1 - (zs - min(zs)) / _data_scale, min_alpha, 1)
+        sats = np.clip(1 - (zs - min(zs)) / data_scale, min_alpha, 1)
 
     rgba = np.broadcast_to(mcolors.to_rgba_array(colors), (len(zs), 4))
 
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -19,7 +19,7 @@
 import numpy as np
 
 import matplotlib as mpl
-from matplotlib import _api, cbook, _docstring, _preprocess_data
+from matplotlib import _api, cbook, _docstring, _preprocess_data, _val_or_rc
 import matplotlib.artist as martist
 import matplotlib.collections as mcoll
 import matplotlib.colors as mcolors
@@ -2940,15 +2940,12 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=None,
             - A 2D array in which the rows are RGB or RGBA.
 
             For more details see the *c* argument of `~.axes.Axes.scatter`.
-        depthshade : bool, default: None
+        depthshade : bool, default: :rc:`axes3d.depthshade`
             Whether to shade the scatter markers to give the appearance of
             depth. Each call to ``scatter()`` will perform its depthshading
             independently.
-            If None, use the value from rcParams['axes3d.depthshade'].
-
-        depthshade_minalpha : float, default: None
+        depthshade_minalpha : float, default: :rc:`axes3d.depthshade_minalpha`
             The lowest alpha value applied by depth-shading.
-            If None, use the value from rcParams['axes3d.depthshade_minalpha'].
         axlim_clip : bool, default: False
             Whether to hide the scatter points outside the axes view limits.
 
@@ -2976,10 +2973,9 @@ def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=None,
             )
         if kwargs.get("color") is not None:
             kwargs['color'] = color
-        if depthshade is None:
-            depthshade = mpl.rcParams['axes3d.depthshade']
-        if depthshade_minalpha is None:
-            depthshade_minalpha = mpl.rcParams['axes3d.depthshade_minalpha']
+        depthshade = _val_or_rc(depthshade, 'axes3d.depthshade')
+        depthshade_minalpha = _val_or_rc(depthshade_minalpha,
+                                         'axes3d.depthshade_minalpha')
 
         # For xs and ys, 2D scatter() will do the copying.
         if np.may_share_memory(zs_orig, zs):  # Avoid unnecessary copies.
@@ -4033,7 +4029,7 @@ def stem(self, x, y, z, *, linefmt='C0-', markerfmt='C0o', basefmt='C3-',
 
         # Determine style for stem lines.
         linestyle, linemarker, linecolor = _process_plot_format(linefmt)
-        linestyle = mpl._val_or_rc(linestyle, 'lines.linestyle')
+        linestyle = _val_or_rc(linestyle, 'lines.linestyle')
 
         # Plot everything in required order.
         baseline, = self.plot(basex, basey, basefmt, zs=bottom,
