name: snippy
description: Rapid variant calling from Illumina sequence reads with optional core-SNP phylogeny
icon: false
keywords:
  - alignment
  - core-snp
  - phylogeny
  - variants
modules:
  - snippy_run
  - snippy_core
  - gubbins
  - iqtree
  - snpdists
input:
  - meta:
    type: map
    description: |
      Groovy Map containing sample information
      e.g. [ id:'test', single_end:false ]
  - reads:
      type: file
      description: |
        List of input FastQ files of size 1 and 2 for single-end and paired-end data,
        respectively.
      pattern: "*.fastq.gz"
  - reference:
      type: file
      description: Reference genome in GenBank format
      pattern: "*.{gbk,gbk.gz}"
output:
  - versions:
      type: file
      description: File containing software versions
      pattern: "versions.yml"
docs:
  meta:
    title: snippy
    description: >-
      A Bactopia Tool which uses Snippy to call SNPs and InDels against a reference and
      create a core-SNP phylogeny using IQ-Tree and Gubbins.
  introduction: |
    The `snippy` subworkflow allows you to call SNPs and InDels against a reference with
    [Snippy](https://github.com/tseemann/snippy). With the called SNPs/InDels, [snippy-core](https://github.com/tseemann/snippy#core-snp-phylogeny) 
    a core-SNP alignment is created.

    A phylogeny, based on the core-SNP alignment, will be created by [IQ-Tree](https://github.com/Cibiv/IQ-TREE). Optionally
    a recombination-masked core-SNP alignment can be created with [Gubbins](https://github.com/nickjcroucher/gubbins).

    Finally, the pair-wise SNP distance for each sample is also calculated with 
    [snp-dists](https://github.com/tseemann/snp-dists).
  output:
    tree: |
      <BACTOPIA_DIR>
      ├── <SAMPLE_NAME>
      │   └── tools
      │       └── snippy
      │           └── <REFERENCE_NAME>
      │               ├── logs
      │               │   ├── nf-snippy.{begin,err,log,out,run,sh,trace}
      │               │   ├── <SAMPLE_NAME>.log
      │               │   └── versions.yml
      │               ├── <SAMPLE_NAME>.aligned.fa.gz
      │               ├── <SAMPLE_NAME>.annotated.vcf.gz
      │               ├── <SAMPLE_NAME>.bam
      │               ├── <SAMPLE_NAME>.bam.bai
      │               ├── <SAMPLE_NAME>.bed.gz
      │               ├── <SAMPLE_NAME>.consensus.fa.gz
      │               ├── <SAMPLE_NAME>.consensus.subs.fa.gz
      │               ├── <SAMPLE_NAME>.consensus.subs.masked.fa.gz
      │               ├── <SAMPLE_NAME>.coverage.txt.gz
      │               ├── <SAMPLE_NAME>.csv.gz
      │               ├── <SAMPLE_NAME>.filt.vcf.gz
      │               ├── <SAMPLE_NAME>.gff.gz
      │               ├── <SAMPLE_NAME>.html
      │               ├── <SAMPLE_NAME>.raw.vcf.gz
      │               ├── <SAMPLE_NAME>.subs.vcf.gz
      │               ├── <SAMPLE_NAME>.tab
      │               ├── <SAMPLE_NAME>.txt
      │               └── <SAMPLE_NAME>.vcf.gz
      └── bactopia-runs
          └── snippy-<TIMESTAMP>
              ├── core-snp-clean.full.aln.gz
              ├── core-snp.full.aln.gz
              ├── gubbins
              │   ├── core-snp.branch_base_reconstruction.embl.gz
              │   ├── core-snp.filtered_polymorphic_sites.fasta.gz
              │   ├── core-snp.filtered_polymorphic_sites.phylip
              │   ├── core-snp.final_tree.tre
              │   ├── core-snp.node_labelled.final_tree.tre
              │   ├── core-snp.per_branch_statistics.csv
              │   ├── core-snp.recombination_predictions.embl.gz
              │   ├── core-snp.recombination_predictions.gff.gz
              │   ├── core-snp.summary_of_snp_distribution.vcf.gz
              │   └── logs
              │       ├── core-snp.log
              │       ├── nf-gubbins.{begin,err,log,out,run,sh,trace}
              │       └── versions.yml
              ├── iqtree
              │   ├── core-snp.alninfo
              │   ├── core-snp.bionj
              │   ├── core-snp.ckp.gz
              │   ├── core-snp.contree
              │   ├── core-snp.iqtree
              │   ├── core-snp.mldist
              │   ├── core-snp.splits.nex
              │   ├── core-snp.treefile
              │   ├── core-snp.ufboot
              │   └── logs
              │       ├── core-snp.log
              │       ├── nf-iqtree.{begin,err,log,out,run,sh,trace}
              │       └── versions.yml
              ├── nf-reports
              │   ├── snippy-dag.dot
              │   ├── snippy-report.html
              │   ├── snippy-timeline.html
              │   └── snippy-trace.txt
              ├── snippy-core
              │   ├── core-snp.aln.gz
              │   ├── core-snp.tab.gz
              │   ├── core-snp.txt
              │   ├── core-snp.vcf.gz
              │   └── logs
              │       ├── nf-snippy-core.{begin,err,log,out,run,sh,trace}
              │       └── versions.yml
              └── snpdists
                  ├── core-snp.distance.tsv
                  └── logs
                      ├── nf-snpdists.{begin,err,log,out,run,sh,trace}
                      └── versions.yml
    add_note: false
    folders:
      - name: Main Results
        description: |
          Below are the main results from the `snippy` Bactopia Tool.
        table:
          - id: core-snp-clean.full.aln.gz
            description: Same as `core-snp.full.aln.gz` with unusual characters replaced with `N`
          - id: core-snp.distance.tsv
            description: Core genome Pair-wise SNP distance for each sample
          - id: core-snp.full.aln.gz
            description: A whole genome SNP alignment (includes invariant sites)
          - id: core-genome.iqtree
            description: Full result of the IQ-TREE core genome phylogeny
          - id: core-genome.masked.aln.gz
            description: A core-SNP alignment with the recombination masked
      - name: Gubbins
        description: |
          Below is a description of the [Gubbins](https://github.com/nickjcroucher/gubbins) results. For more details about
          Gubbins outputs see [Gubbins - Outputs](https://github.com/nickjcroucher/gubbins/blob/master/docs/gubbins_manual.md#output-files).
        table:
          - id: core-snp.branch_base_reconstruction.embl.gz
            description: Base substitution reconstruction in EMBL format
          - id: core-snp.filtered_polymorphic_sites.fasta.gz
            description: FASTA format alignment of filtered polymorphic sites
          - id: core-snp.filtered_polymorphic_sites.phylip
            description: Phylip format alignment of filtered polymorphic sites
          - id: core-snp.final_tree.tre
            description: Final phylogeny in Newick format (_branch lengths are in point mutations_)
          - id: core-snp.node_labelled.final_tree.tre
            description: Final phylogeny in Newick format but with internal node labels
          - id: core-snp.per_branch_statistics.csv
            description: Per-branch reporting of the base substitutions inside and outside recombination events
          - id: core-snp.recombination_predictions.embl.gz
            description: Recombination predictions in EMBL file format
          - id: core-snp.recombination_predictions.gff.gz
            description: Recombination predictions in GFF file format
          - id: core-snp.summary_of_snp_distribution.vcf.gz
            description: VCF file summarising the distribution of point mutations                           |
      - name: IQ-TREE
        description: |
          Below is a description of the [IQ-TREE](http://www.iqtree.org/) results. If ClonalFrameML is executed, a fast tree
          is created and given the prefix `start-tree`, the final tree has the prefix `core-genome`. For more details about
          IQ-TREE outputs see [IQ-TREE - Outputs](https://github.com/Cibiv/IQ-TREE/wiki/Web-Server-Tutorial#analysis-results).
        table:
          - id: core-snp.alninfo
            description: Alignment site statistics
          - id: core-snp.bionj
            description: A neighbor joining tree produced by BIONJ
          - id: core-snp.ckp.gz
            description: IQ-TREE writes a checkpoint file
          - id: core-snp.contree
            description: Consensus tree with assigned branch supports where branch lengths are optimized on the original alignment; printed if Ultrafast Bootstrap is selected
          - id: core-snp.mldist
            description: Contains the likelihood distances
          - id: core-snp.splits.nex
            description: Support values in percentage for all splits (bipartitions), computed as the occurrence frequencies in the bootstrap trees
          - id: core-snp.treefile
            description: Maximum likelihood tree in NEWICK format, can be visualized with treeviewer programs
          - id: core-snp.ufboot
            description: Trees created during the bootstrap steps
      - name: Snippy
        description: |
          Below is a description of the per-sample [Snippy](https://github.com/tseemann/snippy) results. For more details about
          Snippy outputs see [Snippy - Outputs](https://github.com/tseemann/snippy#output-files).
        table:
          - id: <SAMPLE_NAME>.aligned.fa.gz
            description: A version of the reference but with `-` at position with `depth=0` and `N` for `0 < depth < --mincov` (**does not have variants**)
          - id: <SAMPLE_NAME>.annotated.vcf.gz
            description: The final variant calls with additional annotations from Reference genome's GenBank file
          - id: <SAMPLE_NAME>.bam
            description: The alignments in [BAM](http://en.wikipedia.org/wiki/SAMtools) format. Includes unmapped, multimapped reads. Excludes duplicates
          - id: <SAMPLE_NAME>.bam.bai
            description: Index for the .bam file
          - id: <SAMPLE_NAME>.bed.gz
            description: The variants in [BED](http://genome.ucsc.edu/FAQ/FAQformat.html#format1) format
          - id: <SAMPLE_NAME>.consensus.fa.gz
            description: A version of the reference genome with *all* variants instantiated
          - id: <SAMPLE_NAME>.consensus.subs.fa.gz
            description: A version of the reference genome with *only substitution* variants instantiated
          - id: <SAMPLE_NAME>.consensus.subs.masked.fa.gz
            description: A version of the reference genome with *only substitution* variants instantiated and low-coverage regions masked
          - id: <SAMPLE_NAME>.coverage.txt.gz
            description: The per-base coverage of each position in the reference genome
          - id: <SAMPLE_NAME>.csv.gz
            description: A [comma-separated](http://en.wikipedia.org/wiki/Comma-separated_values) version of the .tab file
          - id: <SAMPLE_NAME>.filt.vcf.gz
            description: The filtered variant calls from Freebayes
          - id: <SAMPLE_NAME>.gff.gz
            description: The variants in [GFF3](http://www.sequenceontology.org/gff3.shtml) format
          - id: <SAMPLE_NAME>.html
            description: A [HTML](http://en.wikipedia.org/wiki/HTML) version of the .tab file
          - id: <SAMPLE_NAME>.raw.vcf.gz
            description: The unfiltered variant calls from Freebayes
          - id: <SAMPLE_NAME>.subs.vcf.gz
            description: _Only substitution_ variants from the final annotated variants
          - id: <SAMPLE_NAME>.tab
            description: A simple [tab-separated](http://en.wikipedia.org/wiki/Tab-separated_values) summary of all the variants
          - id: <SAMPLE_NAME>.txt
            description: A summary of the Snippy run
          - id: <SAMPLE_NAME>.vcf.gz
            description: The final annotated variants in [VCF](http://en.wikipedia.org/wiki/Variant_Call_Format) format
      - name: Snippy-Core
        description: |
          Below is a description of the [Snippy-Core](https://github.com/tseemann/snippy) results. For more details about
          Snippy-Core outputs see [Snippy-Core - Outputs](https://github.com/tseemann/snippy#output-files-1).
        table:
          - id: core-snp.aln.gz
            description: A core SNP alignment in FASTA format
          - id: core-snp.tab.gz
            description: Tab-separated columnar list of core SNP sites with alleles but **NO** annotations
          - id: core-snp.txt
            description: Tab-separated columnar list of alignment/core-size statistics
          - id: core-snp.vcf.gz
            description: Multi-sample VCF file with genotype GT tags for all discovered alleles                                                                                                   | 
  citations:
    - gubbins
    - iqtree
    - iqtree_modelfinder
    - iqtree_ufboot
    - snippy
    - snpdists
