spatial-statistics

name	spatial-statistics
description	Load when running spatial autocorrelation / hotspot / co-occurrence / neighbourhood-enrichment / Ripley K stats on a clustered spatial AnnData via squidpy. Skip when ranking spatially variable genes (use spatial-genes) or for tissue domain detection (use spatial-domains).
version	0.5.0
author	OmicsClaw
license	MIT
tags	["spatial","statistics","moran","geary","ripley","co-occurrence","nhood-enrichment","getis-ord","squidpy"]
requires	["anndata","scanpy","squidpy","numpy","pandas"]

spatial-statistics

When to use

The user has a clustered spatial AnnData (obs[--cluster-key] for cluster-aware analyses; obsm["spatial"] populated) and wants a specific spatial-statistics analysis. Pick --analysis-type from VALID_ANALYSIS_TYPES:

• moran / geary — global spatial autocorrelation per gene.
• local_moran — per-spot LISA + GeoDa quadrants (--local-moran-geoda-quads).
• getis_ord — per-spot hotspot Z-scores.
• bivariate_moran — exactly two genes (--genes geneA,geneB).
• neighborhood_enrichment — squidpy NES between cluster pairs.
• ripley — Ripley K / L / G / F (--ripley-mode, --ripley-metric).
• co_occurrence — pairwise label co-occurrence at distance bins (--coocc-interval, --coocc-n-splits).
• spatial_centrality — graph-centrality per spot.

For per-gene SVG ranking use spatial-genes; for tissue-domain detection use spatial-domains.

Inputs & Outputs

Input	Format	Required
Clustered spatial AnnData	.h5ad with obsm["spatial"] + obs[--cluster-key]	yes (unless --demo)
Genes	--genes geneA,geneB,... (comma-separated)	required for bivariate_moran

Output	Path	Notes
Annotated AnnData	processed.h5ad	adds per-gene analysis-specific obs columns: obs[f"local_moran_<gene>"] / obs[f"local_moran_pval_<gene>"] / obs[f"local_moran_q_<gene>"] (_lib/statistics.py:739-741); obs[f"getis_ord_<gene>"] / obs[f"getis_ord_pval_<gene>"] (:832-833). Other analyses write to uns.
Analysis summary	tables/analysis_summary.csv	always
Neighbourhood Z-score matrix	tables/neighborhood_zscore.csv	when --analysis-type neighborhood_enrichment
Neighbourhood counts	tables/neighborhood_counts.csv	when --analysis-type neighborhood_enrichment
Bivariate-Moran summary	tables/bivariate_moran_summary.csv	when --analysis-type bivariate_moran
Per-analysis result tables	tables/<analysis-specific>.csv	dispatched per analysis-type
Report	report.md + result.json	always

Flow

1. Load AnnData (--input) or chain through spatial-preprocess --demo via subprocess (spatial_statistics.py:1499-1515).
2. parser.error validates --analysis-type ∈ VALID_ANALYSIS_TYPES; per-analysis numeric ranges (lines :1558-1601).
3. Auto-resolve --cluster-key if unset; auto-leiden if no cluster column exists (with size guard at :1546).
4. Dispatch to analysis-type runner; squidpy graph build uses --stats-n-neighs / --stats-n-rings / --stats-n-perms.
5. Build standardised result tables; collect per-spot metrics.
6. Save tables, figures, processed.h5ad, report.md, result.json.

Gotchas

• All input + parameter validation goes through parser.error (exit code 2). spatial_statistics.py:1530 for missing --input; :1546 for too-small dataset to auto-leiden; :1558 for invalid --analysis-type; :1560-1601 for numeric / multi-value flag validation. Wrappers expecting ValueError need to catch exit-2.
• bivariate_moran requires exactly TWO genes. spatial_statistics.py:1601 raises parser.error("--analysis-type bivariate_moran requires exactly two genes via --genes geneA,geneB"). Pass them comma-separated, no spaces.
• Demo chains through spatial-preprocess via subprocess. spatial_statistics.py:1499 raises FileNotFoundError(f"spatial-preprocess not found at {preprocess_script}") if the sibling skill is missing; :1510 raises RuntimeError("spatial-preprocess --demo failed (exit ...)") on chained failure; :1515 raises FileNotFoundError(f"Expected {processed}") when the demo output isn't where expected.
• --cluster-key auto-leiden has a size guard. spatial_statistics.py:1546 raises parser.error("Dataset is too small to auto-compute leiden clusters.") when the auto-fallback can't run. Pass --cluster-key <existing-column> for small datasets.
• local_moran writes n_significant_spots; getis_ord writes n_hotspots. spatial_statistics.py:555 documents the value-column divergence. Downstream tools reading "spatially significant cell count" need to branch on --analysis-type.
• neighborhood_enrichment consumes <cluster_key>_nhood_enrichment from uns. Computed lazily within squidpy; if you re-run with a different --cluster-key, the previous uns key remains and won't be reused for the new cluster column. Clean adata.uns between runs or expect stale keys.
• spatial_centrality is graph-only. It produces per-spot centrality without any cluster-key dependency — useful when --cluster-key is unavailable.

Key CLI

# Demo (chained from spatial-preprocess --demo)
python omicsclaw.py run spatial-statistics --demo --analysis-type moran --output /tmp/spatial_stats_demo

# Global Moran's I on a clustered AnnData
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type moran --cluster-key spatial_domain --stats-n-perms 100

# Local Moran with GeoDa quadrants
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type local_moran --local-moran-geoda-quads --n-top-genes 20

# Neighbourhood enrichment between clusters
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type neighborhood_enrichment --cluster-key spatial_domain

# Ripley K on a labelled object
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type ripley --ripley-mode K --ripley-n-simulations 100 --ripley-n-steps 50

# Co-occurrence at increasing distance bins
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type co_occurrence --cluster-key cell_type --coocc-interval 30 --coocc-n-splits 5

# Bivariate Moran between two genes
python omicsclaw.py run spatial-statistics \
  --input clustered.h5ad --output results/ \
  --analysis-type bivariate_moran --genes EGFR,BRCA1

See also

• references/parameters.md — every CLI flag, per-analysis numeric ranges
• references/methodology.md — when each analysis-type wins; squidpy mapping
• references/output_contract.md — per-analysis table / obs / uns schema
• Adjacent skills: spatial-preprocess (upstream — produces obsm["spatial"] + cluster column), spatial-domains / spatial-annotate (upstream — produce obs["spatial_domain"] / cell-type labels for --cluster-key), spatial-genes (parallel — per-gene SVG ranking, NOT statistics on labels), spatial-de (downstream — DE between clusters identified by neighbourhood-enrichment hotspots)