spatialproteomics 0.7.10__tar.gz → 0.8.1__tar.gz

{spatialproteomics-0.7.10/spatialproteomics.egg-info → spatialproteomics-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialproteomics
-Version: 0.7.10
+Version: 0.8.1
 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.10 → spatialproteomics-0.8.1}/pyproject.toml

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

{spatialproteomics-0.7.10 → spatialproteomics-0.8.1}/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([])

{spatialproteomics-0.7.10 → spatialproteomics-0.8.1}/spatialproteomics/pl/utils.py

@@ -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.10 → spatialproteomics-0.8.1}/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
@@ -822,7 +826,7 @@ class PreprocessingAccessor:
     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:
@@ -1593,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.
 
@@ -1601,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.
@@ -1610,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:
@@ -1639,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(
@@ -1659,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.
@@ -1672,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
         -------
@@ -1703,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(
@@ -1785,12 +1799,21 @@ class PreprocessingAccessor:
         layer_key: str,
         key_added: str = "_merged_segmentation",
         labels: Optional[List[str]] = None,
-        threshold: float = 0.8,
+        threshold1: float = 0.7,
+        threshold2: float = 0.8,
     ):
         """
-        Merge segmentation masks.
-        This can be done in two ways: either by merging a multi-dimensional array from the object directly, or by adding a numpy array.
-        You can either just merge a multi-dimensional array, or merge to an existing 1D mask (e. g. a precomputed DAPI segmentation).
+        Merge segmentation masks. Merging works as follows:
+        1. Assume two segmentation masks, S1 (higher priority, e.g., macrophages) and S2 (lower priority, e.g., lymphocytes)
+        2. We start by copying the segmentation regions from S2 into S1, but only for pixels where S1 has background
+        3. Some S2 cells may now be partially overwritten by S1 cells — we drop any S2 cell where less than threshold1
+        fraction of its original area survived (e.g. with threshold1=0.7,
+        an S2 cell that lost more than 30% of its area to S1 is discarded)
+        4. Of the remaining S2 cells, we additionally drop any that overlap with threshold2 or
+        more of any single S1 cell's area — this prevents S2 cells from being retained when they
+        largely encapsulate an S1 cell (e.g. with threshold2=0.8, an S2 cell is discarded if it
+        covers more than 80% of any S1 cell)
+        5. The surviving S1 and S2 regions are combined into a final mask with sequential labels
 
         Parameters
         ----------
@@ -1800,7 +1823,9 @@ class PreprocessingAccessor:
             The name of the new segmentation mask to be added to the xarray object. Default is "_merged_segmentation".
         labels : Optional[List[str]]
             Optional. Labels corresponding to each segmentation mask. If provided, must match number of arrays.
-        threshold : float
+        threshold1: float
+            Optional. Threshold for merging cells. Default is 0.7.
+        threshold2: float
             Optional. Threshold for merging cells. Default is 0.8.
 
         Returns
@@ -1820,6 +1845,9 @@ class PreprocessingAccessor:
             - The merging process starts with merging the biggest cells first, then the smaller ones.
             - Disconnected cells in the input are handled based on the specified method.
         """
+        assert threshold1 >= 0 and threshold1 <= 1, "threshold1 must be between 0 and 1."
+        assert threshold2 >= 0 and threshold2 <= 1, "threshold2 must be between 0 and 1."
+
         # Make sure layer_key is a list internally
         if isinstance(layer_key, str):
             layer_keys = [layer_key]
@@ -1899,7 +1927,8 @@ class PreprocessingAccessor:
                 next_segmentation.squeeze(),
                 label1=label_1,
                 label2=label_2,
-                threshold=threshold,
+                threshold1=threshold1,
+                threshold2=threshold2,
             )
 
             # Update label mapping
@@ -2082,13 +2111,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.
@@ -2117,10 +2149,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(

{spatialproteomics-0.7.10 → spatialproteomics-0.8.1}/spatialproteomics/pp/utils.py

@@ -95,62 +95,144 @@ def _relabel_cells(segmentation: np.ndarray) -> Tuple[np.ndarray, dict]:
     return segmentation_relabeled, value_map
 
 
-def _merge_segmentation(s1: np.ndarray, s2: np.ndarray, label1: int = 1, label2: int = 2, threshold: float = 1.0):
+def _exceeds_overlap(i2: np.ndarray, s1: np.ndarray, n2: np.ndarray, p1: list, threshold2: float) -> np.ndarray:
+    """
+    Return a boolean mask over i2 indicating which s2 regions should be KEPT
+    (i.e. do not exceed the overlap threshold with any s1 cell).
+
+    Instead of looping per s2 label, this builds a joint overlap table in one pass
+    over the image, then checks the threshold condition vectorized.
+
+    Parameters
+    ----------
+    i2 : np.ndarray
+        Array of candidate s2 labels (already filtered by threshold1).
+    s1 : np.ndarray
+        First segmentation mask.
+    n2 : np.ndarray
+        Relabeled second segmentation mask.
+    p1 : list
+        Region properties of s1 (from skimage.measure.regionprops).
+    threshold2 : float
+        Maximum fraction of any s1 cell's area that may overlap with an s2 region
+        before that s2 region is excluded.
+    """
+    # Only consider pixels where both masks are non-zero
+    both = (s1 > 0) & (n2 > 0)
+    s1_vals = s1[both]
+    n2_vals = n2[both]
+
+    # Precompute s1 cell areas from regionprops
+    s1_areas = {p.label: p.area for p in p1}
+
+    # Count overlapping pixels for each (s1_label, s2_label) pair
+    pairs, counts = np.unique(np.stack([s1_vals, n2_vals], axis=1), axis=0, return_counts=True)
+
+    # Filter to only pairs where the s2 label is a candidate in i2
+    i2_set = set(i2.tolist())
+    mask = np.array([p[1] in i2_set for p in pairs])
+    pairs, counts = pairs[mask], counts[mask]
+
+    # Compute overlap fraction: intersection / s1 cell area
+    s1_areas_arr = np.array([s1_areas[p[0]] for p in pairs])
+    fractions = counts / s1_areas_arr
+
+    # Find s2 labels where any s1 cell exceeds the threshold
+    exceeds = pairs[fractions >= threshold2, 1]
+    exceeded_set = set(exceeds.tolist())
+
+    return np.array([label for label in i2 if label not in exceeded_set])
+
+
+def _merge_segmentation(
+    s1: np.ndarray,
+    s2: np.ndarray,
+    label1: int = 1,
+    label2: int = 2,
+    threshold1: float = 1.0,
+    threshold2: float = 1.0,
+) -> Tuple[np.ndarray, dict]:
     """
     Merge two segmentation masks based on specified criteria.
 
+    Regions from s1 are always included (subject to threshold1). Regions from s2 are only
+    included if they do not overlap with s1 beyond the threshold1 and threshold2 criteria.
+
     Parameters
     ----------
     s1 : numpy.ndarray
-        First segmentation mask.
+        First segmentation mask. Regions here take priority over s2.
     s2 : numpy.ndarray
-        Second segmentation mask.
+        Second segmentation mask. Regions are only added where they don't conflict with s1.
     label1 : int
-        Label for regions from the first mask in the final merged mask. Default is 1.
+        Label assigned to s1 regions in the output mapping. Default is 1.
     label2 : int
-        Label for regions from the second mask in the final merged mask. Default is 2.
-    threshold : float, optional
-        Threshold for area ratio of intersection over union for merging regions.
-        Default is 1.0, meaning all regions from the second mask are merged.
-
+        Label assigned to s2 regions in the output mapping. Default is 2.
+    threshold1 : float, optional
+        Minimum fraction of an s2 region's area that must be preserved (i.e. not masked by s1)
+        for it to be included. Default is 1.0, meaning only fully non-overlapping s2 regions
+        are included.
+    threshold2 : float, optional
+        Maximum fraction of any s1 cell's area that may overlap with an s2 region before
+        that s2 region is excluded. Default is 1.0, meaning an s2 region is only excluded
+        if it fully contains an s1 cell.
     Returns
     -------
     numpy.ndarray
-        Merged segmentation mask.
+        Merged segmentation mask with sequentially relabeled regions.
     dict
-        Mapping of labels from the merged mask to the original labels.
-
+        Mapping of labels in the final mask to their origin: label1 (from s1) or label2 (from s2).
     Notes
     -----
-    This function assumes that `s1` and `s2` are 2D segmentation masks with integer labels.
+    This function assumes that s1 and s2 are 2D segmentation masks with integer labels,
+    where 0 represents background.
     """
     s1 = s1.squeeze()
     s2 = s2.squeeze()
 
-    n2, fmap, bmap = relabel_sequential(s2, offset=s1.max() + 1)
+    # Relabel s2 so its labels don't collide with s1's labels
+    n2, fmap, _ = relabel_sequential(s2, offset=s1.max() + 1)
+
+    # Build a combined mask: start with s1, then fill background pixels with s2 regions.
+    # This means s1 always takes priority — s2 only fills where s1 has no label.
     s3 = s1.copy()
     s3[np.logical_and(n2 > 0, s1 == 0)] = n2[np.logical_and(n2 > 0, s1 == 0)]
 
+    # Collect region properties and labels for filtering
     p1 = regionprops(s1)
     p2 = regionprops(n2)
     p3 = regionprops(s3)
-
     l1 = [p.label for p in p1]
     l2 = [p.label for p in p2]
-    l3 = [p.label for p in p3]
+    l3 = [p.label for p in p3]  # labels still present after combining s1 and s2
 
-    # compute intersections
+    # i1: s1 regions that survived into the combined mask (should always be all of them)
+    # i2: s2 regions that survived into the combined mask (may be partial if they overlapped with s1)
     i1 = list(set(l1) & set(l3))
     i2 = list(set(l2) & set(l3))
 
+    # threshold1 filter: only keep s2 regions where the surviving area (in s3) is at least
+    # threshold1 fraction of the original s2 area. Regions heavily masked by s1 are dropped.
     area_ratio = np.array([p.area for p in p3 if p.label in i2]) / np.array([p.area for p in p2 if p.label in i2])
-    i2 = np.array(i2)[area_ratio >= threshold]
-    selected_cells = np.concatenate([np.array(i1), i2])
+    i2 = np.array(i2)[area_ratio >= threshold1]
+
+    # threshold2 filter: exclude s2 regions that overlap too much with any single s1 cell.
+    # If an s2 region covers >= threshold2 of an s1 cell's area, it's considered conflicting
+    # and dropped — even if it passed the threshold1 check.
+    i2 = _exceeds_overlap(i2, s1, n2, p1, threshold2)
 
-    # make final mask
+    # Combine selected s1 and s2 region labels, then clean and relabel the mask
+    selected_cells = np.concatenate([np.array(i1), i2])
     clean_mask = _remove_unlabeled_cells(s3, selected_cells)
-    final_mask, fmap, bmap = relabel_sequential(clean_mask)
-    mapping = dict(zip([fmap[i] for i in selected_cells.astype(int)], [label1] * len(i1) + [label2] * len(i2)))
+    final_mask, fmap, _ = relabel_sequential(clean_mask)
+
+    # Build a mapping from final mask labels back to their origin (label1 or label2)
+    mapping = dict(
+        zip(
+            [fmap[i] for i in selected_cells.astype(int)],
+            [label1] * len(i1) + [label2] * len(i2),
+        )
+    )
 
     return final_mask, mapping
 

{spatialproteomics-0.7.10 → spatialproteomics-0.8.1/spatialproteomics.egg-info}/PKG-INFO

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