first version of render_channels

* pl.render_channels blueprint

* _render_channels blueprint

* implemented basic functionality of _render_channels

* pl.render_channels checks types

* pl.render_channels appends the params dict correctly to the plotting tree

* _render_channels clips the final image

* cast passed ax object in pl.show to an numpy array such that it is an iterable

* added docstring and additional parameter validation to pl.render_channels

* fixed input validation in pl.render_channels

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Tim Treis <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

src/spatialdata_plot/pl/basic.py

@@ -21,7 +21,7 @@
 
 from ..accessor import register_spatial_data_accessor
 from ..pp.utils import _get_instance_key, _get_region_key, _verify_plotting_tree_exists
-from .render import _render_images, _render_labels, _render_shapes
+from .render import _render_channels, _render_images, _render_labels, _render_shapes
 from .utils import (
     _get_color_key_dtype,
     _get_color_key_values,
@@ -231,6 +231,96 @@ def render_images(
 
         return sdata
 
+    def render_channels(
+        self,
+        channels: Union[list[str], list[int]],
+        colors: list[str],
+        normalize: bool = True,
+        clip: bool = True,
+        background: str = "black",
+        pmin: float = 3.0,
+        pmax: float = 99.8,
+    ) -> sd.SpatialData:
+        """Renders selected channels.
+
+        Parameters:
+        -----------
+        self: object
+            The SpatialData object
+        channels: Union[List[str], List[int]]
+            The channels to plot
+        colors: List[str]
+            The colors for the channels. Must be at least as long as len(channels).
+        normalize: bool
+            Perform quantile normalisation (using pmin, pmax)
+        clip: bool
+            Clips the merged image to the range (0, 1).
+        background: str
+            Background color (defaults to black).
+        pmin: float
+            Lower percentile for quantile normalisation (defaults to 3.-).
+        pmax: float
+            Upper percentile for quantile normalisation (defaults to 99.8).
+
+        Raises
+        ------
+        TypeError
+            If any of the parameters have an invalid type.
+        ValueError
+            If any of the parameters have an invalid value.
+
+        Returns
+        -------
+        sd.SpatialData
+            A new `SpatialData` object that is a copy of the original
+            `SpatialData` object, with an updated plotting tree.
+        """
+        if not isinstance(channels, list):
+            raise TypeError("Parameter 'channels' must be a list.")
+
+        if not isinstance(colors, list):
+            raise TypeError("Parameter 'colors' must be a list.")
+
+        if len(channels) > len(colors):
+            raise ValueError("Number of colors must have at least the same length as the number of selected channels.")
+
+        if not isinstance(clip, bool):
+            raise TypeError("Parameter 'clip' must be a bool.")
+
+        if not isinstance(normalize, bool):
+            raise TypeError("Parameter 'normalize' must be a bool.")
+
+        if not isinstance(background, str):
+            raise TypeError("Parameter 'background' must be a str.")
+
+        if not isinstance(pmin, float):
+            raise TypeError("Parameter 'pmin' must be a str.")
+
+        if not isinstance(pmax, float):
+            raise TypeError("Parameter 'pmax' must be a str.")
+
+        if (pmin < 0.0) or (pmin > 100.0) or (pmax < 0.0) or (pmax > 100.0):
+            raise ValueError("Percentiles must be in the range 0 < pmin/pmax < 100.")
+
+        if pmin > pmax:
+            raise ValueError("Percentile parameters must satisfy pmin < pmax.")
+
+        sdata = self._copy()
+        sdata = _verify_plotting_tree_exists(sdata)
+        n_steps = len(sdata.plotting_tree.keys())
+
+        sdata.plotting_tree[f"{n_steps+1}_render_channels"] = {
+            "channels": channels,
+            "colors": colors,
+            "clip": clip,
+            "normalize": normalize,
+            "background": background,
+            "pmin": pmin,
+            "pmax": pmax,
+        }
+
+        return sdata
+
     def render_labels(
         self,
         instance_key: Optional[Union[str, None]] = None,
@@ -458,12 +548,12 @@ def show(
                 num_images = len(sdata.coordinate_systems)
                 fig, axs = _get_subplots(num_images, ncols, width, height)
             elif isinstance(ax, matplotlib.pyplot.Axes):
-                axs = [ax]
+                axs = np.array([ax])
             elif isinstance(ax, list):
                 axs = ax
 
             # Set background color
-            for _, ax in enumerate(axs):
+            for _, ax in enumerate(axs.flatten()):
                 ax.set_facecolor(bg_color)
                 # key = list(sdata.labels.keys())[idx]
                 # ax.imshow(sdata.labels[key].values, cmap=ListedColormap([bg_color]))
@@ -514,12 +604,16 @@ def show(
 
             # go through tree
             for cmd, params in render_cmds.items():
-                if cmd == "render_images":
-                    for idx, ax in enumerate(axs):
-                        key = list(sdata.images.keys())[idx]
+                keys = list(sdata.images.keys())
 
+                if cmd == "render_images":
+                    for key, ax in zip(keys, axs.flatten()):
                         _render_images(sdata=sdata, params=params, key=key, ax=ax, extent=extent)
 
+                elif cmd == "render_channels":
+                    for key, ax in zip(keys, axs.flatten()):
+                        _render_channels(sdata=sdata, key=key, ax=ax, **params)
+
                 elif cmd == "render_shapes":
                     if (
                         sdata.table is not None

src/spatialdata_plot/pl/render.py

@@ -12,7 +12,41 @@
 from sklearn.decomposition import PCA
 
 from ..pl.utils import _normalize
-from ..pp.utils import _get_region_key
+from ..pp.utils import _get_linear_colormap, _get_region_key
+
+
+def _render_channels(
+    sdata: sd.SpatialData,
+    channels: list[Union[str, int]],
+    colors: list[str],
+    clip: bool,
+    normalize: bool,
+    background: str,
+    pmin: float,
+    pmax: float,
+    key: str,
+    ax: matplotlib.axes.SubplotBase,
+) -> None:
+    selection = sdata.images[key].sel({"c": channels})
+    n_channels, y_dim, x_dim = selection.shape  # (c, y, x)
+    img = selection.values.copy()
+    img = img.astype("float")
+
+    if normalize:
+        img = _normalize(img, pmin, pmax, clip)
+
+    cmaps = _get_linear_colormap(colors[:n_channels], background)
+    colored = np.stack([cmaps[i](img[i]) for i in range(n_channels)], 0).sum(0)
+
+    if clip:
+        colored = np.clip(colored, 0, 1)
+
+    ax.imshow(colored)
+    ax.set_title(key)
+    ax.set_xlabel("spatial1")
+    ax.set_ylabel("spatial2")
+    ax.set_xticks([])
+    ax.set_yticks([])
 
 
 def _render_shapes(

src/spatialdata_plot/pl/utils.py

@@ -44,10 +44,10 @@ def _get_subplots(num_images: int, ncols: int = 4, width: int = 4, height: int =
     fig, axes = plt.subplots(nrows, ncols, figsize=(width * ncols, height * nrows))
 
     if not isinstance(axes, Iterable):
-        axes = [axes]
+        axes = np.array([axes])
 
     # get rid of the empty axes
-    # _ = [ax.axis("off") for ax in axes.flatten()[num_images:]]
+    _ = [ax.axis("off") for ax in axes.flatten()[num_images:]]
     return fig, axes