scDiagnostics Manuscript

Comprehensive tutorials, analysis code, and reproducible workflows demonstrating scDiagnostics for systematic assessment of cell type annotation in single-cell transcriptomics data.

Manuscript: Christidis, A., Ghazi, A., Chawla, S., Turaga, N., Gentleman, R., & Geistlinger, L. (2026). scDiagnostics: systematic assessment of cell type annotation in single-cell transcriptomics data. Briefings in Bioinformatics, 27(5), bbag496. doi: 10.1093/bib/bbag496.

Analysis and Results: Manuscript Website

Citation

If you use the code, data, or analyses in this repository, please cite:

Christidis A, Ghazi A, Chawla S, Turaga N, Gentleman R, Geistlinger L (2026). scDiagnostics: systematic assessment of cell type annotation in single-cell transcriptomics data. Briefings in Bioinformatics, 27(5), bbag496. doi: 10.1093/bib/bbag496.

@article{christidis2026scDiagnostics,
  author  = {Christidis, A. and Ghazi, A. and Chawla, S. and Turaga, N. and Gentleman, R. and Geistlinger, L.},
  title   = {scDiagnostics: systematic assessment of cell type annotation in single-cell transcriptomics data},
  journal = {Briefings in Bioinformatics},
  year    = {2026},
  volume  = {27},
  number  = {5},
  doi     = {10.1093/bib/bbag496}
}

If you use the scDiagnostics R package itself, please also cite it as described in the package repository.

Overview

We demonstrate scDiagnostics using a simulated and three different real-world single-cell datasets:

1. Simulated single-cell data (splatter)

• Synthetic data with known cell types and ground truth composition
• Use case: Illustration of common challenges of reference-based annotation transfer in a controlled setting

2. Zeisel Mouse Brain Benchmarking

• Mouse cortex and hippocampus scRNA-seq dataset (Zeisel et al., 2015)
• Use case: Systematic stress-testing of diagnostic sensitivity and specificity against label noise, class imbalance, and batch effects

3. COVID-19 PBMC scRNA-seq

• Single-cell RNA-seq data from severe COVID-19 patients and healthy controls
• Source: CZI CELLxGENE (Stephenson et al., 2021)
• Use case: Discovery and characterization of disease-associated immune cell states

4. MERFISH Mouse Colitis

• Spatial transcriptomics from a mouse model of inflammatory bowel disease
• Source: MerfishData Bioconductor package (Cadinu et al., 2024)
• Use case: Spatial validation of annotation quality and disease-associated cell states

For each dataset, we predict cell type labels using four popular annotation tools:

• Azimuth — Weighted k-NN mapping
• SingleR — Correlation-based assignment
• CellTypist — Machine learning classifier
• scVI/scArches — Deep learning with VAE (GPU-accelerated)

Quick Start

Installation

source("R/covid/R_Package_Installation_Pipeline.R")

Or for MERFISH:

source("R/merfish/R_Package_Installation_Pipeline.R")

Download Data

All pre-processed datasets with annotations are available on Zenodo:

source("data/downloadData.R")
downloadData()

This automated script downloads all four SingleCellExperiment/SpatialExperiment objects into your data/covid/ and data/merfish/ directories. For manual download, visit the Zenodo repository.

See detailed instructions: Setup & Installation, Accessing Data

Documentation

Full tutorials and analysis code available at https://ccb-hms.github.io/scDiagnosticsManuscript/:

Setup & Methods

Analysis environment setup, data retrieval, and reproducible analysis workflows:

• Setup & Installation — Install R and Python dependencies (GPU recommended for scVI/scArches)
• Accessing Data — Download pre-processed datasets from Zenodo
• Cell type annotation — Apply all four annotation methods to query data

Tutorials & Workflows

Quick start, core functionality, and common analysis workflows:

• scDiagnostics Overview — Introduction to diagnostic framework and key concepts
• Simulation Analysis — Demonstration of common challenges in reference-based annotation transfer
• Zeisel Brain Benchmarking — Quantitative benchmarking of scDiagnostics under stress-tested single-cell scenarios
• COVID-19 Analysis — Annotation assessment and anomaly detection in scRNA-seq data
• MERFISH Analysis — Annotation assessment and anomaly detection in spatial transcriptomics data
• Exploring Annotation Tool Diagnostics — Complementary aspects of scDiagnostics and built-in quality metrics from major annotation tools

Installation

R Packages

All required R packages are automatically installed by running:

source("R/covid/R_Package_Installation_Pipeline.R")
source("R/merfish/R_Package_Installation_Pipeline.R")

Python Environment

For GPU-accelerated scVI/scArches annotation:

conda env create -f environment-scvi.yml
conda activate scvi-env

See Setup & Installation for detailed instructions.

Repository

Code and Scripts: github.com/ccb-hms/scDiagnosticsManuscript

Data:

Contact

For questions or feedback, please open an issue on GitHub.