/spatial-genes

name: spatial-genes
description: Load when ranking spatially variable genes with Moran's I, SpatialDE, SPARK-X, or FlashS. Skip when detecting tissue domains (use spatial-domains) or differential expression between groups (use spatial-de).
trigger: spatially variable gene, spatial gene, SVG, SpatialDE, SPARK-X, spatial pattern, Moran, spatial autocorrelation
tags:
- spatial
- svg
- spatially-variable-genes
- morans-i
- spatialde
- sparkx
- flashs

spatial-genes

When to use

Rank genes whose expression varies across spatial coordinates. Moran's I uses continuous log-normalized expression; SpatialDE, SPARK-X and the legacy FlashS approximation use counts. Scores have method-specific meanings.

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-genes")
adata = read_input("processed.h5ad")
library.spatial_genes(adata, random_state=0)
write_output(library.results(adata), "tables/svg_results.csv")

The executable example checks spatial autocorrelation in simulated stripes.

API

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

`spatial_genes(adata, *, method='morans', n_top_genes=20, fdr_threshold=0.05, random_state=None, **parameters)`

Compute spatial gene scores and return the same AnnData.

Moran's I reads X; count-based methods prefer counts, then raw, then X. SpatialDE AEH does not expose a seed: results vary between runs.

:param adata: Expression and spatial coordinates; modified in place. :param method: CLI default morans; spatialde, sparkx or flashs also supported. :param n_top_genes: CLI default 20 reported significant genes. :param fdr_threshold: CLI default 0.05 significance threshold. :param random_state: None uses CLI seeds, 0 for Moran's I and 42 for FlashS. :param parameters: Method-specific CLI parameters in references/parameters.md. :returns: The same AnnData with spatial_genes_results in uns. :raises ValueError: Method, thresholds or spatial coordinates are invalid. :raises ImportError: A backend is missing; use install_skill_deps.

`results(adata, *, significant_only=False)`

Return native spatial-gene scores and significance columns.

:param adata: AnnData returned by spatial_genes. :param significant_only: Default False; True selects the run's FDR threshold. :returns: A new DataFrame; score meaning depends on the method. :raises ValueError: No run is recorded.

`run_info(adata, *, keep=True)`

Read the most recent spatial-gene diagnostics.

:param adata: AnnData returned by spatial_genes. :param keep: Default True; False removes transient diagnostics for CLI output. :returns: Method, thresholds and significant-gene counts. :raises ValueError: No run is recorded.

`ranking_figure(adata, *, n_top=20)`

Plot the highest-scoring genes without writing files.

:param adata: AnnData returned by spatial_genes. :param n_top: Default 20 genes, matching the CLI report size. :returns: A matplotlib Figure. :raises ValueError: No run is recorded or n_top is not positive.

<!-- api:end -->

Methods and parameters

Moran's I defaults to six neighbors and 100 permutations. The default seed is 0 for Moran's I and 42 for FlashS, matching their CLIs. SpatialDE's optional AEH clustering has no seed interface and may vary between runs. SPARK-X requires R and SPARK. See [parameters](references/parameters.md) for backend keywords and [methodology](references/methodology.md) for algorithms.

Gotchas

• `spatial_genes` stores every method's table in `uns['spatial_genes_results']`;

Moran's I also writes `uns['moranI']`.

• `results` returns native scores, not a common calibrated statistic.
• Count methods prefer `layers['counts']`, then raw, then X with a warning;

preserve original counts before normalization.

• `run_info()['significance_column']` names the method's p-value/q-value column.
• `spatial_genes(method='spatialde')` needs both SpatialDE and NaiveDE.

Inputs and outputs

Functions modify AnnData in place and return tables/Figures without file output. The CLI writes `processed.h5ad`, `tables/svg_results.csv`, diagnostics, report and result JSON. The [output contract](references/output_contract.md) distinguishes temporary R exchange files from delivered artifacts.

CLI

python skills/spatial/spatial-genes/spatial_genes.py --input processed.h5ad --output results/genes
python skills/spatial/spatial-genes/spatial_genes.py --demo --output /tmp/spatial-genes_demo

See also

Use spatial-preprocess to prepare expression, spatial-de to compare groups, and spatial-statistics for spatial relationships between labels.

Dependencies

`anndata`, `matplotlib`, `numpy`, `pandas`, `scanpy`, `scipy`, `seaborn`, `SpatialDE`, `squidpy`, `statsmodels`

SpatialDE also imports NaiveDE. SPARK-X requires the R package SPARK.