Replace ML package and add annotations API

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations

.github/workflows/python-package.yml

@@ -19,9 +19,9 @@ jobs:
  python-version: [ "3.12", "3.13", "3.14" ]
 
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v6
  - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v6
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install dependencies

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+1.4.0 (2026-05-01)
+------------------
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.
+
+API and Bug Fixes:
+* Added row and polygon annotations.
+
 1.3.0 (2026-02-24)
 ------------------
 * Removed interactive stLearn/embedded web application.

docs/index.rst

@@ -38,6 +38,8 @@ undissociated tissue sample.
 Latest Additions
 ----------------
 
+.. include:: release_notes/1.4.0.rst
+
 .. include:: release_notes/1.3.0.rst
 
 .. include:: release_notes/1.2.2.rst

docs/release_notes/1.4.0.rst

@@ -0,0 +1,12 @@
+1.4.0 `2026-05-01`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rubric:: Features
+
+* Removed tensorflow and keras and replaced with torch and torchvision.
+* Added row and polygon annotations.
+
+.. rubric:: Bugs
+
+* Refactor of CCI implementation to removed string comparison for LR pairs lists and replaced with one set of two
+ packed 32 bit integers. Removed deduplication pass m^2 pass with a hash lookup.

docs/release_notes/index.rst

@@ -1,6 +1,8 @@
 Release Notes
 ===================================================
 
+.. include:: 1.4.0.rst
+
 .. include:: 1.3.0.rst
 
 .. include:: 1.2.2.rst

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stlearn"
-version = "1.3.0"
+version = "1.4.0"
 authors = [
  { name = "Genomics and Machine Learning Lab", email = "andrew.newman@uq.edu.au" },
 ]
@@ -13,24 +13,27 @@ readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "BSD license" }
 requires-python = ">=3.12"
 dependencies = [
- "anndata>=0.10.0,<0.12",
+ "anndata>=0.12.0",
  "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",
+ "numpy>=2.4.0",
  "pillow>=11.0.0,<12.0",
- "scanpy>=1.11.0,<2.0",
+ "scanpy>=1.12.0",
  "scikit-image>=0.22.0",
- "tensorflow>=2.14.1",
- "keras>=2.14.0",
  "pandas>=2.3.0",
  "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",
+ "scipy>=1.17.0,<2.0",
+ "scikit-learn>=1.8.0,<2.0",
+ "zarr>=3.1",
+ "dask>=2024.11.2",
+ "spatialdata>=0.7.0",
+ "spatialdata-io>=0.6.0",
+ "spatialdata-plot>=0.3.0",
+ "torch>=2.0",
+ "torchvision>=0.15",
  "geopandas>=1.0.0,<2.0",
  "shapely>=2.0.0,<3.0",
 ]

stlearn/add.py

@@ -6,7 +6,9 @@
 from .adds.labels import labels
 from .adds.lr import lr
 from .adds.parsing import parsing
+from .adds.polygon_annotations import polygon_annotations
 from .adds.positions import positions
+from .adds.row_annotations import row_annotations
 
 __all__ = [
  "image",
@@ -19,4 +21,6 @@
  "add_mask",
  "apply_mask",
  "add_loupe_clusters",
+ "row_annotations",
+ "polygon_annotations",
 ]

stlearn/adds/polygon_annotations.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import geopandas as gpd
+import spatialdata.models as models
 
 from stlearn._compat import get_adata, is_spatial_data
 
@@ -46,18 +47,11 @@ def polygon_annotations(
 
  # 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
+ else:
+ return adata if copy else None

stlearn/adds/row_annotations.py

@@ -2,6 +2,7 @@
 
 import pandas as pd
 from anndata import AnnData
+from pandas import DataFrame
 
 
 def row_annotations(
@@ -40,12 +41,78 @@ def row_annotations(
  """
  adata = adata.copy() if copy else adata
 
+ annotations = _read_annotations(annotations, columns, join_column)
+ merged = annotations.reindex(adata.obs_names)
+
+ added_cols = list(merged.columns)
+
+ for col in added_cols:
+ adata.obs[col] = merged[col].values
+
+ return adata if copy else None
+
+
+def row_annotations_proportions(
+ adata: AnnData,
+ annotations: pd.DataFrame | str | Path,
+ proportion_column_name: str = "cell_type",
+ 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 and then
+ assuming that the values are cell proportions picking the highest proportion.
+
+ 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.
+ proportion_column_name, default =
+ The column name to use to add the high proprotion value to
+ 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
+
+ annotations = _read_annotations(annotations, columns, join_column)
+ annotations = annotations.astype("float64")
+ labels = annotations.idxmax(axis=1)
+ adata.obs[proportion_column_name] = labels
+
+ return adata if copy else None
+
+
+def _read_annotations(
+ annotations: DataFrame | str | Path,
+ columns: list[str] | None,
+ join_column: str | None,
+) -> DataFrame:
  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 is None:
+ annotations = annotations.set_index(annotations.columns[0])
+ else:
  if join_column not in annotations.columns:
  raise ValueError(
  f"Column '{join_column}' not found. "
@@ -58,18 +125,4 @@ def row_annotations(
  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
+ return annotations