spoQC is a modular framework for multimodal quality control (QC) of imaging-based spatially resolved transcriptomics (SRT). It independently evaluates cell segmentation, imaging, and transcript data to identify high-quality regions (HQRs) across entire tissue sections. In addition, spoQC uses Markov random fields (MRFs) to incorporate spatial dependencies and generate spatially refined QC masks.
Note
SpoQC is currently under active development and is still in the alpha phase. You may encounter bugs, incomplete features, or unexpected behavior. If you are testing spoQC and run into any issues, please contact the development team or open an issue in the repository. Feedback, bug reports, and pull requests are highly appreciated and help us improve the project.
Note
Processing a full-resolution spatial transcriptomics (SRT) dataset with spoQC typically requires access to an HPC (High Performance Computing) environment. For smaller datasets, reduced-resolution data, or data subsets, it may be possible to run spoQC locally.
To reduce runtime and improve scalability, we recommend running spoQC with Nextflow. We are continuously working on improving performance and making local execution easier.
Currently supported:
- 10x Xenium (XOA v4.0 or lower)
Note
Atera support is currently under development and is not yet available.
If you use spoQC in your work, please cite:
@software{spoqc,
author = {Heyl, Florian and
Sen, Ezgi and
Müller-Bötticher, Niklas and
Kher, Sameesh and
He, Dongze and
Long, Brian and
Ishaque, Naveed and
Stegle, Oliver},
title = {spoQC},
url = {https://bio.tools/spoqc},
note = {bio.tools identifier: biotools:spoqc},
urldate = {2026-08-17}
}
This tool was developed in collaboration with the following institutions:
- German Cancer Research Center (DKFZ, Heidelberg, Germany)
- Centro Nacional de Análisis Genómico (CNAG, Barcelona, Spain)
- Center for Quantitative Analysis of Molecular and Cellular Biosystems (BioQuant, Heidelberg, Germany)
- Berlin Institute of Health at Charité (Berlin, Germany)
- Altos Labs San Diego Institute of Technology (San Diego, USA)
- Allen Institute for Brain Science (Seattle, USA)
- European Molecular Biology Laboratory (EMBL, Heidelberg, Germany)
The following people contributed directly or indirectly through supervision, code review, and the development of concepts and ideas:
- Florian Heyl
- Ezgi Sen
- Niklas Müller-Bötticher
- Sameesh Kher
- Dongze He
- Brian Long
- Naveed Ishaque
- Oliver Stegle
For further details please read the documentation.
pip install spoqc
Once istalled, run spoQC exactly as described in Run.
spoQC also provides a prebuilt Docker image (quay.io/heylf/spoqc:0.1.0) on Quay.io with all
dependencies already installed. This is useful if you do not want to set up a local Python
environment.
Start a container and drop into a shell, bind-mounting the directory that holds your data so the container can read and write it:
docker run -ti -v /path/to/data:/data quay.io/heylf/spoqc:0.1.0 bash
Once inside the container, run spoQC exactly as described in Run, for example:
python3 -m spoqc -s all -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores] -a [annotation_file]
Many HPC clusters do not allow running Docker directly, but support Singularity or Apptainer instead. Both can pull and run Docker images directly, so you can use the same spoQC image on such systems.
Pull the Docker image and convert it to a Singularity image file:
singularity pull spoqc.sif docker://quay.io/heylf/spoqc:0.1.0
Then run spoQC through the image, bind-mounting your data directory:
singularity exec -B /path/to/data:/data spoqc.sif \
python3 -m spoqc -s all -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores] -a [annotation_file]
On clusters using the newer Apptainer branding, apptainer is a drop-in replacement for
singularity, thus the same commands work by substituting apptainer for singularity.
spoQC is designed to process large spatial transcriptomics (SRT) datasets at full resolution. Running the complete pipeline typically requires access to an HPC (High Performance Computing) environment.
If you do not have access to an HPC system, you may still be able to run spoQC locally by:
- Using a lower-resolution dataset.
- Running spoQC on a subset of your data.
- Testing individual pipeline steps before processing the full dataset.
If your dataset does not already contain a cell type annotation, spoQC can create one automatically using unsupervised Leiden clustering.
Run:
python3 -m spoqc -s "annotation" -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores]After the analysis finishes, spoQC will create an annotation file:
[spoqc_tmp_folder]/report/annotation/unsupervised_cell_annotation.tsv
You can use this file as the value for the [annotation_file] parameter in later steps.
To execute all spoQC analyses in the correct order, run:
python3 -m spoqc -s all -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores] -a [annotation_file]This is the recommended option for most users.
Advanced users can execute individual spoQC steps separately.
Run:
python3 -m spoqc -s [step] -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores] -a [annotation_file]Replace [step] with one of the following pipeline stages.
Important: These steps must be executed in the exact order shown below. Running steps out of order will cause downstream analyses to fail.
- generalqc
- bubbleqc
- doubletqc
- voidqc
- cellqc
- ambientqc
- hqcr_ident
- hqcr_celltype
- hqpr_metrices (has to be run for each staining)
- hqpr_clustering (has to be run for each staining)
- hqpr_refinement (has to be run for each staining)
- hqpr_bounding_box (has to be run for each staining)
- hqpr_celltype (has to be run for each staining)
- hqtr_metrices
- hqtr_ac
- hqtr_qv
- hqtr_clustering
- hqtr_refinement
- hqtr_bounding_box
- hqtr_celltype
- combine_masks (has to be run for each staining)
- transcriptqc
- modelqc
- cellcycleqc
- analysis_overview
- analysis_cluster
- analysis_category
- final_report
To run the first pipeline step (generalqc), execute:
python3 -m spoqc -s generalqc -i [input_spatial_data_bundle] -o [output_folder] -t [spoqc_tmp_folder] -n [n_cores] -a [annotation_file]Wait until the step has completed successfully before continuing with the next step in the list.
spoQC can be executed sequentially, but processing a full-resolution spatial transcriptomics dataset typically takes 4–5 days to complete.
To significantly reduce runtime, we provide a dedicated Nextflow subworkflow that parallelizes many of the processing steps. Using the Nextflow workflow can reduce the total runtime to approximately 1–2 days, depending on the available computational resources.
The workflow is available on the dev branch of nf-core/spatialaxe.
Note
Processing a full-resolution spatial transcriptomics (SRT) dataset with spoQC typically requires access to an HPC (High Performance Computing) environment.
If an HPC system is not available, you may still be able to run spoQC locally by:
- Using a lower-resolution dataset.
- Processing a subset of your data.
- Running selected workflow components instead of the complete pipeline.
There are several ways to contribute to spoQC. The project is built around four main pillars:
- metrics
- priors
- subworkflows
- standard pre- and postprocessing scripts
Note
We are currently working on standardizing these components and providing templates to make contributions easier and more consistent.
Metrics are used to quantify different aspects of spatial transcriptomics data quality. Currently, metrics are organized into three categories:
- image metrics
- segmentation metrics
- transcript density metrics
Some metrics may be relevant to multiple categories. The organization of these layers is still being refined as spoQC evolves.
Segmentation metric
spoqc/metrics/segmentation/overlap_area.py
Segmentation metrics must be linked back to individual cells and stored in the SpatialData object (within the associated AnnData table).
Image metric
spoqc/metrics/image/edge_strength.py
Image metrics should be saved as a one-dimensional (1D) array.
Transcript density metric
spoqc/metrics/image/transcript_density_image.py
Transcript density metrics should also be saved as a one-dimensional (1D) array.
Priors are used to estimate the initial probability that a spatial observation (for example, a cell or pixel) is of high or low quality based on a specific metric.
All priors are combined in:
spoqc/priors/combine_priors.py
Each prior contributes evidence about the quality of a spatial observation and is integrated into the overall quality assessment.
SpoQC contains several predefined subworkflows that automate common analysis tasks.
Some subworkflows, such as qc_doublets.py, serve as entry points for metric calculation, quality assessment, visualization, and reporting.
Subworkflows are a good place to contribute additional analysis pipelines or improve existing workflows.
SpoQC also includes scripts for common preprocessing and postprocessing operations.
Examples include:
- normalization methods
- data transformations
- filtering procedures
- result aggregation and reporting
Contributions that improve interoperability with new data formats or analysis workflows are particularly welcome.
To contribute a new metric, follow these steps:
-
Identify which metric category the new metric belongs to (image, segmentation, transcript density, or another relevant layer).
-
Implement the metric calculation and place the script in the appropriate folder under:
spoqc/metrics/ -
Create a corresponding prior estimation method and place it in:
spoqc/priors/ -
Register the new prior in:
spoqc/priors/combine_priors.py -
Ensure that the prior returns the probability that a spatial observation (for example, a cell or pixel) is of high quality.
- Metric implementation added to
spoqc/metrics/ - Metric output stored in the expected format
- Prior implementation added to
spoqc/priors/ - Prior registered in
spoqc/priors/combine_priors.py - Prior represents the probability of high-quality observations
- Documentation and examples added where appropriate