make outline behavior more similar to squidpy (#472)

Author: Sonja-Stockhaus

src/spatialdata_plot/pl/basic.py

@@ -61,7 +61,7 @@
 # replace with
 # from spatialdata._types import ColorLike
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
-ColorLike = tuple[float, ...] | str
+ColorLike = tuple[float, ...] | list[float] | str
 
 
 @register_spatial_data_accessor("pl")
@@ -156,14 +156,14 @@ def _copy(
     def render_shapes(
         self,
         element: str | None = None,
-        color: str | None = None,
-        fill_alpha: float | int = 1.0,
+        color: ColorLike | None = None,
+        fill_alpha: float | int | None = None,
         groups: list[str] | str | None = None,
         palette: list[str] | str | None = None,
         na_color: ColorLike | None = "default",
-        outline_width: float | int = 1.5,
-        outline_color: str | list[float] = "#000000",
-        outline_alpha: float | int = 0.0,
+        outline_width: float | int | tuple[float | int, float | int] | None = None,
+        outline_color: ColorLike | tuple[ColorLike] | None = None,
+        outline_alpha: float | int | tuple[float | int, float | int] | None = None,
         cmap: Colormap | str | None = None,
         norm: Normalize | None = None,
         scale: float | int = 1.0,
@@ -186,15 +186,18 @@ def render_shapes(
         element : str | None, optional
             The name of the shapes element to render. If `None`, all shapes elements in the `SpatialData` object will be
             used.
-        color : str | None
-            Can either be string representing a color-like or key in :attr:`sdata.table.obs`. The latter can be used to
-            color by categorical or continuous variables. If `element` is `None`, if possible the color will be
-            broadcasted to all elements. For this, the table in which the color key is found must annotate the
-            respective element (region must be set to the specific element). If the color column is found in multiple
-            locations, please provide the table_name to be used for the elements.
-        fill_alpha : float | int, default 1.0
-            Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the user, this value
-            will multiply the value present in the cmap.
+        color : ColorLike | None, optional
+            Can either be color-like (name of a color as string, e.g. "red", hex representation, e.g. "#000000" or
+            "#000000ff", or an RGB(A) array as a tuple or list containing 3-4 floats within [0, 1]. If an alpha value is
+            indicated, the value of `fill_alpha` takes precedence if given) or a string representing a key in
+            :attr:`sdata.table.obs`. The latter can be used to color by categorical or continuous variables. If
+            `element` is `None`, if possible the color will be broadcasted to all elements. For this, the table in which
+            the color key is found must annotate the respective element (region must be set to the specific element). If
+            the color column is found in multiple locations, please provide the table_name to be used for the elements.
+        fill_alpha : float | int | None, optional
+            Alpha value for the fill of shapes. By default, it is set to 1.0 or, if a color is given that implies an
+            alpha, that value is used for `fill_alpha`. If an alpha channel is present in a cmap passed by the user,
+            `fill_alpha` will overwrite the value present in the cmap.
         groups : list[str] | str | None
             When using `color` and the key represents discrete labels, `groups` can be used to show only a subset of
             them. Other values are set to NA. If elment is None, broadcasting behaviour is attempted (use the same
@@ -204,18 +207,25 @@ def render_shapes(
             match the number of groups. If element is None, broadcasting behaviour is attempted (use the same values for
             all elements). If groups is provided but not palette, palette is set to default "lightgray".
         na_color : ColorLike | None, default "default" (gets set to "lightgray")
-            Color to be used for NAs values, if present. Can either be a named color ("red"), a hex representation
+            Color to be used for NA values, if present. Can either be a named color ("red"), a hex representation
             ("#000000ff") or a list of floats that represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values
             won't be shown.
-        outline_width : float | int, default 1.5
-            Width of the border.
-        outline_color : str | list[float], default "#000000"
+        outline_width : float | int | tuple[float | int, float | int], optional
+            Width of the border. If 2 values are given (tuple), 2 borders are shown with these widths (outer & inner).
+            If `outline_color` and/or `outline_alpha` are used to indicate that one/two outlines should be drawn, the
+            default outline widths 1.5 and 0.5 are used for outer/only and inner outline respectively.
+        outline_color : ColorLike | tuple[ColorLike], optional
             Color of the border. Can either be a named color ("red"), a hex representation ("#000000") or a list of
             floats that represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). If the hex representation includes alpha, e.g.
-            "#000000ff", the last two positions are ignored, since the alpha of the outlines is solely controlled by
-            `outline_alpha`.
-        outline_alpha : float | int, default 0.0
-            Alpha value for the outline of shapes. Invisible by default.
+            "#000000ff", and `outline_alpha` is not given, this value controls the opacity of the outline. If 2 values
+            are given (tuple), 2 borders are shown with these colors (outer & inner). If `outline_width` and/or
+            `outline_alpha` are used to indicate that one/two outlines should be drawn, the default outline colors
+            "#000000" and "#ffffff are used for outer/only and inner outline respectively.
+        outline_alpha : float | int | tuple[float | int, float | int] | None, optional
+            Alpha value for the outline of shapes. Invisible by default, meaning outline_alpha=0.0 if both outline_color
+            and outline_width are not specified. Else, outlines are rendered with the alpha implied by outline_color, or
+            with outline_alpha=1.0 if outline_color does not imply an alpha. For two outlines, alpha values can be
+            passed in a tuple of length 2.
         cmap : Colormap | str | None, optional
             Colormap for discrete or continuous annotations using 'color', see :class:`matplotlib.colors.Colormap`.
         norm : bool | Normalize, default False
@@ -283,8 +293,12 @@ def render_shapes(
         sdata = self._copy()
         sdata = _verify_plotting_tree(sdata)
         n_steps = len(sdata.plotting_tree.keys())
-        outline_params = _set_outline(outline_alpha > 0, outline_width, outline_color)
         for element, param_values in params_dict.items():
+            final_outline_alpha, outline_params = _set_outline(
+                params_dict[element]["outline_alpha"],
+                params_dict[element]["outline_width"],
+                params_dict[element]["outline_color"],
+            )
             cmap_params = _prepare_cmap_norm(
                 cmap=cmap,
                 norm=norm,
@@ -299,7 +313,7 @@ def render_shapes(
                 outline_params=outline_params,
                 cmap_params=cmap_params,
                 palette=param_values["palette"],
-                outline_alpha=param_values["outline_alpha"],
+                outline_alpha=final_outline_alpha,
                 fill_alpha=param_values["fill_alpha"],
                 transfunc=kwargs.get("transfunc"),
                 table_name=param_values["table_name"],
@@ -316,8 +330,8 @@ def render_shapes(
     def render_points(
         self,
         element: str | None = None,
-        color: str | None = None,
-        alpha: float | int = 1.0,
+        color: ColorLike | None = None,
+        alpha: float | int | None = None,
         groups: list[str] | str | None = None,
         palette: list[str] | str | None = None,
         na_color: ColorLike | None = "default",
@@ -343,14 +357,17 @@ def render_points(
         element : str | None, optional
             The name of the points element to render. If `None`, all points elements in the `SpatialData` object will be
             used.
-        color : str | None
-            Can either be string representing a color-like or key in :attr:`sdata.table.obs`. The latter can be used to
-            color by categorical or continuous variables. If `element` is `None`, if possible the color will be
-            broadcasted to all elements. For this, the table in which the color key is found must annotate the
-            respective element (region must be set to the specific element). If the color column is found in multiple
-            locations, please provide the table_name to be used for the elements.
-        alpha : float | int, default 1.0
-            Alpha value for the points.
+        color : str | None, optional
+            Can either be color-like (name of a color as string, e.g. "red", hex representation, e.g. "#000000" or
+            "#000000ff", or an RGB(A) array as a tuple or list containing 3-4 floats within [0, 1]. If an alpha value is
+            indicated, the value of `fill_alpha` takes precedence if given) or a string representing a key in
+            :attr:`sdata.table.obs`. The latter can be used to color by categorical or continuous variables. If
+            `element` is `None`, if possible the color will be broadcasted to all elements. For this, the table in which
+            the color key is found must annotate the respective element (region must be set to the specific element). If
+            the color column is found in multiple locations, please provide the table_name to be used for the elements.
+        alpha : float | int | None, optional
+            Alpha value for the points. By default, it is set to 1.0 or, if a color is given that implies an alpha, that
+            value is used instead.
         groups : list[str] | str | None
             When using `color` and the key represents discrete labels, `groups` can be used to show only a subset of
             them. Other values are set to NA. If `element` is `None`, broadcasting behaviour is attempted (use the same
@@ -360,7 +377,7 @@ def render_points(
             match the number of groups. If `element` is `None`, broadcasting behaviour is attempted (use the same values
             for all elements). If groups is provided but not palette, palette is set to default "lightgray".
         na_color : ColorLike | None, default "default" (gets set to "lightgray")
-            Color to be used for NAs values, if present. Can either be a named color ("red"), a hex representation
+            Color to be used for NA values, if present. Can either be a named color ("red"), a hex representation
             ("#000000ff") or a list of floats that represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values
             won't be shown.
         cmap : Colormap | str | None, optional
@@ -601,7 +618,7 @@ def render_labels(
         element : str | None
             The name of the labels element to render. If `None`, all label
             elements in the `SpatialData` object will be used and all parameters will be broadcasted if possible.
-        color : list[str] | str | None
+        color : str | None
             Can either be string representing a color-like or key in :attr:`sdata.table.obs` or in the index of
             :attr:`sdata.table.var`. The latter can be used to color by categorical or continuous variables. If the
             color column is found in multiple locations, please provide the table_name to be used for the element if you
@@ -626,7 +643,7 @@ def render_labels(
             won't be shown.
         outline_alpha : float | int, default 0.0
             Alpha value for the outline of the labels. Invisible by default.
-        fill_alpha : float | int, default 0.3
+        fill_alpha : float | int, default 0.4
             Alpha value for the fill of the labels.
         scale :  str | None
             Influences the resolution of the rendering. Possibilities for setting this parameter: