spatialproteomics 0.8.5__tar.gz → 0.9.0__tar.gz

spatialproteomics-0.9.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__
+.pytest_cache
+format.sh
+tests/test_files/test2.zarr
+data
+Dev.ipynb
+Dev-checkpoint.ipynb
+.ipynb_checkpoints
+.DS_Store
+docs/notebooks/Interactivity.py
+docs/notebooks/.ipynb_checkpoints
+*.egg-info/
+*.egg
+dist/
+build/

spatialproteomics-0.9.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: spatialproteomics
+Version: 0.9.0
+Summary: Spatialproteomics is an interoperable toolbox for analyzing highly multiplexed fluorescence image data
+Author: Matthias Meyer-Bender, Harald Vohringer
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cffi>=1.15.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: numpy>=1.25
+Requires-Dist: opencv-python>=4.11.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-image>=0.25
+Requires-Dist: scikit-learn>=1.4.2
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: xarray>=2025.6.0
+Requires-Dist: zarr>=3.0.0
+Provides-Extra: all
+Requires-Dist: astir; extra == 'all'
+Requires-Dist: cellpose; extra == 'all'
+Requires-Dist: instanseg-torch>=0.1.0; extra == 'all'
+Requires-Dist: spatialdata; extra == 'all'
+Requires-Dist: spotiflow; extra == 'all'
+Requires-Dist: stardist; extra == 'all'
+Provides-Extra: anndata
+Requires-Dist: anndata>=0.10.0; extra == 'anndata'
+Provides-Extra: astir
+Requires-Dist: astir>=0.1.5; extra == 'astir'
+Provides-Extra: cellpose
+Requires-Dist: cellpose>=3.1.0; extra == 'cellpose'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.4; extra == 'dev'
+Requires-Dist: black[jupyter]>=22.6.0; extra == 'dev'
+Requires-Dist: flake8>=5.0.4; extra == 'dev'
+Requires-Dist: isort>=5.10.1; extra == 'dev'
+Requires-Dist: pytest-cov>=3.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.1.2; extra == 'dev'
+Requires-Dist: safety>=2.1.1; extra == 'dev'
+Requires-Dist: typing-extensions>=4.16; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ipython>=8.0.0; extra == 'docs'
+Requires-Dist: nbsphinx>=0.9; extra == 'docs'
+Requires-Dist: sphinx-book-theme>=0.0.39; extra == 'docs'
+Requires-Dist: sphinx-multiversion>=0.2.4; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
+Requires-Dist: sphinxcontrib-napoleon==0.7; extra == 'docs'
+Provides-Extra: instanseg
+Requires-Dist: instanseg-torch>=0.1.0; extra == 'instanseg'
+Provides-Extra: spatialdata
+Requires-Dist: spatialdata>=0.7.3; extra == 'spatialdata'
+Requires-Dist: zarr>=3.1.2; extra == 'spatialdata'
+Provides-Extra: spotiflow
+Requires-Dist: spotiflow; extra == 'spotiflow'
+Provides-Extra: stardist
+Requires-Dist: stardist>=0.9.1; extra == 'stardist'
+Description-Content-Type: text/markdown
+
+# spatialproteomics
+
+[![PyPI version](https://badge.fury.io/py/spatialproteomics.svg)](https://badge.fury.io/py/spatialproteomics)
+
+`Spatialproteomics` is an interoperable toolbox for analyzing highly multiplexed fluorescence image data. This analysis involves a sequence of steps, including segmentation, image processing, marker quantification, cell type classification, and neighborhood analysis. 
+
+<p align="center" width="100%">
+    <img src="docs/_static/img/figure_1.png" alt="Spatialproteomics orchestrates analysis workflows for highly multiplexed fluorescence images." style="width:70%;">
+</p>
+
+## Principles
+
+Multiplexed imaging data comprises at least 3 dimensions (i.e. `channels`, `x`, and `y`) and often contains additional data such as segmentation masks or cell type annotations associated with it. In `spatialproteomics`, we use `xarray` to create a data structure that keeps all of these data dimension in sync. This data structure can then be used to apply all sorts of operations to the data. Users can segment cells, perform different image processing steps, quantify protein expression, predict cell types, and plot their data in various ways. By providing researchers with those tools, `spatialproteomics` can be used to quickly explore highly multiplexed spatial proteomics data directly within jupyter notebooks.
+
+<p align="center" width="100%">
+    <img src="docs/_static/img/supplementary_figure_1.png" alt="The spatialproteomics data structure enables synchronized subsetting across shared dimensions." style="width:70%;">
+</p>
+
+## Getting Started
+
+Please refer to the [documentation](https://sagar87.github.io/spatialproteomics) for details on the API and tutorials.
+
+If you work with an AI coding assistant, point it to [llms.txt](https://sagar87.github.io/spatialproteomics/llms.txt) (an index of the documentation in Markdown) or [llms-full.txt](https://sagar87.github.io/spatialproteomics/llms-full.txt) (the complete documentation in a single file). Contributors using coding agents will find repository instructions in [AGENTS.md](AGENTS.md).
+
+## Installation
+
+To install `spatialproteomics`, first create a python environment and install the package using 
+
+```
+pip install spatialproteomics
+```
+
+The installation of the package should take less than a minute.
+
+## System Requirements
+### Hardware Requirements
+`spatialproteomics` requires only a standard computer with enough RAM to support the in-memory operations. Certain steps of the pipeline, such as segmentation, benefit from using a GPU.
+
+### Software Requirements
+The base version of `spatialproteomics` depends on the following packages:
+```
+xarray
+zarr
+numpy
+pandas
+scikit-image
+scikit-learn
+opencv-python
+matplotlib
+```
+
+## Citation
+> Meyer-Bender, M., Voehringer, H., Schniederjohann, C., Koziel, S., Chung, E., Popova, E., ... & Huber, W. (2026). Spatialproteomics: an interoperable toolbox for analyzing highly multiplexed fluorescence image data. Nature Methods, 1-10.

{spatialproteomics-0.8.5 → spatialproteomics-0.9.0}/README.md

@@ -10,7 +10,7 @@
 
 ## Principles
 
-Multiplexed imaging data comprises at least 3 dimensions (i.e. `channels`, `x`, and `y`) and has often additional data such as segmentation masks or cell type annotations associated with it. In `spatialproteomics`, we use `xarray` to create a data structure that keeps all of these data dimension in sync. This data structure can then be used to apply all sorts of operations to the data. Users can segment cells, perform different image processing steps, quantify protein expression, predict cell types, and plot their data in various ways. By providing researchers with those tools, `spatialproteomics` can be used to quickly explore highly multiplexed spatial proteomics data directly within jupyter notebooks.
+Multiplexed imaging data comprises at least 3 dimensions (i.e. `channels`, `x`, and `y`) and often contains additional data such as segmentation masks or cell type annotations associated with it. In `spatialproteomics`, we use `xarray` to create a data structure that keeps all of these data dimension in sync. This data structure can then be used to apply all sorts of operations to the data. Users can segment cells, perform different image processing steps, quantify protein expression, predict cell types, and plot their data in various ways. By providing researchers with those tools, `spatialproteomics` can be used to quickly explore highly multiplexed spatial proteomics data directly within jupyter notebooks.
 
 <p align="center" width="100%">
     <img src="docs/_static/img/supplementary_figure_1.png" alt="The spatialproteomics data structure enables synchronized subsetting across shared dimensions." style="width:70%;">
@@ -20,6 +20,8 @@ Multiplexed imaging data comprises at least 3 dimensions (i.e. `channels`, `x`,
 
 Please refer to the [documentation](https://sagar87.github.io/spatialproteomics) for details on the API and tutorials.
 
+If you work with an AI coding assistant, point it to [llms.txt](https://sagar87.github.io/spatialproteomics/llms.txt) (an index of the documentation in Markdown) or [llms-full.txt](https://sagar87.github.io/spatialproteomics/llms-full.txt) (the complete documentation in a single file). Contributors using coding agents will find repository instructions in [AGENTS.md](AGENTS.md).
+
 ## Installation
 
 To install `spatialproteomics`, first create a python environment and install the package using 
@@ -40,6 +42,7 @@ The base version of `spatialproteomics` depends on the following packages:
 xarray
 zarr
 numpy
+pandas
 scikit-image
 scikit-learn
 opencv-python

{spatialproteomics-0.8.5 → spatialproteomics-0.9.0}/pyproject.toml

@@ -1,31 +1,27 @@
 [project]
 name = "spatialproteomics"
-version = "0.8.5"
+version = "0.9.0"
 description = "Spatialproteomics is an interoperable toolbox for analyzing highly multiplexed fluorescence image data"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 authors = [
     {name="Matthias Meyer-Bender"},
     {name="Harald Vohringer"}
 ]
 dependencies = [
     "cffi>=1.15.0",
-    "xarray>=2024.0.0",
+    "xarray>=2025.6.0",
     "scikit-image>=0.25",
     "matplotlib>=3.8.0",
     "tqdm>=4.64.0",
     "scikit-learn>=1.4.2",
-    "zarr",  # note that if you use spatialdata, you should use zarr>=3.0.0
-    "numpy>=1.23",
+    "zarr>=3.0.0",  # zarr-python 3 reads and writes both zarr format v2 and v3
+    "numpy>=1.25",
     "opencv-python>=4.11.0",
+    "pandas>=2.2.2",
     "pyyaml>=6.0"
 ]
 
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["spatialproteomics*"]
-
-
 [project.optional-dependencies]
 docs = [
     "Sphinx>=7.0.0",
@@ -35,11 +31,13 @@ docs = [
     "sphinx-multiversion>=0.2.4",
     "IPython>=8.0.0",
 ]
-spatialdata = ["spatialdata>=0.4.0"]
+spatialdata = ["spatialdata>=0.7.3", "zarr>=3.1.2"]  # spatialdata needs zarr>=3.1.2 but does not declare it
 cellpose = ["cellpose>=3.1.0"]
 stardist = ["stardist>=0.9.1"]
-anndata = ["anndata"]
+anndata = ["anndata>=0.10.0"]
 astir = ["astir>=0.1.5"]
+spotiflow = ["spotiflow"]
+instanseg = ["instanseg-torch>=0.1.0"]
 dev = [
     "pytest>=7.1.2",
     "pytest-cov>=3.0.0",
@@ -48,12 +46,20 @@ dev = [
     "flake8>=5.0.4",
     "bandit>=1.7.4",
     "safety>=2.1.1",
+    "typing_extensions>=4.16",  # to avoid anndata issues
 ]
-all = ["spatialdata", "cellpose", "stardist", "astir"]
+all = ["spatialdata", "cellpose", "stardist", "astir", "spotiflow", "instanseg-torch>=0.1.0"]
 
 [build-system]
-requires = ["setuptools>=61.0,<81.0"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spatialproteomics"]
+
+[tool.hatch.build.targets.sdist]
+# only ship the package and the tests, not the docs (notebooks with outputs) or the data folder
+include = ["spatialproteomics", "tests", "README.md", "LICENSE"]
 
 
 [tool.black]

{spatialproteomics-0.8.5 → spatialproteomics-0.9.0}/spatialproteomics/__init__.py

@@ -48,7 +48,7 @@ from .pp import (
     threshold,
     transform_expression_matrix,
 )
-from .tl import ToolAccessor, astir, cellpose, mesmer, stardist
+from .tl import ToolAccessor, astir, cellpose, instanseg, stardist
 
 __all__ = [
     "load_image_data",
@@ -57,19 +57,17 @@ __all__ = [
     "PreprocessingAccessor",
     "LabelAccessor",
     "PlotAccessor",
-    "SegmentationAccessor",
     "ToolAccessor",
     "NeighborhoodAccessor",
     "Layers",
     "Dims",
     "Features",
     "Props",
-    "merge_segmentation",
     "percentage_positive",
     "is_positive",
     "cellpose",
     "stardist",
-    "mesmer",
+    "instanseg",
     "add_observations",
     "add_quantification",
     "apply",

{spatialproteomics-0.8.5 → spatialproteomics-0.9.0}/spatialproteomics/container.py

@@ -125,6 +125,7 @@ def read_from_spatialdata(
         spatial_data_object (spatialdata.SpatialData, str): The spatialdata object to read data from. If str, spatialdata is used to read the file from that path.
         image_key (str): The key of the image in the spatialdata object.
         segmentation_key (str): The key of the segmentation in the spatialdata object.
+        table_key (str): The key of the table in the spatialdata object. If it does not exist, the observations are computed from the segmentation.
         data_key (Optional[str], optional): The key for the image data in the spatialdata object. If None, the image_key will be used. Defaults to None.
         consolidate_segmentation (bool, optional): If True, the segmentation will be consolidated to only include cells that are present in the table. Defaults to False.
         cell_id (Optional[str], optional): The column name for the cell ID in the table. Defaults to "id".
@@ -132,12 +133,7 @@ def read_from_spatialdata(
         spatialproteomics_object (xr.Dataset): The spatialproteomics object.
     """
     import spatialdata
-    from spatialdata.transformations import (
-        Affine,
-        Identity,
-        Translation,
-        get_transformation,
-    )
+    from spatialdata.transformations import get_transformation
 
     if isinstance(spatial_data_object, str):
         spatial_data_object = spatialdata.read_zarr(spatial_data_object)
@@ -160,30 +156,20 @@ def read_from_spatialdata(
     y_coords = np.arange(image.shape[1])
     x_coords = np.arange(image.shape[2])
 
-    # apply transform if exists
-    if isinstance(transform, Identity):
-        pass  # Identity transform — do nothing
-
-    elif isinstance(transform, Translation):
-        shift_y, shift_x = transform.translation
-        y_coords = y_coords + shift_y
-        x_coords = x_coords + shift_x
-
-    elif isinstance(transform, Affine):
-        matrix = transform.matrix
-
-        a, b, c = matrix[0, :]
-        d, e, f = matrix[1, :]
-
-        if not np.isclose(b, 0) or not np.isclose(d, 0):
-            logger.warning(
-                "Affine transformation has shear components, which are not supported in spatialproteomics. Resetting coordinates to start from 0."
-            )
-        else:
-            x_coords = a * x_coords + c
-            y_coords = e * y_coords + f
+    # express any transform (Identity, Translation, Scale, Affine, Sequence, ...) as a 2D x/y affine.
+    # do not read transform.matrix directly: after a zarr round trip spatialdata stores the affine on
+    # the element axes, e.g. (c, y, x -> c, x, y), so the raw matrix is 4x4 and its row order varies.
+    matrix = transform.to_affine_matrix(input_axes=("x", "y"), output_axes=("x", "y"))
+    a, b, c = matrix[0, :]
+    d, e, f = matrix[1, :]
+    if not np.isclose(b, 0) or not np.isclose(d, 0):
+        logger.warning(
+            "Affine transformation has shear components, which are not supported in spatialproteomics. "
+            "Resetting coordinates to start from 0."
+        )
     else:
-        logger.warning(f"Unsupported transform {transform}, resetting coordinates for the spatialproteomics object.")
+        x_coords = a * x_coords + c
+        y_coords = e * y_coords + f
 
     # create the spatialproteomics object
     obj = load_image_data(image, channel_coords=markers, x_coords=x_coords, y_coords=y_coords)
@@ -213,35 +199,49 @@ def read_from_spatialdata(
             )  # Cast back to original dtype
 
         # if there are obs in the spatialdata object, we just use those and do not recompute them
-        add_obs_from_sdata = len(spatial_data_object.tables.keys()) > 0
+        add_obs_from_sdata = table_key in spatial_data_object.tables
+        if not add_obs_from_sdata and len(spatial_data_object.tables.keys()) > 0:
+            logger.warning(
+                f"Table key {table_key} not found in spatial data object (available keys: {list(spatial_data_object.tables.keys())}). "
+                "Computing the observations from the segmentation instead."
+            )
 
-        # obs (from anndata)
         if add_obs_from_sdata:
-            obs = spatial_data_object.tables[table_key].obs
-            if not consolidate_segmentation:
-                assert (
-                    obs.shape[0] == len(np.unique(segmentation)) - 1
-                ), f"The number of cells in the segmentation does not match the number of observations in the table.\nNumber of cells in the segmentation mask: {len(np.unique(segmentation)) - 1}\nNumber of observations: {obs.shape[0]}\nIf you wish to proceed regardless, set `consolidate_segmentation=True`, which will only keep cells appearing both in the segmentation mask and the table."
-            else:
-                # Consolidate segmentation to only include cells that are present in the table and the segmentation mask
-                # Step 1: Get IDs in both segmentation and obs
-                ids_in_segmentation = np.unique(segmentation).astype(int)
-                ids_in_obs = obs[cell_id].astype(int).unique()
+            # copying, so that the table of the input object is not modified
+            obs = spatial_data_object.tables[table_key].obs.copy()
+            assert (
+                cell_id in obs.columns
+            ), f"Column {cell_id} not found in the table. It is required to match the rows of the table to the cells in the segmentation mask. Available columns: {list(obs.columns)}."
+            obs[cell_id] = obs[cell_id].astype(int)
 
-                # Step 2: Keep only valid IDs (appear in both)
-                valid_ids = np.intersect1d(ids_in_segmentation, ids_in_obs, assume_unique=True)
+            if consolidate_segmentation:
+                # Consolidate segmentation to only include cells that are present in the table and the segmentation mask
+                # Step 1: Keep only valid IDs (appear in both the segmentation and the table)
+                valid_ids = np.intersect1d(np.unique(segmentation).astype(int), obs[cell_id].unique())
 
-                # Step 3: Filter segmentation mask to keep only valid IDs
+                # Step 2: Filter segmentation mask to keep only valid IDs
                 segmentation = np.where(np.isin(segmentation, valid_ids), segmentation, 0)
 
-                # Step 4: Filter obs to keep only cells present in segmentation
-                obs[cell_id] = obs[cell_id].astype(int)
-                obs = obs[obs[cell_id].isin(valid_ids)].copy()
+                # Step 3: Filter obs to keep only cells present in segmentation
+                obs = obs[obs[cell_id].isin(valid_ids)]
+
+            obj = obj.pp.add_segmentation(segmentation, add_obs=False, reindex=False)
+
+            # the cells coordinate is sorted by cell id, while the rows of the table can be in any order
+            # hence we align the table to the cells by their id instead of relying on the row order
+            cells = obj.coords[Dims.CELLS].values
+            table_ids = obs[cell_id].values
+            cells_without_row = np.setdiff1d(cells, table_ids)
+            rows_without_cell = np.setdiff1d(table_ids, cells)
+            has_duplicates = obs[cell_id].duplicated().any()
+            assert (
+                len(cells_without_row) == 0 and len(rows_without_cell) == 0 and not has_duplicates
+            ), f"The cell ids in the table do not match the cells in the segmentation mask.\nCells in the segmentation mask without a row in the table: {len(cells_without_row)}\nRows in the table without a cell in the segmentation mask: {len(rows_without_cell)}\nDuplicate ids in the table: {has_duplicates}\nIf you wish to proceed regardless, set `consolidate_segmentation=True`, which will only keep cells appearing both in the segmentation mask and the table."
+            obs = obs.set_index(cell_id, drop=False).loc[cells].rename_axis(None)
 
-            obj = obj.pp.add_segmentation(segmentation, add_obs=not add_obs_from_sdata, reindex=False)
             # next to adding the obs from the dataframe, we also add default obs to the object to ensure that obs includes the centroids
             obj = obj.pp.add_obs_from_dataframe(obs).pp.add_observations()
         else:
-            obj = obj.pp.add_segmentation(segmentation, add_obs=not add_obs_from_sdata, reindex=False)
+            obj = obj.pp.add_segmentation(segmentation, add_obs=True, reindex=False)
 
     return obj

{spatialproteomics-0.8.5 → spatialproteomics-0.9.0}/spatialproteomics/image_container/ImageContainer.py

@@ -1,12 +1,12 @@
 from typing import Dict
 
-import numpy as np
 import pandas as pd
 import xarray as xr
 from sklearn.cluster import KMeans
 from sklearn.preprocessing import StandardScaler
 
-from ..constants import COLORS, Features, Layers
+from ..constants import Features, Layers
+from ..pl.utils import _sample_colors
 
 
 class ImageContainer:
@@ -114,7 +114,7 @@ class ImageContainer:
         self.kmeans_df = kmeans_df
 
         # === ADDING CLUSTERS TO OBJECTS ===
-        colors = np.random.choice(COLORS, size=k, replace=False)
+        colors = _sample_colors(k)
         for id, sp_obj in self.objects.items():
             # obtaining the number of cells contained in the object we are currently looking at
             num_cells = sp_obj.sizes["cells"]
@@ -160,7 +160,7 @@ class ImageContainer:
             self._compute_dataframes_from_existing_neighborhoods(neighborhood_col=neighborhood_col)
 
         # computing the composition of neighborhoods (grouping by the neighborhood labels and summing them up)
-        neighborhood_composition = self.neighborhood_df
+        neighborhood_composition = self.neighborhood_df.copy()
         neighborhood_composition[Features.NEIGHBORHOODS] = self.kmeans_df[Features.NEIGHBORHOODS].values
 
         neighborhood_composition = neighborhood_composition.groupby(Features.NEIGHBORHOODS).mean()
@@ -189,7 +189,12 @@ class ImageContainer:
             assert (
                 neighborhood_col in self.objects[id].pp.get_layer_as_df().columns
             ), f"Column {neighborhood_col} not found in the object. Please set the column with the parameter 'neighborhood_col'. Available columns are {self.objects[id].pp.get_layer_as_df().columns}"
-            kmeans_df.append(self.objects[id].pp.get_layer_as_df()[[neighborhood_col]])
+            # the column is renamed, so that the cluster annotations can be accessed in the same way as after compute_neighborhoods()
+            kmeans_df.append(
+                self.objects[id]
+                .pp.get_layer_as_df()[[neighborhood_col]]
+                .rename(columns={neighborhood_col: Features.NEIGHBORHOODS})
+            )
 
         # replacing nans with 0s (this means that the ct was never called in that specific sample)
         neighborhood_df = pd.concat(neighborhood_df).fillna(0)