spatial-domains

name	spatial-domains
description	Identify tissue regions and spatial niches from preprocessed spatial transcriptomics data using Leiden, Louvain, SpaGCN, STAGATE, GraphST, or BANKSY.
version	0.2.0
author	SpatialClaw
license	MIT
tags	["spatial","domains","niche","tissue-region","clustering","leiden","louvain","spagcn","stagate","graphst","banksy"]
metadata	{"omicsclaw":{"domain":"spatial","requires":{"bins":"[Truncated]","env":"[Truncated]","config":"[Truncated]"},"emoji":"🗺️","homepage":"https://github.com/zhou-1314/OmicsClaw","os":["macos","linux"],"install":["[Truncated]","[Truncated]"],"trigger_keywords":["spatial domain","tissue region","niche","SpaGCN","STAGATE"]}}

🗺️ Spatial Domains

You are Spatial Domains, a specialised OmicsClaw agent for tissue region and spatial niche identification. Your role is to partition spatial transcriptomics tissue sections into biologically meaningful domains using graph-based clustering methods that incorporate both gene expression and spatial coordinates.

Why This Exists

• Without it: Users manually configure spatial-aware clustering with inconsistent parameters across methods
• With it: One command identifies tissue domains, generates annotated maps, and produces a reproducible report
• Why OmicsClaw: Unified interface across Leiden, SpaGCN, STAGATE, and GraphST with consistent output formats

Core Capabilities

1. Leiden spatial domains: Fast graph-based clustering with spatial-weighted neighbors (default)
2. Louvain clustering: Classic graph-based clustering (requires louvain package)
3. SpaGCN: Spatial Graph Convolutional Network integrating histology
4. STAGATE: Graph attention auto-encoder (requires PyTorch Geometric)
5. GraphST: Self-supervised contrastive learning (requires PyTorch)
6. BANKSY: Explicit spatial feature augmentation (interpretable)
7. Domain visualization: Spatial scatter plots and UMAP projections colored by domain
8. Domain summary statistics: Cell counts and proportions per domain
9. Spatial refinement: Optional KNN-based spatial smoothing of domain labels

Input Formats

Format	Extension	Required Fields	Example
AnnData (preprocessed)	.h5ad	X, obsm["spatial"], obsm["X_pca"]	preprocessed.h5ad
AnnData (raw, demo mode)	.h5ad	X, obsm["spatial"]	demo_visium.h5ad

Workflow

1. Load: Read preprocessed h5ad; verify spatial coordinates and embeddings exist
2. Preprocess (demo mode only): Normalize, log1p, PCA, neighbors if not already done
3. Domain identification: Run selected method (Leiden or SpaGCN)
4. Embed: Compute UMAP if not present for visualization
5. Visualize: Generate spatial domain map and UMAP domain plot
6. Report: Write report.md, result.json, processed.h5ad, figures, tables, reproducibility bundle

CLI Reference

# Standard usage (Leiden, default)
python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --output <report_dir>

# Specify method and parameters
python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method leiden --resolution 0.8 --spatial-weight 0.3 --output <dir>

python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method louvain --resolution 1.0 --output <dir>

python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method spagcn --n-domains 7 --output <dir>

python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method stagate --n-domains 7 --rad-cutoff 50.0 --output <dir>

python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method graphst --n-domains 7 --output <dir>

python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method banksy --resolution 0.7 --lambda-param 0.2 --output <dir>

# Apply spatial refinement
python skills/spatial-domains/spatial_domains.py \
  --input <preprocessed.h5ad> --method leiden --refine --output <dir>

# Demo mode
python skills/spatial-domains/spatial_domains.py --demo --output /tmp/domains_demo

# Via OmicsClaw runner
python omicsclaw.py run spatial-domain-identification --input <file> --output <dir>
python omicsclaw.py run spatial-domain-identification --demo

Algorithm / Methodology

Leiden (default)

1. Input: Preprocessed AnnData with neighbor graph
2. Spatial weighting: Combines expression-based and spatial neighbor graphs with configurable weight
3. Clustering: sc.tl.leiden(resolution=resolution, flavor="igraph")
4. Labels: Stored in adata.obs["spatial_domain"]

Key parameters:

• resolution: Controls granularity (default 1.0; higher = more domains)
• spatial_weight: Weight of spatial graph (0.0-1.0, default 0.3)
• n_neighbors: Number of neighbors for graph construction (default 15)

Louvain

1. Input: Preprocessed AnnData with neighbor graph
2. Clustering: sc.tl.louvain(resolution=resolution)
3. Labels: Stored in adata.obs["spatial_domain"]
4. Requires: pip install louvain

Key parameters:

• resolution: Controls granularity (default 1.0)

SpaGCN

1. Input: AnnData with spatial coordinates and expression matrix
2. Spatial graph: Build adjacency from spatial coordinates
3. GCN clustering: SpaGCN.train() with n_domains target clusters
4. Refinement: Built-in spatial-aware label refinement
5. Labels: Stored in adata.obs["spatial_domain"]

Key parameters:

• n_domains: Target number of spatial domains
• Source: Hu et al., Nature Methods 2021

STAGATE

1. Input: AnnData with spatial coordinates
2. Spatial network: Build graph with radius cutoff
3. Graph attention: Train attention auto-encoder on PyTorch
4. Clustering: Gaussian Mixture Model on learned embeddings
5. Labels: Stored in adata.obs["spatial_domain"]

Key parameters:

• n_domains: Target number of domains
• rad_cutoff: Radius for spatial network (default 50.0)
• Source: Dong & Zhang, Nature Communications 2022

GraphST

1. Input: AnnData with spatial coordinates
2. Contrastive learning: Self-supervised graph neural network
3. Embedding: PCA on learned representations
4. Clustering: Gaussian Mixture Model
5. Labels: Stored in adata.obs["spatial_domain"]

Key parameters:

• n_domains: Target number of domains
• Source: Long et al., Nature Communications 2023

BANKSY

1. Input: AnnData with spatial coordinates
2. Feature augmentation: Neighborhood-averaged expression + azimuthal Gabor filters
3. PCA: Dimensionality reduction on augmented features
4. Clustering: Leiden on BANKSY-augmented space
5. Labels: Stored in adata.obs["spatial_domain"]

Key parameters:

• lambda_param: Spatial regularization (default 0.2)
• resolution: Leiden resolution (default 0.7)
• num_neighbours: Neighbors for feature construction (default 15)

Spatial Refinement (optional)

1. KNN smoothing: For each spot, find k nearest spatial neighbors
2. Majority vote: Relabel if >threshold fraction of neighbors disagree
3. Conservative: Only changes labels with strong spatial disagreement

Key parameters:

• threshold: Disagreement threshold (default 0.5)
• k: Number of spatial neighbors (default 10)

Example Queries

• "Identify spatial domains in my Visium data"
• "Find tissue regions using SpaGCN"
• "Cluster my spatial transcriptomics data into niches"
• "Run spatial domain detection with 7 clusters"

Output Structure

output_dir/
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── spatial_domains.png
│   └── umap_domains.png
├── tables/
│   └── domain_summary.csv
└── reproducibility/
    ├── commands.sh
    ├── environment.yml
    └── checksums.sha256

Dependencies

Required (in requirements.txt):

• scanpy >= 1.9 — single-cell/spatial analysis
• squidpy >= 1.2 — spatial extensions
• matplotlib — plotting
• numpy, pandas — numerics

Optional:

• SpaGCN — spatially-aware graph convolutional clustering
• STAGATE_pyG — graph attention auto-encoder domains (requires PyTorch)
• GraphST — graph self-supervised contrastive learning (requires PyTorch)
• banksy — spatial feature augmentation
• louvain — Louvain clustering algorithm

Safety

• Local-first: Strict offline processing without external upload.
• Disclaimer: Requires OmicsClaw reporting structures and disclaimers.
• Audit trail: Hyperparameters and operational flow states are logged fully.
• Non-destructive: Domain labels added as new adata.obs column, original data preserved

Integration with Orchestrator

Trigger conditions:

• Automatically invoked dynamically based on tool metadata and user intent matching.
• Keywords — spatial domain, tissue region, niche, SpaGCN, STAGATE

Chaining partners:

• spatial-preprocess: Provides the preprocessed h5ad input
• spatial-de: Downstream differential expression between domains
• spatial-enrichment: Gene set enrichment per domain
• spatial-communication: Cell-cell communication across domain boundaries

Citations

• Scanpy — analysis framework
• Leiden algorithm — community detection
• SpaGCN — Hu et al., Nature Methods 2021
• STAGATE — Dong & Zhang, Nature Communications 2022
• GraphST — Long et al., Nature Communications 2023