From 874ce151d466de03d74da39be925be739483e678 Mon Sep 17 00:00:00 2001
From: "Philipp A." <flying-sheep@web.de>
Date: Fri, 20 Sep 2024 16:13:49 +0200
Subject: [PATCH] Deprecate defunct `order` parameter in `stacked_violin`
 (#3252)

---
 src/scanpy/plotting/_dotplot.py        |  2 ++
 src/scanpy/plotting/_matrixplot.py     |  4 +++-
 src/scanpy/plotting/_stacked_violin.py | 15 ++++++++++-----
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/src/scanpy/plotting/_dotplot.py b/src/scanpy/plotting/_dotplot.py
index 48f7dbca44..a895a269ce 100644
--- a/src/scanpy/plotting/_dotplot.py
+++ b/src/scanpy/plotting/_dotplot.py
@@ -881,6 +881,7 @@ def dotplot(
     use_raw: bool | None = None,
     log: bool = False,
     num_categories: int = 7,
+    categories_order: Sequence[str] | None = None,
     expression_cutoff: float = 0.0,
     mean_only_expressed: bool = False,
     cmap: str = "Reds",
@@ -1024,6 +1025,7 @@ def dotplot(
         use_raw=use_raw,
         log=log,
         num_categories=num_categories,
+        categories_order=categories_order,
         expression_cutoff=expression_cutoff,
         mean_only_expressed=mean_only_expressed,
         standard_scale=standard_scale,
diff --git a/src/scanpy/plotting/_matrixplot.py b/src/scanpy/plotting/_matrixplot.py
index 0567cf27c1..059233ce37 100644
--- a/src/scanpy/plotting/_matrixplot.py
+++ b/src/scanpy/plotting/_matrixplot.py
@@ -134,7 +134,7 @@ def __init__(
         var_group_labels: Sequence[str] | None = None,
         var_group_rotation: float | None = None,
         layer: str | None = None,
-        standard_scale: Literal["var", "group"] = None,
+        standard_scale: Literal["var", "group"] | None = None,
         ax: _AxesSubplot | None = None,
         values_df: pd.DataFrame | None = None,
         vmin: float | None = None,
@@ -343,6 +343,7 @@ def matrixplot(
     use_raw: bool | None = None,
     log: bool = False,
     num_categories: int = 7,
+    categories_order: Sequence[str] | None = None,
     figsize: tuple[float, float] | None = None,
     dendrogram: bool | str = False,
     title: str | None = None,
@@ -436,6 +437,7 @@ def matrixplot(
         use_raw=use_raw,
         log=log,
         num_categories=num_categories,
+        categories_order=categories_order,
         standard_scale=standard_scale,
         title=title,
         figsize=figsize,
diff --git a/src/scanpy/plotting/_stacked_violin.py b/src/scanpy/plotting/_stacked_violin.py
index 0d18956fcd..a3d5e65834 100644
--- a/src/scanpy/plotting/_stacked_violin.py
+++ b/src/scanpy/plotting/_stacked_violin.py
@@ -694,7 +694,7 @@ def stacked_violin(
     size: int = StackedViolin.DEFAULT_JITTER_SIZE,
     density_norm: DensityNorm = StackedViolin.DEFAULT_DENSITY_NORM,
     yticklabels: bool | None = StackedViolin.DEFAULT_PLOT_YTICKLABELS,
-    order: Sequence[str] | None = None,
+    categories_order: Sequence[str] | None = None,
     swap_axes: bool = False,
     show: bool | None = None,
     save: bool | str | None = None,
@@ -707,6 +707,7 @@ def stacked_violin(
     vcenter: float | None = None,
     norm: Normalize | None = None,
     # deprecated
+    order: Sequence[str] | None | Empty = _empty,
     scale: DensityNorm | Empty = _empty,
     **kwds,
 ) -> StackedViolin | dict | None:
@@ -735,10 +736,6 @@ def stacked_violin(
         See :func:`~seaborn.stripplot`.
     size
         Size of the jitter points.
-    order
-        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.
     density_norm
         The method used to scale the width of each violin.
         If 'width' (the default), each violin will have the same width.
@@ -809,6 +806,13 @@ def stacked_violin(
         print(axes_dict)
 
     """
+    if order is not _empty:
+        msg = (
+            "`order` is deprecated (and never worked for `stacked_violin`), "
+            "use categories_order instead"
+        )
+        warnings.warn(msg, FutureWarning)
+        # no reason to set `categories_order` here, as `order` never worked.
 
     vp = StackedViolin(
         adata,
@@ -817,6 +821,7 @@ def stacked_violin(
         use_raw=use_raw,
         log=log,
         num_categories=num_categories,
+        categories_order=categories_order,
         standard_scale=standard_scale,
         title=title,
         figsize=figsize,