spatial-aim 1.5.2__tar.gz → 1.5.4__tar.gz

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-aim
-Version: 1.5.2
+Version: 1.5.4
 Summary: SpatialAIM — annotation-independent mapping of scRNA-seq references onto high-resolution spatial transcriptomics
 Author-email: Dominik Pysch <dominik.pysch@fau.de>
 License:                     GNU GENERAL PUBLIC LICENSE

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/deploy/demo/Dockerfile

@@ -36,8 +36,11 @@ COPY deploy/demo/legal ./legal
 
 RUN useradd --create-home --uid 10001 spatialaim
 USER spatialaim
-# numba (via scanpy/umap) caches compiled code next to the sources by default.
-ENV NUMBA_CACHE_DIR=/tmp/numba \
+# The container runs read-only with only /tmp writable: numba (via scanpy/umap)
+# caches compiled code next to the sources by default, and anything else that
+# writes to the home folder (~/.streamlit, ~/.cache) lands in /tmp too.
+ENV HOME=/tmp \
+    NUMBA_CACHE_DIR=/tmp/numba \
     MPLCONFIGDIR=/tmp/matplotlib
 
 EXPOSE 8501

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/deploy/demo/README.md

@@ -68,7 +68,7 @@ workflow run). The pages are linked from the sidebar footer on every page (`/imp
 ## 4. Run
 
 ```bash
-docker run -d --name spatialaim-demo --restart unless-stopped -p 127.0.0.1:8501:8501 -v /srv/spatialaim-demo/data:/data:ro --read-only --tmpfs /tmp --tmpfs /home/spatialaim --memory 16g --cpus 4 ghcr.io/domipysch/spatialaim-demo:latest
+docker run -d --name spatialaim-demo --restart unless-stopped -p 127.0.0.1:8501:8501 -v /testmount2/zi69hebi/spatialaim-demo/data:/data:ro --read-only --tmpfs /tmp --memory 16g --cpus 4 ghcr.io/domipysch/spatialaim-demo:latest
 ```
 
 The container serves plain HTTP on port 8501; `127.0.0.1:` keeps it reachable only for the

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/src/spatial_aim.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-aim
-Version: 1.5.2
+Version: 1.5.4
 Summary: SpatialAIM — annotation-independent mapping of scRNA-seq references onto high-resolution spatial transcriptomics
 Author-email: Dominik Pysch <dominik.pysch@fau.de>
 License:                     GNU GENERAL PUBLIC LICENSE

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/src/spatial_aim.egg-info/SOURCES.txt

@@ -68,6 +68,10 @@ src/spatialaim/data/curate_datasets/curate_07_mouse_mpfc.py
 src/spatialaim/data/curate_datasets/curate_08_mouse_visual_cortex.py
 src/spatialaim/data/curate_datasets/curate_09_human_breast_cancer.py
 src/spatialaim/data/curate_datasets/curate_10_human_mtg.py
+src/spatialaim/data/curate_datasets/curate_11_human_crc.py
+src/spatialaim/data/curate_datasets/curate_12_human_ovarian_cancer.py
+src/spatialaim/data/curate_datasets/curate_13_human_carotid_plaque.py
+src/spatialaim/data/curate_datasets/curate_14_mouse_kidney_iri.py
 src/spatialaim/data/curate_datasets/dump_retina_counts.R
 src/spatialaim/data/curate_datasets/environment_retina_qs.yml
 src/spatialaim/data/validate/__init__.py
@@ -104,6 +108,7 @@ src/spatialaim/gui/views/cell_type_modal.py
 src/spatialaim/gui/views/choose_k.py
 src/spatialaim/gui/views/compare_tab.py
 src/spatialaim/gui/views/controls.py
+src/spatialaim/gui/views/gene_modal.py
 src/spatialaim/gui/views/mapper_tab.py
 src/spatialaim/gui/views/overview.py
 src/spatialaim/gui/views/pages.py

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/src/spatial_aim.egg-info/scm_file_list.json

@@ -57,6 +57,10 @@
     "src/spatialaim/data/curate_datasets/curate_08_mouse_visual_cortex.py",
     "src/spatialaim/data/curate_datasets/curate_09_human_breast_cancer.py",
     "src/spatialaim/data/curate_datasets/curate_10_human_mtg.py",
+    "src/spatialaim/data/curate_datasets/curate_11_human_crc.py",
+    "src/spatialaim/data/curate_datasets/curate_12_human_ovarian_cancer.py",
+    "src/spatialaim/data/curate_datasets/curate_13_human_carotid_plaque.py",
+    "src/spatialaim/data/curate_datasets/curate_14_mouse_kidney_iri.py",
     "src/spatialaim/data/curate_datasets/dump_retina_counts.R",
     "src/spatialaim/data/curate_datasets/environment_retina_qs.yml",
     "src/spatialaim/data/validate/__init__.py",
@@ -93,6 +97,7 @@
     "src/spatialaim/gui/views/choose_k.py",
     "src/spatialaim/gui/views/compare_tab.py",
     "src/spatialaim/gui/views/controls.py",
+    "src/spatialaim/gui/views/gene_modal.py",
     "src/spatialaim/gui/views/mapper_tab.py",
     "src/spatialaim/gui/views/overview.py",
     "src/spatialaim/gui/views/pages.py",

spatial_aim-1.5.4/src/spatial_aim.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.5.4",
+  "distance": 0,
+  "node": "gdd5395362e0c4b4e871535e0cebf530345d63a2d",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-11-09"
+}

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/src/spatialaim/data/curate_datasets/README.md

@@ -12,3 +12,16 @@ Only minor pre-processing (deleting near-empty columns etc.) has been applied.
 No normalization or log operations are applied to the data, as we are working on raw counts.
 
 These 10 script are fully generated by AI (Claude Opus 5.5).
+
+## GUI use-case candidates (11-14)
+
+`curate_11` to `curate_14` build candidate pairs for the GUI section (scRNA + imaging-based ST, all
+Xenium with segmentation masks). They write to `Data/03_GUI`, not to `01_Datasets_Paper`, and are
+not part of Experiment 1.
+
+| Script | Pair(s) | Sources |
+|---|---|---|
+| `curate_11_human_crc.py` | `11_human-crc-p2`, `11_human-crc-p5` | Oliveira et al. 2025, Flex + 10x Xenium |
+| `curate_12_human_ovarian_cancer.py` | `12_human-ovarian-cancer` (3 x 3 mm crop) | 10x Flex + Xenium Prime 5K |
+| `curate_13_human_carotid_plaque.py` | `13_human-carotid-plaque` | Nat Commun 2025, Zenodo scRNA + GEO Xenium |
+| `curate_14_mouse_kidney_iri.py` | `14_mouse-kidney-iri` | Kirita et al. 2020 snRNA + Humphreys lab Xenium |

{spatial_aim-1.5.2 → spatial_aim-1.5.4}/src/spatialaim/data/curate_datasets/_segmentation.py

@@ -300,7 +300,8 @@ def extract_remote_zip_members(
         info = next(
             i
             for i in archive.infolist()
-            if i.filename.endswith("/" + name) and "__MACOSX" not in i.filename
+            if (i.filename == name or i.filename.endswith("/" + name))
+            and "__MACOSX" not in i.filename
         )
         logger.info(
             "  extract %s (%.0f MB compressed) from %s",

spatial_aim-1.5.4/src/spatialaim/data/curate_datasets/curate_11_human_crc.py

@@ -0,0 +1,338 @@
+"""
+Build dataset 11_human-crc: two patient-matched pairs (P2, P5), each a Flex
+reference + one Xenium slice, for the GUI use case (Results section 5). Not part
+of the Experiment 1 corpus, so it is written to Data/03_GUI by default, not to
+01_Datasets_Paper.
+
+Pairs covered (one per patient, same_paper):
+    11_human-crc-p2 <-> 11_human-crc-p2
+    11_human-crc-p5 <-> 11_human-crc-p5
+
+Paper: Oliveira et al., Nature Genetics 2025, "High-definition spatial
+transcriptomic profiling of immune cell populations in colorectal cancer"
+(https://doi.org/10.1038/s41588-025-02193-3; GEO SuperSeries GSE280318). Per
+patient, both sides come from one FFPE block: the Flex reference was dissociated
+from curls serial to the sections the spatial assays used.
+
+Downloads per patient: four Flex libraries, the authors' metadata and three
+Xenium files (P2 ~460 MB, P5 ~330 MB; the segmentation is most of it).
+
+------------------------------------------------------------------------------
+scRNA  11_human-crc-p{2,5}.h5ad   —  Chromium Flex
+------------------------------------------------------------------------------
+  counts      GSE280311 (Flex). Each patient is one probe barcode in four
+              libraries: P2CRC = BC1 in pool 1 (GSM8594533..36, *_P1L{1..4}_*),
+              P5CRC = BC3 in pool 2 (GSM8594537..40, *_P2L{1..4}_*);
+              files *_count_filtered_feature_bc_matrix.h5
+  annotation  github.com/10XGenomics/HumanColonCancer_VisiumHD,
+              MetaData/SingleCell_MetaData.csv.gz (all 8 Flex samples)
+
+The authors' barcodes carry the cellranger-aggr index as suffix (pool 1: two
+samples per library, pool 2: four), so P2CRC's libraries are aggr samples
+1, 3, 5, 7 and P5CRC's 11, 15, 19, 23. A patient's barcodes match its four
+matrices one to one; the authors' QC (``QCFilter == "Keep"``) selects the cells,
+kept in metadata order: P2 41933 -> 35673, P5 24615 -> 23823.
+
+Curation:
+  * obs  index = the authors' ``Barcode``; ``Level1`` and ``Level2`` verbatim.
+           Level2 was sub-clustered within Level1 on a 15 % sketch and then
+           extended to all cells, so it is only mostly nested (P2: 3.8 % of
+           cells sit outside their Level2's main Level1); kept as published.
+  * X    = the four matrices' columns for those barcodes, float32
+  * var  index = gene symbols uppercased; three symbols occur twice and are
+           summed onto the first occurrence, 18082 -> 18079
+
+------------------------------------------------------------------------------
+ST  11_human-crc-p{2,5}.h5ad   —  Xenium, 422 genes (colon panel + 100 add-on)
+------------------------------------------------------------------------------
+  https://cf.10xgenomics.com/samples/xenium/2.0.0/
+  Xenium_V1_Human_Colon_Cancer_P{2,5}_CRC_Add_on_FFPE/  (the GSE280314 samples)
+    ..._cell_feature_matrix.h5, ..._cells.csv.gz, ..._cells.zarr.zip
+
+The full outs bundles (14-16 GB) are unnecessary. The authors' repo lists ~1.1M
+cells per slide for a larger Xenium region; the public 10x releases used here
+have P2 340837 and P5 275998 cells and carry no cell-type labels.
+
+Curation:
+  * cells in the Xenium output's own order; obs index = Xenium ``cell_id``
+  * cells with fewer than 10 transcripts over the 422 genes are dropped
+           (P2 340837 -> 331383, P5 275998 -> 270956): mapped, they form
+           spurious states of near-empty cells
+  * X    = the 422 ``Gene Expression`` features; unassigned / negative control
+           codewords and probes are dropped
+  * var  index = the feature names uppercased
+  * obsm["spatial"] = ``x_centroid``, ``y_centroid`` (um), float32
+  * no cell-type column: the paper annotated Visium HD bins, not Xenium cells
+  * obs["segmentation_id"], uns["segmentation_pixel_size_um"] = 0.2125 and the
+           mask ST/Segmentation/<name>.tif: cells.zarr.zip masks/1, copied as
+           is. Its labels are the row of the zarr ``cell_id`` array plus one,
+           which is the cells.csv order, so segmentation_id = that row + 1
+           (the dropped cells' labels stay in the mask). Xenium 2.0
+           multimodal segmentation (boundary stain, then interior stain, then
+           5 um nucleus expansion).
+
+------------------------------------------------------------------------------
+Usage
+------------------------------------------------------------------------------
+    python -m spatialaim.data.curate_datasets.curate_11_human_crc
+    python -m spatialaim.data.curate_datasets.curate_11_human_crc --out-dir <root>
+
+Sources are downloaded to a temporary folder below --out-dir and deleted again.
+Set SPATIALAIM_KEEP_DOWNLOADS=1 to keep (and on a re-run reuse) them in
+<out-dir>/_downloads/11_human-crc-p{2,5} instead. The 4-5 GB masks are copied
+band by band, never held whole.
+"""
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import anndata as ad
+import numpy as np
+import pandas as pd
+from scipy.sparse import hstack
+
+from . import _common, _segmentation
+from .curate_09_human_breast_cancer import (
+    GENE_EXPRESSION,
+    MASK_PIXEL_UM,
+    _check_shape,
+    _copy_cell_mask,
+    _fold_duplicates,
+    _read_10x_h5,
+)
+
+logger = logging.getLogger(__name__)
+
+OUT_ROOT = _common.DATA_ROOT / "03_GUI"
+
+GEO_SAMPLES = "https://ftp.ncbi.nlm.nih.gov/geo/samples/GSM8594nnn"
+REPO = "https://raw.githubusercontent.com/10XGenomics/HumanColonCancer_VisiumHD/main"
+SC_META_URL = f"{REPO}/MetaData/SingleCell_MetaData.csv.gz"
+SC_META_BYTES = 7_288_481
+XENIUM = "https://cf.10xgenomics.com/samples/xenium/2.0.0"
+SC_GENES = 18079
+ST_GENES = 422
+MIN_TRANSCRIPTS = 10
+
+
+@dataclass(frozen=True)
+class Patient:
+    patient: str  # the metadata's Patient value, e.g. "P5CRC"
+    probe_barcode: str
+    # (GSM, library, aggr index of this patient in the authors' barcodes, bytes)
+    libraries: tuple[tuple[str, str, int, int], ...]
+    n_cells: int
+    n_spots: int  # all Xenium cells
+    n_spots_kept: int  # with >= MIN_TRANSCRIPTS
+    # bytes of cell_feature_matrix.h5, cells.csv.gz, cells.zarr.zip
+    xenium_bytes: tuple[int, int, int]
+
+    @property
+    def name(self) -> str:
+        return f"11_human-crc-{self.patient[:2].lower()}"
+
+    @property
+    def xenium_prefix(self) -> str:
+        sample = f"Xenium_V1_Human_Colon_Cancer_{self.patient[:2]}_CRC_Add_on_FFPE"
+        return f"{XENIUM}/{sample}/{sample}"
+
+
+PATIENTS = (
+    Patient(
+        patient="P2CRC",
+        probe_barcode="BC1",
+        libraries=(
+            ("GSM8594533", "P1L1", 1, 26_874_789),
+            ("GSM8594534", "P1L2", 3, 27_306_204),
+            ("GSM8594535", "P1L3", 5, 27_294_024),
+            ("GSM8594536", "P1L4", 7, 26_361_551),
+        ),
+        n_cells=35673,
+        n_spots=340837,
+        n_spots_kept=331383,
+        xenium_bytes=(21_438_841, 18_562_765, 291_928_061),
+    ),
+    Patient(
+        patient="P5CRC",
+        probe_barcode="BC3",
+        libraries=(
+            ("GSM8594537", "P2L1", 11, 9_062_161),
+            ("GSM8594538", "P2L2", 15, 9_081_608),
+            ("GSM8594539", "P2L3", 19, 9_784_770),
+            ("GSM8594540", "P2L4", 23, 9_630_123),
+        ),
+        n_cells=23823,
+        n_spots=275998,
+        n_spots_kept=270956,
+        xenium_bytes=(15_479_659, 14_803_142, 248_276_261),
+    ),
+)
+
+
+# --------------------------------------------------------------------------- #
+# scRNA
+# --------------------------------------------------------------------------- #
+def build_scrna(p: Patient, tmp_dir: Path, out_path: Path) -> None:
+    logger.info("scRNA %s — Chromium Flex, patient %s (GSE280311)", p.name, p.patient)
+    meta_file = _common.download(
+        SC_META_URL,
+        tmp_dir / "SingleCell_MetaData.csv.gz",
+        expected_bytes=SC_META_BYTES,
+    )
+    meta = pd.read_csv(meta_file)
+    meta = meta[meta["Patient"] == p.patient]
+    logger.info("  read    metadata (%d %s barcodes)", len(meta), p.patient)
+
+    blocks = []
+    barcodes: list[str] = []
+    names: np.ndarray | None = None
+    for gsm, library, aggr, size in p.libraries:
+        file_name = (
+            f"{gsm}_{library}_{p.patient}_{p.probe_barcode}"
+            "_count_filtered_feature_bc_matrix.h5"
+        )
+        path = _common.download(
+            f"{GEO_SAMPLES}/{gsm}/suppl/{file_name}",
+            tmp_dir / file_name,
+            expected_bytes=size,
+        )
+        matrix, library_barcodes, library_names, _ = _read_10x_h5(path)
+        if names is not None and not np.array_equal(names, library_names):
+            raise ValueError(f"{file_name}: gene list differs from the first library")
+        names = library_names
+        blocks.append(matrix)
+        barcodes.extend(b.split("-")[0] + f"-{aggr}" for b in library_barcodes)
+    if names is None:
+        raise ValueError(f"{p.patient}: no libraries listed")
+    matrix = hstack(blocks).tocsc()
+    logger.info("  read    %d libraries (%d x %d)", len(blocks), *matrix.shape)
+
+    if set(barcodes) != set(meta["Barcode"]):
+        raise ValueError("the four libraries no longer match the metadata's barcodes")
+    meta = meta[meta["QCFilter"] == "Keep"]
+    position = pd.Index(barcodes).get_indexer(meta["Barcode"].to_numpy())
+
+    X = matrix[:, position].T.tocsr().astype(np.float32)
+    X, genes = _fold_duplicates(X, np.asarray(_common.uppercase(names)))
+    logger.info("  genes   %d -> %d (duplicate symbols summed)", len(names), len(genes))
+
+    adata = ad.AnnData(
+        X=X,
+        obs=pd.DataFrame(
+            {
+                level: pd.Categorical(meta[level].astype(str).to_numpy())
+                for level in ("Level1", "Level2")
+            },
+            index=pd.Index(meta["Barcode"].to_numpy(), name=None),
+        ),
+        var=pd.DataFrame(index=pd.Index(genes, name=None)),
+    )
+    _check_shape(adata, (p.n_cells, SC_GENES), "scRNA")
+    for level in ("Level1", "Level2"):
+        logger.info("  %s: %d types", level, adata.obs[level].cat.categories.size)
+    _common.write(adata, out_path)
+
+
+# --------------------------------------------------------------------------- #
+# ST
+# --------------------------------------------------------------------------- #
+def build_st(p: Patient, tmp_dir: Path, st_dir: Path) -> None:
+    logger.info(
+        "ST %s — Xenium human colon cancer %s (GSE280314)", p.name, p.patient[:2]
+    )
+    tag = f"Xenium_{p.patient[:2]}"
+    counts_bytes, cells_bytes, masks_bytes = p.xenium_bytes
+    counts_file = _common.download(
+        f"{p.xenium_prefix}_cell_feature_matrix.h5",
+        tmp_dir / f"{tag}_cell_feature_matrix.h5",
+        expected_bytes=counts_bytes,
+    )
+    cells_file = _common.download(
+        f"{p.xenium_prefix}_cells.csv.gz",
+        tmp_dir / f"{tag}_cells.csv.gz",
+        expected_bytes=cells_bytes,
+    )
+    masks_file = _common.download(
+        f"{p.xenium_prefix}_cells.zarr.zip",
+        tmp_dir / f"{tag}_cells.zarr.zip",
+        expected_bytes=masks_bytes,
+    )
+
+    matrix, barcodes, names, types = _read_10x_h5(counts_file)
+    genes = types == GENE_EXPRESSION
+    logger.info(
+        "  read    matrix (%d x %d, %d gene features)", *matrix.shape, int(genes.sum())
+    )
+
+    cells = pd.read_csv(cells_file)
+    if not np.array_equal(cells["cell_id"].astype(str).to_numpy(), barcodes):
+        raise ValueError("cells.csv.gz and the matrix no longer share a cell order")
+
+    adata = ad.AnnData(
+        X=matrix[genes].T.tocsr().astype(np.float32),
+        obs=pd.DataFrame(index=pd.Index(barcodes, name=None)),
+        var=pd.DataFrame(index=pd.Index(_common.uppercase(names[genes]), name=None)),
+    )
+    adata.obsm["spatial"] = np.column_stack(
+        [cells["x_centroid"].to_numpy(), cells["y_centroid"].to_numpy()]
+    ).astype(np.float32)
+    _check_shape(adata, (p.n_spots, ST_GENES), "ST")
+
+    _check_mask_order(masks_file, barcodes)
+    _copy_cell_mask(masks_file, _segmentation.mask_path(st_dir, p.name), adata.n_obs)
+    _segmentation.annotate(adata, np.arange(1, adata.n_obs + 1), MASK_PIXEL_UM)
+
+    keep = np.asarray(adata.X.sum(axis=1)).ravel() >= MIN_TRANSCRIPTS
+    adata = adata[keep].copy()
+    logger.info(
+        "  cells   %d -> %d (>= %d transcripts)",
+        len(keep),
+        adata.n_obs,
+        MIN_TRANSCRIPTS,
+    )
+    _check_shape(adata, (p.n_spots_kept, ST_GENES), "ST")
+    _common.write(adata, st_dir / f"{p.name}.h5ad")
+
+
+def _check_mask_order(zarr_zip: Path, barcodes: np.ndarray) -> None:
+    """Mask label i+1 is the zarr's cell_id row i; assert that row order = ours."""
+    import zarr
+
+    group: Any = zarr.open_group(
+        zarr.storage.ZipStore(str(zarr_zip), mode="r"), mode="r"
+    )
+    rows = np.asarray(group["cell_id"][:])
+    # Xenium string ids: the prefix integer in base 16 written with letters a..p
+    decoded = np.array(
+        [
+            [int(prefix.translate(_HEX_LETTERS), 16), int(suffix)]
+            for prefix, suffix in (b.split("-") for b in barcodes)
+        ],
+        dtype=rows.dtype,
+    )
+    if not np.array_equal(decoded, rows):
+        raise ValueError("the mask's cell_id rows no longer follow the cells.csv order")
+
+
+_HEX_LETTERS = str.maketrans("abcdefghijklmnop", "0123456789abcdef")
+
+
+# --------------------------------------------------------------------------- #
+def main() -> None:
+    _common.setup_logging()
+    parser = _common.build_parser(__doc__)
+    parser.set_defaults(out_dir=OUT_ROOT)
+    args = parser.parse_args()
+    sc_dir, st_dir = _common.prepare_dirs(args.out_dir)
+
+    for p in PATIENTS:
+        with _common.staging(args.out_dir, p.name) as tmp_dir:
+            build_scrna(p, tmp_dir, sc_dir / f"{p.name}.h5ad")
+            build_st(p, tmp_dir, st_dir)
+        logger.info("%s done", p.name)
+
+
+if __name__ == "__main__":
+    main()