Single-cell
The single-cell pipeline follows a standard Scanpy-style workflow ported from Seurat-class methods. All steps operate on AnnData and chain through on-disk checkpoints.
Pipeline steps
1. Quality control
Filters cells and optionally genes based on:
- Minimum and maximum genes per cell
- Minimum counts per cell
- Maximum mitochondrial gene percentage
- Optionally, predicted doublets (see Doublets; off by default, so doublets are flagged but kept)
Set the Assay type (whole cells, nuclei, or fixed cells) so QC is interpreted correctly; see Assay type.
It also reports, without filtering on them:
- % ribosomal (cytosolic ribosomal protein genes,
RPS*/RPL*, excluding ribosomal S6 kinases) and % hemoglobin (an explicit human/mouse hemoglobin gene list), useful for spotting nuclei-like profiles and red-cell contamination - Stress and cell-death signatures on the cells that pass: apoptosis, necrosis, oxidative stress, cellular senescence, DNA damage, heat shock, unfolded protein response, and an immediate-early dissociation-response signature. See Stress and cell-death signatures.
Outputs QC metrics, histograms, per-sample retention charts, and the signature table visible in Explore → Sample QC.
Stress and cell-death signatures
Each signature gets two per-cell readouts, saved in the QC checkpoint as stress_<signature>_pct and stress_<signature>_score:
| Readout | Definition |
|---|---|
| % counts | Share of the cell's raw counts from the signature's genes (as Seurat's PercentageFeatureSet) |
| Module score | Mean log-normalized expression of the signature genes minus that of expression-matched control genes: 100 controls per gene from the same of 24 average-expression bins, seed 1 (as Seurat's AddModuleScore) |
The apoptosis, necrosis, oxidative stress, senescence, DNA damage, heat shock, and UPR gene lists follow the methods of Utkina, Shcherbakova et al. 2024 (bioRxiv, doi:10.1101/2024.03.26.586727), who used them to compare enzymatic dissociation, fixed-cell (ACME HS), and nuclei preparations of endocrine tumors. The dissociation-response list is a core set of immediate-early genes after van den Brink et al. 2017. Gene matching is case-insensitive, so the human symbols also match mouse and rat orthologs that share the symbol; each signature lists the genes found and missing. Signatures with fewer than three genes found are flagged.
Compare signatures across samples (or conditions) in the table: a sample or preparation method with markedly higher stress readouts points to handling artefacts rather than biology. Module scores are relative within a dataset; do not compare them across separately processed datasets.
Doublets
Doublets (two cells captured in one droplet) are scored per sample on raw counts after the threshold filters. Two methods are available under Doublet detection:
| Method | How it works |
|---|---|
| scrublet (default) | After Scrublet (Wolock et al. 2019): simulates doublets by adding the counts of random pairs of cells (2 per observed cell), embeds observed and simulated cells together (variable genes by v-score, z-scored PCA with 30 components fit on observed cells), and scores each cell by the share of simulated doublets among its nearest neighbours, corrected for the simulated-to-observed ratio and the expected doublet rate. The threshold is the dip between the two modes of the simulated-score distribution (homotypic and heterotypic doublets). |
| classifier (experimental) | After scDblFinder (Germain et al. 2021): artificial doublets drawn mostly from pairs of cells in different clusters, neighbourhood features at several k plus library size, detected genes, and top principal components, and a gradient-boosted classifier trained to separate real from artificial cells with out-of-fold predictions, iterated three times. The threshold balances missed artificial doublets against called cells and the expected rate. It ranks doublets well but calls close to the expected rate; validate on your data before relying on it. |
The expected doublet rate defaults to 0.8% per 1,000 cells captured in each sample (10x Chromium); set it if your loading differed. Doublets of two cells of the same type cannot be detected from expression, so a predicted rate somewhat below the true rate is normal. Turn on Remove predicted doublets to drop them before normalization; otherwise they are kept and flagged in obs['predicted_doublet'] with scores in obs['doublet_score']. Samples with fewer than 50 cells are not scored.
Assay type
Choose cells, nuclei, or fixed_cells for the dataset, or name an obs column (Assay type column, advanced) whose values give the assay per cell, for example a preparation-method column with values such as nuclei, enzymatic, or ACME. The assay type is saved as obs['assay_type'] and changes how results are read:
- Nuclei carry little cytoplasmic mRNA, so mitochondrial transcripts should be near zero. A high mitochondrial fraction in nuclei signals cytoplasmic carry-over, not dying cells; QC reports the share of nuclei above 5% and suggests a lower cutoff than for whole cells.
- Fixed cells stop transcribing when fixed, so compare their stress signatures with an unfixed preparation of the same tissue.
- When a dataset mixes assay types, differential expression between groups of different assay composition flags mitochondrial, ribosomal-protein, and nuclear-retained transcripts (MALAT1, NEAT1, and similar) in an
assay_biascolumn and warns, and integration warns unless assay type is part of the batch variable.
1b. Ambient RNA correction (optional)
Cell-free RNA from lysed cells (the "soup") is captured in every droplet and adds counts of genes the cell does not express, such as hormone or hemoglobin transcripts in unrelated cell types. Ambient RNA Correction runs after QC on the QC-filtered cells and writes corrected counts that normalization, clustering, DE, and pseudobulk then use. The original counts are kept as layers['counts_uncorrected']; corrected counts are stochastically rounded to integers.
| Method | Needs | How it works |
|---|---|---|
| soupx | Raw droplet matrix | After SoupX (Young & Behjati 2020): the soup profile is estimated from droplets with fewer than 100 UMIs in Cell Ranger's unfiltered matrix. The contamination fraction is estimated automatically from cluster-specific marker genes that are abundant in the soup (posterior with a gamma prior, mean 5%, searched between 1% and 80%), or from genes you name as absent in some cells (Genes absent in some cells, e.g. HB: HBB, HBA1, HBA2), or fixed (Contamination fraction). Each gene's expected soup counts are removed at cluster level and the removal is distributed across the cluster's cells. |
| decontx | Nothing extra | After decontX (Yang et al. 2020): each cell is modelled as a mixture of its cluster's native profile and a contamination profile (the other clusters, or the empty droplets when a raw matrix is uploaded), with a Beta prior on the contamination fraction, fit by EM per sample. |
| both | Raw droplet matrix | Corrects with SoupX-style and reports the decontX-style per-cell estimate alongside for comparison. |
| auto (default) | — | SoupX-style when a raw droplet matrix is uploaded, otherwise decontX-style. |
To upload the raw matrix, click Add raw droplet matrix under the dataset on the Data page and choose Cell Ranger's raw_feature_bc_matrix.h5 (or the raw_feature_bc_matrix folder as a zip). It must come from the same Cell Ranger run as the dataset. One raw matrix per dataset is supported; for a dataset that merges several channels, the soup profile is shared across them.
Ambient correction uses the clusters from the Clustering step when it has been run on the same cells, otherwise quick k-means clusters (named in the results). For the best estimate, run QC → Normalization → Clustering → Ambient RNA Correction, then re-run Normalization and Clustering on the corrected counts. Re-running QC discards the correction. Results appear in Explore → Sample QC.
2. Normalization
Log-normalizes counts, identifies highly variable genes, and optionally scales. Writes a checkpoint used by clustering.
3. Clustering
Builds a neighbor graph, runs Leiden clustering at a configurable resolution, and computes UMAP coordinates for interactive exploration.
4. Integration, annotation, trajectory, and scaling
Single-cell studies can add higher-level review steps after clustering:
| Step | Purpose |
|---|---|
| Batch integration | Correct batch effects, compare integrated vs. unintegrated views, and review batch mixing and cell-type preservation (see below) |
| Reference annotation | Label clusters from a built-in marker panel, your own markers, or a labelled reference dataset, with confidence scores, marker sources, and compatibility warnings (see below) |
| Sketch analysis | Work with larger AnnData inputs through backed mode, representative-cell sketches, projected labels, and guardrails |
| Trajectory and cell cycle | Score cell-cycle phase, compute graph-based pseudotime, and review UMAP overlays and pseudotime-associated genes |
Batch integration methods
| Method | How it works |
|---|---|
| harmony (default) | After Harmony (Korsunsky et al. 2019): soft clustering in PCA space with a penalty that favours clusters mixing all batches, then a per-cluster linear correction of the batch effect. Harmony diversity (theta) sets how hard it pushes for mixing. |
| fastmnn | After fastMNN (Haghverdi et al. 2018; batchelor): batch-weighted PCA of cosine-normalised expression, then batches are merged largest first, using mutual nearest neighbours as anchors. Each merge's number of anchor pairs and lost variance are reported. |
| pca_center | Shifts each batch's PCA centroid to the global centroid. A weak baseline, kept for comparison; it fails when batches differ in cell-type mix. |
Diagnostics compare the unintegrated and integrated spaces:
- iLISI (batch mixing): the effective number of batches in each cell's neighbourhood. Higher is better; the maximum is the number of batches. When batches genuinely differ in cell-type mix, the achievable maximum is lower.
- cLISI and cell-type silhouette (preservation): computed when a cell-type column exists (
cell_type, or the column named in Cell-type column). A cLISI close to 1 means cell types stay separate. A warning appears if cell types become more mixed after integration. - Batch silhouette, mixing entropy, and a confounding check (batch vs. biology), as before.
On synthetic data, both methods mix batches while keeping cell types apart. Under a very strong batch effect combined with very different cell-type mixes per batch, fastMNN mixed batches better than Harmony.
Annotation references
| Reference | Labels |
|---|---|
| pbmc_builtin | Blood immune cells (T, NK, B, monocytes, DCs, platelets, red cells) |
| adrenal | Zona glomerulosa, zona fasciculata, zona reticularis (human), X-zone (mouse), chromaffin and sustentacular cells |
| pituitary | Corticotrophs, melanotrophs (mouse), somatotrophs, lactotrophs, thyrotrophs, gonadotrophs, stem/folliculostellate cells |
| thyroid | Thyrocytes and C cells |
| testis | Leydig, Sertoli, peritubular myoid cells, spermatogonia, spermatocytes, round and elongating spermatids |
| custom | Your own panel in Custom markers, one label per line: Leydig: Cyp17a1, Insl3, Star |
| dataset | A labelled dataset in the same study (see below) |
Each panel has human and mouse gene symbols (rat uses the mouse symbols), chosen from the study's organism. Gene names are matched ignoring case. Tissue panels also score shared stroma and immune labels (endothelial cells, fibroblasts, pericytes/smooth muscle, macrophages, T, B, NK and red cells) unless Add stroma & immune labels is off. The results table shows each label's marker source.
With Reference = dataset, cells are labelled with a SingleR-style method (Aran et al. 2019). Marker genes are learned between every pair of labels in the reference. Each cell (or each cluster's average, with Label per = cluster) is scored by Spearman correlation with the reference profiles, and the labelling is then fine-tuned among the closest labels. Ambiguous cells (more than 3 MADs below their label's typical margin) are set to Unknown. The reference must be another dataset in the same study, with its labels in Reference label column.
RNA velocity
RNA Velocity (Find Structure) estimates where each cell is heading in expression space from spliced and unspliced counts. First attach the counts under the dataset on the Data page (Add velocity counts: a velocyto .loom, or an .h5ad with spliced and unspliced layers), and run Clustering so cells have neighbours and a UMAP.
| Model | How it works |
|---|---|
| stochastic (default) | After Bergen et al. 2020 (scVelo): uses first and second moments of spliced/unspliced counts over each cell's 30 nearest neighbours to fit each gene's degradation rate γ |
| steady_state | After La Manno et al. 2018 (velocyto): fits γ from cells at the extremes of each gene's expression (bottom and top 5%), assuming they are near steady state |
Velocity per gene is u − γ·s. Genes are kept when the fit's R² and γ exceed 0.01 and both layers are expressed. A velocity graph (cosine similarity between each cell's velocity and the displacement to its neighbours) is projected onto the UMAP and shown as arrows, smoothed on a grid. Results also list each gene's fit and a coherence score (how well a cell's velocity agrees with its neighbours').
The same counts give each cell's spliced fraction (spliced / (spliced + unspliced) over all genes). Whole cells typically show 75–90% spliced reads; nuclei are intron-rich and much lower, so it is also a QC signal separating nuclei from whole cells. It feeds the preparation comparison below.
5. Differential expression
Two modes:
| Mode | When to use |
|---|---|
| Cluster markers | Find genes enriched in each cluster vs all others |
| Contrast | Compare groups defined on the Data page (for example treated vs control) |
Uses Wilcoxon rank-sum tests by default. Results include log fold change, adjusted p-values, and percent expressing.
On the DE results page, selecting a gene also offers View 3D structure — its predicted protein structure for the study's organism — which follows your selection as you click through the gene table.
Pseudobulk DE is also available when biological replicate/sample metadata exists. It aggregates cells by sample and cell type or cluster before testing, then reports per-cell-type volcano/result views and exportable tables.
Cell composition between conditions
Cell Composition (Compare Groups) tests whether cell-type proportions differ between conditions, for example an expanded Sertoli fraction in a knockout. It follows propeller (Phipson et al. 2022):
- Count each sample's cells per cell type (or cluster) and convert to proportions.
- Transform the proportions: logit (default, with a 0.5 pseudo-count) or arcsine square root.
- Fit a linear model per cell type across samples, with an optional Covariate column such as batch or sex. Moderate the variances across cell types with limma's empirical Bayes, then test with a moderated t-test (two conditions) or a moderated F-test (three or more).
- Adjust p-values across cell types with Benjamini–Hochberg.
At least two biological samples per condition are needed. With fewer, the proportions are shown without a test, and the results say why. Samples whose cells span more than one condition, and samples below Min cells / sample, are excluded and listed. Run annotation first to test cell types; otherwise clusters are used, with a note.
Preparation method comparison
Preparation Method Comparison (Compare Groups) benchmarks sample-preparation methods, such as enzymatic dissociation, fixed cells (for example ACME), and nuclei, in the layout of Utkina, Shcherbakova et al. 2024. It needs an obs column naming each cell's method (Preparation column) and uses the latest QC, ambient, stress, annotation and velocity results:
| Section | What it shows |
|---|---|
| Cell recovery | Cells in the upload vs passing QC, per method |
| Quality metrics | UMIs and genes per cell; mitochondrial, ribosomal and hemoglobin %; doublet rate; ambient fraction; spliced fraction; each stress signature. Median [IQR] per cell, and a test between methods on per-sample medians (linear model and F-test, BH FDR across metrics) |
| Composition | Cell-type proportions by method, tested as in Cell composition |
| Marker preservation | Share of each cell type's cells detecting its canonical markers (the annotation panel), per method |
| DE between methods | Pseudobulk DE per cell type, each method vs the Reference method; mitochondrial, ribosomal and nuclear-retained genes are flagged as technical |
Each sample (library) should come from one method. When each tissue was split across methods, set Pairing column to the tissue so methods are compared within tissue. Tests need at least two samples per method; with fewer, the report is descriptive. The metrics table can be added to a report from the Report Builder.
6. Pathway enrichment
Over-representation analysis (ORA), ranked GSEA, and ssGSEA/GSVA scoring against the study organism's gene sets:
| Collection | Organisms | Source |
|---|---|---|
| GO_BP | Human, mouse, rat | Gene Ontology biological process, propagated over is_a/part_of, from the GO Consortium annotations (GOA human, MGI, RGD); NOT annotations and ND evidence excluded |
| REACTOME | Human, mouse, rat | Reactome pathways (all levels), mapped to gene symbols through reviewed UniProtKB entries |
| KEGG | Human symbols | Small curated subset; matched to other organisms case-insensitively |
The organism comes from the study settings; when it is not set, human sets are used and the run says so. Results record the collection versions and organism. Gene symbols must match the organism's nomenclature (HGNC for human, MGI for mouse, RGD for rat).
7. Single-cell CNV and malignant-cell evidence
For tumor single-cell studies, single_cell_cnv infers expression-derived chromosome-scale CNV signal from an AnnData dataset. It uses chromosome-ordered genes, reference-cell centering, smoothing, CNV burden scoring, malignant confidence, segment/event calls, optional deletion/neutral/gain state calls, and CNV-defined subclone summaries.
The result view includes a chromosome-ordered heatmap preview (downsampled for display only — all scores/events/subclones are computed on the full dataset), reference QC, group/sample malignant evidence, event filters, subclone summaries, state-call tables, UMAP malignant-score overlay when coordinates exist, TSV exports, and an oncology handoff artifact. See Single-cell CNV and malignant cells.
Checkpoints
Each step's intermediate checkpoint is tied to its run. Re-running an upstream step deletes downstream checkpoints and marks dependent results stale.
Metadata merge
Before each step, saved metadata columns merge into obs. Ensure join keys match barcodes or sample IDs to avoid silent failures.
See Quick start for a hands-on walkthrough.