Spatial transcriptomics

Spatial Transcriptomics Visium Analysis

When to Use This Skill

• You have 10x Visium spatial gene expression data (with or without H&E image)
• You want to identify spatially variable genes across a tissue section
• You want to discover spatial tissue domains via clustering
• You want to quantify neighborhood enrichment between cell clusters
• You want to analyze co-occurrence patterns of cell types across distances
• Input is Space Ranger output, .h5ad, or .h5 file

Not for: Single-molecule FISH (MERFISH/Xenium), Slide-seq, or single-cell RNA-seq without spatial coordinates. For scRNA-seq, use scrnaseq-scanpy-core-analysis.

Installation

pip install squidpy scanpy anndata scikit-misc plotnine plotnine-prism seaborn matplotlib numpy pandas scikit-learn

Package	Version	License	Commercial Use	Installation
squidpy	≥1.4	BSD-3-Clause	✅ Permitted	pip install squidpy
scanpy	≥1.9	BSD-3-Clause	✅ Permitted	pip install scanpy
anndata	≥0.8	BSD-3-Clause	✅ Permitted	pip install anndata
plotnine	≥0.12	MIT	✅ Permitted	pip install plotnine
plotnine-prism	≥0.2	MIT	✅ Permitted	pip install plotnine-prism
seaborn	≥0.11	BSD-3-Clause	✅ Permitted	pip install seaborn
matplotlib	≥3.5	PSF	✅ Permitted	pip install matplotlib
scikit-learn	≥1.0	BSD-3-Clause	✅ Permitted	pip install scikit-learn
scikit-misc	≥0.1	BSD-3-Clause	✅ Permitted	pip install scikit-misc
numpy	≥1.21	BSD-3-Clause	✅ Permitted	pip install numpy
pandas	≥1.3	BSD-3-Clause	✅ Permitted	pip install pandas

License Compliance: All packages use permissive licenses (BSD, MIT, PSF) that permit commercial use in AI agent applications.

Inputs

Input	Format	Description
Visium data	.h5ad, .h5, or Space Ranger directory	Gene expression + spatial coordinates
H&E image	Embedded in above	Tissue histology (optional, enhances spatial plots)

Built-in example: V1_Human_Heart from 10x Genomics (~4,247 spots, ~33,538 genes, includes H&E image).

Outputs

Analysis objects:

• adata_processed.h5ad — Complete processed AnnData for downstream use
  • Load with: adata = sc.read_h5ad('adata_processed.h5ad')
  • Contains: clusters, embeddings, SVG results, spatial graph

Tables (CSV):

• spatially_variable_genes.csv — SVGs ranked by Moran's I with FDR
• cluster_assignments.csv — Spot barcodes + Leiden cluster + spatial coordinates
• neighborhood_enrichment.csv — Cluster-cluster enrichment z-scores
• spot_metadata.csv — All spot-level QC and annotation metadata
• analysis_summary.txt — Human-readable report

Plots (PNG + SVG):

• qc_violins — QC metric distributions
• spatial_clusters — Leiden clusters overlaid on tissue
• spatial_markers — Selected marker gene expression on tissue
• umap_clusters — UMAP embedding colored by cluster
• neighborhood_enrichment — Cluster enrichment heatmap
• co_occurrence — Co-occurrence probability vs distance
• top_svgs — Bar chart of top spatially variable genes
• spatial_svg_[GENE] — Spatial expression of top SVG

Clarification Questions

ALWAYS ask Question 1 FIRST:

1. Input Files (ASK THIS FIRST):

• Do you have Visium data files to analyze?
  • Supported formats: .h5ad, .h5, or Space Ranger output directory
• Or use example data? V1_Human_Heart from 10x Genomics (human cardiac tissue, ~4K spots)

🚨 IF EXAMPLE DATA SELECTED: All parameters are pre-configured. Skip remaining questions. Proceed directly to Step 1.

2. Analysis Parameters (ONLY if user provides own data):

• Clustering resolution?
  • a) 0.5 (fewer, broader clusters)
  • b) 0.8 (standard — recommended)
  • c) 1.2 (more, finer clusters)
• Mitochondrial threshold?
  • a) 50% (recommended for cardiac/muscle tissue — high MT is normal)
  • b) 20% (standard for most tissues)
  • c) 30% (moderate)

3. Marker Genes (ONLY if user provides own data):

• Which marker genes to highlight in spatial plots?
  • Provide a list or use tissue-appropriate defaults

Standard Workflow

🚨 MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE 🚨

Note: Run from the OmicsClaw root directory and add the workflow scripts to sys.path:

import sys; import os; sys.path.insert(0, os.path.abspath('knowledge_base/scripts/spatial-transcriptomics'))

Step 1 — Load data:

from load_example_data import load_visium_heart
adata = load_visium_heart()

DO NOT write inline data loading code. Just use the script.

✅ VERIFICATION: You MUST see: "✓ Data loaded successfully!"

---

Step 2 — Run analysis:

from spatial_workflow import run_spatial_analysis
adata = run_spatial_analysis(adata, output_dir="visium_results")

DO NOT write inline analysis code. Just use the script.

✅ VERIFICATION: You MUST see: "✓ Spatial analysis completed successfully!"

❌ IF YOU DON'T SEE THIS: You wrote inline code. Stop and use the script.

---

Step 3 — Generate visualizations:

from generate_all_plots import generate_all_plots
generate_all_plots(adata, output_dir="visium_results")
# For non-cardiac tissue, pass tissue-appropriate markers:
# generate_all_plots(adata, output_dir="visium_results", marker_genes=["GENE1", "GENE2"])

🚨 DO NOT write inline plotting code (plt.savefig, ggplot, clustermap, etc.). Just use the script. 🚨

The script handles PNG + SVG export with graceful fallback for SVG.

✅ VERIFICATION: You MUST see: "✓ All visualizations generated successfully!"

---

Step 4 — Export results:

from export_results import export_all
export_all(adata, output_dir="visium_results")

DO NOT write custom export code. Use export_all().

✅ VERIFICATION: You MUST see:

==================================================
=== Export Complete ===
==================================================

---

⚠️ CRITICAL — DO NOT:

• ❌ Write inline analysis code → STOP: Use run_spatial_analysis()
• ❌ Write inline plotting code → STOP: Use generate_all_plots()
• ❌ Write custom export code → STOP: Use export_all()
• ❌ Try to install system libraries → scripts handle optional deps gracefully

⚠️ IF SCRIPTS FAIL — Script Failure Hierarchy:

1. Fix and Retry (90%) — Install missing package, re-run script
2. Modify Script (5%) — Edit the script file itself, document changes
3. Use as Reference (4%) — Read script, adapt approach, cite source
4. Write from Scratch (1%) — Only if genuinely impossible, explain why

NEVER skip directly to writing inline code without trying the script first.

Common Issues

Error	Cause	Fix
ModuleNotFoundError: squidpy	Missing package	pip install squidpy
ModuleNotFoundError: plotnine_prism	Missing theme package	pip install plotnine-prism
SVG export failed	Missing SVG backend	Normal — PNG always generated. SVG is best-effort.
ValueError: coord_type='grid'	Non-grid spatial data	Use coord_type='generic' for non-Visium data
0 SVGs found (FDR < 0.05)	Low signal or few permutations	Increase svgs_n_perms=1000 or relax FDR threshold
Memory error on large dataset	Too many spots/genes	Filter more aggressively or use sc.pp.subsample()
KeyError: 'spatial'	Missing spatial coordinates	Ensure data was loaded with sc.read_visium() or has .obsm['spatial']
NaN in co-occurrence	Known squidpy issue with n_splits	Use default n_splits parameter (do not override)

Interpreting Results

Spatially Variable Genes (SVGs):

• Moran's I close to +1 → Gene expression is spatially clustered (strong spatial pattern)
• Moran's I close to 0 → No spatial structure (random distribution)
• Moran's I close to -1 → Dispersed pattern (checkerboard; rare in practice)
• FDR < 0.05 is the standard significance threshold; use < 0.01 for stringent filtering
• Top SVGs typically include tissue-specific markers and boundary genes

Neighborhood Enrichment Z-scores:

• Z > 2 → Clusters are significantly co-localized (tend to be spatially adjacent)
• Z < -2 → Clusters are significantly segregated (avoid each other spatially)
• -2 to 2 → No significant spatial preference
• Diagonal values (self-enrichment) indicate how spatially cohesive each cluster is

Co-occurrence Curves:

• Probability above expected → Clusters co-occur more than random at that distance
• Distance-dependent changes reveal spatial organization (e.g., border zone cell types co-occur at short range)

Cluster-to-Tissue Mapping:

• Compare spatial cluster plots with H&E histology to validate biological relevance
• Well-defined spatial clusters that match visible tissue structures (e.g., myocardium, fibrotic region) indicate meaningful tissue domains

Agent Summary Guidelines

When presenting results to the user, the agent should:

• Report key numbers: spots analyzed, clusters found, number of significant SVGs
• Highlight top 5-10 SVGs with Moran's I values and known biological roles
• Describe spatial patterns: which clusters are co-localized vs segregated
• Connect to biology: relate spatial patterns to tissue architecture visible in H&E
• Note limitations: permutation count affects SVG p-values; low n_perms may miss weak signals
• DO NOT hallucinate gene functions — only report known annotations or suggest looking up unknown genes
• DO NOT over-interpret co-occurrence curves from small datasets or few clusters

Mitochondrial content note: Cardiac/muscle tissue has naturally high MT% (~30-40%) due to mitochondria-rich cells. The default max_pct_mito=50% is appropriate for heart tissue. For other tissues (brain, liver, immune), use 20% or lower.

Suggested Next Steps

• Functional enrichment on SVG gene sets → functional-enrichment-from-degs
• Cell type deconvolution with cell2location or RCTD (specialized workflow)
• Cell-cell communication with CellChat or COMMOT on spatial data
• Multi-sample integration for comparing conditions (e.g., MI vs healthy)
• Gene regulatory networks on spatial clusters → grn-pyscenic

Related Skills

Skill	Relationship
scrnaseq-scanpy-core-analysis	Companion scRNA-seq analysis (non-spatial)
functional-enrichment-from-degs	Downstream: enrichment on SVG gene lists
de-results-to-gene-lists	Downstream: gene list preparation from SVGs
grn-pyscenic	Downstream: regulatory networks from spatial clusters
coexpression-network	Downstream: co-expression on spatial domains

References

• Squidpy: Palla G, et al. "Squidpy: a scalable framework for spatial omics analysis." Nature Methods (2022). doi:10.1038/s41592-021-01358-2
• Scanpy: Wolf FA, et al. "SCANPY: large-scale single-cell gene expression data analysis." Genome Biology (2018). doi:10.1186/s13059-017-1382-0
• Moran's I: Moran PAP. "Notes on continuous stochastic phenomena." Biometrika (1950). doi:10.2307/2332142
• 10x Visium: 10x Genomics. "Visium Spatial Gene Expression." https://www.10xgenomics.com/platforms/visium

Detailed parameter guidance: See references/spatial-analysis-guide.md