spatial-de

spatial-de

When to use

Rank spatial group markers with Wilcoxon or t-test, or compare conditions with sample-aware PyDESeq2 pseudobulk. Biological sample labels are required; spatial spots do not supply independent replicates.

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-de")
adata = read_input("processed.h5ad")
library.differential_expression(adata, groupby="leiden")
write_output(library.results(adata), "tables/de_full.csv")

The executable example checks known markers in simulated spatial domains.

API

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

differential_expression(adata, *, method='wilcoxon', groupby='leiden', group1=None, group2=None, n_top_genes=10, fdr_threshold=0.05, log2fc_threshold=1.0, **parameters)

Test groups and return the same AnnData, with results in its diagnostics.

Scanpy uses raw when present, otherwise log-normalized X. PyDESeq2 uses counts, then raw, then X; provide integer counts and biological samples.

:param adata: Expression and group labels; modified in place. :param method: CLI default wilcoxon; t-test or pydeseq2 for other tests. :param groupby: CLI default leiden; obs column defining comparisons. :param group1: Tested group, or None for each group versus rest. :param group2: Reference group; supply together with group1. :param n_top_genes: CLI default 10 marker genes per group. :param fdr_threshold: CLI default 0.05 adjusted-p-value threshold. :param log2fc_threshold: CLI default 1.0 effect-size threshold. :param parameters: Method-specific CLI parameters from references/parameters.md. :returns: The same AnnData; results returns the full result table. :raises ValueError: Groups, method or sample replication are invalid. :raises ImportError: PyDESeq2 is unavailable; use install_skill_deps.

results(adata, *, markers_only=False)

Return the full or selected marker table without changing expression.

:param adata: AnnData returned by differential_expression. :param markers_only: Default False; True selects the reported top markers. :returns: A new DataFrame with method-native effect and significance columns. :raises ValueError: No differential expression run is recorded.

run_info(adata, *, keep=True)

Read diagnostics and the result tables from the most recent run.

:param adata: AnnData returned by differential_expression. :param keep: Default True; False removes diagnostics before CLI serialization. :returns: Diagnostic dictionary including full_df and markers_df. :raises ValueError: No differential expression run is recorded.

volcano_figure(adata, *, group=None)

Plot effect size against adjusted significance for one comparison.

:param adata: AnnData returned by differential_expression. :param group: Tested group; None chooses the first reported group. :returns: A matplotlib Figure; no files are written. :raises ValueError: No results exist for the selected group.

<!-- api:end -->

Methods and parameters

Scanpy ranks every gene, then optionally filters markers. PyDESeq2 requires both group labels and two retained pseudobulk profiles per condition. It uses a paired design when two biological samples contribute to both groups. See parameters for keyword arguments and methodology for matrix and design details.

Gotchas

• differential_expression uses Scanpy's raw preference when raw exists; otherwise provide log-normalized X. Count methods prefer layers['counts'].
• run_info()['design_formula'] records the PyDESeq2 paired/unpaired design.
• tables/skipped_sample_groups.csv records bins below the cell threshold.
• results(markers_only=True) may contain nonsignificant top genes when no genes pass all filters; inspect the significance columns.

Inputs and outputs

Functions modify AnnData in place and return DataFrames/Figures without writing files. The CLI writes processed.h5ad, tables/de_full.csv, marker/diagnostic tables, report and result JSON. The output contract lists conditional figures.

CLI

python skills/spatial/spatial-de/spatial_de.py --input processed.h5ad --output results/de
python skills/spatial/spatial-de/spatial_de.py --demo --output /tmp/spatial-de_demo

See also

Use spatial-preprocess before analysis, spatial-genes for autocorrelation, and sc-de or bulkrna-de for their respective modalities.

Dependencies

anndata, matplotlib, numpy, pandas, pydeseq2, scanpy, scipy, seaborn