Finish scale→density_norm deprecation

docs/release-notes/3244.bugfix.md

@@ -0,0 +1 @@
+Use `density_norm` instead of of `scale` (cont. from {pr}`2844`) in {func}`~scanpy.pl.violin` and {func}`~scanpy.pl.stacked_violin` {smaller}`P Angerer`

src/scanpy/plotting/_anndata.py

@@ -21,7 +21,7 @@
 from .. import logging as logg
 from .._compat import old_positionals
 from .._settings import settings
-from .._utils import _check_use_raw, _doc_params, sanitize_anndata
+from .._utils import _check_use_raw, _doc_params, _empty, sanitize_anndata
 from . import _utils
 from ._docs import (
     doc_common_plot_args,
@@ -30,6 +30,7 @@
     doc_vboundnorm,
 )
 from ._utils import (
+    _deprecated_scale,
     check_colornorm,
     scatter_base,
     scatter_group,
@@ -47,7 +48,14 @@
     from seaborn import FacetGrid
     from seaborn.matrix import ClusterGrid
 
-    from ._utils import ColorLike, _FontSize, _FontWeight, _LegendLoc
+    from .._utils import Empty
+    from ._utils import (
+        ColorLike,
+        DensityNorm,
+        _FontSize,
+        _FontWeight,
+        _LegendLoc,
+    )
 
     # TODO: is that all?
     _Basis = Literal["pca", "tsne", "umap", "diffmap", "draw_graph_fr"]
@@ -688,7 +696,7 @@ def violin(
     jitter: float | bool = True,
     size: int = 1,
     layer: str | None = None,
-    scale: Literal["area", "count", "width"] = "width",
+    density_norm: DensityNorm = "width",
     order: Sequence[str] | None = None,
     multi_panel: bool | None = None,
     xlabel: str = "",
@@ -697,6 +705,8 @@ def violin(
     show: bool | None = None,
     save: bool | str | None = None,
     ax: Axes | None = None,
+    # deprecatd
+    scale: DensityNorm | Empty = _empty,
     **kwds,
 ) -> Axes | FacetGrid | None:
     """\
@@ -729,7 +739,7 @@ def violin(
         default adata.raw.X is plotted. If `use_raw=False` is set,
         then `adata.X` is plotted. If `layer` is set to a valid layer name,
         then the layer is plotted. `layer` takes precedence over `use_raw`.
-    scale
+    density_norm
         The method used to scale the width of each violin.
         If 'width' (the default), each violin will have the same width.
         If 'area', each violin will have the same area.
@@ -808,6 +818,8 @@ def violin(
     if isinstance(keys, str):
         keys = [keys]
     keys = list(OrderedDict.fromkeys(keys))  # remove duplicates, preserving the order
+    density_norm = _deprecated_scale(density_norm, scale, default="width")
+    del scale
 
     if isinstance(ylabel, (str, type(None))):
         ylabel = [ylabel] * (1 if groupby is None else len(keys))
@@ -855,7 +867,7 @@ def violin(
             y=y,
             data=obs_tidy,
             kind="violin",
-            density_norm=scale,
+            density_norm=density_norm,
             col=x,
             col_order=keys,
             sharey=False,
@@ -903,7 +915,7 @@ def violin(
                 data=obs_tidy,
                 order=order,
                 orient="vertical",
-                density_norm=scale,
+                density_norm=density_norm,
                 ax=ax,
                 **kwds,
             )

src/scanpy/plotting/_stacked_violin.py

@@ -12,7 +12,7 @@
 from .. import logging as logg
 from .._compat import old_positionals
 from .._settings import settings
-from .._utils import _doc_params
+from .._utils import _doc_params, _empty
 from ._baseplot_class import BasePlot, doc_common_groupby_plot_args
 from ._docs import doc_common_plot_args, doc_show_save_ax, doc_vboundnorm
 from ._utils import (
@@ -30,8 +30,9 @@
     from matplotlib.axes import Axes
     from matplotlib.colors import Normalize
 
+    from .._utils import Empty
     from ._baseplot_class import _VarNames
-    from ._utils import _AxesSubplot
+    from ._utils import DensityNorm, _AxesSubplot
 
 
 @_doc_params(common_plot_args=doc_common_plot_args)
@@ -118,7 +119,7 @@ class StackedViolin(BasePlot):
     DEFAULT_JITTER_SIZE = 1
     DEFAULT_LINE_WIDTH = 0.2
     DEFAULT_ROW_PALETTE = None
-    DEFAULT_DENSITY_NORM: Literal["area", "count", "width"] = "width"
+    DEFAULT_DENSITY_NORM: DensityNorm = "width"
     DEFAULT_PLOT_YTICKLABELS = False
     DEFAULT_YLIM = None
     DEFAULT_PLOT_X_PADDING = 0.5  # a unit is the distance between two x-axis ticks
@@ -270,13 +271,13 @@ def style(
         jitter_size: int | None = DEFAULT_JITTER_SIZE,
         linewidth: float | None = DEFAULT_LINE_WIDTH,
         row_palette: str | None = DEFAULT_ROW_PALETTE,
-        density_norm: Literal["area", "count", "width"] = DEFAULT_DENSITY_NORM,
+        density_norm: DensityNorm = DEFAULT_DENSITY_NORM,
         yticklabels: bool | None = DEFAULT_PLOT_YTICKLABELS,
         ylim: tuple[float, float] | None = DEFAULT_YLIM,
         x_padding: float | None = DEFAULT_PLOT_X_PADDING,
         y_padding: float | None = DEFAULT_PLOT_Y_PADDING,
         # deprecated
-        scale: Literal["area", "count", "width"] | None = None,
+        scale: DensityNorm | Empty = _empty,
     ) -> Self:
         r"""\
         Modifies plot visual parameters
@@ -686,7 +687,7 @@ def stacked_violin(
     stripplot: bool = StackedViolin.DEFAULT_STRIPPLOT,
     jitter: float | bool = StackedViolin.DEFAULT_JITTER,
     size: int = StackedViolin.DEFAULT_JITTER_SIZE,
-    scale: Literal["area", "count", "width"] = StackedViolin.DEFAULT_DENSITY_NORM,
+    density_norm: DensityNorm = StackedViolin.DEFAULT_DENSITY_NORM,
     yticklabels: bool | None = StackedViolin.DEFAULT_PLOT_YTICKLABELS,
     order: Sequence[str] | None = None,
     swap_axes: bool = False,
@@ -700,6 +701,8 @@ def stacked_violin(
     vmax: float | None = None,
     vcenter: float | None = None,
     norm: Normalize | None = None,
+    # deprecated
+    scale: DensityNorm | Empty = _empty,
     **kwds,
 ) -> StackedViolin | dict | None:
     """\
@@ -731,7 +734,7 @@ def stacked_violin(
         Order in which to show the categories. Note: if `dendrogram=True`
         the categories order will be given by the dendrogram and `order`
         will be ignored.
-    scale
+    density_norm
         The method used to scale the width of each violin.
         If 'width' (the default), each violin will have the same width.
         If 'area', each violin will have the same area.
@@ -835,7 +838,9 @@ def stacked_violin(
         jitter=jitter,
         jitter_size=size,
         row_palette=row_palette,
-        density_norm=kwds.get("density_norm", scale),
+        density_norm=_deprecated_scale(
+            density_norm, scale, default=StackedViolin.DEFAULT_DENSITY_NORM
+        ),
         yticklabels=yticklabels,
         linewidth=kwds.get("linewidth", StackedViolin.DEFAULT_LINE_WIDTH),
     ).legend(title=colorbar_title)

src/scanpy/plotting/_tools/__init__.py

@@ -15,7 +15,7 @@
 from ... import logging as logg
 from ..._compat import old_positionals
 from ..._settings import settings
-from ..._utils import _doc_params, sanitize_anndata, subsample
+from ..._utils import _doc_params, _empty, sanitize_anndata, subsample
 from ...get import rank_genes_groups_df
 from .._anndata import ranking
 from .._docs import (
@@ -47,6 +47,9 @@
     from matplotlib.colors import Colormap, Normalize
     from matplotlib.figure import Figure
 
+    from ..._utils import Empty
+    from .._utils import DensityNorm
+
 # ------------------------------------------------------------------------------
 # PCA
 # ------------------------------------------------------------------------------
@@ -1213,15 +1216,15 @@ def rank_genes_groups_violin(
     use_raw: bool | None = None,
     key: str | None = None,
     split: bool = True,
-    density_norm: Literal["area", "count", "width"] = "width",
+    density_norm: DensityNorm = "width",
     strip: bool = True,
     jitter: int | float | bool = True,
     size: int = 1,
     ax: Axes | None = None,
     show: bool | None = None,
     save: bool | None = None,
     # deprecated
-    scale: Literal["area", "count", "width"] | None = None,
+    scale: DensityNorm | Empty = _empty,
 ):
     """\
     Plot ranking of genes for all tested comparisons.

src/scanpy/plotting/_utils.py

@@ -3,7 +3,7 @@
 import collections.abc as cabc
 import warnings
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Callable, Literal, TypedDict, Union
+from typing import TYPE_CHECKING, Callable, Literal, TypedDict, Union, overload
 
 import matplotlib as mpl
 import numpy as np
@@ -19,7 +19,7 @@
 from .. import logging as logg
 from .._compat import old_positionals
 from .._settings import settings
-from .._utils import NeighborsView
+from .._utils import NeighborsView, _empty
 from . import palettes
 
 if TYPE_CHECKING:
@@ -32,6 +32,8 @@
     from numpy.typing import ArrayLike
     from PIL.Image import Image
 
+    from .._utils import Empty
+
     # TODO: more
     DensityNorm = Literal["area", "count", "width"]
 
@@ -1309,10 +1311,31 @@ def check_colornorm(vmin=None, vmax=None, vcenter=None, norm=None):
     return norm
 
 
+@overload
+def _deprecated_scale(
+    density_norm: DensityNorm,
+    scale: DensityNorm | Empty,
+    *,
+    default: DensityNorm,
+) -> DensityNorm: ...
+
+
+@overload
 def _deprecated_scale(
-    density_norm: DensityNorm, scale: DensityNorm | None, *, default: DensityNorm
-) -> DensityNorm:
-    if scale is None:
+    density_norm: DensityNorm | Empty,
+    scale: DensityNorm | Empty,
+    *,
+    default: DensityNorm | Empty = _empty,
+) -> DensityNorm | Empty: ...
+
+
+def _deprecated_scale(
+    density_norm: DensityNorm | Empty,
+    scale: DensityNorm | Empty,
+    *,
+    default: DensityNorm | Empty = _empty,
+) -> DensityNorm | Empty:
+    if scale is _empty:
         return density_norm
     if density_norm != default:
         msg = "can’t specify both `scale` and `density_norm`"