spatialproteomics 0.7.9__tar.gz → 0.8.0__tar.gz

{spatialproteomics-0.7.9/spatialproteomics.egg-info → spatialproteomics-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialproteomics
-Version: 0.7.9
+Version: 0.8.0
 Summary: Spatialproteomics is an interoperable toolbox for analyzing highly multiplexed fluorescence image data
 Author: Matthias Meyer-Bender, Harald Vohringer
 Requires-Python: >=3.10

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spatialproteomics"
-version = "0.7.9"
+version = "0.8.0"
 description = "Spatialproteomics is an interoperable toolbox for analyzing highly multiplexed fluorescence image data"
 readme = "README.md"
 requires-python = ">=3.10"

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0}/spatialproteomics/pl/plot.py

@@ -245,6 +245,10 @@ class PlotAccessor:
             min_val = obs_colors["min"]
             max_val = obs_colors["max"]
 
+        # handling the special case where all values in the segmentation are the same,
+        # which would lead to a division by zero in the normalization step
+        max_val = max_val if max_val > min_val else min_val + 1
+
         # Create the colorbar with dynamic positioning and size
         sm = plt.cm.ScalarMappable(cmap=cmap, norm=plt.Normalize(vmin=min_val, vmax=max_val))
         sm.set_array([])
@@ -294,8 +298,8 @@ class PlotAccessor:
         normalize: bool = True,
         merge: bool = True,
         layer_key: str = Layers.IMAGE,
-        amin: Optional[float] = None,
-        amax: Optional[float] = None,
+        amin: Optional[float | List] = None,
+        amax: Optional[float | List] = None,
     ) -> xr.Dataset:
         """
         Colorizes a stack of images.
@@ -312,10 +316,10 @@ class PlotAccessor:
             Merge the channel dimension. Default is True.
         layer_key : str, optional
             The key of the layer containing the image. Default is '_image'.
-        amin : float, optional
-            The minimum absolute value for normalization. Default is None.
-        amax : float, optional
-            The maximum absolute value for normalization. Default is None.
+        amin : float | List, optional
+            The minimum absolute value for normalization (either global or per channel). Default is None.
+        amax : float | List, optional
+            The maximum absolute value for normalization (either global or per channel). Default is None.
 
         Returns
         -------

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0}/spatialproteomics/pl/utils.py

@@ -77,8 +77,8 @@ def _colorize(
     colors: List[str] = ["C1", "C2", "C3", "C4", "C5"],
     background: str = "black",
     normalize: bool = True,
-    amin: Optional[float] = None,
-    amax: Optional[float] = None,
+    amin: Optional[float | List] = None,
+    amax: Optional[float | List] = None,
 ) -> np.ndarray:
     """
     Apply colorization to an image based on a given colors.
@@ -88,8 +88,8 @@ def _colorize(
         colors (List[str], optional): The list of colors to be used for colorization. Defaults to ["C1", "C2", "C3", "C4", "C5"].
         background (str, optional): The background color. Defaults to "black".
         normalize (bool, optional): Whether to normalize the image before colorization. Defaults to True.
-        amin (Optional[float], optional): The minimum value for normalization. Defaults to None.
-        amax (Optional[float], optional): The maximum value for normalization. Defaults to None.
+        amin (Optional[float | List], optional): The minimum value for normalization. Defaults to None.
+        amax (Optional[float | List], optional): The maximum value for normalization. Defaults to None.
 
     Returns:
         np.ndarray: The colorized image.
@@ -219,6 +219,9 @@ def _render_obs(
     vmin: float = None,
     vmax: float = None,
 ) -> np.ndarray:
+    # handling the special case where all values in the segmentation are the same,
+    # which would lead to a division by zero in the normalization step
+    vmax = vmax if vmax > vmin else vmin + 1
     # normalize the segmentation to be in the range [0, 1]
     segmentation = (segmentation - vmin) / (vmax - vmin)
 

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0}/spatialproteomics/pp/preprocessing.py

@@ -313,6 +313,7 @@ def filter_by_obs(
     func: Callable,
     segmentation_key: str = SDLayers.SEGMENTATION,
     table_key: str = SDLayers.TABLE,
+    reindex: bool = False,
     copy: bool = False,
 ):
     """
@@ -324,6 +325,7 @@ def filter_by_obs(
         func (Callable): A filtering function that takes in the values of the feature and returns a boolean array.
         segmentation_key (str): The key of the segmentation mask in the object. Default is SDLayers.SEGMENTATION.
         table_key (str): The key of the table in the object. Default is SDLayers.TABLE.
+        reindex (bool): Whether to reindex the obs after filtering. Default is False.
         copy (bool): If True, a copy of the object is returned. Default is False.
     """
     import spatialdata
@@ -347,13 +349,15 @@ def filter_by_obs(
     # setting all cells that are not in cells to 0
     segmentation = _remove_unlabeled_cells(segmentation, cells_sel)
     # relabeling cells in the segmentation mask so the IDs go from 1 to n again
-    segmentation, relabel_dict = _relabel_cells(segmentation)
+    if reindex:
+        segmentation, relabel_dict = _relabel_cells(segmentation)
 
     # removing the cells which are not in cells_sel
     adata = adata[adata.obs[SDFeatures.ID].isin(cells_sel), :].copy()
     # updating the cell coords of the object
-    adata.obs[SDFeatures.ID] = [relabel_dict[cell] for cell in adata.obs[SDFeatures.ID].values]
-    adata.obs.index = [f"Cell_{x}" for x in adata.obs[SDFeatures.ID].values]
+    if reindex:
+        adata.obs[SDFeatures.ID] = [relabel_dict[cell] for cell in adata.obs[SDFeatures.ID].values]
+        adata.obs.index = [f"Cell_{x}" for x in adata.obs[SDFeatures.ID].values]
 
     # overwriting the segmentation mask in the object
     # get transformations
@@ -743,7 +747,7 @@ class PreprocessingAccessor:
 
     def add_channel(self, channels: Union[str, list], array: np.ndarray, layer_key: str = Layers.IMAGE) -> xr.Dataset:
         """
-        Adds channel(s) to an existing image container.
+        Adds channel(s) to an existing spatialproteomics object.
 
         Parameters
         ----------
@@ -752,12 +756,12 @@ class PreprocessingAccessor:
         array : np.ndarray
             The numpy array representing the channel(s) to be added.
         layer_key : str
-            The layer key where the channel(s) should be added. Default is 'image'.
+            The layer key where the channel(s) should be added. Default is '_image'.
 
         Returns
         -------
         xr.Dataset
-            The updated image container with added channel(s).
+            The updated spatialproteomics object with added channel(s).
         """
         assert type(array) is np.ndarray, "Added channels must be numpy arrays."
         assert array.ndim in [2, 3], "Added channels must be 2D or 3D arrays."
@@ -795,10 +799,34 @@ class PreprocessingAccessor:
 
         return xr.merge([self._obj, da], join="outer", compat="no_conflicts")
 
+    def drop_channel(self, channels: Union[str, list]) -> xr.Dataset:
+        """
+        Drops channel(s) from an existing spatialproteomics object.
+
+        Parameters
+        ----------
+        channels : Union[str, list]
+            The name of the channel or a list of channel names to be dropped.
+
+        Returns
+        -------
+        xr.Dataset
+            The updated spatialproteomics object with dropped channel(s).
+        """
+        if type(channels) is str:
+            channels = [channels]
+
+        nonexistent_channels = set(channels) - set(self._obj.coords[Dims.CHANNELS].values)
+        assert (
+            len(nonexistent_channels) == 0
+        ), f"Some of the channels to be dropped do not exist in the object: {nonexistent_channels}. Please set the channel_names argument to a list of existing channels."
+
+        return self._obj.drop_sel({Dims.CHANNELS: channels})
+
     def add_segmentation(
         self,
         segmentation: Union[str, np.ndarray] = None,
-        reindex: bool = True,
+        reindex: bool = False,
         keep_labels: bool = True,
         add_obs: bool = True,
     ) -> xr.Dataset:
@@ -1569,7 +1597,9 @@ class PreprocessingAccessor:
 
         return xr.merge([obj, new_img, new_seg], join="outer", compat="no_conflicts")
 
-    def filter_by_obs(self, col: str, func: Callable, segmentation_key: str = Layers.SEGMENTATION):
+    def filter_by_obs(
+        self, col: str, func: Callable, segmentation_key: str = Layers.SEGMENTATION, reindex: bool = False
+    ):
         """
         Filter the object by observations based on a given feature and filtering function.
 
@@ -1577,6 +1607,7 @@ class PreprocessingAccessor:
             col (str): The name of the feature to filter by.
             func (Callable): A filtering function that takes in the values of the feature and returns a boolean array.
             segmentation_key (str): The key of the segmentation mask in the object. Default is Layers.SEGMENTATION.
+            reindex (bool): Whether to reindex the cell IDs after filtering. Default is False.
 
         Returns:
             xr.Dataset: The filtered object with the selected cells and updated segmentation mask.
@@ -1586,7 +1617,6 @@ class PreprocessingAccessor:
 
         Notes:
             - This method filters the object by selecting only the cells that satisfy the filtering condition.
-            - It also updates the segmentation mask to remove cells that are not selected and relabels the remaining cells.
 
         Example:
             To filter the object by the feature "area" and keep only the cells with an area greater than 70px:
@@ -1615,10 +1645,11 @@ class PreprocessingAccessor:
         segmentation = obj[segmentation_key].values
         # setting all cells that are not in cells to 0
         segmentation = _remove_unlabeled_cells(segmentation, cells_sel)
-        # relabeling cells in the segmentation mask so the IDs go from 1 to n again
-        segmentation, relabel_dict = _relabel_cells(segmentation)
-        # updating the cell coords of the object
-        obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords[Dims.CELLS].values]
+        if reindex:
+            # relabeling cells in the segmentation mask so the IDs go from 1 to n again
+            segmentation, relabel_dict = _relabel_cells(segmentation)
+            # updating the cell coords of the object
+            obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords[Dims.CELLS].values]
 
         # creating a data array with the segmentation mask, so that we can merge it to the original
         da = xr.DataArray(
@@ -1635,7 +1666,11 @@ class PreprocessingAccessor:
         return xr.merge([obj, da], join="outer", compat="no_conflicts")
 
     def remove_outlying_cells(
-        self, dilation_size: int = 25, threshold: int = 5, segmentation_key: str = Layers.SEGMENTATION
+        self,
+        dilation_size: int = 25,
+        threshold: int = 5,
+        segmentation_key: str = Layers.SEGMENTATION,
+        reindex: bool = False,
     ):
         """
         Removes outlying cells from the image container. It does so by dilating the segmentation mask and removing cells that belong to a connected component with less than 'threshold' cells.
@@ -1648,6 +1683,8 @@ class PreprocessingAccessor:
             The minimum number of cells in a connected component required for the cells to be kept. Default is 5.
         segmentation_key : str
             The key of the segmentation mask in the object. Default is '_segmentation'.
+        reindex : bool
+            Whether to reindex the cell IDs after filtering. Default is False.
 
         Returns
         -------
@@ -1679,10 +1716,11 @@ class PreprocessingAccessor:
         obj = self._obj.sel(query)
         # setting all cells that are not in cells to 0
         segmentation = _remove_unlabeled_cells(segmentation, cells_sel)
-        # relabeling cells in the segmentation mask so the IDs go from 1 to n again
-        segmentation, relabel_dict = _relabel_cells(segmentation)
-        # updating the cell coords of the object
-        obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords[Dims.CELLS].values]
+        if reindex:
+            # relabeling cells in the segmentation mask so the IDs go from 1 to n again
+            segmentation, relabel_dict = _relabel_cells(segmentation)
+            # updating the cell coords of the object
+            obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords[Dims.CELLS].values]
 
         # creating a data array with the segmentation mask, so that we can merge it to the original
         da = xr.DataArray(
@@ -2058,13 +2096,16 @@ class PreprocessingAccessor:
 
         return xr.merge([obj, da], join="outer", compat="no_conflicts")
 
-    def mask_cells(self, mask_key: str = Layers.MASK, segmentation_key=Layers.SEGMENTATION) -> xr.Dataset:
+    def mask_cells(
+        self, mask_key: str = Layers.MASK, segmentation_key=Layers.SEGMENTATION, reindex: bool = False
+    ) -> xr.Dataset:
         """
         Mask cells in the segmentation mask.
 
         Parameters:
             mask_key (str): The key of the mask to use for masking.
             segmentation_key (str): The key of the segmentation mask in the object. Default is Layers.SEGMENTATION.
+            reindex (bool): Whether to reindex the cell IDs after filtering. Default is False.
 
         Returns:
             xr.Dataset: The object with the masked cells in the segmentation mask.
@@ -2093,10 +2134,11 @@ class PreprocessingAccessor:
         segmentation = obj[segmentation_key].values
         # setting all cells that are not in cells to 0
         segmentation = _remove_unlabeled_cells(segmentation, cells_sel)
-        # relabeling cells in the segmentation mask so the IDs go from 1 to n again
-        segmentation, relabel_dict = _relabel_cells(segmentation)
-        # updating the cell coords of the object
-        obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords["cells"].values]
+        if reindex:
+            # relabeling cells in the segmentation mask so the IDs go from 1 to n again
+            segmentation, relabel_dict = _relabel_cells(segmentation)
+            # updating the cell coords of the object
+            obj.coords[Dims.CELLS] = [relabel_dict[cell] for cell in obj.coords["cells"].values]
 
         # creating a data array with the segmentation mask, so that we can merge it to the original
         da = xr.DataArray(
@@ -2199,3 +2241,83 @@ class PreprocessingAccessor:
         # if there are multiple layers with channels as coordinates, this will turn it into float32, since it will introduce NaNs for the new channel in other layers
         obj = self._obj.pp.add_channel(channels=key_added, array=merged)
         return obj
+
+    def find_bright_cells(
+        self,
+        channels: Optional[Union[str, list]] = None,
+        frac_channels: float = 0.5,
+        quantile: float = 0.95,
+        key: str = Layers.INTENSITY,
+        key_added: str = "is_bright",
+    ) -> xr.Dataset:
+        """
+        Flags cells that are bright across multiple channels (e.g., due to a lot of antibodies binding to that cell).
+        A cell is considered bright in a channel if its intensity exceeds the given quantile threshold
+        for that channel. Cells that are bright in at least frac_channels of the
+        considered channels are flagged.
+
+        Parameters
+        ----------
+        channels : Optional[Union[str, list]]
+            The channels to consider. If None, all channels are used.
+        frac_channels : float
+            The fraction of channels in which a cell must be bright to be flagged.
+            Default is 0.5.
+        quantile : float
+            The quantile threshold above which a cell is considered bright in a
+            given channel. Computed per channel. Default is 0.95.
+        key : str
+            The key of the intensity layer to use. Default is Layers.INTENSITY.
+        key_added : str
+            The name of the feature added to obs. Default is 'is_bright'.
+
+        Returns
+        -------
+        xr.Dataset
+            The updated image container with the 'is_bright' flag added to obs.
+
+        Raises
+        ------
+        ValueError
+            If no intensity matrix is found at the specified layer.
+
+        Example
+        -------
+        Flag cells that are bright in at least 50% of all channels at the 95th percentile:
+        >>> ds = ds.pp.find_bright_cells()
+
+        Flag cells that are bright in at least 2 out of 3 specific channels:
+        >>> ds = ds.pp.find_bright_cells(channels=['CD3', 'CD8', 'CD20'], frac_channels=0.66)
+        """
+        if key not in self._obj:
+            raise ValueError(f"No intensity matrix found at layer {key}. Please run pp.add_quantification() first.")
+
+        assert 0 <= frac_channels <= 1, "frac_channels must be between 0 and 1."
+        assert 0 <= quantile <= 1, "quantile must be between 0 and 1."
+
+        # resolve channels
+        all_channels = self._obj.coords[Dims.CHANNELS].values
+        if channels is None:
+            channels = all_channels
+        elif isinstance(channels, str):
+            channels = [channels]
+
+        nonexistent = set(channels) - set(all_channels)
+        assert (
+            len(nonexistent) == 0
+        ), f"The following channels were not found: {nonexistent}. Please adjust the 'channels' argument to only contain existing channels."
+
+        # get the intensity matrix for the selected channels, shape (n_cells, n_channels)
+        intensity = self._obj[key].sel({Dims.CHANNELS: channels}).values
+
+        # compute per-channel quantile thresholds
+        thresholds = np.quantile(intensity, quantile, axis=0)  # shape (n_channels,)
+
+        # a cell is bright in a channel if it exceeds that channel's threshold
+        is_above = intensity > thresholds  # shape (n_cells, n_channels)
+
+        # flag cells that are bright in at least frac_channels of the considered channels
+        min_channels = int(np.ceil(frac_channels * len(channels)))
+        is_bright = is_above.sum(axis=1) >= min_channels  # shape (n_cells,)
+
+        return self._obj.pp.add_feature(key_added, is_bright.astype(float))

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0}/spatialproteomics/pp/utils.py

@@ -161,8 +161,8 @@ def _normalize(
     pmax: float = 99.8,
     eps: float = 1e-20,
     clip: bool = False,
-    amin: Optional[float] = None,
-    amax: Optional[float] = None,
+    amin: Optional[float | List] = None,
+    amax: Optional[float | List] = None,
 ) -> np.ndarray:
     """
     Performs a min max normalisation.
@@ -181,9 +181,9 @@ def _normalize(
     clip: bool
         Ensures that normed image array contains no values greater than 1.
     amin: float
-        Absolute value to perform normalization. If set, this overrides pmin.
+        Absolute value to perform normalization. If set, this overrides pmin. Can be a list of values, in which case each channel is normalized independently.
     amax: float
-        Absolute value to perform normalization. If set, this overrides pmax.
+        Absolute value to perform normalization. If set, this overrides pmax. Can be a list of values, in which case each channel is normalized independently.
 
     Returns
     -------

{spatialproteomics-0.7.9 → spatialproteomics-0.8.0/spatialproteomics.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialproteomics
-Version: 0.7.9
+Version: 0.8.0
 Summary: Spatialproteomics is an interoperable toolbox for analyzing highly multiplexed fluorescence image data
 Author: Matthias Meyer-Bender, Harald Vohringer
 Requires-Python: >=3.10