tumourevo
nf-core/tumourevo
Analysis pipeline to model tumour clonal evolution from WGS data (driver annotation, quality control of copy number calls, subclonal and mutational signature deconvolution)
Key tools
Run it
nfclaw run tumourevo --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/tumourevo/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run tumourevo --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
dataset | string or integer | yes | ||
patient | string or integer | yes | ||
tumour_sample | string or integer | yes | ||
normal_sample | string or integer | no | ||
cancer_type | string | no | ||
cna_caller | string | yes | ||
vcf | string (file path) | yes | ||
tbi | string (file path) | yes | ||
tumour_alignment | string (file path) | no | ||
tumour_alignment_index | string (file path) | no | ||
cna_segments | string (file path) | yes | ||
cna_extra | string (file path) | no |
--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):
dataset,patient,tumour_sample,cna_caller,vcf,tbi,cna_segmentsAny of the optional columns above may be appended to the header when your data needs them: normal_sample, cancer_type, tumour_alignment, tumour_alignment_index, cna_extra.
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: vcf, tbi, tumour_alignment, tumour_alignment_index from files matching their patterns, by sample name. Optional columns left out take their schema defaults in the pipeline: cancer_type = PANCANCER — set them with --sheet-set where your design differs. Set the required columns no file determines with --sheet-set COLUMN=VALUE (a constant or a {sample}/{lane} template): dataset (string or integer); patient (string or integer); tumour_sample (string or integer); cna_caller (string); cna_segments (string). Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Reference genome
This release resolves a reference genome remotely by default. --genome defaults to GRCh38; the schema declares AWS iGenomes at s3://ngi-igenomes/igenomes/. The pinned configuration gives that key the FASTA ${params.igenomes_base}/Homo_sapiens/NCBI/GRCh38/Sequence/WholeGenomeFasta/genome.fa. Resolving references through that default needs access to this source. For a self-contained run, pass your own reference instead (e.g. --fasta; the main_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 tumourevo --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 tumourevo ... --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 tumourevo --demo --outdir results # adds the upstream test profile (-profile test,docker)This pinned test profile misspells sparsesignatures_K; the declared parameter is sparsesignatures_k. For its bundled tiny input, nfclaw supplies the intended 2:3 grid and records it in params/provenance. Explicit CLI or params-file values win. Your own input, test-data base, extra profiles or --config disable this demo default. A native original and fresh replay completed with a 24 GiB task ceiling; an 8 GiB task was killed. Allocate sufficient memory for SparseSignatures. Other releases retain their own defaults.
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.
dataset,patient,tumour_sample,cna_caller,vcf,tbi,cna_segments| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
dataset | string or integer | required | — |
patient | string or integer | required | — |
tumour_sample | string or integer | required | — |
normal_sample | string or integer | optional | — |
cancer_type | string | optional | — |
cna_caller | string | required | — |
vcf | string (file path) | required | — |
tbi | string (file path) | required | — |
tumour_alignment | string (file path) | optional | — |
tumour_alignment_index | string (file path) | optional | — |
cna_segments | string (file path) | required | — |
cna_extra | string (file path) | optional | — |
Required parameters
--inputstring (file path)Path to comma-separated file containing information about the samples in the experiment.
Constraint · matches ^\S+\.csv$
--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
--genomestringReference genome name.
GRCh38GRCh37Parameter explorer
82 parameters · 15 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.
81 parameters · 1 hidden
Cnaqc5
If TRUE INDEL are excluded from CNAqc analysis and following steps otherwise are kept.
For clonal simple CNAs, if "closest" the closest peak will be used to match the expected peak. If "rightmost" peaks are matched prioritizing right to left peaks (the higher-VAF gets matched first); this strategy is more correct in principle but works only if there are no spurious peaks in the estimated density.
For clonal simple CNAs, this is the same as cnaqc_min_karyotype_size (not declared in this pinned schema), but with a cut measured on absolute mutation counts.
Minimum number of mutations that are required to be mapped to a karyotype in order to compute CCF values.
For clonal simple CNAs, the purity error tolerance to determine QC pass or fail.
Driver Annotation1
Path to driver table.
Generic options4
Email address for completion summary.
Email address for completion summary, only when pipeline fails.
Do not use coloured log outputs.
Send plain-text email instead of HTML.
Input Output options2
Path to comma-separated file containing information about the samples in the experiment.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Joincnaqc1
If TRUE the original CNAqc object is kept in the joinCNAqc object, otherwise it is lost.
Main options6
Path to reference fasta file.
Flag for filtering or not QC mutations.
Reference genome name.
Method used to save pipeline results to output directory.
If True QC analysis is performed by chromosome otherwise is performed whole genome
List of tools for running the pipeline.
Mobster5
A vector with the number of Beta components to use.
Threshold for minimum VAF to use in the deconvolution
The minimum number of mutations assigned to a cluster to be returned as output.
The minimum mixing proportion of a cluster to be returned as output.
Whether to use tail mutations for subclonal deconvolution or not .
Other17
Institutional config contact information.
Institutional config description.
Institutional config URL link.
Base directory for Institutional configs.
Git commit id for Institutional configs.
Display the help message.
Display the full detailed help message.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Pyclone Vi4
The probability density used to model the read count data. Choices are beta-binomial and binomial.
The number of clusters to use while fitting.
Number of grid points used for approximating the posterior distribution.
Number of random restarts of variational inference.
Sigprofiler11
Specify True if the reference genome should be downloaded.
Specify the path to the reference genome (if downloaded by the user), e.g. path/to/genome/tsb
Mode of publishing the SigProfiler genome.
Mutation context name(s), separated by commas (,), that define the mutational contexts for signature extraction. In the default value, 96 represents the SBS96 context, DINUC represents the dinucleotide context, and ID represents the indel context.
'matrix' is used for table format inputs using a tab separated file.
The maximum number of iterations to be completed before NMF converges .
The maximum number of signatures to be extracted.
The minimum number of iterations to be completed before NMF converges.
The minimum number of signatures to be extracted.
The number of iterations to be performed to extract each number signature.
The number number of iterations to done between checking next convergence .
Sparsesignature12
The cross-validation test size, i.e., the percentage of entries set to zero during NMF and used for validation.
The number of randomized restarts of a single cross-validation repetition, in case of poor fits.
The number of repetitions of the cross-validation procedure.
The number of iterations of every single run of NMF LASSO.
Number of signatures to be discovered.
The candidate values of the sparsity parameter for the exposure-matrix entries alpha whose goodness of fit is assessed by cross-validation.
The candidate values of the sparsity parameter for the exposure-matrix entries alpha whose goodness of fit is assessed by cross-validation.
The candidate values of the sparsity parameter for the signature matrix 'beta' whose goodness of fit is assessed by cross-validation.
The number of sub-iterations involved in the sparsification phase, within a full NMF LASSO iteration.
Number of iterations to estimate the length(K) matrices beta (including the background signature) in case the argument beta is NULL. Ignored if beta is given.
The number of requested NMF worker subprocesses to spawn. If Inf, an adaptive maximum number is automatically chosen. If NA or NULL, the function is run as a single process.
Seed for the random number generation. To be set for reproducibility.
Tinc1
A number that represent the normal contamination level for which the sample is considered passed or failed.
Variant Annotation6
Parameter for downloading VEP cache.
Path to VEP cache.
VEP cache version.
Add an extra custom argument to VEP.
VEP reference genome name.
VEP species.
Vcf2cnaqc1
Flag for filtering mutations from vcf.
Viber5
The minimum Binomial success probability when applying a heuristic procedure to filter clusters after Variational Inference.
The minimum number of dimensions where we want to detect a Binomial component when applying a heuristic procedure to filter clusters after Variational Inference.
The maximum number of clusters returned. Lower values speed up convergence.
The minimum size of the mixture component when applying a heuristic procedure to filter clusters after Variational Inference.
Boolean value whether points assigned to a cluster that is filtered our, are re-assigned from the density function.
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/tumourevo/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.