nf-core pipeline · cell-hashing, deconvolution, demultiplexing
nf-core/hadge
Demultiplexes single-cell sequencing samples using combined hashing and genotype deconvolution methods.
What nf-core/hadge is
nf-core/hadge is a bioinformatics pipeline designed for donor demultiplexing in single-cell multiplexing studies. In pooled single-cell sequencing, assigning individual cells back to their originating donors is essential for resolving sample identity and distinguishing single cells from doublets. The pipeline integrates 11 different deconvolution tools spanning both antibody- or oligonucleotide-derived hashtag deconvolution and genotype-based deconvolution.
Originally developed by Fabiola Curion, Xichen Wu, Lukas Heumos, and Mariana Gonzales Andre, and adapted into the nf-core framework by Luis Heinzlmeier, Nico Trummer, and Seo Hyon Kim, the pipeline addresses inconsistencies between individual demultiplexing algorithms. By executing multiple methods, consolidating assignments, and matching donors across approaches, it recovers previously discarded cells and improves sample deconvolution reliability.
What the pipeline does
The pipeline ingests single-cell data through a samplesheet containing compressed 10x Genomics RNA-seq and hashtag oligonucleotide (HTO) count matrices, BAM alignments, a list of common single nucleotide polymorphisms (SNPs) in VCF format, barcodes identifying target cells, and the expected donor count. It extracts HTO names and retrieves single-cell genotypes using cellSNP before executing genetic deconvolution methods (vireo, demuxlet, freemuxlet, and souporcell) and hashing deconvolution tools (htodemux, multiseq, bff, demuxem, gmm-demux, hasheddrops, and hashsolo).
After classifying cells and summarizing assignments across both categories, the workflow joins all outputs and performs donor matching to rescue unassigned or conflicting cells using top-performing methods. It then identifies informative variants, packages the unified results into AnnData and MuData data objects, and generates quality reports using MultiQC.
Key facts
- Software type
- Nextflow pipeline
- Current version
- 0.2.0
- Input formats
- tar.gz (10x count matrices), BAM, VCF, TSV (barcodes), CSV (samplesheet)
- Output formats
- AnnData, MuData, MultiQC reports
- Integrated hashing tools
- htodemux, multiseq, bff, demuxem, gmm-demux, hasheddrops, hashsolo
- Integrated genetic tools
- cellSNP, vireo, demuxlet, freemuxlet, souporcell
What you can use it for
- Hash-based sample demultiplexing
- Assign single cells to donor samples based on hashtag oligonucleotide matrices using algorithms such as bff, htodemux, and multiseq.
- Genotype-based sample demultiplexing
- Deconvolve donor identities without hashtag oligos using aligned reads (BAM) and known or unreferenced genetic variants via vireo, demuxlet, freemuxlet, and souporcell.
- Cross-method donor matching and cell recovery
- Combine hashing and genetic demultiplexing results in rescue mode to cross-match donors and reassign unclassified or discordant single cells.
Run it here
The research agent runs nf-core/hadge with Nextflow on its own machine — up to 32 cores, 256 GiB of memory and 24 hours per run, which covers the test profile and real single-sample runs. It builds the samplesheet, checks it against the pipeline's schema and reads the results back. When a run is too big for one machine, it gives you the exact command for your own cluster instead.
Strengths and limits
Good at
- Combines 11 distinct hashing and genotype deconvolution algorithms within a single standardized pipeline.
- Recovers unassigned or discarded cells by cross-referencing hashing and genetic deconvolution outputs via donor matching.
- Exports processed assignments directly into AnnData and MuData structures for downstream single-cell analysis.
Watch out for
- Requires 10x Genomics-formatted count matrices compressed specifically as tar.gz archives.
- Demands BAM alignments, candidate SNP VCF files, and a FASTA reference when performing genetic deconvolution.
- Requires the exact number of pooled donors to be specified up front in the samplesheet.
Questions
Can I run nf-core/hadge without my own cluster?
The research agent runs nf-core/hadge with Nextflow on its own machine — up to 32 cores, 256 GiB of memory and 24 hours per run, which covers the test profile and real single-sample runs. It builds the samplesheet, checks it against the pipeline's schema and reads the results back. When a run is too big for one machine, it gives you the exact command for your own cluster instead.
What licence is nf-core/hadge under?
MIT, like every nf-core pipeline.
What operational modes does the pipeline support?
The pipeline includes configurations such as rescue mode (the default comprehensive profile that combines genetic and hashing deconvolution), as well as dedicated modes for testing genetic deconvolution (test_genetic), hashing deconvolution (test_hashing), and donor matching (test_donor_match).
What input files are required in the samplesheet?
Each samplesheet entry requires an RNA count matrix (tar.gz), a hashtag matrix (tar.gz), a BAM alignment file, a VCF file of SNPs, the count of multiplexed donors, and a list of target cell barcodes in TSV format.
Which tools are used for genetic deconvolution?
Genotype-based deconvolution is performed using vireo, demuxlet, freemuxlet, and souporcell, with single-cell genotyping handled by cellSNP.
Which tools are used for cell hashing deconvolution?
Hashing deconvolution leverages htodemux, multiseq, bff, demuxem, gmm-demux, hasheddrops, and hashsolo.
How to cite it
Curion, Fabiola, Xichen Wu, Lukas Heumos, Mariana Gonzales Andre, Lennard Halle, Melissa Grant-Peters, Charlotte Rich-Griffin, Hing-Yuen Yeung, Calliope A. Dendrou, Herbert B. Schiller & Fabian J. Theis. hadge: a comprehensive pipeline for donor deconvolution in single-cell studies. Genome Biol. 2024 Apr 26;25(1):109. doi: 10.1186/s13059-024-03249-z.
Written from nf-core/hadge's own README. Statements citing a figure that does not appear there are removed before publication. Licence and running details come from our registry.