/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); tissue domain detection (use spatial-domains).
trigger: spatial statistics, Moran, Geary, Ripley, co-occurrence, Getis-Ord, local Moran, centrality
tags:
- spatial
- statistics
- moran
- geary
- ripley
- co-occurrence
- nhood-enrichment
- getis-ord
- squidpy

spatial-statistics

When to use

Measure spatial enrichment, co-occurrence, autocorrelation or graph structure. Use spatial-genes for SVG ranking and spatial-domains for regions.

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-statistics")
data = read_input("input.h5ad")
data = library.analyze(data, analysis_type="neighborhood_enrichment", random_state=123)
write_output(library.results_table(data), "tables/results.csv")

Run [examples/example_step.py](examples/example_step.py) through the step runner.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`analyze(adata, *, analysis_type: str='neighborhood_enrichment', random_state: int=123, **parameters)`

Run one spatial analysis in place and return the same AnnData.

Gene analyses read X (log-normalized expression); cluster and network analyses read labels, coordinates and spatial_connectivities. Existing spatial graphs are reused unless force_graph_rebuild=True. Bivariate Moran's backend cannot be seeded: results vary between runs.

:param adata: Spatial AnnData; cluster-aware methods require categorical labels. :param analysis_type: CLI default neighborhood_enrichment; also ripley, co_occurrence, moran, geary, local_moran, getis_ord, bivariate_moran, network_properties or spatial_centrality. :param random_state: Permutation/simulation seed, matching CLI default 123. Ignored by bivariate_moran; its run_info records this limitation. :param parameters: Method keyword options from references/parameters.md; omitted values retain backend wrapper defaults. Unknown options raise. :returns: The same AnnData with JSON-encoded diagnostics and result tables. :raises ValueError: Unknown analysis or invalid input. :raises TypeError: An option does not belong to the chosen method. :raises ImportError: Missing backend; use install_skill_deps with squidpy, esda, libpysal or networkx as reported in the error.

`run_info(adata, *, keep: bool=True) -> dict`

Read the analysis diagnostics, including method-specific DataFrames.

:param adata: AnnData returned by analyze. :param keep: True retains the record; False removes it before CLI serialization. :returns: Diagnostic dict; encoded tables are restored as DataFrames.

`results_table(adata, *, name: str='pair_summary_df')`

Return a method result table independently of the CLI gallery.

:param adata: AnnData returned by analyze. :param name: Default pair_summary_df for enrichment; results_df for most other methods, or zscore_df/count_df/per_cluster_df when present. :returns: A DataFrame copy. :raises KeyError: The selected analysis has no table with this name.

`enrichment_figure(adata)`

Plot the neighborhood enrichment z-score matrix.

:param adata: AnnData after neighborhood_enrichment; expression is not read. :returns: A matplotlib Figure without saving it. :raises KeyError: No enrichment matrix is available.

<!-- api:end -->

Methods and parameters

Ten methods remain available through analysis_type; extra keywords use Python wrapper names documented in references/parameters.md. Existing spatial graphs are reused unless force_graph_rebuild=True. See [parameters](references/parameters.md) and [methodology](references/methodology.md).

Gotchas

• `results_table` defaults to pair_summary_df; other methods often return results_df. `spatial_centrality` requires labels and returns cluster-level scores.
• `run_info(keep=False)` removes library diagnostics before CLI serialization.

Inputs and outputs

The library returns AnnData, DataFrames or Figures without file writes. The CLI keeps reports, result.json, tables and conditional gallery outputs. See the complete [output contract](references/output_contract.md) for filenames and conditions.

CLI

python skills/spatial/spatial-statistics/spatial_statistics.py --input data.h5ad --output results/spatial-statistics

See also

• [Methodology](references/methodology.md)
• [Parameters](references/parameters.md)
• [Output contract](references/output_contract.md)

Dependencies

`anndata`, `esda`, `libpysal`, `matplotlib`, `networkx`, `numpy`, `pandas`, `scanpy`, `scipy`, `seaborn`, `squidpy`