Spatial Domains

<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

---
name: bio-spatial-domains
description: Identify tissue regions and spatial niches from preprocessed spatial
  transcriptomics data using Leiden, Louvain, SpaGCN, STAGATE, GraphST, or BANKSY.
tool_type: mixed
primary_tool: spatial
measurable_outcome: Execute skill workflow successfully with valid output within 15
  minutes.
allowed-tools:
- read_file
- run_shell_command
---

# 🗺️ 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

```bash
# 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](https://scanpy.readthedocs.io/) — analysis framework
- [Leiden algorithm](https://www.nature.com/articles/s41598-019-41695-z) — community detection
- [SpaGCN](https://doi.org/10.1038/s41592-021-01255-8) — Hu et al., *Nature Methods* 2021
- [STAGATE](https://doi.org/10.1038/s41467-022-29439-6) — Dong & Zhang, *Nature Communications* 2022
- [GraphST](https://doi.org/10.1038/s41467-023-36796-3) — Long et al., *Nature Communications* 2023

<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->