Refactor tests and add new annotation methods (need to add tests).

Author: newmana

CONTRIBUTING.rst

@@ -70,7 +70,7 @@ Ready to contribute? Here's how to set up `stlearn` for local development.
     $ conda create -n stlearn-dev python=3.12 --y
     $ conda activate stlearn-dev
     $ cd stlearn/
-    $ pip install -e .[dev,test]
+    $ pip install -e ".[dev,test]"
 
     You can also use conda to install these dependencies (after creating the environment):
     $ conda install -c conda-forge leidenalg python-igraph
@@ -80,7 +80,7 @@ Ready to contribute? Here's how to set up `stlearn` for local development.
     $ python -m venv stlearn-env
     $ source stlearn-env/bin/activate  # On Windows: stlearn-env\Scripts\activate
     $ cd stlearn/
-    $ pip install -e .[dev,test]
+    $ pip install -e ".[dev,test]"
 
 4. Create a branch for local development::
 

pyproject.toml

@@ -13,12 +13,13 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
+    "anndata>=0.10.0,<0.12",
     "bokeh>=3.7.0,<4.0",
     "click>=8.2.0,<9.0",
     "igraph>=1.0.0",
     "leidenalg>=0.11.0",
     "numba>=0.58.1",
-    "numpy>=1.26.0,<2.0",
+    "numpy>=1.26.0",
     "pillow>=11.0.0,<12.0",
     "scanpy>=1.11.0,<2.0",
     "scikit-image>=0.22.0",
@@ -28,6 +29,10 @@ dependencies = [
     "imageio>=2.37.0,<3.0",
     "scipy>=1.11.0,<2.0",
     "scikit-learn>=1.7.0,<2.0",
+    "spatialdata>=0.2.5,<0.3",
+    "spatialdata-io>=0.1.5,<0.2",
+    "geopandas>=1.0.0,<2.0",
+    "shapely>=2.0.0,<3.0",
 ]
 keywords = ["stlearn"]
 classifiers = [
@@ -86,9 +91,6 @@ include = ["stlearn", "stlearn.*"]
 [tool.setuptools.package-data]
 "*" = ["*"]
 
-[tool.setuptools.dynamic]
-dependencies = { file = ["requirements.txt"] }
-
 [tool.ruff]
 target-version = "py311"
 line-length = 88

stlearn/_compat.py

@@ -0,0 +1,16 @@
+import spatialdata as sd
+from anndata import AnnData
+
+
+def get_adata(data, table_key="table"):
+    """Extract AnnData from either SpatialData or AnnData input."""
+    if isinstance(data, sd.SpatialData):
+        return data.tables[table_key]
+    elif isinstance(data, AnnData):
+        return data
+    else:
+        raise TypeError(f"Expected SpatialData or AnnData, got {type(data)}")
+
+
+def is_spatial_data(data):
+    return isinstance(data, sd.SpatialData)

stlearn/add.py

@@ -1,10 +1,10 @@
 from .adds.add_deconvolution import add_deconvolution
-from .adds.add_image import image
-from .adds.add_labels import labels
+from .adds.image import image
+from .adds.labels import labels
 from .adds.add_loupe_clusters import add_loupe_clusters
-from .adds.add_lr import lr
+from .adds.lr import lr
 from .adds.add_mask import add_mask, apply_mask
-from .adds.add_positions import positions
+from .adds.positions import positions
 from .adds.annotation import annotation
 from .adds.parsing import parsing
 

stlearn/adds/add_image.py stlearn/adds/image.pystlearn/adds/add_image.py renamed to stlearn/adds/image.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+
+import geopandas as gpd
+
+from stlearn._compat import get_adata, is_spatial_data
+
+
+def polygon_annotations(
+    data,
+    annotations,
+    label_column="label",
+    obs_key="region",
+    spatial_key="spatial",
+    table_key="table",
+    copy=False,
+):
+    """
+    Annotate cells/spots by spatial overlap with polygon regions.
+
+    Parameters
+    ----------
+    data
+        SpatialData or AnnData object with spatial coordinates.
+    annotations
+        GeoDataFrame or path to GeoJSON/shapefile.
+    ...
+    """
+    adata = get_adata(data, table_key)
+    if copy:
+        adata = adata.copy()
+
+    if isinstance(annotations, (str, Path)):
+        annotations = gpd.read_file(annotations)
+
+    coords = adata.obsm[spatial_key]
+    points = gpd.GeoDataFrame(
+        index=adata.obs_names,
+        geometry=gpd.points_from_xy(coords[:, 0], coords[:, 1]),
+    )
+
+    joined = gpd.sjoin(points, annotations, how="left", predicate="within")
+    joined = joined[~joined.index.duplicated(keep="first")]
+    adata.obs[obs_key] = (
+        joined.reindex(adata.obs_names)[label_column].astype("category").values
+    )
+
+    # If SpatialData, also store the polygons as a shapes element
+    if is_spatial_data(data):
+        import spatialdata.models as models
+
+        parsed = models.ShapesModel.parse(annotations)
+        data.shapes[obs_key] = parsed
+        data.tables[table_key] = adata
+
+    n_annotated = adata.obs[obs_key].notna().sum()
+    print(
+        f"Added polygon annotations to adata.obs['{obs_key}']: "
+        f"{n_annotated}/{adata.n_obs} cells/spots annotated"
+    )
+
+    if is_spatial_data(data):
+        return data
+    return adata if copy else None

stlearn/adds/add_labels.py stlearn/adds/labels.pystlearn/adds/add_labels.py renamed to stlearn/adds/labels.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+
+import pandas as pd
+from anndata import AnnData
+
+
+def row_annotations(
+    adata: AnnData,
+    annotations: pd.DataFrame | str | Path,
+    join_column: str | None = None,
+    columns: list[str] | None = None,
+    copy: bool = False,
+) -> AnnData | None:
+    """\
+    Add annotations to adata.obs by joining on cell/spot identifiers.
+
+    Merges a DataFrame (or CSV file) into adata.obs based on a
+    shared index or column. Useful for adding metadata such as
+    manual labels, clinical annotations, or external classifications.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix.
+    annotations
+        DataFrame or path to a CSV/TSV file containing annotations.
+    join_column
+        Column in annotations to join on. If None, uses the
+        DataFrame index. The join is always against adata.obs_names.
+    columns
+        Subset of columns to add. If None, adds all columns
+        (excluding join_column).
+    copy
+        Return a copy instead of writing to adata.
+
+    Returns
+    -------
+    Depending on `copy`, returns or updates `adata` with new
+    columns added to `adata.obs`.
+    """
+    adata = adata.copy() if copy else adata
+
+    if isinstance(annotations, (str, Path)):
+        path = Path(annotations)
+        sep = "\t" if path.suffix in (".tsv", ".txt") else ","
+        annotations = pd.read_csv(path, sep=sep)
+
+    if join_column is not None:
+        if join_column not in annotations.columns:
+            raise ValueError(
+                f"Column '{join_column}' not found. "
+                f"Available: {list(annotations.columns)}"
+            )
+        annotations = annotations.set_index(join_column)
+
+    if columns is not None:
+        missing = [c for c in columns if c not in annotations.columns]
+        if missing:
+            raise ValueError(f"Columns not found: {missing}")
+        annotations = annotations[columns]
+
+    merged = annotations.reindex(adata.obs_names)
+
+    n_matched = merged.notna().any(axis=1).sum()
+    added_cols = list(merged.columns)
+
+    for col in added_cols:
+        adata.obs[col] = merged[col].values
+
+    print(
+        f"Added {len(added_cols)} column(s) to adata.obs: {added_cols}. "
+        f"{n_matched}/{adata.n_obs} cells/spots matched."
+    )
+
+    return adata if copy else None