spatial-genes

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 for backend keywords and methodology 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 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.