🧬 Spatial Transcriptomics (Visium)
You are spatial-transcriptomics, a ClawBio agent that analyses measured 10x Visium data. You load SpaceRanger outs/ or a spatial h5ad, then write QC, clustering, markers and spatial statistics as a local report.
Trigger
Fire this skill when the user says any of:
- "analyse my Visium data"
- "spatial transcriptomics QC and clustering"
- "SpaceRanger outs"
- "spatially variable genes"
- "Moran's I on visium"
- "neighbourhood enrichment"
- "spot co-occurrence"
Do NOT fire when:
- The user has an H&E tile and wants predicted expression. That is
deepspot-m.
- The user has dissociated scRNA-seq (h5ad/mtx with no
obsm['spatial']). That is scrna-orchestrator.
- The user has a marker-by-spot table and wants region labels. That is
marker-dominance-mapper.
Why This Exists
- Without it: Visium analysis is a Scanpy plus Squidpy notebook stitched by hand, with no
--demo and no reproducibility bundle.
- With it: One command turns SpaceRanger
outs/ into a report with Leiden, Wilcoxon markers, Moran's I, neighbourhood enrichment and co-occurrence.
- Why ClawBio: Local-first, synthetic demo, shared reproducibility helpers. Complementary to
deepspot-m, which predicts expression from histology; this skill analyses expression that was measured.
Core Capabilities
- Load Visium: SpaceRanger
outs/ (filtered_feature_bc_matrix/ + spatial/) or h5ad with obsm['spatial'].
- QC and clustering: Scanpy filter, normalise, HVG, PCA, UMAP, Leiden.
- Markers: Wilcoxon cluster-vs-rest on log-normalised expression.
- Spatial statistics: kNN Moran's I, permutation neighbourhood enrichment, distance-binned co-occurrence.
- Report: Markdown, JSON, figures, tables, reproducibility bundle.
Scope
One skill, one task. Measured Visium-like spot data in, one analysis report out. It does not predict expression from H&E, call cells on a WSI, or run Visium HD / Xenium.
Input Formats
| Format |
Extension |
Required Fields |
Example |
| SpaceRanger outs |
directory |
filtered_feature_bc_matrix/ mtx + spatial/tissue_positions.csv |
sample/outs |
| Spatial AnnData |
.h5ad |
raw counts in X or an explicit --counts-layer; finite obsm['spatial'] x,y per spot |
visium.h5ad |
| Demo |
n/a |
none |
--demo |
HDF5 filtered_feature_bc_matrix.h5 is not read in v0.1; pass the mtx folder. Tissue images are not required.
Counts must be finite, nonnegative integers. A processed h5ad must supply an
explicit raw-count layer (for example --counts-layer counts); .raw is not
assumed to contain counts. Normalised/log-transformed X is rejected. Analyse one
slide at a time; this workflow does not model multiple libraries or donors.
Workflow
- Validate (prescriptive): Accept
outs/, raw-count spatial h5ad, or --demo. Validate counts and finite two-dimensional coordinates. Abstain below 10 spots or two retained genes; require --overwrite for a nonempty output directory.
- Process (prescriptive): Export per-spot counts, detected genes and mitochondrial percentages before QC; filter with
min_genes, min_cells and optional max_pct_mt; normalise to 1e4, log1p, HVGs, PCA, expression neighbours, UMAP and Leiden.
- Markers (prescriptive): Wilcoxon cluster-vs-rest on the tested gene universe; omit groups without enough observations, export a marker heatmap and report the limitation.
- Spatial graph: k=6 nearest spots on
obsm['spatial'] (not the PCA graph).
- Moran's I: row-standardised kNN I per gene (Moran 1950; Squidpy
spatial_autocorr).
- Neighbourhood enrichment: observed cluster–cluster neighbour counts vs shuffled labels (Squidpy
nhood_enrichment).
- Co-occurrence (prescriptive): For each cumulative radius r, compute P(target | source, 0 < distance ≤ r) / P(target | eligible pair, r), using the Squidpy 1.6.0 estimator and six positive-distance quantile radii. Export all scores, cluster axes and radii.
- Generate (prescriptive outputs, flexible narrative): Write
report.md, strict JSON, figures, tables and reproducibility/ with actual parameters, software versions, source/input hashes and a replay command that verifies the input and writes a new directory.
Steps 1–7 are prescriptive. Report narrative is flexible.
CLI Reference
python skills/spatial-transcriptomics/spatial_transcriptomics.py \
--input sample/outs --output /tmp/visium_out
python skills/spatial-transcriptomics/spatial_transcriptomics.py \
--input visium.h5ad --output /tmp/visium_out
python skills/spatial-transcriptomics/spatial_transcriptomics.py \
--demo --output /tmp/spatial_demo
python clawbio.py run spatial --input sample/outs --output /tmp/visium_out
python clawbio.py run spatial --demo
# A processed h5ad with a preserved raw-count layer:
python clawbio.py run spatial --input processed.h5ad --counts-layer counts \
--n-pcs 30 --n-neighbors 15 --nhood-perms 1000 --output /tmp/visium_review
| Flag |
Default |
Purpose |
--min-genes |
5 |
Drop spots with fewer genes |
--min-cells |
1 |
Drop genes in fewer spots |
--leiden-resolution |
0.5 |
Leiden resolution |
--n-top-hvg |
2000 |
Highly variable genes (capped at the gene count) |
--random-state |
7 |
PCA / neighbours / Leiden / permutations |
--n-pcs |
8 |
PCA components, capped by spots and selected genes |
--n-neighbors |
8 |
Expression graph neighbours; spatial k stays 6 |
--nhood-perms |
50 |
Label permutations for exploratory neighbourhood z-scores |
--top-markers |
5 |
Reported markers per supported cluster |
--max-pct-mt |
none |
Optional mitochondrial percentage ceiling (0–100) |
--counts-layer |
none |
Explicit raw-count layer for h5ad |
--overwrite |
false |
Explicitly replace report files in a nonempty directory |
--expected-input-sha256 |
none |
Replay integrity check before analysis |
Demo
python clawbio.py run spatial --demo
Expected output: 64-spot synthetic grid, two spatial domains, Leiden ≥ 2, EPCAM/COL1A1 among high Moran's I genes, figures, tables, reproducibility bundle. No download.
Algorithm / Methodology
- Load:
scanpy.read_10x_mtx plus tissue_positions.csv (or tissue_positions_list.csv); keep in_tissue==1.
- QC:
calculate_qc_metrics(percent_top=None), min detected genes, positive total counts, optional mitochondrial ceiling and filter_genes(min_cells). Mitochondrial genes match case-insensitive MT-; absence of such symbols is reported as unavailable mitochondrial QC.
- Normalise:
normalize_total(1e4), log1p. Raw counts kept in layers["counts"].
- Embed: Seurat HVGs, PCA, explicit
use_rep="X_pca" neighbours, UMAP, Leiden (flavor="igraph" when Scanpy accepts it). Requested and effective embedding dimensions are recorded.
- Markers: Wilcoxon with Scanpy Benjamini–Hochberg adjustment over tested genes. This is exploratory cluster characterisation, not independent confirmatory inference after clustering.
- Spatial kNN: sklearn
NearestNeighbors on coordinates, k=6, self excluded.
- Moran's I: I = (zᵀWz)/(zᵀz) with row-standardised W.
- Enrichment: Configurable label permutations on the frozen directed spatial graph; z = (obs − mean_null) / sd_null. Zero null SD is undefined (
null in JSON, blank in CSV, NA in the report).
- Co-occurrence: Cumulative Euclidean radii, excluding zero-distance pairs; conditional target frequency divided by the target marginal over eligible pairs. The six quantile radii differ from Squidpy's automatic radius selection. Tensor axis order is source cluster, target cluster, radius; radius intervals are
(0, r]. Unsupported ratios are undefined.
Above 80 post-QC genes, both Moran and Wilcoxon evaluate HVGs only;
otherwise every retained gene is evaluated. result.json.analysis_scope records
the exact tested gene names and count. A gene missing from the Moran table has
not been evaluated, and cannot be called spatially neutral. Moran is a descriptive
statistic with no permutation p-value or multiple-testing correction. Constant
genes have undefined Moran's I, represented as null/blank/NA.
Key thresholds:
- Minimum spots: 10 (below this the kNN graph is not meaningful)
- Spatial k: 6 (hex-like Visium neighbourhood)
- Leiden resolution: 0.5 (demo default; user-overridable)
- Permutations: 50 (exploratory default; configurable with
--nhood-perms)
- Mitochondrial ceiling: none by default; inspect QC and choose a tissue-appropriate threshold rather than applying a universal cutoff
Example Queries
- "Run QC and clustering on this Visium outs folder"
- "Which genes are spatially variable in my Visium sample?"
- "Neighbourhood enrichment on my visium h5ad"
Example Output
# Spatial Transcriptomics Report (demo)
**Spots**: 64
**Leiden clusters**: 2
## Spatially variable genes (Moran's I)
| Gene | Moran's I |
|------|-----------|
| DCN | 0.745 |
| VIM | 0.639 |
Output Structure
output_directory/
├── report.md
├── result.json
├── figures/
│ ├── umap_leiden.png
│ ├── spatial_leiden.png
│ ├── marker_heatmap.png # optional when no valid cluster-vs-rest markers exist
│ └── qc_spot_metrics.png
├── tables/
│ ├── markers_top.csv
│ ├── moran_i.csv
│ ├── nhood_enrichment.csv
│ ├── co_occurrence.csv
│ ├── qc_spot_metrics.csv
│ └── qc_summary.csv
└── reproducibility/
├── commands.sh
├── environment.yml
├── checksums.sha256
└── run_manifest.json
Dependencies
Required:
scanpy >= 1.10; QC, HVG, PCA, UMAP, Leiden, Wilcoxon
leidenalg >= 0.10; Leiden
numpy, pandas, matplotlib, scikit-learn, scipy; spatial graph, stats, figures
Not required:
squidpy. Its SpatialData/Dask/OME-Zarr dependency chain can pull S3 dependencies into every uv sync --all-extras job. Runtime estimators are implemented locally. Co-occurrence follows the explicitly cited 1.6.0 cumulative-radius definition, not the annular 1.4 definition; automatic graph/radius construction and random streams are not claimed to be interchangeable.
Gotchas
- You will want to route an H&E tile here. Do not. This skill needs measured spot counts and coordinates. Predicted expression from histology is
deepspot-m.
- You will want to cluster on the spatial kNN graph. Do not, unless you mean it. Leiden uses the PCA neighbour graph. The spatial kNN graph is only for Moran's I and enrichment. Mixing them silently changes what a cluster is.
- You will want to treat Moran's I as a p-value. Do not. v0.1 reports the statistic, not a permutation p-value per gene.
- You will want to quote demo numbers as a tissue result. Do not.
--demo is an 8×8 synthetic grid.
- You will want to pass a Visium HDF5 matrix. Do not in v0.1. Supply the mtx
filtered_feature_bc_matrix/ directory.
- You will want to threshold enrichment at |z|>1.96 as a discovery claim. Do not. 50 permutations make the tails coarse; the diagonal sign is the supported reading.
- You will want to load already normalised X as counts. Do not. Select a verified raw-count layer explicitly; a
.raw attribute is not proof of raw counts.
- You will want to replay into the original output. Do not by default.
commands.sh writes to replay/ or $REPLAY_OUTPUT, verifies $INPUT_PATH against the recorded digest, and preserves all analysis parameters.
- You will want to label a missing Moran gene as non-spatial. Do not. Check
analysis_scope; HVG screening omits untested genes.
Safety
- Local-first: Spots are read from disk. No upload.
--demo does not download a Visium dataset.
- Disclaimer: Every report includes the ClawBio medical disclaimer.
- No hallucinated science: Cluster labels, Moran's I and enrichment come from the matrices above.
- Audit trail:
reproducibility/commands.sh, environment.yml, checksums.sha256 via clawbio.common.reproducibility.
- Archive safety: The public-data helper verifies pinned SHA-256 digests, stages downloads, rejects traversal/links/special files, and copies only known matrix/position/scalefactor files. Images are not extracted.
Validation and Replay
# Default tests and demo are offline. Live-test failures are failures when opted in.
uv run --extra spatial --with pytest pytest skills/spatial-transcriptomics/tests/ -m 'not network'
CLAWBIO_RUN_PUBLIC_VISIUM=1 uv run --extra spatial --with pytest \
pytest skills/spatial-transcriptomics/tests/ -m network
# On a compatible machine, install the recorded environment and use the same source.
cd /path/to/output
sha256sum -c reproducibility/checksums.sha256
INPUT_PATH=/path/to/original/outs REPLAY_OUTPUT=/tmp/visium_replay \
bash reproducibility/commands.sh
The environment file pins the installed analysis dependency closure and Python
version; the manifest records the platform and source hashes. Cross-platform
bitwise numerical identity is not promised. The public integration test uses 400
measured spots for runtime; full-slide validation is a separate explicit run.
See the full-slide validation record.
The offline Squidpy 1.6 fixture was
generated in a separate pinned environment using the adjacent regeneration
script. It checks co-occurrence at explicit radii, Moran on an explicit graph,
and observed neighbourhood counts. It does not assert identical permutation
z-scores across different random streams. Undefined ratios use null here
instead of Squidpy's zero convention.
Agent Boundary
The agent dispatches and explains. The Python skill loads data, runs Scanpy and the spatial estimators, and writes files. The agent must not invent Moran's I, relabel clusters, or present demo values as a patient sample.
Integration with Bio Orchestrator
Trigger conditions: Visium, SpaceRanger outs/, spatially variable genes, Moran's I, neighbourhood enrichment, spot co-occurrence.
Chaining partners:
deepspot-m: complementary. Predicted per-tile expression is not a Visium outs/ tree; do not pipe it here without building a spatial AnnData first.
scrna-orchestrator: dissociated scRNA-seq without coordinates.
marker-dominance-mapper: downstream if you export a marker-by-spot table.
Maintenance
- Review cadence: Recheck Scanpy Leiden (
flavor="igraph") and 10x position CSV headers each quarter.
- Staleness signals: SpaceRanger position file rename, Scanpy dropping
rank_genes_groups Wilcoxon, a request for Visium HD / Xenium.
- Deprecation: Archive if a maintained Visium wrapper in this repo supersedes the report contract.
Citations
- Wolf, Angerer and Theis (2018) Genome Biol 19:15. PMID 29409532. Scanpy.
- Moran (1950) Biometrika 37:17–23. Global Moran's I.
- Palla et al. (2022) Nat Methods 19:171–178. PMID 35102346. DOI 10.1038/s41592-021-01358-2. Squidpy.
- Squidpy 1.6.0 co-occurrence source: cumulative radii and eligible-pair marginals; explicit thresholds are required for numeric comparisons.
- Traag, Waltman and van Eck (2019) Sci Rep 9:5233. Leiden.
1---2name: spatial-transcriptomics3description: >-4 Analyse 10x Visium spatial transcriptomics: SpaceRanger outs or spatial h5ad5 in, then QC, Leiden clustering, Wilcoxon markers, Moran's I, neighbourhood6 enrichment and co-occurrence in one local report.7license: MIT8metadata:9 source: https://skillmd.com/skills/clawbio/spatial-transcriptomics10 version: "0.1.0"11 author: Zhihao Wan12 domain: spatial-transcriptomics13 tags:14 - spatial-transcriptomics15 - visium16 - scanpy17 - moran18 - clustering19 inputs:20 - name: visium_input21 type: file22 format:23 - dir24 - h5ad25 description: SpaceRanger outs/ or h5ad with raw counts and finite two-dimensional obsm['spatial'] coordinates26 required: false27 outputs:28 - name: report29 type: file30 format:31 - md32 description: Analysis report33 - name: result34 type: file35 format:36 - json37 description: Machine-readable summary38 dependencies:39 python: ">=3.11"40 packages:41 - scanpy>=1.1042 - leidenalg>=0.1043 - numpy>=1.2444 - pandas>=2.045 - matplotlib>=3.746 - scikit-learn>=1.347 - scipy>=1.1048 demo_data:49 - path: examples/demo_spec.json50 description: Recipe for the offline 8x8 two-domain synthetic grid51 endpoints:52 cli: python skills/spatial-transcriptomics/spatial_transcriptomics.py --input {visium_input} --output {output_dir}53 openclaw:54 requires:55 bins:56 - python357 always: false58 emoji: "🧬"59 homepage: https://github.com/ClawBio/ClawBio60 os:61 - darwin62 - linux63 install:64 - kind: pip65 package: scanpy66 - kind: pip67 package: leidenalg68 trigger_keywords:69 - visium70 - spatial transcriptomics71 - SpaceRanger72 - Moran's I73 - neighbourhood enrichment74 - spatially variable genes75---7677# 🧬 Spatial Transcriptomics (Visium)7879You are **spatial-transcriptomics**, a ClawBio agent that analyses measured 10x Visium data. You load SpaceRanger `outs/` or a spatial h5ad, then write QC, clustering, markers and spatial statistics as a local report.8081## Trigger8283**Fire this skill when the user says any of:**84- "analyse my Visium data"85- "spatial transcriptomics QC and clustering"86- "SpaceRanger outs"87- "spatially variable genes"88- "Moran's I on visium"89- "neighbourhood enrichment"90- "spot co-occurrence"9192**Do NOT fire when:**93- The user has an H&E tile and wants predicted expression. That is `deepspot-m`.94- The user has dissociated scRNA-seq (h5ad/mtx with no `obsm['spatial']`). That is `scrna-orchestrator`.95- The user has a marker-by-spot table and wants region labels. That is `marker-dominance-mapper`.9697## Why This Exists9899- **Without it**: Visium analysis is a Scanpy plus Squidpy notebook stitched by hand, with no `--demo` and no reproducibility bundle.100- **With it**: One command turns SpaceRanger `outs/` into a report with Leiden, Wilcoxon markers, Moran's I, neighbourhood enrichment and co-occurrence.101- **Why ClawBio**: Local-first, synthetic demo, shared reproducibility helpers. Complementary to `deepspot-m`, which *predicts* expression from histology; this skill *analyses* expression that was measured.102103## Core Capabilities1041051. **Load Visium**: SpaceRanger `outs/` (`filtered_feature_bc_matrix/` + `spatial/`) or h5ad with `obsm['spatial']`.1062. **QC and clustering**: Scanpy filter, normalise, HVG, PCA, UMAP, Leiden.1073. **Markers**: Wilcoxon cluster-vs-rest on log-normalised expression.1084. **Spatial statistics**: kNN Moran's I, permutation neighbourhood enrichment, distance-binned co-occurrence.1095. **Report**: Markdown, JSON, figures, tables, reproducibility bundle.110111## Scope112113**One skill, one task.** Measured Visium-like spot data in, one analysis report out. It does not predict expression from H&E, call cells on a WSI, or run Visium HD / Xenium.114115## Input Formats116117| Format | Extension | Required Fields | Example |118|--------|-----------|-----------------|---------|119| SpaceRanger outs | directory | `filtered_feature_bc_matrix/` mtx + `spatial/tissue_positions.csv` | `sample/outs` |120| Spatial AnnData | `.h5ad` | raw counts in X or an explicit `--counts-layer`; finite `obsm['spatial']` x,y per spot | `visium.h5ad` |121| Demo | n/a | none | `--demo` |122123HDF5 `filtered_feature_bc_matrix.h5` is not read in v0.1; pass the mtx folder. Tissue images are not required.124125Counts must be finite, nonnegative integers. A processed h5ad must supply an126explicit raw-count layer (for example `--counts-layer counts`); `.raw` is not127assumed to contain counts. Normalised/log-transformed X is rejected. Analyse one128slide at a time; this workflow does not model multiple libraries or donors.129130## Workflow1311321. **Validate (prescriptive)**: Accept `outs/`, raw-count spatial h5ad, or `--demo`. Validate counts and finite two-dimensional coordinates. Abstain below 10 spots or two retained genes; require `--overwrite` for a nonempty output directory.1332. **Process (prescriptive)**: Export per-spot counts, detected genes and mitochondrial percentages before QC; filter with `min_genes`, `min_cells` and optional `max_pct_mt`; normalise to 1e4, log1p, HVGs, PCA, expression neighbours, UMAP and Leiden.1343. **Markers (prescriptive)**: Wilcoxon cluster-vs-rest on the tested gene universe; omit groups without enough observations, export a marker heatmap and report the limitation.1354. **Spatial graph**: k=6 nearest spots on `obsm['spatial']` (not the PCA graph).1365. **Moran's I**: row-standardised kNN I per gene (Moran 1950; Squidpy `spatial_autocorr`).1376. **Neighbourhood enrichment**: observed cluster–cluster neighbour counts vs shuffled labels (Squidpy `nhood_enrichment`).1387. **Co-occurrence (prescriptive)**: For each cumulative radius r, compute P(target | source, 0 < distance ≤ r) / P(target | eligible pair, r), using the Squidpy 1.6.0 estimator and six positive-distance quantile radii. Export all scores, cluster axes and radii.1398. **Generate (prescriptive outputs, flexible narrative)**: Write `report.md`, strict JSON, figures, tables and `reproducibility/` with actual parameters, software versions, source/input hashes and a replay command that verifies the input and writes a new directory.140141Steps 1–7 are prescriptive. Report narrative is flexible.142143## CLI Reference144145```bash146python skills/spatial-transcriptomics/spatial_transcriptomics.py \147 --input sample/outs --output /tmp/visium_out148149python skills/spatial-transcriptomics/spatial_transcriptomics.py \150 --input visium.h5ad --output /tmp/visium_out151152python skills/spatial-transcriptomics/spatial_transcriptomics.py \153 --demo --output /tmp/spatial_demo154155python clawbio.py run spatial --input sample/outs --output /tmp/visium_out156python clawbio.py run spatial --demo157158# A processed h5ad with a preserved raw-count layer:159python clawbio.py run spatial --input processed.h5ad --counts-layer counts \160 --n-pcs 30 --n-neighbors 15 --nhood-perms 1000 --output /tmp/visium_review161```162163| Flag | Default | Purpose |164|------|---------|---------|165| `--min-genes` | 5 | Drop spots with fewer genes |166| `--min-cells` | 1 | Drop genes in fewer spots |167| `--leiden-resolution` | 0.5 | Leiden resolution |168| `--n-top-hvg` | 2000 | Highly variable genes (capped at the gene count) |169| `--random-state` | 7 | PCA / neighbours / Leiden / permutations |170| `--n-pcs` | 8 | PCA components, capped by spots and selected genes |171| `--n-neighbors` | 8 | Expression graph neighbours; spatial k stays 6 |172| `--nhood-perms` | 50 | Label permutations for exploratory neighbourhood z-scores |173| `--top-markers` | 5 | Reported markers per supported cluster |174| `--max-pct-mt` | none | Optional mitochondrial percentage ceiling (0–100) |175| `--counts-layer` | none | Explicit raw-count layer for h5ad |176| `--overwrite` | false | Explicitly replace report files in a nonempty directory |177| `--expected-input-sha256` | none | Replay integrity check before analysis |178179## Demo180181```bash182python clawbio.py run spatial --demo183```184185Expected output: 64-spot synthetic grid, two spatial domains, Leiden ≥ 2, EPCAM/COL1A1 among high Moran's I genes, figures, tables, reproducibility bundle. No download.186187## Algorithm / Methodology1881891. **Load**: `scanpy.read_10x_mtx` plus `tissue_positions.csv` (or `tissue_positions_list.csv`); keep `in_tissue==1`.1902. **QC**: `calculate_qc_metrics(percent_top=None)`, min detected genes, positive total counts, optional mitochondrial ceiling and `filter_genes(min_cells)`. Mitochondrial genes match case-insensitive `MT-`; absence of such symbols is reported as unavailable mitochondrial QC.1913. **Normalise**: `normalize_total(1e4)`, `log1p`. Raw counts kept in `layers["counts"]`.1924. **Embed**: Seurat HVGs, PCA, explicit `use_rep="X_pca"` neighbours, UMAP, Leiden (`flavor="igraph"` when Scanpy accepts it). Requested and effective embedding dimensions are recorded.1935. **Markers**: Wilcoxon with Scanpy Benjamini–Hochberg adjustment over tested genes. This is exploratory cluster characterisation, not independent confirmatory inference after clustering.1946. **Spatial kNN**: sklearn `NearestNeighbors` on coordinates, k=6, self excluded.1957. **Moran's I**: I = (zᵀWz)/(zᵀz) with row-standardised W.1968. **Enrichment**: Configurable label permutations on the frozen directed spatial graph; z = (obs − mean_null) / sd_null. Zero null SD is undefined (`null` in JSON, blank in CSV, `NA` in the report).1979. **Co-occurrence**: Cumulative Euclidean radii, excluding zero-distance pairs; conditional target frequency divided by the target marginal over eligible pairs. The six quantile radii differ from Squidpy's automatic radius selection. Tensor axis order is source cluster, target cluster, radius; radius intervals are `(0, r]`. Unsupported ratios are undefined.198199Above 80 post-QC genes, **both Moran and Wilcoxon evaluate HVGs only**;200otherwise every retained gene is evaluated. `result.json.analysis_scope` records201the exact tested gene names and count. A gene missing from the Moran table has202not been evaluated, and cannot be called spatially neutral. Moran is a descriptive203statistic with no permutation p-value or multiple-testing correction. Constant204genes have undefined Moran's I, represented as `null`/blank/`NA`.205206**Key thresholds**:207- Minimum spots: 10 (below this the kNN graph is not meaningful)208- Spatial k: 6 (hex-like Visium neighbourhood)209- Leiden resolution: 0.5 (demo default; user-overridable)210- Permutations: 50 (exploratory default; configurable with `--nhood-perms`)211- Mitochondrial ceiling: none by default; inspect QC and choose a tissue-appropriate threshold rather than applying a universal cutoff212213## Example Queries214215- "Run QC and clustering on this Visium outs folder"216- "Which genes are spatially variable in my Visium sample?"217- "Neighbourhood enrichment on my visium h5ad"218219## Example Output220221```markdown222# Spatial Transcriptomics Report (demo)223224**Spots**: 64225**Leiden clusters**: 2226227## Spatially variable genes (Moran's I)228| Gene | Moran's I |229|------|-----------|230| DCN | 0.745 |231| VIM | 0.639 |232```233234## Output Structure235236```237output_directory/238├── report.md239├── result.json240├── figures/241│ ├── umap_leiden.png242│ ├── spatial_leiden.png243│ ├── marker_heatmap.png # optional when no valid cluster-vs-rest markers exist244│ └── qc_spot_metrics.png245├── tables/246│ ├── markers_top.csv247│ ├── moran_i.csv248│ ├── nhood_enrichment.csv249│ ├── co_occurrence.csv250│ ├── qc_spot_metrics.csv251│ └── qc_summary.csv252└── reproducibility/253 ├── commands.sh254 ├── environment.yml255 ├── checksums.sha256256 └── run_manifest.json257```258259## Dependencies260261**Required**:262- `scanpy` >= 1.10; QC, HVG, PCA, UMAP, Leiden, Wilcoxon263- `leidenalg` >= 0.10; Leiden264- `numpy`, `pandas`, `matplotlib`, `scikit-learn`, `scipy`; spatial graph, stats, figures265266**Not required**:267- `squidpy`. Its SpatialData/Dask/OME-Zarr dependency chain can pull S3 dependencies into every `uv sync --all-extras` job. Runtime estimators are implemented locally. Co-occurrence follows the explicitly cited 1.6.0 cumulative-radius definition, not the annular 1.4 definition; automatic graph/radius construction and random streams are not claimed to be interchangeable.268269## Gotchas270271- **You will want to route an H&E tile here. Do not.** This skill needs measured spot counts and coordinates. Predicted expression from histology is `deepspot-m`.272- **You will want to cluster on the spatial kNN graph. Do not, unless you mean it.** Leiden uses the PCA neighbour graph. The spatial kNN graph is only for Moran's I and enrichment. Mixing them silently changes what a cluster is.273- **You will want to treat Moran's I as a p-value. Do not.** v0.1 reports the statistic, not a permutation p-value per gene.274- **You will want to quote demo numbers as a tissue result. Do not.** `--demo` is an 8×8 synthetic grid.275- **You will want to pass a Visium HDF5 matrix. Do not in v0.1.** Supply the mtx `filtered_feature_bc_matrix/` directory.276- **You will want to threshold enrichment at |z|>1.96 as a discovery claim. Do not.** 50 permutations make the tails coarse; the diagonal sign is the supported reading.277- **You will want to load already normalised X as counts. Do not.** Select a verified raw-count layer explicitly; a `.raw` attribute is not proof of raw counts.278- **You will want to replay into the original output. Do not by default.** `commands.sh` writes to `replay/` or `$REPLAY_OUTPUT`, verifies `$INPUT_PATH` against the recorded digest, and preserves all analysis parameters.279- **You will want to label a missing Moran gene as non-spatial. Do not.** Check `analysis_scope`; HVG screening omits untested genes.280281## Safety282283- **Local-first**: Spots are read from disk. No upload. `--demo` does not download a Visium dataset.284- **Disclaimer**: Every report includes the ClawBio medical disclaimer.285- **No hallucinated science**: Cluster labels, Moran's I and enrichment come from the matrices above.286- **Audit trail**: `reproducibility/commands.sh`, `environment.yml`, `checksums.sha256` via `clawbio.common.reproducibility`.287- **Archive safety**: The public-data helper verifies pinned SHA-256 digests, stages downloads, rejects traversal/links/special files, and copies only known matrix/position/scalefactor files. Images are not extracted.288289## Validation and Replay290291```bash292# Default tests and demo are offline. Live-test failures are failures when opted in.293uv run --extra spatial --with pytest pytest skills/spatial-transcriptomics/tests/ -m 'not network'294CLAWBIO_RUN_PUBLIC_VISIUM=1 uv run --extra spatial --with pytest \295 pytest skills/spatial-transcriptomics/tests/ -m network296297# On a compatible machine, install the recorded environment and use the same source.298cd /path/to/output299sha256sum -c reproducibility/checksums.sha256300INPUT_PATH=/path/to/original/outs REPLAY_OUTPUT=/tmp/visium_replay \301 bash reproducibility/commands.sh302```303304The environment file pins the installed analysis dependency closure and Python305version; the manifest records the platform and source hashes. Cross-platform306bitwise numerical identity is not promised. The public integration test uses 400307measured spots for runtime; full-slide validation is a separate explicit run.308309See [the full-slide validation record](examples/public_visium_validation.md).310The offline [Squidpy 1.6 fixture](fixtures/squidpy_v1_6_co_occurrence.json) was311generated in a separate pinned environment using the adjacent regeneration312script. It checks co-occurrence at explicit radii, Moran on an explicit graph,313and observed neighbourhood counts. It does not assert identical permutation314z-scores across different random streams. Undefined ratios use `null` here315instead of Squidpy's zero convention.316317## Agent Boundary318319The agent dispatches and explains. The Python skill loads data, runs Scanpy and the spatial estimators, and writes files. The agent must not invent Moran's I, relabel clusters, or present demo values as a patient sample.320321## Integration with Bio Orchestrator322323**Trigger conditions**: Visium, SpaceRanger `outs/`, spatially variable genes, Moran's I, neighbourhood enrichment, spot co-occurrence.324325**Chaining partners**:326- `deepspot-m`: complementary. Predicted per-tile expression is not a Visium `outs/` tree; do not pipe it here without building a spatial AnnData first.327- `scrna-orchestrator`: dissociated scRNA-seq without coordinates.328- `marker-dominance-mapper`: downstream if you export a marker-by-spot table.329330## Maintenance331332- **Review cadence**: Recheck Scanpy Leiden (`flavor="igraph"`) and 10x position CSV headers each quarter.333- **Staleness signals**: SpaceRanger position file rename, Scanpy dropping `rank_genes_groups` Wilcoxon, a request for Visium HD / Xenium.334- **Deprecation**: Archive if a maintained Visium wrapper in this repo supersedes the report contract.335336## Citations337338- Wolf, Angerer and Theis (2018) Genome Biol 19:15. PMID 29409532. Scanpy.339- Moran (1950) Biometrika 37:17–23. Global Moran's I.340- Palla et al. (2022) Nat Methods 19:171–178. [PMID 35102346](https://pubmed.ncbi.nlm.nih.gov/35102346/). [DOI 10.1038/s41592-021-01358-2](https://doi.org/10.1038/s41592-021-01358-2). Squidpy.341- [Squidpy 1.6.0 co-occurrence source](https://github.com/scverse/squidpy/blob/v1.6.0/src/squidpy/gr/_ppatterns.py): cumulative radii and eligible-pair marginals; explicit thresholds are required for numeric comparisons.342- Traag, Waltman and van Eck (2019) Sci Rep 9:5233. Leiden.