From 33168d3c87afe52b3b45338a6c723abbebc6291b Mon Sep 17 00:00:00 2001 From: Jonathan Manning Date: Fri, 14 Nov 2025 18:05:16 +0000 Subject: [PATCH 1/2] Add warning about Qualimap read counting bug Document known limitation where Qualimap reports more reads than exist in the BAM file when assigning reads to genomic features. Provide workarounds including using RSeQC as alternative and --skip_qualimap flag. Addresses #1273 --- docs/output.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/output.md b/docs/output.md index b47593a05..77b921fb4 100644 --- a/docs/output.md +++ b/docs/output.md @@ -614,6 +614,18 @@ RSeQC documentation: [tin.py](http://rseqc.sourceforge.net/#tin-py) The [Qualimap RNA-seq QC module](http://qualimap.bioinfo.cipf.es/doc_html/analysis.html#rna-seq-qc) is used within this pipeline to assess the overall mapping and coverage relative to gene features. +:::warning +**Known limitation**: Qualimap has a known bug ([#1273](https://github.com/nf-core/rnaseq/issues/1273), [Qualimap issue #81](https://bitbucket.org/kokonech/qualimap/issues/81)) where it may report more reads assigned to genomic features (exons, introns, intergenic regions) than the total number of reads in the BAM file. This can lead to inflated read counts and incorrect genomic origin statistics. + +If accurate read distribution metrics are critical for your analysis, we recommend: + +- Cross-referencing Qualimap results with RSeQC output (particularly `read_distribution.txt`) +- Using `--skip_qualimap` to disable Qualimap and rely on RSeQC for genomic feature distribution +- Validating suspicious results with alternative tools or custom scripts + +This is an upstream tool issue that cannot be fixed at the pipeline level. +::: + ![MultiQC - Qualimap gene coverage plot](images/mqc_qualimap_coverage.png) ![MultiQC - Qualimap genomic origin plot](images/mqc_qualimap_features.png) From f2ddd31f5a8660dea9d4ab21376bc692f48c0c5f Mon Sep 17 00:00:00 2001 From: Jonathan Manning Date: Fri, 14 Nov 2025 18:07:55 +0000 Subject: [PATCH 2/2] Update CHANGELOG.md for Qualimap documentation PR --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5c45983f..134dd0031 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Special thanks to the following for their contributions to the release: - [PR #1608](https://github.com/nf-core/rnaseq/pull/1608) - Bump version after release 3.21.0 - [PR #1617](https://github.com/nf-core/rnaseq/pull/1617) - Update bbmap/bbsplit module +- [PR #1625](https://github.com/nf-core/rnaseq/pull/1625) - Add documentation warning about Qualimap read counting bug ([#1273](https://github.com/nf-core/rnaseq/issues/1273)) ## [[3.21.0](https://github.com/nf-core/rnaseq/releases/tag/3.21.0)] - 2025-09-18