/spatial-transcriptomics

name: spatial-transcriptomics
description: >-
  Analyse 10x Visium spatial transcriptomics: SpaceRanger outs or spatial h5ad
  in, then QC, Leiden clustering, Wilcoxon markers, Moran's I, neighbourhood
  enrichment and co-occurrence in one local report.
license: MIT
metadata:
  version: "0.1.0"
  author: Zhihao Wan
  domain: spatial-transcriptomics
  tags:
    - spatial-transcriptomics
    - visium
    - scanpy
    - moran
    - clustering
  inputs:
    - name: visium_input
      type: file
      format:
        - dir
        - h5ad
      description: SpaceRanger outs/ or h5ad with raw counts and finite two-dimensional obsm['spatial'] coordinates
      required: false
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Analysis report
    - name: result
      type: file
      format:
        - json
      description: Machine-readable summary
  dependencies:
    python: ">=3.11"
    packages:
      - scanpy>=1.10
      - leidenalg>=0.10
      - numpy>=1.24
      - pandas>=2.0
      - matplotlib>=3.7
      - scikit-learn>=1.3
      - scipy>=1.10
  demo_data:
    - path: examples/demo_spec.json
      description: Recipe for the offline 8x8 two-domain synthetic grid
  endpoints:
    cli: python skills/spatial-transcriptomics/spatial_transcriptomics.py --input {visium_input} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🧬"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: scanpy
      - kind: pip
        package: leidenalg
    trigger_keywords:
      - visium
      - spatial transcriptomics
      - SpaceRanger
      - Moran's I
      - neighbourhood enrichment
      - spatially variable genes

🧬 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

1. **Load Visium**: SpaceRanger `outs/` (`filtered_feature_bc_matrix/` + `spatial/`) or h5ad with `obsm['spatial']`. 2. **QC and clustering**: Scanpy filter, normalise, HVG, PCA, UMAP, Leiden. 3. **Markers**: Wilcoxon cluster-vs-rest on log-normalised expression. 4. **Spatial statistics**: kNN Moran's I, permutation neighbourhood enrichment, distance-binned co-occurrence. 5. **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

1. **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. 2. **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. 3. **Markers (prescriptive)**: Wilcoxon cluster-vs-rest on the tested gene universe; omit groups without enough observations, export a marker heatmap and report the limitation. 4. **Spatial graph**: k=6 nearest spots on `obsm['spatial']` (not the PCA graph). 5. **Moran's I**: row-standardised kNN I per gene (Moran 1950; Squidpy `spatial_autocorr`). 6. **Neighbourhood enrichment**: observed cluster–cluster neighbour counts vs shuffled labels (Squidpy `nhood_enrichment`). 7. **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. 8. **Generate (prescriptive outputs, flexible narrative)**: Write `report.md`, strict JSON, figures, tables and `repro