spatial-enrichment

spatial-enrichment

When to use

Interpret group markers with gene sets, or score group-mean expression. The default is a small local OmicsClaw signature library. Hosted libraries require network access; explicit gene-set mappings and local GMT/JSON files work offline. Synthetic demo signatures are not curated biological pathways.

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-enrichment")
adata = read_input("processed.h5ad")
library.enrich(adata, groupby="leiden", source="omicsclaw_core")
write_output(library.results(adata), "tables/enrichment_results.csv")

The executable example uses explicit synthetic marker sets and checks their known group enrichment.

For local libraries use sets = read_input("data/sets.gmt", reader=library.read_gene_sets), then library.enrich(adata, gene_sets=sets). read_input records the file hash. library.fetch_gene_sets("KEGG_2021_Human") explicitly accesses the network. Cache that mapping as JSON before a repeatable analysis, then load the cached file with read_input and this reader. Computation accepts built-in sources or mappings.

API

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

read_gene_sets(path)

Read a local GMT or JSON gene-set library without writing files.

In a step call read_input(path, reader=library.read_gene_sets) to record the input file hash and resolve the path relative to the project root.

:param path: Local GMT or JSON path supplied by read_input or the CLI. :returns: Term-to-gene mapping retaining its local source metadata. :raises FileNotFoundError: The local file is absent. :raises ValueError: The format or JSON structure is invalid.

fetch_gene_sets(source, *, species='human')

Fetch a remote Enrichr library; this call requires network access.

Cache the mapping as JSON, then use read_input(path, reader=library.read_gene_sets) for repeatable analysis steps. Fetching alone does not record a file hash.

:param source: Enrichr library name or an alias in references/parameters.md. :param species: Default human; mouse is also supported. :returns: Term-to-gene mapping retaining requested and resolved library names. :raises ValueError: Species or remote source is invalid or unavailable. :raises ImportError: gseapy is unavailable; use install_skill_deps.

enrich(adata, *, method='enrichr', groupby='leiden', source='omicsclaw_core', species='human', gene_sets=None, gene_set=None, fdr_threshold=0.05, n_top_terms=20, random_state=123, **parameters)

Enrich group markers or score group means and return the same AnnData.

Marker ranking reads raw when present, otherwise X; ssGSEA reads X and scores group means, then copies each group's score to its observations.

:param adata: Log-normalized expression and group labels; modified in place. :param method: CLI default enrichr; gsea or ssgsea also supported. :param groupby: CLI default leiden; obs column defining groups. :param source: CLI default omicsclaw_core; only built-in libraries are resolved here. :param species: CLI default human; mouse changes the built-in symbols. :param gene_sets: Already-read term-to-gene mapping; None selects the built-in source. :param gene_set: Optional built-in library alias overriding source. :param fdr_threshold: CLI default 0.05 adjusted significance cutoff. :param n_top_terms: CLI default 20 reported terms or attached score columns. :param random_state: CLI default 123 for GSEA and ssGSEA backend randomness. :param parameters: Method-specific CLI options in references/parameters.md. :returns: The same AnnData, with canonical enrichment_results in uns. :raises ValueError: Groups, gene sets or numeric thresholds are invalid. :raises TypeError: A file path is passed; use read_gene_sets first.

results(adata, *, significant_only=False)

Return enrichment results, retaining missing p values for score-only methods.

:param adata: AnnData returned by enrich. :param significant_only: Default False; True selects adjusted p values below FDR. :returns: A new DataFrame; ssGSEA scores do not imply significance. :raises ValueError: No enrichment run is recorded.

run_info(adata, *, keep=True)

Read enrichment diagnostics, including any executed fallback method.

:param adata: AnnData returned by enrich. :param keep: Default True; False removes transient diagnostics for CLI output. :returns: Diagnostic dictionary, including enrich_df and marker_df. :raises ValueError: No enrichment run is recorded.

terms_figure(adata, *, n_top=20)

Plot available term scores without treating scores as calibrated p values.

:param adata: AnnData returned by enrich. :param n_top: Default 20 rows, matching the CLI report size. :returns: A matplotlib Figure; an empty result is labelled explicitly. :raises ValueError: No run is recorded or n_top is not positive.

<!-- api:end -->

Methods and parameters

Enrichr performs local over-representation on positive markers; GSEA uses per-group rankings. ssGSEA scores group means and copies each score to its spots. These are not independent per-spot estimates. Defaults include 100 GSEA permutations and seed 123. See parameters for keyword arguments and methodology for scoring details.

Gotchas

• run_info() records warnings and the executed method if GSEApy falls back to hypergeometric, mean-rank permutation or descriptive mean scoring.
• fetch_gene_sets raises when a requested remote library cannot be resolved.
• uns['enrichment_score_columns'] lists attached ssGSEA columns.
• results(significant_only=True) excludes rows without p values.
• enrich requires group labels; automatic Leiden clustering belongs to the CLI.

Inputs and outputs

The library reads log-normalized expression; Scanpy marker ranking prefers raw if present. Functions modify AnnData and return tables/Figures. The CLI writes processed.h5ad, tables/enrichment_results.csv, diagnostics, report and result JSON. See output contract for conditional outputs.

CLI

python skills/spatial/spatial-enrichment/spatial_enrichment.py --input processed.h5ad --output results/enrichment
python skills/spatial/spatial-enrichment/spatial_enrichment.py --demo --output /tmp/enrichment_demo

See also

Use spatial-de for markers, spatial-genes for autocorrelation, or sc-enrichment for non-spatial data.

Dependencies

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