name: qc
description: Quality control of Illumina and ONT reads
icon: false
keywords:
  - quality control
  - qc
modules:
  - qc
input:
  - meta:
    type: map
    description: |
      Groovy Map containing sample information
      e.g. [ id:'test', single_end:false ]
output:
  - meta:
      type: map
      description: |
        Groovy Map containing sample information
        e.g. [ id:'test', single_end:false ]
  - versions:
      type: file
      description: File containing software versions
      pattern: "versions.yml"
docs:
  meta:
    title: qc
    description: >
      A Bactopia Tool which uses a variety of tools to perform quality control on Illumina and
      Oxford Nanopore reads.
  introduction: |
      The `qc` module uses  a variety of tools to perform quality control on Illumina and
      Oxford Nanopore reads. The tools used are:

      | Tool | Technology | Description |
      |------|------------|-------------|
      | [bbtools](https://jgi.doe.gov/data-and-tools/bbtools/) | Illumina | A suite of tools for manipulating reads |
      | [fastp](https://github.com/OpenGene/fastp) | Illumina | A tool designed to provide fast all-in-one preprocessing for FastQ files |
      | [fastqc](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/) | Illumina | A quality control tool for high throughput sequence data |
      | [fastq_scan](https://github.com/rpetit3/fastq-scan) | Nanopore | A tool for quickly scanning FASTQ files |
      | [lighter](https://github.com/mourisl/Lighter) | Illumina | A tool for correcting sequencing errors in Illumina reads |
      | [NanoPlot](https://github.com/wdecoster/NanoPlot) | Nanopore | A tool for plotting long read sequencing data |
      | [nanoq](https://github.com/esteinig/nanoq) | Nanopore | A tool for calculating quality metrics for Oxford Nanopore reads |
      | [porechop](https://github.com/rrwick/Porechop) | Nanopore | A tool for removing adapters from Oxford Nanopore reads |
      | [rasusa](https://github.com/mbhall88/rasusa) | Nanopore | Randomly subsample sequencing reads to a specified coverage |

      Similar to the `gather` step, the `qc` step will also stop samples that fail to meet
      basic QC checks from continuing downstream.
  output:
    tree: |
      <BACTOPIA_DIR>
      ├── <SAMPLE_NAME>
      │   └── main
      │       └── qc
      │           ├── extra
      │           ├── logs
      │           │   ├── nf-qc.{begin,err,log,out,run,sh,trace}
      │           │   ├── output-fastp.log
      │           │   └── versions.yml
      │           ├── <SAMPLE_NAME>-low-read-count-error.txt
      │           ├── <SAMPLE_NAME>-low-sequence-coverage-error.txt
      │           ├── <SAMPLE_NAME>-low-sequence-depth-error.txt
      │           ├── <SAMPLE_NAME>{|_R1|_R2}.error-fastq.gz
      │           ├── <SAMPLE_NAME>{|_R1|_R2}.fastq.gz
      │           └── summary
      │               ├── <SAMPLE_NAME>.fastp.{html|json}
      │               ├── <SAMPLE_NAME>{|_R1|_R2}-{final|original}.json
      │               └── <SAMPLE_NAME>{|_R1|_R2}-{final|original}_fastqc.{html|zip}
      │               └── <SAMPLE_NAME>{|_R1|_R2}-{final|original}_NanoPlot-report.html
      │               └── <SAMPLE_NAME>{|_R1|_R2}-{final|original}_NanoPlot.tar.gz
      └── bactopia-runs
          └── bactopia-<TIMESTAMP>
              └── nf-reports
                  ├── bactopia-dag.dot
                  ├── bactopia-report.html
                  ├── bactopia-timeline.html
                  └── bactopia-trace.txt
    add_note: false
    folders:
      - name: Quality Control
        description: |
          Below is a description of the _per-sample_ results from `qc` subworkflow.
        table:
          - id: <SAMPLE_NAME>.fastq.gz
            description: A gzipped FASTQ file containing the cleaned Illumina single-end, or Oxford Nanopore reads
          - id: <SAMPLE_NAME>_R{1\|2}.fastq.gz
            description: A gzipped FASTQ file containing the cleaned Illumina paired-end reads
          - id: <SAMPLE_NAME>-{final\|original}.json
            description: A JSON file containing the QC results generated by [fastq-scan](https://github.com/rpetit3/fastq-scan)
          - id: <SAMPLE_NAME>-{final\|original}_fastqc.html
            description: (Illumina Only) A HTML report of the QC results generated by [fastqc](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/)
          - id: <SAMPLE_NAME>-{final\|original}_fastqc.zip
            description: (Illumina Only) A zip file containing the complete set of [fastqc](https://www.bioinformatics.babraham.ac.uk/projects/fastqc/) results
          - id: <SAMPLE_NAME>-{final\|original}_fastp.json
            description: (Illumina Only) A JSON file containing the QC results generated by [fastp](https://github.com/OpenGene/fastp)
          - id: <SAMPLE_NAME>-{final\|original}_fastp.html
            description: (Illumina Only) A HTML report of the QC results generated by [fastp](https://github.com/OpenGene/fastp)
          - id: <SAMPLE_NAME>-{final\|original}_NanoPlot-report.html
            description: (ONT Only) A HTML report of the QC results generated by [NanoPlot](https://github.com/wdecoster/NanoPlot)
          - id: <SAMPLE_NAME>-{final\|original}_NanoPlot.tar.gz
            description: (ONT Only) A tarball containing the complete set of [NanoPlot](https://github.com/wdecoster/NanoPlot) results
      - name: Failed Quality Checks
        description: |
          Built into Bactopia are few basic quality checks to help prevent downstream failures.
          If a sample fails one of these checks, it will be excluded from further analysis. By
          excluding these samples, complete pipeline failures are prevented.
        include_error_note: true
        is_extensions: true
        table:
          - id: .error-fastq.gz
            description: A gzipped FASTQ file of Illumina Single-End or Oxford Nanopore reads that failed QC
          - id: _R{1\|2}.error-fastq.gz
            description: A gzipped FASTQ file of Illumina Single-End or Oxford Nanopore reads that failed QC
          - id: -low-read-count-error.txt
            description: Sample failed read count checks and excluded from further analysis
          - id: -low-sequence-coverage-error.txt
            description: Sample failed sequenced coverage checks and excluded from further analysis
          - id: -low-sequence-depth-error.txt
            description: Sample failed sequenced basepair checks and excluded from further analysis
        note: |
          ??? warning "Example Error: After QC, too few reads remain"
              If after cleaning reads, a sample has less than the minimum required reads, the
              sample will be excluded from further analysis. You can adjust this minimum read
              count using the `--min_reads` parameter.

              __Example Text from <SAMPLE_NAME>-low-read-count-error.txt__  
              _<SAMPLE_NAME> FASTQ(s) contain `X` total reads. This does not exceed the required
              minimum `Y` read count. Further analysis is discontinued._

          ??? warning "Example Error: After QC, too little sequence coverage remains"
              If after cleaning reads, a sample has failed to meet the minimum sequence 
              coverage required, the sample will be excluded from further analysis. You can
              adjust this minimum read count using the `--min_coverage` parameter.

              __Note:__ This check is only performed when a genome size is available.

              __Example Text from <SAMPLE_NAME>-low-sequence-coverage-error.txt__  
              _After QC, <SAMPLE_NAME> FASTQ(s) contain `X` total basepairs. This does not
              exceed the required minimum `Y` bp (`Z`x coverage). Further analysis is
              discontinued._

          ??? warning "Example Error: After QC, too little sequenced basepairs remain"
              If after cleaning reads, a sample has failed to meet the minimum number of
              sequenced basepairs, the sample will be excluded from further analysis. You can
              adjust this minimum read count using the `--min_basepairs` parameter.

              __Example Text from <SAMPLE_NAME>-low-sequence-depth-error.txt__  
              _<SAMPLE_NAME> FASTQ(s) contain `X` total basepairs. This does not exceed the
              required minimum `Y` bp. Further analysis is discontinued._
  citations:
    - bbtools
    - fastp
    - fastqc
    - fastq_scan
    - lighter
    - nanoplot
    - nanoq
    - pigz
    - porechop
    - rasusa
