Merge pull request #873 from nf-core/doc_perc_id

Document percent identity parameters

Author: prototaxites

.nf-core.yml

@@ -17,4 +17,4 @@ template:
   name: mag
   org: nf-core
   outdir: .
-  version: 5.0.0
+  version: 5.1.0dev

CHANGELOG.md

@@ -3,6 +3,20 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 5.1.0dev - [unreleased]
+
+### `Added`
+
+- [#873](https://github.com/nf-core/mag/pull/873) - Document usage of `longread_percentidentity` and `shortread_percentidentity` and set the value of `longread_percentidentity` in the `test_full` profile to 85 (by @prototaxites)
+
+### `Changed`
+
+### `Fixed`
+
+### `Dependencies`
+
+### `Deprecated`
+
 ## 5.0.0 - [2025-09-30]
 
 ### `Added`

assets/multiqc_config.yml

@@ -1,7 +1,7 @@
 report_comment: >
-  This report has been generated by the <a href="https://github.com/nf-core/mag/releases/tag/5.0.0"
+  This report has been generated by the <a href="https://github.com/nf-core/mag/tree/dev"
   target="_blank">nf-core/mag</a> analysis pipeline. For information about how to
-  interpret these results, please see the <a href="https://nf-co.re/mag/5.0.0/docs/output"
+  interpret these results, please see the <a href="https://nf-co.re/mag/dev/docs/output"
   target="_blank">documentation</a>.
 report_section_order:
   "nf-core-mag-methods-description":

conf/test_full.config

@@ -31,6 +31,9 @@ params {
     spadeshybrid_fix_cpus      = 10
     megahit_fix_cpu_1          = true
 
+    // mapping options
+    longread_percentidentity   = 85
+
     // available options to enable reproducibility for BUSCO (--busco_db) not used here
     // to allow detection of possible problems in automated lineage selection mode using public databases
 

docs/usage.md

@@ -417,6 +417,18 @@ nf-core/mag integrates an additional subworkflow to validate ancient DNA _de nov
 
 [Characteristic patterns of ancient DNA (aDNA) damage](<(https://doi.org/10.1073/pnas.0704665104)>), namely DNA fragmentation and cytosine deamination (observed as C-to-T transitions) are typically used to authenticate aDNA sequences. By identifying assembled contigs carrying typical aDNA damages using [PyDamage](https://github.com/maxibor/pydamage), nf-core/mag can report and distinguish ancient contigs from contigs carrying no aDNA damage. Furthermore, to mitigate the effect of aDNA damage on contig sequence assembly, [freebayes](https://github.com/freebayes/freebayes) in combination with [BCFtools](https://github.com/samtools/bcftools) are used to (re)call the variants from the reads aligned to the contigs, and (re)generate contig consensus sequences.
 
+## A note on coverage estimation
+
+In order to run the binning tools included in the pipeline, MAG must first align reads back to the assemblies, and estimate the coverage of each contig.
+
+During the coverage estimation step, these alignments are by default filtered to retain alignments that have a percentage identity of 97% (i.e., of the base pairs that match between the read and the contig, 97% are identical). This value is a good default for short read Illumina data, however for certain long read technologies, the error rates in the reads can be much higher.
+For example, older Oxford Nanopore chemistries can have error rates approaching
+15% - 20%.
+
+If you are having trouble with the coverage estimation steps (for example, the output depths for each bin are all at or near zero), it may be worth manually adjusting this parameter, if it is appropriate for your data.
+You can do this by adjusting the `--longread_percentidentity` and `--shortread_percentidentity` parameters for long reads and short reads, respectively.
+For older ONT data, you may wish to look at values of around 85% to improve coverage estimation.
+
 ## A note on bin refinement
 
 ### Error Reporting

nextflow.config

@@ -506,7 +506,7 @@ manifest {
     mainScript      = 'main.nf'
     defaultBranch   = 'main'
     nextflowVersion = '!>=25.04.2'
-    version         = '5.0.0'
+    version         = '5.1.0dev'
     doi             = '10.1093/nargab/lqac007'
 }
 

ro-crate-metadata.json

@@ -135,7 +135,7 @@
                     "pandas": "1.1.5"
                 },
                 "Workflow": {
-                    "nf-core/mag": "v5.0.0"
+                    "nf-core/mag": "v5.1.0dev"
                 }
             }
         ],

tests/default.nf.test.snap

@@ -97,7 +97,7 @@
                     "trimmomatic": 0.39
                 },
                 "Workflow": {
-                    "nf-core/mag": "v5.0.0"
+                    "nf-core/mag": "v5.1.0dev"
                 },
                 "r-base": "4.1.3",
                 "r-tidyverse": "1.3.1"

tests/test_alternatives.nf.test.snap

@@ -106,7 +106,7 @@
                     "pandas": "1.1.5"
                 },
                 "Workflow": {
-                    "nf-core/mag": "v5.0.0"
+                    "nf-core/mag": "v5.1.0dev"
                 }
             }
         ],