[BenjaminWehnert1008]

First release: nf-core/deepmutscan v1.0.0

This PR merges dev into master for the first release of nf-core/deepmutscan. @MaximilianStammnitz and I would be very grateful for your release reviews 🙏🙂.

What this pipeline does

nf-core/deepmutscan processes deep mutational scanning (DMS) data from short-read sequencing of site-saturation mutagenesis libraries. It was primarily designed for shotgun sequencing of long open reading frames, where the variant library is randomly fragmented before sequencing (no tiling or barcoding), and it handles amplicon data in the same way. Importantly, because variant frequencies in shotgun sequencing data are often sparse – below 1 in 10,000 reads – and thus in the range of per-base sequencing error rates (Q30-Q40), we conceptualise and implement key single-nucleotide count error correction modules.

1. Pre-processing and counting: FastQC → BWA-MEM alignment to a gene-sized (small) reference → samtools filtering (MAPQ ≥ 30, no indels) → vsearch read-pair merging and re-alignment → variant counting with a light-weight pysam/polars counter (replaces GATK AnalyzeSaturationMutagenesis, column-compatible output) → annotation and filtering against the programmed codon library (--mutagenesis_type).
2. Error correction and library QC: single-nucleotide variant sequencing-error correction from read-linked "false double" mutants (maximum likelihood or empirical Bayes estimation) or from additionally supplied wildtype template sequencing data, with an interactive report; per-library QC plots (count heatmaps, positional coverage and count profiles, sequencing-depth rarefaction).
3. Fitness: default log-ratio estimator relative to a high-quality and high-count synonymous wildtype proxy, rescaled to synonymous = 0 / stop = −1; optional DiMSum (--dimsum) and mutscan edgeR/limma (--mutscan); optional interactive 3D variant effect inspection tool from a user-supplied structure (--pdb).
4. Reporting: A single, self-contained deepmutscan_report.html per run.

Testing

• -profile test: 50,000 read-pair subsamples of a minimal GID1A nicking-mutagenesis GluePCA experiment (2 input + 2 output libraries) on the deepmutscan branch of nf-core/test-datasets, with fitness, DiMSum, mutscan and the structure viewer switched on. nf-test snapshot test in tests/default.nf.test.
• -profile test_full: the complete GID1A experiment (3 input + 3 output libraries, ~480M read pairs) from ENA project PRJEB110196, linked from a samplesheet on the same test-datasets branch, with fitness, DiMSum, mutscan and the structure viewer switched on (Full-size test profile (test_full) and AWS full test #68).
• Test data PR: Add a full test samplesheet test-datasets#1972 (adds the test_full samplesheet and the GID1A AlphaFold DB structure used by --pdb).

Known follow-ups

Done since this PR was opened:

• Template update to nf-core/tools 4.1.0 and re-linting #66 (Important! Template update for nf-core/tools v4.1.0 #65)
• Full-size test profile (test_full) and AWS full test #68 (Add full-size test and finer seqdepth grid #74, Add a full test samplesheet test-datasets#1972)
• Parameter and samplesheet conventions #69 (Samplesheet checks and parameter conventions (Issue #69) #82, Release review fixes: samplesheet and parameters (#82), counting, read merging, publishing and docs #84)
• Mini-bug with MultiQC report embedded in HTML #75 (Fix/report frame anchor links #77)
• Incomplete or corrupted input FASTQ files #85 (Merge reads before alignment, input FASTQ checks and more pipeline tests. #87)
• Containers built from each module's environment.yml; rename PREMERGE to MERGE_ALIGN #92

Release review: many thanks @piplus2! We are working through the points in a few small PRs into dev (correctness of counting and mutscan, module containers/versions/ext.args, docs and citations). Once these are merged, we will reply to every point here in one go, so that only one re-review is needed.

Planned for later releases (see the milestones and the roadmap in #90):

• v1.1.0, robustness: Interactive 3D protein structure viewer – config enhancement #79, Optional re-pairing of out-of-order mates (--repair_pairs) #86
• v1.2.0, sort-seq and improved count error model: Support for FACS / sort-seq data #67, SNV error rate improvements & mutational signature support #72
• v1.3.0, more fitness estimators: Enrich2 and rosace support #71
• v1.4.0, read input diversification: Overall efficiency tuning of the pipeline #70, Read adapter (or base quality-dependent) pre-trimming #80, Single-end read mode #81
• v2.x, beyond one ORF and saturation mutagenesis libraries: Multi-ORF support #83, In-frame insertion and deletion (indel) variants #88, Multi-codon variant libraries (designed higher-order mutants) #89, Barcoded DMS: long-read barcode–variant association and short-read barcode counting #91

PR checklist

• This comment contains a description of changes (with reason).
• If you've fixed a bug or added code that should be tested, add tests! (pipeline-level nf-test with the test profile)
• If you've added a new tool - have you followed the pipeline conventions in the contribution docs
• If necessary, also make a PR on the nf-core/deepmutscan branch on the nf-core/test-datasets repository.
• Make sure your code lints (nf-core pipelines lint). (passes with nf-core/tools 4.1.0; see Important! Template update for nf-core/tools v4.1.0 #65)
• Ensure the test suite passes (nextflow run . -profile test,docker --outdir <OUTDIR>).
• Usage Documentation in docs/usage.md is updated.
• Output Documentation in docs/output.md is updated.
• CHANGELOG.md is updated.
• README.md is updated (including new tool citations and authors/contributors).
• Check for unexpected warnings in debug mode (nextflow run . -profile debug,test,docker --outdir <OUTDIR>).

Many thanks in advance to the reviewers, and to @mirpedrol and @mashehu for their guidance along the way.

[MaximilianStammnitz]

Hi @piplus2,

Thanks again for your follow-up! We have completed both of these remaining points now:

1. Conda/Singularity CI (Brandnew README #2): after the 4.2.1 template update and the master merge (Important! Template update for nf-core/tools v4.2.1 #94, Resolve the BWA index prefix without find(1) #96), the full conda, docker and singularity matrix is green on the current head (eb0d3ce), for both Nextflow 25.10.4 and latest-everything.
2. Container configs (Added functional hyperlinks to Readme #3): with Container metadata, conda lock files and container configs for all local modules #97, conf/containers_*.config now cover all local modules. We generated them with nf-core modules containers create, which built Docker and Singularity images for amd64 and arm64, conda lock files and the containers: sections in each meta.yml. Modules with identical environment.yml files share one image. There are two exceptions, both noted in docs/usage.md:
   • mutscan isn't packaged for linux-aarch64 on bioconda, so RUN_MUTSCAN is amd64 only.
   • RUN_DIMSUM keeps its existing amd64 image from Release review fixes: samplesheet and parameters (#82), counting, read merging, publishing and docs #84. The new pixi-based builds lack the data of GenomeInfoDbData, which a conda post-link script installs, so DiMSum failed with them.

We also set manifest.diagram to the metro map. nf-core pipelines lint --release passes with 0 failures; the only warnings left are the Zenodo placeholder and newer nf-core module versions, which we'd update in v1.1.0.

Could you take another look when you have time? Many thanks!

[piplus2]

Hi @MaximilianStammnitz and @BenjaminWehnert1008,

Thanks for wrapping these up! I checked the current head (eb0d3ce): the full conda/docker/singularity matrix is green on both Nextflow versions, and conf/containers_*.config now cover all local modules. The arm64 exceptions for RUN_MUTSCAN and RUN_DIMSUM are reasonable and well documented in usage.md. All my inline threads are resolved too.

The remaining items (release date/name, Zenodo DOI, module version bumps, EDAM) are fine as release-day tasks or follow-ups.

Great work on this, it's a big improvement since the first round. LGTM, congrats on the first release! 🎉

[maxulysse]

First quick pass.

I am slightly confused by the execution trace, are you in need of such a file in your report?

[maxulysse]

I think the R scripts could gain to be re-assess.

I like that you kept them bundled in templates, but I do think we can move to bin, and try to reuse some of the code, instead of copying it.

Made some other comments on the code.

I would pay attention to queue vs value channel for the references.

Other general comment on my part, is I think some part are slightly too complex, or over designed, and would gain from being simplified, but I know how hard it can be, and I do like what you have made here, but I think collaborators and future you would like less maintenance burden

[MaximilianStammnitz]

Thanks again @maxulysse for these thorough checks! 😇

The value channel update and some other small fixes are now in #99. On the R scripts and overall complexity: fair point. @BenjaminWehnert1008 and I agree that shared R code should live in one place, and we've opened #101 for v1.1.0. A good part of our v1.1.0 performance overhaul plans already goes towards that direction: fewer but larger processes, improved thread use and some tool replacements/upgrades (e.g. FastQC --> Falco #102).