spatialrna 0.2.0__tar.gz → 0.3.0.dev0__tar.gz

spatialrna-0.3.0.dev0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: spatialrna
+Version: 0.3.0.dev0
+Summary: Spatial RNA graph data processing and analysis for single-molecule spatial transcriptomics (Xenium / Atera): graphs, GNN training / embedding, clustering, spatial maps.
+Author-email: Anne Pan <anne.pan@svi.edu.au>
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: zarr>=3
+Requires-Dist: numcodecs
+Requires-Dist: tqdm
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Provides-Extra: gnn
+Requires-Dist: torch; extra == "gnn"
+Requires-Dist: torch_geometric; extra == "gnn"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# spatialrna
+
+Spatial RNA graph data processing and analysis for single-molecule spatial
+transcriptomics (10x Xenium and Atera): transcripts → tile graphs and subgraphs →
+any graph neural network (train / validate / embed) → clusters → spatial maps.
+
+This continues the lab's `spatialrna` 0.2 (Ruqian Lyu) with the same scope and adds
+reading of raw Xenium / Atera outputs, zarr storage, a fast KD-tree graph builder,
+balanced grid tiling for large sections, and GPU Gaussian mixtures. The ISTIST
+pipeline builds on it with its own model (CrossSampleGAT), transcript-level
+annotation, statistics and an HTML report.
+
+## Install
+
+```bash
+pip install -e .                 # readers, graph builders, clustering, maps (no torch)
+pip install -e ".[gnn]"          # + SpatialRNA dataset, datasets, train_val
+                                 #   (install torch + PyG for your CUDA first)
+```
+
+Python >= 3.10, zarr-python >= 3.
+
+## Modules
+
+| module | what it does | 0.2 equivalent | needs torch |
+|---|---|---|---|
+| `readers` | Xenium / Atera `transcripts.zarr.zip` → transcripts (layout auto-detected) | – | no |
+| `graph_build` | KD-tree radius graphs, subgraph sampling, `plan_tiles` (grid tiling) | – | no |
+| `graph_zarr_io` | `SpatialRNA`: tiles (strips or grid) + padding → radius graphs → subgraphs, zarr I/O | `spatialrna.py` | yes |
+| `datasets` | `ZarrGraphDataset` over many tile / subgraph stores | `spatialrna_ondisk.py` | yes |
+| `train_val` | model-agnostic link-prediction training / validation, `embed_tile` | `train_val.py` | yes |
+| `cluster` | `gmm` (GPU or numpy EM), `kmeans` | `run_kmeans.py` | optional |
+| `viz` | `pixel_map`, two-panel overviews, one panel per label | `viz.py` | no |
+
+## Quick start
+
+```python
+import numpy as np, torch
+import spatialrna as sr
+
+df = sr.readers.load_transcripts("/path/to/output")          # x, y, z, qv, gene
+print(sr.readers.describe("/path/to/output"))
+
+# tile graphs (here: 100 near-square tiles with equal transcript counts)
+# SpatialRNA(root="data/S01.zarr", sample_name="S01", cohort_zarr_path="data/cohort.zarr",
+#            num_tiles=100, tile_mode="grid", one_hot_encoding=enc, ...)
+
+# train any model(x, edge_index) on the tiles / subgraphs
+from spatialrna import train_val as tv
+from spatialrna.datasets import ZarrGraphDataset
+graphs = ZarrGraphDataset.from_sample_store("data/S01.zarr", kind="subgraphs")
+opt = torch.optim.Adam(model.parameters(), lr=1e-3)
+loss, acc = tv.train_link_prediction(model, graphs, opt, device, num_genes)
+emb, tx_id = tv.embed_tile(model, graphs[0], device, num_genes)
+
+# clusters and a map
+labels, gmm = sr.cluster.gmm(emb.numpy(), 12)
+fig = sr.viz.pixel_map(x, y, labels)
+```
+
+## Tiling
+
+`SpatialRNA(tile_mode="strips")` (default, as in 0.2) cuts `num_tiles` equal-width
+bands along `tile_by_dim`. `tile_mode="grid"` cuts near-square tiles with equal
+transcript counts: no empty tiles in irregular tissue and little padding with many
+tiles (~5–7 % at 500 tiles, vs ~40 % for 500 strips).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest              # test_zarr_roundtrip needs the [gnn] extra
+```
+
+## Note on the name
+
+`spatialrna` 0.1–0.2 on PyPI is maintained by Ruqian Lyu; this is 0.3.0.dev0.
+Coordinate with her before uploading to PyPI under the same name.

spatialrna-0.3.0.dev0/README.md

@@ -0,0 +1,78 @@
+# spatialrna
+
+Spatial RNA graph data processing and analysis for single-molecule spatial
+transcriptomics (10x Xenium and Atera): transcripts → tile graphs and subgraphs →
+any graph neural network (train / validate / embed) → clusters → spatial maps.
+
+This continues the lab's `spatialrna` 0.2 (Ruqian Lyu) with the same scope and adds
+reading of raw Xenium / Atera outputs, zarr storage, a fast KD-tree graph builder,
+balanced grid tiling for large sections, and GPU Gaussian mixtures. The ISTIST
+pipeline builds on it with its own model (CrossSampleGAT), transcript-level
+annotation, statistics and an HTML report.
+
+## Install
+
+```bash
+pip install -e .                 # readers, graph builders, clustering, maps (no torch)
+pip install -e ".[gnn]"          # + SpatialRNA dataset, datasets, train_val
+                                 #   (install torch + PyG for your CUDA first)
+```
+
+Python >= 3.10, zarr-python >= 3.
+
+## Modules
+
+| module | what it does | 0.2 equivalent | needs torch |
+|---|---|---|---|
+| `readers` | Xenium / Atera `transcripts.zarr.zip` → transcripts (layout auto-detected) | – | no |
+| `graph_build` | KD-tree radius graphs, subgraph sampling, `plan_tiles` (grid tiling) | – | no |
+| `graph_zarr_io` | `SpatialRNA`: tiles (strips or grid) + padding → radius graphs → subgraphs, zarr I/O | `spatialrna.py` | yes |
+| `datasets` | `ZarrGraphDataset` over many tile / subgraph stores | `spatialrna_ondisk.py` | yes |
+| `train_val` | model-agnostic link-prediction training / validation, `embed_tile` | `train_val.py` | yes |
+| `cluster` | `gmm` (GPU or numpy EM), `kmeans` | `run_kmeans.py` | optional |
+| `viz` | `pixel_map`, two-panel overviews, one panel per label | `viz.py` | no |
+
+## Quick start
+
+```python
+import numpy as np, torch
+import spatialrna as sr
+
+df = sr.readers.load_transcripts("/path/to/output")          # x, y, z, qv, gene
+print(sr.readers.describe("/path/to/output"))
+
+# tile graphs (here: 100 near-square tiles with equal transcript counts)
+# SpatialRNA(root="data/S01.zarr", sample_name="S01", cohort_zarr_path="data/cohort.zarr",
+#            num_tiles=100, tile_mode="grid", one_hot_encoding=enc, ...)
+
+# train any model(x, edge_index) on the tiles / subgraphs
+from spatialrna import train_val as tv
+from spatialrna.datasets import ZarrGraphDataset
+graphs = ZarrGraphDataset.from_sample_store("data/S01.zarr", kind="subgraphs")
+opt = torch.optim.Adam(model.parameters(), lr=1e-3)
+loss, acc = tv.train_link_prediction(model, graphs, opt, device, num_genes)
+emb, tx_id = tv.embed_tile(model, graphs[0], device, num_genes)
+
+# clusters and a map
+labels, gmm = sr.cluster.gmm(emb.numpy(), 12)
+fig = sr.viz.pixel_map(x, y, labels)
+```
+
+## Tiling
+
+`SpatialRNA(tile_mode="strips")` (default, as in 0.2) cuts `num_tiles` equal-width
+bands along `tile_by_dim`. `tile_mode="grid"` cuts near-square tiles with equal
+transcript counts: no empty tiles in irregular tissue and little padding with many
+tiles (~5–7 % at 500 tiles, vs ~40 % for 500 strips).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest              # test_zarr_roundtrip needs the [gnn] extra
+```
+
+## Note on the name
+
+`spatialrna` 0.1–0.2 on PyPI is maintained by Ruqian Lyu; this is 0.3.0.dev0.
+Coordinate with her before uploading to PyPI under the same name.

spatialrna-0.3.0.dev0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatialrna"
+version = "0.3.0.dev0"
+description = "Spatial RNA graph data processing and analysis for single-molecule spatial transcriptomics (Xenium / Atera): graphs, GNN training / embedding, clustering, spatial maps."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Anne Pan", email = "anne.pan@svi.edu.au" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+# Core: readers, graph builders, clustering, maps. No torch needed.
+dependencies = [
+    "numpy",
+    "pandas",
+    "scipy",
+    "zarr>=3",
+    "numcodecs",
+    "tqdm",
+    "scikit-learn",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+# SpatialRNA dataset, datasets, train_val. Install torch and the PyG wheels matching
+# your CUDA first -- see README.
+gnn = ["torch", "torch_geometric"]
+dev = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["spatialrna*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spatialrna-0.3.0.dev0/src/spatialrna/__init__.py

@@ -0,0 +1,60 @@
+"""spatialrna: spatial RNA graph data processing and analysis for single-molecule
+spatial transcriptomics (Xenium / Atera): transcripts -> tile graphs / subgraphs ->
+any GNN (train / validate / embed) -> clusters -> spatial maps.
+
+    import spatialrna as sr
+    df = sr.readers.load_transcripts("/path/to/xenium_or_atera_output")
+    from spatialrna import SpatialRNA                 # tile graphs / subgraphs; needs torch + PyG
+
+The ISTIST pipeline builds on this with its own model (CrossSampleGAT), transcript
+annotation, statistics and report.
+
+Submodules (imported on first use, so the light ones need neither torch nor a GPU):
+
+    readers         Xenium / Atera transcripts.zarr.zip -> transcripts
+    graph_build     radius graphs (KD-tree) and subgraph sampling
+    graph_zarr_io   SpatialRNA tile dataset (strips or grid tiles) + zarr I/O [torch]
+    datasets        ZarrGraphDataset over many tile / subgraph stores        [torch]
+    train_val       model-agnostic link-prediction training, validation, tile embedding [torch]
+    cluster         Gaussian mixture (GPU or numpy) and k-means on embeddings
+    viz             pixel maps of labels / niches / cell types
+
+"""
+from __future__ import annotations
+
+import importlib
+
+__version__ = "0.3.0.dev0"
+
+_SUBMODULES = {"readers", "graph_build", "graph_zarr_io", "datasets", "train_val", "cluster", "viz"}
+
+# name -> submodule, for `from spatialrna import SpatialRNA` etc. (resolved lazily, so
+# `import spatialrna` works without torch; the graph_zarr_io names need it).
+_EXPORTS = {
+    **{n: "graph_zarr_io" for n in (
+        "SpatialRNA", "save_data_zarr", "load_data_zarr", "zarr_group_exists", "save_raw_transcripts_zarr",
+        "load_raw_transcripts_zarr", "store_exists", "tile_store_path", "sample_store_path",
+        "ensure_sample_store", "subgraph_store_path", "read_tile_graph", "write_tile_graph",
+        "read_subgraph", "write_subgraph")},
+    "load_transcripts": "readers",
+    "ZarrGraphDataset": "datasets",
+    "plan_tiles": "graph_build",
+}
+
+__all__ = sorted(_SUBMODULES | set(_EXPORTS)) + ["__version__"]
+
+
+def __getattr__(name):
+    if name in _SUBMODULES:
+        mod = importlib.import_module(f".{name}", __name__)
+        globals()[name] = mod
+        return mod
+    if name in _EXPORTS:
+        value = getattr(importlib.import_module(f".{_EXPORTS[name]}", __name__), name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'spatialrna' has no attribute {name!r}")
+
+
+def __dir__():
+    return __all__