spatial-preprocess

spatial-preprocess

When to use

Use on raw-count spatial AnnData for QC, filtering, normalization, HVGs, PCA, neighbors, UMAP and Leiden. The expression graph does not use spatial coordinates. Use spatial-raw-processing for FASTQs and spatial-domains for spatially informed domain detection on preprocessed data.

Use from a step

from skills._sdk.notebook import load_demo, load_skill, write_output

library = load_skill("spatial-preprocess")
adata = library.preprocess(load_demo("spatial_synthetic"), n_top_hvg=150, n_pcs=15)
write_output(adata, "intermediate/processed.h5ad")
write_output(library.cluster_summary(adata), "tables/clusters.csv")

The demo is synthetic, with three known spatial stripes. See examples/example_step.py for count-preservation and domain-recovery checks. For real H5AD input use read_input("data/slide.h5ad") instead of load_demo.

API

preprocess(adata, *, min_genes: int=0, min_cells: int=0, max_mt_pct: float=20.0, max_genes: int=0, n_top_hvg: int=2000, n_pcs: int=30, n_neighbors: int=15, leiden_resolution: float=0.5, resolutions: list[float] | None=None, tissue: str | None=None, species: str='human', random_state: int=0)

Filter raw spatial counts and return a processed copy without changing the input.

Reads raw counts from X. The returned X is total-normalized to 10,000 and log1p-transformed; layers['counts'] and raw retain the filtered counts. Adds QC metrics, HVGs, PCA, neighbors, UMAP and Leiden. Coordinates are preserved but do not enter the expression neighbor graph.

:param adata: AnnData with raw counts in X and optional spatial coordinates. :param min_genes: Minimum detected genes per spot; 0 disables this filter. :param min_cells: Minimum spots per gene; 0 disables this filter. :param max_mt_pct: Keep spots strictly below this percentage; 20 by default, 100 disables the filter. Adjust for tissue and assay quality. :param max_genes: Keep spots strictly below this detected-gene count; 0 disables the upper bound. :param n_top_hvg: Select up to 2000 HVGs from counts with Seurat v3 by default. :param n_pcs: Request 30 PCs by default; clipped below both dimensions. Neighbors use at most 30 of the computed PCs. :param n_neighbors: Graph neighborhood size, 15 by default. :param leiden_resolution: Primary Leiden resolution, 0.5 by default. :param resolutions: Optional positive resolutions for extra obs['leiden_res_<value>'] columns; None skips the sweep. :param tissue: Optional QC preset such as brain or pbmc. Values equal to the defaults (0, 20, 0) for min_genes, max_mt_pct and max_genes are replaced by the preset, even when passed explicitly. None uses no preset. :param species: Human (default, MT-) or mouse (mt-) mitochondrial prefix. :param random_state: Seed for PCA, neighbors, UMAP and Leiden; default 0 matches the original CLI. Change it to assess seed sensitivity. :returns: A new AnnData with counts, embeddings, labels and JSON diagnostics. :raises ValueError: Invalid thresholds or too few spots, genes or HVGs remain. :raises ImportError: A backend is missing; use install_skill_deps for scikit-misc (HVGs), igraph (Leiden) or umap-learn (embedding).