spatialagent/skill/squidpy_analysis.md

Squidpy Spatial Analysis

Comprehensive spatial analysis tools for single-cell and spatial transcriptomics data using Squidpy.

When to Use Squidpy

Analysis Type	Tool
Build spatial graph	squidpy_spatial_neighbors
Cell type colocalization	squidpy_nhood_enrichment
Co-occurrence patterns	squidpy_co_occurrence
Spatially variable genes	squidpy_spatial_autocorr
Point pattern analysis	squidpy_ripley
Network topology	squidpy_centrality
Cell-cell interactions	squidpy_ligrec

---

Workflow Overview

1. Build spatial neighbors graph (required first step)
2. Analyze spatial patterns (choose based on question)
3. Interpret results

---

Step 1: Build Spatial Neighbors Graph

Tool: squidpy_spatial_neighbors

This is required before any other Squidpy analysis.

Parameters

Parameter	Description	Default
coord_type	"visium" (hex), "grid" (square), or "generic" (any)	"generic"
n_neighs	Number of neighbors for generic/KNN	6
n_rings	Number of hex/grid rings for visium/grid	1
delaunay	Use Delaunay triangulation	False
radius	Radius cutoff (0 = disabled)	0

Tips

• For Visium data: Use coord_type="visium", n_rings=1 (6 neighbors)
• For generic spatial data: Use coord_type="generic", n_neighs=6-10
• For Delaunay triangulation: Set delaunay=True for natural neighbor connections
• For radius-based neighbors: Set radius to distance threshold (e.g., 100 microns)

---

Step 2: Choose Analysis Based on Question

A. Are certain cell types colocalized?

Tool: squidpy_nhood_enrichment

Tests whether cells of one type are more/less likely to neighbor cells of another type.

Output:

• Z-scores: positive = enriched, negative = depleted
• Heatmap showing cell type interactions

Example questions:

• "Are T cells enriched near tumor cells?"
• "Which cell types cluster together?"

---

B. Do cell types co-occur spatially?

Tool: squidpy_co_occurrence

Measures co-occurrence probability at different spatial distances.

Parameters:

• interval: Number of distance bins (default 50)
• n_splits: Split for computation (default 2)

Output:

• Co-occurrence scores per distance
• Shows spatial range of interactions

Example questions:

• "At what distance do T cells and tumor cells interact?"
• "How does co-occurrence change with distance?"

---

C. Which genes are spatially variable?

Tool: squidpy_spatial_autocorr

Identifies genes with spatial patterns using Moran's I or Geary's C statistics.

Parameters:

• mode: "moran" (default) or "geary"
• genes: List of genes or "highly_variable" or None (all)
• n_perms: Permutations for p-value (default 100)
• n_jobs: Parallel jobs (default 1)

Output:

• Moran's I: 1 = clustered, 0 = random, -1 = dispersed
• Geary's C: 0 = clustered, 1 = random
• p-values from permutation test

Example questions:

• "Which genes show spatial clustering?"
• "Are marker genes spatially organized?"

---

D. What are the spatial patterns? (Point Process)

Tool: squidpy_ripley

Characterizes point patterns using Ripley's statistics.

Parameters:

• mode: "F", "G", or "L"
  • F: Empty space function
  • G: Nearest neighbor distribution
  • L: Ripley's L (cluster detection)
• n_simulations: Bootstrap simulations (default 100)

Output:

• L > 0: Clustering at that distance
• L < 0: Dispersion/regularity
• L = 0: Complete spatial randomness

Example questions:

• "Are tumor cells clustered or dispersed?"
• "At what scale do clusters form?"

---

E. What is the network structure?

Tool: squidpy_centrality

Computes graph centrality metrics per cell type.

Parameters:

• mode: "closeness" or "degree"
  • closeness: How central in the network
  • degree: Number of connections

Output:

• Centrality scores per cell type
• Identifies spatially central vs peripheral populations

Example questions:

• "Which cell types are most central?"
• "Are tumor cells at the network periphery?"

---

F. How do cell types interact physically?

Tool: squidpy_interaction_matrix

Computes cell-cell contact/interaction matrix.

Parameters:

• normalized: Normalize by cell counts (default True)

Output:

• Interaction counts/frequencies between all cell type pairs

---

G. What ligand-receptor interactions occur?

Tool: squidpy_ligrec

Permutation-based ligand-receptor analysis with spatial context.

Parameters:

• n_perms: Number of permutations (default 1000)
• threshold: Expression threshold (default 0.01)
• corr_method: Multiple testing correction (default "fdr_bh")
• gene_symbols: Column with gene symbols (optional)

Output:

• Significant LR pairs between cell types
• P-values from permutation test
• Mean expression values

---

Complete Workflow Examples

Example 1: Tumor Microenvironment Analysis

1. squidpy_spatial_neighbors(coord_type="generic", n_neighs=6)
2. squidpy_nhood_enrichment(cluster_key="cell_type")
   → Find which immune cells infiltrate tumor
3. squidpy_co_occurrence(cluster_key="cell_type")
   → Measure distance-dependent interactions
4. squidpy_ligrec(cluster_key="cell_type")
   → Identify signaling between tumor and immune cells

Example 2: Spatial Gene Expression Analysis

1. squidpy_spatial_neighbors(coord_type="visium", n_rings=1)
2. squidpy_spatial_autocorr(mode="moran", genes="highly_variable")
   → Find spatially variable genes
3. squidpy_ripley(cluster_key="cell_type", mode="L")
   → Characterize spatial clustering

Example 3: Tissue Organization Analysis

1. squidpy_spatial_neighbors(coord_type="generic", delaunay=True)
2. squidpy_centrality(cluster_key="cell_type", mode="closeness")
   → Find central cell populations
3. squidpy_nhood_enrichment(cluster_key="cell_type")
   → Identify neighborhood preferences

---

Output Files

All tools save results to the specified save_path:

Tool	Outputs
squidpy_spatial_neighbors	Updated AnnData with spatial graph
squidpy_nhood_enrichment	Heatmap PNG, Z-scores CSV
squidpy_co_occurrence	Co-occurrence plot PNG, scores CSV
squidpy_spatial_autocorr	Autocorrelation results CSV
squidpy_ripley	Ripley's statistics plot PNG, CSV
squidpy_centrality	Centrality scores CSV
squidpy_interaction_matrix	Interaction matrix PNG, CSV
squidpy_ligrec	LR results CSV, dotplot PNG

---

Tips

1. Always run squidpy_spatial_neighbors first - Other tools depend on the spatial graph.

2. Choose coord_type carefully:

   • Visium: Use "visium" for hex grid
   • Slide-seq, MERFISH: Use "generic"

3. Moran's I interpretation:

   • High positive I → Gene is spatially clustered
   • Near zero → Random distribution
   • High negative I → Gene is spatially dispersed (rare)

4. Neighborhood enrichment interpretation:

   • Positive z-score → Cell types colocalize more than expected
   • Negative z-score → Cell types avoid each other
   • Near zero → Random spatial distribution

5. For large datasets: Use n_jobs > 1 for parallel computation in spatial_autocorr.