FlashDeconv

Estimate spatial cell-type proportions at atlas scale.

FlashDeconv estimates cell type proportions from spatial transcriptomics data (Visium, Visium HD, Stereo-seq). It is designed for large-scale analyses where computational efficiency is essential, using reference-derived gene weighting and sparse spatial regularization.

Paper: Yang, C., Zhang, X. & Chen, J. FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution via structure-preserving sketching. bioRxiv (2025). DOI: 10.64898/2025.12.22.696108

Installation

pip install "flashdeconv[io,scanpy]"

Requires Python 3.9–3.14. This installs the dependencies used in the Quick Start below. For development or additional I/O support, see Installation Options.

Quick Start

import scanpy as sc
import flashdeconv as fd

# Load count matrices, spatial coordinates, and reference cell-type labels
adata_st = sc.read_h5ad("spatial.h5ad")
adata_ref = sc.read_h5ad("reference.h5ad")

# Deconvolve
fd.tl.deconvolve(adata_st, adata_ref, cell_type_key="cell_type")

# Rows are spatial locations; columns are reference cell types
proportions = adata_st.obsm["flashdeconv"]
print(proportions.head())

The example expects raw counts in .X, spatial coordinates in adata_st.obsm["spatial"], and reference labels in adata_ref.obs["cell_type"]. If counts are stored in layers, pass layer_st="counts" and layer_ref="counts". Match gene identifiers across datasets before running; the AnnData interface intersects and aligns shared genes.

FlashDeconv is also available as a tool in ChatSpatial, an MCP server for spatial transcriptomics — run deconvolution through natural language from any compatible client.

How it works

1. Select the union of spatial highly variable genes and reference markers; derive leverage scores from the reference signatures.
2. Apply the selected preprocessing (by default log1p of expression normalized to 10,000 counts per spot or cell type) and a shared deterministic leverage-weighted gene representation to spatial and reference expression: each selected gene is scaled by its exact expected weight in a column-normalized leverage-weighted CountSketch with sketch_dim buckets (default 512), averaged analytically over the random bucket assignment. No random projection is drawn, so results do not depend on random_state. The previous randomized CountSketch projection (uniform hashing, random signs, leverage-weighted amplitudes) remains available with gene_weighting="countsketch".
3. Construct a sparse spatial neighbor graph and fit non-negative regression coefficients with spatial smoothing and an L1 penalty.
4. Normalize each coefficient row to obtain estimated cell-type proportions.

The regression operates on the weighted (or, in legacy mode, sketched) matrices:

minimize  ½‖Y_s − βX_s‖²_F + ½λ Tr(βᵀLβ) + ρ_eff‖β‖₁,  subject to β ≥ 0

Here Y_s is N × p and X_s is K × p, with p the number of selected genes (p = sketch_dim in legacy mode), and L = D − A is the spatial graph Laplacian. The solver scales the user parameter as ρ_eff = rho_sparsity × mean(diag(X_s X_sᵀ)).

beta_ contains regression coefficients, not absolute cell counts. proportions_ contains their row-normalized values, P[i, k] = β[i, k] / sum(β[i, :]). An all-zero coefficient row is assigned a uniform distribution as a numerical fallback, not evidence of equal biological composition.

With fixed gene count, cell-type count, iteration count, and bounded graph degree, the regression stage has linear time and memory scaling in the number of spots. End-to-end runtime also includes preprocessing and neighbor search; it is not an unconditional O(N) guarantee. Radius graphs can become dense when many spots fall within the radius.

Performance

Scalability

Reported on MacBook Pro M2 Max (32GB unified memory), CPU-only. The million-spot result uses simulated data. These timings describe the benchmark configurations, not a runtime guarantee for arbitrary gene counts, cell-type counts, or graph settings.

Accuracy

On the 54 Silver Standard datasets (6 tissues × 9 abundance patterns) from the Spotless benchmark:

Values follow the current manuscript’s unified benchmark table (Silver Standard rows). These datasets use simulated mixtures; rankings differ on real-data benchmarks. See the reproducibility repository for benchmark materials. Evaluate performance on data and reference conditions relevant to your application.

API

See the Quick Start for the AnnData interface and the full API reference for methods, I/O utilities, and evaluation functions.

NumPy

Provide spatial counts Y (N × G, dense or SciPy sparse), reference signatures X (K × G), and coordinates coords (N × 2 or N × 3). The columns of Y and X must contain the same genes in the same order, and both must be non-negative and finite.

from flashdeconv import FlashDeconv

model = FlashDeconv(
    sketch_dim=512,
    lambda_spatial="auto",
    n_hvg=2000,
    k_neighbors=6,
    random_state=0,
)
proportions = model.fit_transform(Y, X, coords)

Parameters

Output

Input Formats

• Spatial data: AnnData, NumPy array (N × G), or SciPy sparse matrix
• Reference: AnnData (aggregated by cell type) or NumPy array (K × G)
• Coordinates: Extracted from adata.obsm["spatial"] or NumPy array (N × 2 or N × 3)

Reference quality and limitations

• Use reference annotations supported by marker expression, and check that expected tissue cell types are represented. Missing types can distort the estimated proportions of included types.
• Assess signature stability across cells or donors. Required sample size depends on heterogeneity, sequencing depth, and separation between types; there is no universal cell-count or marker-fold-change cutoff.
• Inspect highly correlated signatures and consider a coarser annotation when subtypes cannot be distinguished reliably.
• Review labels such as Unknown or Unassigned before aggregation. A heterogeneous pool can produce an ambiguous signature, but the label alone is not a reason to discard a coherent population.
• Spatial smoothing can blur sharp boundaries. Compare smoothing strengths when boundaries or rare populations are central to the analysis.
• Estimated proportions depend on reference quality and preprocessing; they are not direct measurements of cell numbers. The opt-in uncertainty estimates (compute_uncertainty, bootstrap_uncertainty) are model-based: they reflect sampling uncertainty under the fitted model and exclude reference–tissue mismatch, missing cell types and model misspecification, which usually dominate the error. Use them to compare estimate stability across spots and types, not as calibrated intervals for true proportions.

Installation Options

# Standard
pip install flashdeconv

# With AnnData support
pip install "flashdeconv[io]"

# Development
git clone https://github.com/cafferychen777/flashdeconv.git
cd flashdeconv && pip install -e ".[dev]"

Requirements: Python 3.9–3.14, numpy, scipy, numba. Optional: scanpy, anndata.

Citation

If you use FlashDeconv in your research, please cite:

Yang, C., Zhang, X. & Chen, J. FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution via structure-preserving sketching. bioRxiv (2025). DOI: 10.64898/2025.12.22.696108

@article{yang2025flashdeconv,
  title={FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution
         via structure-preserving sketching},
  author={Yang, Chen and Zhang, Xianyang and Chen, Jun},
  journal={bioRxiv},
  year={2025},
  doi={10.64898/2025.12.22.696108}
}

Resources

• Paper reproducibility code
• Stereo-seq guide — Platform-specific considerations
• GitHub Issues
• BSD-3-Clause License

Acknowledgments

We thank the developers of Spotless, Cell2Location, RCTD, CARD, and other deconvolution methods whose work contributed to this field.