Merge pull request #372 from MannLabs/add_image_normalization

improve image normalization capabilities

Author: sophiamaedler

docs/conf.py

@@ -33,6 +33,7 @@ def setup(app):
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
     "sphinxarg.ext",
@@ -95,6 +96,7 @@ def setup(app):
     "member-order": "bysource",
 }
 autoclass_content = "both"
+autosummary_generate = True
 
 html_favicon = "favicon.png"
 html_logo = "_static/scPortrait_logo_light.svg"

docs/pages/module/plotting.rst

@@ -2,5 +2,22 @@
 plotting
 *******************
 
-.. automodule:: scportrait.plotting
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    scportrait.plotting.add_scalebar
+    scportrait.plotting.colorize
+    scportrait.plotting.generate_composite
+
+sdata
+=====
+
+.. automodule:: scportrait.plotting.sdata
+    :members:
+
+h5sc
+====
+
+.. automodule:: scportrait.plotting.h5sc
     :members:

src/scportrait/_utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility helpers for scPortrait."""
+
+from .deprecation import deprecated
+
+__all__ = ["deprecated"]

src/scportrait/_utils/deprecation.py

@@ -0,0 +1,38 @@
+"""Helpers for deprecating public APIs."""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T", bound=Callable[..., object])
+
+try:
+    from deprecation import deprecated as _deprecated
+except (ImportError, ModuleNotFoundError):  # pragma: no cover - optional dependency
+    _deprecated = None
+
+
+def deprecated(*args, **kwargs):
+    """Return a deprecation decorator.
+
+    If the optional `deprecation` dependency is installed, this proxies to
+    `deprecation.deprecated`. Otherwise it falls back to a lightweight wrapper
+    that emits a DeprecationWarning at call time.
+    """
+    if _deprecated is not None:
+        return _deprecated(*args, **kwargs)
+
+    details = kwargs.get("details", "This function is deprecated and will be removed in a future release.")
+
+    def _decorator(func: T) -> T:
+        @functools.wraps(func)
+        def _wrapped(*f_args, **f_kwargs):
+            warnings.warn(details, DeprecationWarning, stacklevel=2)
+            return func(*f_args, **f_kwargs)
+
+        return _wrapped  # type: ignore[return-value]
+
+    return _decorator

src/scportrait/pipeline/_utils/segmentation.py

@@ -17,7 +17,7 @@
 from skimage.transform import resize
 
 from scportrait.pipeline._utils.constants import DEFAULT_SEGMENTATION_DTYPE
-from scportrait.plotting.vis import plot_image
+from scportrait.plotting._vis import plot_image_array
 
 
 def global_otsu(image: NDArray) -> float:
@@ -72,7 +72,7 @@ def _segment_threshold(
     image_mask = image > threshold
 
     if debug:
-        plot_image(image_mask, cmap="Greys_r")
+        plot_image_array(image_mask, cmap="Greys_r")
 
     image_mask_clean = binary_erosion(image_mask, footprint=disk(speckle_kernel))
     image_mask_clean = sk_dilation(image_mask_clean, footprint=disk(speckle_kernel - 1))

src/scportrait/pipeline/project.py

@@ -704,7 +704,12 @@ def plot_input_image(
 
             # subset spatialdata object if its too large
             if x > max_width or y > max_width:
-                _sdata = get_bounding_box_sdata(_sdata, max_width, center_x, center_y)
+                _sdata = get_bounding_box_sdata(
+                    _sdata,
+                    max_width,
+                    center_y=center_y,
+                    center_x=center_x,
+                )
 
         if normalize:
             lower_percentile, upper_percentile = normalization_percentile
@@ -902,7 +907,7 @@ def plot_segmentation_masks(
 
             # subset spatialdata object if its too large
             if x > max_width or y > max_width:
-                _sdata = get_bounding_box_sdata(_sdata, max_width, center_x, center_y)
+                _sdata = get_bounding_box_sdata(_sdata, max_width, center_x=center_x, center_y=center_y)
 
         if normalize:
             lower_percentile, upper_percentile = normalization_percentile

src/scportrait/pipeline/segmentation/workflows/_cellpose.py

@@ -306,8 +306,6 @@ def _get_kernel_config(self):
         else:
             self.kernel_size = 20  # default value
 
-        print(self.kernel_size)
-
     def _expand_nucleus_mask(self, nucleus_mask: np.ndarray, kernel_size: int) -> np.ndarray:
         """
         Expands the nucleus mask by a given kernel size using dilation

src/scportrait/plotting/__init__.py

@@ -1,7 +1,7 @@
 from ._utils import add_scalebar
+from ._vis import colorize, generate_composite
 from .h5sc import cell_grid, cell_grid_multi_channel, cell_grid_single_channel
-from .sdata import plot_image, plot_labels, plot_segmentation_mask
-from .vis import generate_composite
+from .sdata import plot_image, plot_labels, plot_segmentation_mask, plot_shapes
 
 __all__ = [
     "add_scalebar",
@@ -11,5 +11,7 @@
     "plot_segmentation_mask",
     "plot_image",
     "plot_labels",
+    "plot_shapes",
     "generate_composite",
+    "colorize",
 ]

src/scportrait/plotting/vis.py src/scportrait/plotting/_vis.pysrc/scportrait/plotting/vis.py renamed to src/scportrait/plotting/_vis.py

@@ -12,7 +12,10 @@
     from scportrait.pipeline.project import Project
 
 
-def plot_image(
+from scportrait._utils.deprecation import deprecated
+
+
+def plot_image_array(
     array: np.ndarray,
     size: tuple[int, int] = (10, 10),
     save_name: str | None = "",
@@ -34,11 +37,11 @@ def plot_image(
         **kwargs: Additional keyword arguments to be passed to `ax.imshow`.
 
     Returns:
-        None: The function will display the image but does not return any values.
+        Matplotlib figure if `return_fig=True`, otherwise `None`.
 
     Example:
     >>> array = np.random.rand(10, 10)
-    >>> plot_image(array, size=(5, 5))
+    >>> plot_image_array(array, size=(5, 5))
     """
 
     fig = plt.figure(frameon=False)
@@ -60,12 +63,25 @@ def plot_image(
         plt.close()
 
 
+@deprecated(
+    deprecated_in="1.6.2",
+    removed_in="1.7.0",
+    details=(
+        "This function is not used internally and will be removed in a future release. "
+        "Prefer scportrait.plotting.sdata.plot_labels or scportrait.plotting.sdata.plot_shapes."
+    ),
+)
 def visualize_class(
     class_ids: np.ndarray | list[int], seg_map: np.ndarray, image: np.ndarray, all_ids=None, return_fig=False, **kwargs
 ):
     """
     Visualize specific classes in a segmentation map by highlighting them on top of a background image.
 
+    .. deprecated:: 1.6.2
+        This function is not used internally and will be removed in a future release. Prefer
+        `scportrait.plotting.sdata.plot_labels` or `scportrait.plotting.sdata.plot_shapes` for
+        SpatialData-based workflows.
+
     This function takes in class IDs and a segmentation map, and creates an output visualization
     where the specified classes are highlighted on top of the provided background image.
 
@@ -106,12 +122,20 @@ def visualize_class(
 
     vis_map = label2rgb(outmap, image=image, colors=["red", "blue"], alpha=0.4, bg_label=0)
 
-    fig = plot_image(vis_map, return_fig=True, **kwargs)
+    fig = plot_image_array(vis_map, return_fig=True, **kwargs)
 
     if return_fig:
         return fig
 
 
+@deprecated(
+    deprecated_in="1.6.2",
+    removed_in="1.7.0",
+    details=(
+        "This helper is superseded by scportrait.plotting.sdata.plot_segmentation_mask and "
+        "is not used internally. It will be removed in a future release."
+    ),
+)
 def plot_segmentation_mask(
     project: Project,
     mask_channel: int = 0,
@@ -124,6 +148,10 @@ def plot_segmentation_mask(
 ) -> object:
     """Visualize the segmentation mask overlayed with a channel of the input image.
 
+    .. deprecated:: 1.6.2
+        This helper is superseded by `scportrait.plotting.sdata.plot_segmentation_mask` and
+        is not used internally. It will be removed in a future release.
+
     Args:
        project: Instance of a scPortrait project.
        mask_channel: The index of the channel to use for the segmentation mask.
@@ -167,17 +195,22 @@ def colorize(
     im: np.ndarray, color: tuple[int, ...] = (1, 0, 0), clip_percentile: float = 0.0, normalize_image: bool = False
 ):
     """
-    Helper function to create an RGB image from a single-channel image using a
-    specific color.
+    Create an RGB image from a single-channel image using a specified color.
 
     Args:
-        im: A single-channel input image. If normalize_image = False, ensure that its values fall between the [0, 1] range.
+        im: A single-channel input image. If normalize_image = False, ensure that its values fall between [0, 1].
         color: The color to use for the image. Defaults to (1, 0, 0).
-        clip_percentile: The percentile to clip the image at rescaling. Defaults to 0.0 which is equivalent to Min-Max scaling.
-        normalize_image: boolean value indicating if rescaling should be performed or not.
+        clip_percentile: Percentile to clip the image at when rescaling. Defaults to 0.0 (min-max scaling).
+        normalize_image: Whether to rescale the image before colorizing.
 
     Returns:
         np.ndarray: The colorized image.
+
+    Example:
+        >>> import numpy as np
+        >>> from scportrait.plotting import colorize
+        >>> im = np.random.rand(64, 64)
+        >>> rgb = colorize(im, color=(0, 1, 0), normalize_image=True)
     """
     # Check that we do just have a 2D image
     if im.ndim > 2 and im.shape[2] != 1: