Merge pull request #762 from d4straub/output-docs-asv-post-processing

Update documentation: ASV post processing & parameters description

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Changed`
 
+- [#762](https://github.com/nf-core/ampliseq/pull/762) - Improved output documentation section "Optional ASV filtering" and parameter documentation
+
 ### `Fixed`
 
 ### `Dependencies`

docs/output.md

@@ -23,7 +23,7 @@ The pipeline is built using [Nextflow](https://www.nextflow.io/) and processes d
   - [Cutadapt](#cutadapt) - Primer trimming
   - [MultiQC](#multiqc) - Aggregate report describing results
 - [ASV inferrence with DADA2](#asv-inferrence-with-dada2) - Infer Amplicon Sequence Variants (ASVs)
-- [Optional ASV filtering](#optional-asv-filtering) - Filter ASVs to optimize downstream analysis
+- [Optional ASV post processing](#optional-asv-post-processing) - Filter ASVs to optimize downstream analysis
   - [VSEARCH cluster](#vsearch-cluster) - Centroid fasta file, filtered asv table, and stats
   - [Barrnap](#barrnap) - Predict ribosomal RNA sequences and optional filtering
   - [Length filter](#length-filter) - Optionally, ASV can be filtered by length thresholds
@@ -163,7 +163,9 @@ For binned quality scores in NovaSeq data, monotonicity in the fitted error mode
 
 </details>
 
-### Optional ASV filtering
+### Optional ASV post processing
+
+ASV post-processing takes place after DADA2's ASV computation (i.e. after chimera removal, for example table `ASV_tax.tsv`) but _before_ taxonomic classification. Post-processing will affect all downstream files. Clustering and filters are applied sequentially, in the same sequence as shown here. All filters are off by default and can be enabled by setting thresholds as detailed in the parameter documentation.
 
 #### VSEARCH cluster
 
@@ -184,7 +186,7 @@ This directory will hold the centroid fasta file, the filtered asv count table (
 
 Barrnap predicts the location of ribosomal RNA genes in genomes, here it can be used to discriminate rRNA sequences from potential contamination. It supports bacteria (5S,23S,16S), archaea (5S,5.8S,23S,16S), metazoan mitochondria (12S,16S) and eukaryotes (5S,5.8S,28S,18S).
 
-Optionally, ASV sequences can be filtered for rRNA sequences identified by Barrnap with `--filter_ssu` that can take a list of abbreviations of the above supported categories (kingdoms), e.g. `bac,arc,mito,euk`. This filtering takes place after DADA2's ASV computation (i.e. after chimera removal) but _before_ taxonomic classification (also applies to above mentioned taxonomic classification with DADA2, i.e. files `ASV_tax.tsv` & `ASV_tax_species.tsv`).
+Optionally, ASV sequences can be filtered for rRNA sequences identified by Barrnap with `--filter_ssu` that can take a list of abbreviations of the above supported categories (kingdoms), e.g. `bac,arc,mito,euk`.
 
 <details markdown="1">
 <summary>Output files</summary>
@@ -200,7 +202,7 @@ Optionally, ASV sequences can be filtered for rRNA sequences identified by Barrn
 
 #### Length filter
 
-Optionally, a length filter can be used to reduce potential contamination after ASV computation. For example with 515f and 806r primers the majority of 16S rRNA amplicon sequences should have a length of 253 bp and amplicons vary significantely are likely spurious.
+Optionally, a length filter can be used to reduce potential contamination after ASV computation. For example with 515f and 806r primers the majority of 16S rRNA amplicon sequences should have a length of 253 bp and amplicons that vary significantly are likely spurious.
 
 The minimum ASV length threshold can be set by `--min_len_asv` and the maximum length threshold with `--max_len_asv`. If no threshold is set, the filter (and output) is omitted.
 

nextflow_schema.json

@@ -150,6 +150,7 @@
         "primer_removal": {
             "title": "Primer removal",
             "type": "object",
+            "description": "Spurious sequences sometimes lack primer sequences and primers introduce errors that can be removed in that step",
             "default": "",
             "properties": {
                 "retain_untrimmed": {
@@ -188,7 +189,7 @@
         "read_trimming_and_quality_filtering": {
             "title": "Read trimming and quality filtering",
             "type": "object",
-            "description": "",
+            "description": "Read trimming and quality filtering is supposed to reduce spurious results and aid error correction",
             "default": "",
             "properties": {
                 "trunclenf": {
@@ -271,6 +272,7 @@
         "asv_post_processing": {
             "title": "ASV post processing",
             "type": "object",
+            "description": "ASV post-processing takes place after ASV computation but before taxonomic assignment, it will affect all downstream processes",
             "default": "",
             "properties": {
                 "vsearch_cluster": {
@@ -575,6 +577,7 @@
             "title": "ASV filtering",
             "type": "object",
             "default": "",
+            "description": "Filtering by taxonomy or abundance will affect all downstream analysis",
             "fa_icon": "fas fa-filter",
             "properties": {
                 "exclude_taxa": {
@@ -600,7 +603,7 @@
         "downstream_analysis": {
             "title": "Downstream analysis",
             "type": "object",
-            "description": "",
+            "description": "Metadata is used here to visualize data either for quality control or publication ready figures",
             "default": "",
             "fa_icon": "fas fa-bacteria",
             "properties": {
@@ -652,7 +655,7 @@
         "differential_abundance_analysis": {
             "title": "Differential abundance analysis",
             "type": "object",
-            "description": "",
+            "description": "Differential abundance analysis relies on provided metadata",
             "default": "",
             "fa_icon": "fas fa-bacteria",
             "properties": {
@@ -705,7 +708,7 @@
         "pipeline_report": {
             "title": "Pipeline summary report",
             "type": "object",
-            "description": "",
+            "description": "Customization of the pipeline report",
             "default": "",
             "properties": {
                 "report_template": {