hadge
nf-core/hadge
Comprehensive pipeline for donor demultiplexing in single cell
Key tools
Run it
nfclaw run hadge --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/hadge/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run hadge --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string | yes | matches ^\S+$ | |
rna_matrix | string (file or directory path) | no | matches ^\S+$ | |
hto_matrix | string (file or directory path) | no | matches ^\S+$ | |
bam | string (file path) | no | matches ^\S+\.bam$ | |
barcodes | string (file path) | no | matches ^\S+\.tsv$ | |
n_samples | integer | no | ≥ 1 | |
vcf | string (file path) | no | matches ^\S+\.vcf$ |
--input must match ^\S+\.csv$.
The samplesheet is a CSV with this header (the columns the schema requires); fill each value per the table above and reference.md (no example value is invented here):
sampleAny of the optional columns above may be appended to the header when your data needs them: rna_matrix, hto_matrix, bam, barcodes, n_samples, vcf.
From data files. --input may also be the data files — a directory (searched recursively), a quoted glob, or files (--input once per file) — from which nfclaw writes this samplesheet: sample from file names; bam, barcodes, vcf from files matching their patterns, by sample name. Set other columns with --sheet-set COLUMN=VALUE. Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Reference genome
No reference genome is set by default: supply your own reference. The schema declares AWS iGenomes at s3://ngi-igenomes/igenomes/; selecting --genome <id> uses the paths in the pipeline's reference configuration. Access to that remote source is required. To supply your own reference, use e.g. --fasta; the reference_genome_options group in reference.md lists every reference option. Set --igenomes-ignore true to disable the lookup entirely. Confirm the selected reference's paths and source in the pinned upstream/nextflow.config and upstream/conf/ before running.
Resources
Resource requests follow the pipeline's configs and selected profiles. nf-core's resource labels often assume a server — a single step can request far more memory than a workstation has, and retry rules can increase requests. If a run fails with Process requirement exceeds available memory (or CPUs), cap every request, and every retry, at what this machine actually has:
nfclaw run hadge --input samplesheet.csv --outdir results -profile docker \ --limit-cpus 4 --limit-memory 15.GBnfclaw turns those into Nextflow's process.resourceLimits and passes them as a -c config — the mechanism nf-core prescribes for exactly this (docs). Set them to the machine's real capacity. --limit-time DURATION also caps how long any one task may run: a task that needs longer is stopped, and so is every retry, so set it only as a deliberate ceiling, never as a guess at how long the analysis takes. The generated config is kept in <outdir>/provenance/, so commands.sh replays the run under the same ceiling.
Nextflow engine
This release declares nextflowVersion = '!>=25.10.4'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run hadge ... --nxf-ver 25.10.4--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run hadge --demo --outdir results # adds the upstream test profile (-profile test,docker)Samplesheet
A CSV with this header (the columns the schema requires). Fill each value per the constraints below; optional columns from the table may be appended.
sample| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string | required | matches ^\S+$ |
rna_matrix | string (file or directory path) | optional | matches ^\S+$ |
hto_matrix | string (file or directory path) | optional | matches ^\S+$ |
bam | string (file path) | optional | matches ^\S+\.bam$ |
barcodes | string (file path) | optional | matches ^\S+\.tsv$ |
n_samples | integer | optional | ≥ 1 |
vcf | string (file path) | optional | matches ^\S+\.vcf$ |
Required parameters
--inputstring (file path)Path to comma-separated file containing information about the samples in the experiment.
Constraint · matches ^\S+\.csv$
--modestringMode of the pipeline.
genetichashingrescuedonor_match--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Parameter explorer
195 parameters · 20 groupsEvery parameter from the pinned nextflow_schema.json. nfclaw checks explicit values before launch; complex rules use the pinned pipeline's runtime validation. Search, filter by group, and expand any parameter for its default, allowed values and constraints.
176 parameters · 19 hidden
Bff options12
Path to barcode whitelist for preprocessing.
Threshold for caller disagreement.
Path to cell barcode whitelist for GenerateCellHashingCalls().
Library chemistry (e.g., 10xV3).
Whether to generate heatmaps in BFF.
Whether to compute tSNE visualization in BFF.
Majority consensus threshold.
Method(s) to use within BFF.
Methods to use for consensus calling.
Optional metrics file path.
Per-cell saturation value.
Whether to run preprocessing steps for BFF.
Cellsnp options10
Tag for cell barcodes, e.g., CB for 10x Genomics. Set to 'None' for bulk RNA-seq or SMART-seq2.
If true, do not skip anomalous read pairs (i.e., count orphan reads).
Excluding flags in SAM/BAM: skip reads that have ANY of these flags. See SAM format specification for details.
Required flags in SAM/BAM: skip reads that don't have ALL of these flags. See SAM format specification for details.
Maximum read depth at a position per input file. Set to 0 for highest possible value.
Minimum aggregated count (across cells) for SNPs to be included in the output.
Minimum read length (after clipping) for a read to be included.
Minimum minor allele frequency (MAF) for SNPs to be included in the output.
Minimum mapping quality for a read to be included.
Tag for UMI barcodes, e.g., UB for 10x Genomics. Set to 'None' for bulk RNA-seq or SMART-seq2 without UMIs.
Demuxem options7
The Dirichlet prior concentration parameter (alpha) on samples. An alpha value < 1.0 will make the prior sparse.
Comma-separated list of gender-specific genes (e.g. Xist) for generating violin plots.
Generate diagnostic plots.
Only demultiplex cells/nuclei with at least this number of expressed genes.
Only demultiplex cells/nuclei with at least this number of UMIs.
Any cell/nucleus with less than this count of hashtags from the signal will be marked as unknown.
The random seed used in the KMeans algorithm to separate empty ADT droplets from others.
Demuxlet options8
Grid of alpha to search for.
Prior probability of doublet.
FORMAT field to extract the genotype, likelihood, or posterior from.
Slope of genotype error rate. [error] = [offset] + [1-offset]*[coeff]*[1-r2]
Offset of genotype error rate. [error] = [offset] + [1-offset]*[coeff]*[1-r2]
Minimum call rate.
Minimum minor allele frequency.
INFO field name representing R2 value. Used for representing imputation quality.
Donor Match options11
Path to cell genotype file (necessary only for donor_match mode).
Path to demultiplexing result CSV file (necessary only for donor_match mode).
Find variants for donor matching.
Path to cell genotype file (necessary only for donor_match mode).
Match donor between different demultiplexing methods.
First method to use for donor matching.
Second method to use for donor matching.
Option to subset the donor genotype based on detected variants.
Minimum variant count threshold.
The Minimal percentage of a variant for filtering. Has to be in a range between [0,5;1[. For example, 0.9 means that we only keep variants with a frequency higher than 90% or lower than 10%.
Path to Vireo filtered variants file (optional, only used in donor_match mode).
Dsc Pileup options10
Maximum base quality (higher BQ will be capped).
SAM/BAM FLAGs to be excluded.
Minimum base quality to consider (lower BQ will be skipped).
Minimum mapping quality to consider (lower MQ will be ignored).
Minimum number of SNPs with coverage for a droplet/cell to be considered.
Minimum distance to the tail (lower will be ignored).
Minimum number of total reads for a droplet/cell to be considered.
Minimum number of unique reads (determined by UMI/SNP pair) for a droplet/cell to be considered.
Tag representing readgroup or cell barcodes to partition the BAM file into multiple groups. For 10x Genomics, use CB.
Tag representing UMIs. For 10x Genomics, use UB.
Freemuxlet options8
Bayes Factor Threshold used in the initial clustering.
Prior probability of doublet.
Fraction of droplets to be clustered in the very first round of initial clustering procedure.
Genotype error parameter per cluster.
Iteration for initial cluster assignment (set to zero to skip the iterations).
Keep missing cluster assignment as missing in the initial iteration.
Randomize the singlet scores to test its effect.
Seed for random number (use clocks if not set).
Generic options4
Display the help message.
Display the full detailed help message.
Custom MultiQC yaml file containing HTML including a methods description.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Gmmdemux options9
If specified, it will generate the statistic summary of the dataset, including MSM and SSM rates. This requires an estimated total number of cells in the assay as input.
Provide the cell list. Requires a file path argument. Only executes if -u is set.
Names of the HTO tag(s) to extract, separated by ','. Joint HTO samples are combined with '+', such as 'HTO_1+HTO_2'.
Comma separated list of HTO names, without whitespace. If null, hto_names are extracted from the input hto matrix from features.tsv.gz.
The random seed used in the GaussianMixture algorithm.
Load a full classification report and skip the mtx folder as input. Requires a file path argument.
If true, summary report is generated.
The confidence threshold value for classification. A higher value leads to more stringent classification.
If true, full classification report is generated, otherwise the simplified classification report.
Hasheddrops options20
Scaling parameter for Dirichlet-multinomial sampling.
Whether to use ambient solution abundance.
Alternative method for identifying empty droplets.
An integer matrix specifying valid combinations of HTOs. Number of items in each row has to be the same.
Minimum threshold for confident singlet identification.
Number of MADs to identify confident singlets.
Whether to use constant ambient contamination level.
Minimum threshold for doublet identification.
Whether to use 2-component mixture model for doublets.
Number of MADs to identify doublets.
Column to use for gene names.
Lower bound for ignoring barcodes.
FDR threshold for cell filtering.
Lower bound on total UMI count for empty droplets.
Minimum proportion for ambient profile inference.
Number of iterations for Monte Carlo p-value calculations.
Minimum pseudo-count for log-fold change computation.
Whether to round non-integer values.
Whether to run EmptyDrops analysis as part of HashedDrops.
Whether to test ambient RNA.
Hashsolo options6
Groovy list (['hash_1', 'hash_2']) of .obs columns that contain cell hashing counts. Can be null if the data is in 10x Genomics format, as the columns are derived from the input.
Input directory containing transcriptomic data in 10x mtx format.
Number of barcodes to use to create noise distribution.
Column in cell_hashing_adata.obs for how to break up demultiplexing.
List of comma-separated priors for each hypothesis: NEGATIVE, SINGLET, DOUBLET.
Number of decimal places to round numeric values in cell_hashing_data.obs before saving. If omitted, no rounding is applied.
Htodemux options7
Initialization method for clustering.
Clustering function to use.
Number of samples for clustering.
Number of starts for clustering.
The quantile to use for thresholding.
Random seed for reproducibility.
Whether to print verbose output.
Htodemux Visualization options17
Generate feature scatter plot. If no features are provided (one of them is null), the first two features from the assay will be used.
Generate heatmap.
Number of cells for heatmap.
The number of plots that are dispalyed next to each other in one row. The number of plots corresponds to the number of Hash Tag Oligo (HTO) identifiers.
Generate ridge plot.
Name of a Hash Tag Oligo (HTO) identifiers, usually defined in the feature.tsv of the hto matrix folder.
Name of a Hash Tag Oligo (HTO) identifiers, usually defined in the feature.tsv of the hto matrix folder.
Generate a two dimensional tSNE embedding for HTOs.
Approximate tSNE.
Max number of donors.
What should we remove from the object (we have Singlet, Doublet and Negative).
Invert tSNE selection.
Value for perplexity.
Verbose tSNE.
Features to plot (gene expression, metrics, PC scores, anything that can be retrieved by FetchData).
Plot the feature axis on log scale.
Generate violin plot.
Input Output options10
Perform BAM QC.
File with common variants. If provided, the BAM files will be filtered to only include reads that overlap with the common variants.
Email address for completion summary.
Tools used for genetic demultiplexing.
Tools used for hash demultiplexing.
Path to comma-separated file containing information about the samples in the experiment.
Mode of the pipeline.
MultiQC report title. Printed as page header, used for filename if not otherwise specified.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Save intermediate files.
Multiseqdemux options7
Whether to automatically determine thresholds.
Maximum number of iterations.
Step size for quantile range.
Start of quantile range.
End of quantile range.
The quantile to use for thresholding.
Whether to print verbose output.
Preprocessing options7
Assay type for preprocessing.
Column containing gene information.
Margin parameter for preprocessing.
Number of features to select.
Delimiter for parsing feature names.
Normalization method to use.
Method for feature selection.
Reference Genome options2
Path to FASTA genome file.
Name of iGenomes reference.
Souporcell options10
Common variant loci or known variant loci vcf, must be vs same reference fasta.
Set to True to ignore data error assertions.
Known variants per clone in population vcf mode, must be .vcf right now we dont accept gzip or bcf sorry.
Which samples in population vcf from known genotypes option represent the donors in your sample. Provide space-separated sample names for multiple donors.
Max loci per cell, affects speed.
Min alt to use locus.
Min ref to use locus.
Ploidy, must be 1 or 2.
Number of restarts in clustering, when there are > 12 clusters we recommend increasing this to avoid local minima.
Don't remap with minimap2 (not recommended unless in conjunction with --common_variants).
Vireo options11
If true, turn on SNP specific allelic ratio (ASE mode).
If true, detect ambient RNAs in each cell (experimental feature).
Range of cells to process, e.g., '0-10000'. Default is 'all'.
Number of extra donors in pre-cluster, when GT needs to be learned.
Method for searching from extra donors. 'size': n_cell per donor; 'distance': GT distance between donors.
If true, treat donor GT as prior only and learn genotypes from data.
The tag for donor genotype in VCF file. Options: GT, GP, PL.
Number of random initializations when GT needs to be learned.
If true, do not check for doublets during demultiplexing.
If true, turn off plotting GT distance.
Random seed for initialization.
Outputs
Results land in --outdir; the files and directory layout depend on the selected workflow, parameters and publication settings. Run metadata is normally placed in <outdir>/pipeline_info/ (execution report, software versions), when those outputs are enabled. The pinned tree includes MultiQC support; a report is produced only when its workflow step runs. nfclaw run also writes <outdir>/provenance/ with the exact params file and the run log, <outdir>/provenance/logs/run.log — the whole launch, whose last line states the outcome (Nextflow's own log is <outdir>/.nextflow.log); unless --no-provenance it adds a run manifest (pinned version, commit and exact command), input/output SHA-256 checksums, and a replayable commands.sh.
The exact output files and directory layout for this release are documented upstream: github.com/nf-core/hadge/blob/1.0.0/docs/output.md
Check a run — in the foreground or the background — with nfclaw status <outdir>: success, still running, how it ended (with the error), or stopped without an outcome; exit 0 success, 3 running, 1 otherwise.