nf-core pipeline ·
nf-core/provenancereport
A Nextflow pipeline that renders reproducible Quarto reports with full data, runtime and environment provenance.
What nf-core/provenancereport is
nf-core/provenancereport is a Nextflow bioinformatics pipeline developed by Alexander Peltzer, Gregor Sturm, and Julian Schwab. It validates an input samplesheet, stages the specified data files, and executes Quarto notebook reports within containerised or Conda-managed execution environments.
The pipeline focuses on computational reproducibility and auditability. It calculates MD5 checksums for input datasets, notebook templates, and outputs, whilst collecting detailed software version lists and runtime environment data. In addition to rendered HTML reports, it produces standardised provenance metadata records in BioCompute Object (BCO) and Workflow Run Research Object Crate (RO-Crate) formats.
What the pipeline does
The pipeline begins by validating and normalising a two-column CSV samplesheet using nf-schema. It resolves each file path and stages all input files by basename into the Quarto working directory. An untouched copy of the Quarto notebook is preserved, while a cached copy is prepared with a guarded R or Python package-version fallback mechanism. The pipeline then renders the notebook using the nf-core quarto_notebook module and logs packages loaded in the active R session or Python kernel.
Following report generation, the pipeline runs the nf-core md5sum module to generate MD5 checksums for every samplesheet input, the source notebook, the rendered Quarto HTML, and an optional sign-off document. The REPORTENVIRONMENT step inspects the Quarto runtime to capture R session, Python version, and container or Conda environment settings. Finally, the nf-prov plugin compiles BioCompute Object and RO-Crate provenance files, and MultiQC aggregates the software versions, inputs, checksums, and execution parameters into a final audit report.
Key facts
- Pipeline engine
- Nextflow (25.10.4 or later)
- Reporting engine
- Quarto
- Primary inputs
- Two-column CSV samplesheet (id, path) and a Quarto notebook (.qmd)
- Primary outputs
- Rendered Quarto HTML, MultiQC audit report, MD5 checksum file, and execution provenance files
- Provenance formats
- BioCompute Object (.bco.json) and Workflow Run RO-Crate (ro-crate-metadata.json)
- Supported container runtimes
- Docker, Singularity, Apptainer, and Conda
What you can use it for
- Default provenance reporting
- Execute the bundled Quarto template to summarise staged inputs, software environments, and file checksums for routine data tracking.
- Auditing custom Quarto notebooks
- Render user-supplied analysis notebooks while capturing package versions, runtime specifications, and output artifact checksums without modifying the source notebook file.
- Generating formal provenance crates
- Create standardised BioCompute Object (BCO) and Workflow Run RO-Crate metadata files using the nf-prov plugin for regulatory or institutional archiving.
- Review document publishing
- Stage an optional sign-off or review document alongside data files to verify and distribute signed audit records with complete checksum verification.
Run it here
The research agent runs nf-core/provenancereport 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
- Generates standardised BioCompute Object (BCO) and Workflow Run RO-Crate provenance files automatically via the nf-prov plugin.
- Verifies data integrity by calculating MD5 checksums for all input files, the original notebook, and the rendered outputs.
- Preserves the original source notebook unmodified while maintaining an internal traceable copy with package capture fallbacks.
- Compiles environment parameters, software packages, and run configurations into a single MultiQC audit report.
Watch out for
- Requires all input files listed in the samplesheet to have unique basenames because they are staged directly into a flat Quarto rendering directory.
- Custom notebooks require a pre-configured execution runtime containing Quarto and every language, library, and system dependency utilised by the report.
- Requires Nextflow version 25.10.4 or newer to execute.
Questions
Can I run nf-core/provenancereport without my own cluster?
The research agent runs nf-core/provenancereport 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/provenancereport under?
MIT, like every nf-core pipeline.
What structure is required for the input samplesheet?
The samplesheet must be a CSV file with two columns: id and path. Each row points to exactly one input file.
Can custom Quarto notebooks be used instead of the default template?
Yes. A custom template can be provided with the --notebook parameter, provided the target execution environment contains Quarto and all required software dependencies.
How should custom Quarto notebooks access staged input files?
Input files are staged by their basename directly into the Quarto working directory. Custom notebooks should read those basenames directly without including directory paths.
How does the pipeline detect which software packages were used in the report?
If a custom notebook provides a versions.csv file, that file is authoritative. If absent, the pipeline appends a guarded hidden cell to an internal notebook copy to record packages loaded in the R session or Python kernel.
Which files are evaluated for MD5 checksums?
Checksums are calculated for every file listed in the samplesheet, the unchanged source notebook, the rendered HTML report, and the review document if one was supplied.
How to cite it
Philip Ewels, Alexander Peltzer, Sven Fillinger, Harshil Patel, Johannes Alneberg, Andreas Wilm, Maxime Ulysse Garcia, Paolo Di Tommaso & Sven Nahnsen. The nf-core framework for community-curated bioinformatics pipelines. Nat Biotechnol. 2020 Feb 13. doi: 10.1038/s41587-020-0439-x.
Written from nf-core/provenancereport's own README. Statements citing a figure that does not appear there are removed before publication. Licence and running details come from our registry.