teton

Tags: metagenomics classification kraken2 bracken abundance profiling named-workflow

Taxonomic classification and abundance profiling of metagenomic reads.

This workflow performs metagenomic classification using Kraken2 and Bracken, with optional host read removal using SRA Scrubber. It processes metagenomic sequencing reads to estimate bacterial genome sizes and separate bacterial from non-bacterial organisms.

Usage

teton CLI:

teton \
  --input samples.csv \
  --outdir results/

Nextflow:

nextflow run bactopia/bactopia/workflows/teton/main.nf \
  --input samples.csv \
  --outdir results/

Outputs

Expected Output Files

<BACTOPIA_DIR>
├── <SAMPLE_NAME>
│   ├── teton-<TIMESTAMP>
│   │   ├── main
│   │   │   └── gather
│   │   │       ├── <SAMPLE_NAME>-meta.tsv
│   │   │       └── logs
│   │   │           ├── nf.command.{begin,err,log,out,run,sh,trace}
│   │   │           └── versions.yml
│   │   ├── teton-prepare
│   │   │   ├── <SAMPLE_NAME>-sizemeup.txt
│   │   │   ├── <SAMPLE_NAME>.bacteria.tsv
│   │   │   ├── <SAMPLE_NAME>.nonbacteria.tsv
│   │   │   └── logs
│   │   │       ├── nf.command.{begin,err,log,out,run,sh,trace}
│   │   │       └── versions.yml
│   │   └── tools
│   │       └── bracken
│   │           ├── <SAMPLE_NAME>.bracken.abundances.txt
│   │           ├── <SAMPLE_NAME>.bracken.adjusted.abundances.txt
│   │           ├── <SAMPLE_NAME>.bracken.classification.txt
│   │           ├── <SAMPLE_NAME>.bracken.krona.html
│   │           ├── <SAMPLE_NAME>.bracken.report.txt
│   │           ├── <SAMPLE_NAME>.bracken.tsv
│   │           ├── <SAMPLE_NAME>.kraken2.krona.html
│   │           ├── <SAMPLE_NAME>.kraken2.report.txt
│   │           └── logs
│   │               ├── nf.command.{begin,err,log,out,run,sh,trace}
│   │               └── versions.yml
│   └── tools
│       └── nohuman
│           ├── <SAMPLE_NAME>.scrub.report.tsv
│           ├── <SAMPLE_NAME>_R1.scrubbed.fastq.gz
│           ├── <SAMPLE_NAME>_R2.scrubbed.fastq.gz
│           └── logs
│               ├── nf.command.{begin,err,log,out,run,sh,trace}
│               └── versions.yml
├── bactopia-runs
│   └── teton-<TIMESTAMP>
│       ├── merged-results
│       │   ├── bracken-adjusted.tsv
│       │   ├── bracken-species-abundance.tsv
│       │   ├── logs
│       │   │   ├── bracken-adjusted-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── bracken-species-abundance-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── meta-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── scrubber-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── sizemeup-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── teton-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   ├── teton-prepare-concat
│       │   │   │   ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │   │   └── versions.yml
│       │   │   └── teton-prepare-nonbacteria-concat
│       │   │       ├── nf.command.{begin,err,log,out,run,sh,trace}
│       │   │       └── versions.yml
│       │   ├── meta.tsv
│       │   ├── scrubber.tsv
│       │   ├── sizemeup.tsv
│       │   ├── teton-prepare-nonbacteria.tsv
│       │   ├── teton-prepare.tsv
│       │   └── teton.tsv
│       └── nf-reports
│           ├── teton-dag.dot
│           ├── teton-report.html
│           └── teton-timeline.html
└── merged-results
    ├── <SAMPLE_NAME>.tsv
    └── logs
        └── <SAMPLE_NAME>-join
            ├── nf.command.{begin,err,log,out,run,sh,trace}
            └── versions.yml

Per-Sample Results

File	Description
bacteria.tsv	Per-sample TSV files containing bacterial organisms and their properties
nonbacteria.tsv	Per-sample TSV files containing non-bacterial organisms
sizemeup.tsv	Per-sample TSV files with genome size estimates

Merged Results

File	Description
merged-bacteria.tsv	Consolidated TSV file of all bacterial organisms across samples
merged-nonbacteria.tsv	Consolidated TSV file of all non-bacterial organisms across samples
merged-sizemeup.tsv	Consolidated TSV file of genome size estimates across samples
report.tsv	Joined TSV file combining scrubber and classification results

Audit Trail

Below are files that can assist you in understanding which parameters and program versions were used.

Logs

Each process that is executed will have a folder named logs. In this folder are helpful files for you to review if the need ever arises.

Extension	Description
.begin	An empty file used to designate the process started
.err	Contains STDERR outputs from the process
.log	Contains both STDERR and STDOUT outputs from the process
.out	Contains STDOUT outputs from the process
.run	The script Nextflow uses to stage/unstage files and queue processes based on given profile
.sh	The script executed by bash for the process
.trace	The Nextflow trace report for the process
versions.yml	A YAML formatted file with program versions

Nextflow Reports

These Nextflow reports provide great a great summary of your run. These can be used to optimize resource usage and estimate expected costs if using cloud platforms.

Filename	Description
teton-dag.dot	The Nextflow DAG visualization
teton-report.html	The Nextflow Execution Report
teton-timeline.html	The Nextflow Timeline Report
teton-trace.txt	The Nextflow Trace report

Parameters

Required Parameters

The following parameters are how you will provide either local or remote samples to be processed by Bactopia.

Parameter	Type	Default	Description
--samples	string		A FOFN (via bactopia prepare) with sample names and paths to FASTQ/FASTAs to process
--r1	string		First set of compressed (gzip) Illumina paired-end FASTQ reads (requires --r2 and --sample)
--r2	string		Second set of compressed (gzip) Illumina paired-end FASTQ reads (requires --r1 and --sample)
--se	string		Compressed (gzip) Illumina single-end FASTQ reads (requires --sample)
--ont	string		Compressed (gzip) Oxford Nanopore FASTQ reads (requires --sample)
--hybrid	boolean	false	Create hybrid assembly using Unicycler. (requires --r1, --r2, --ont and --sample)
--short_polish	boolean	false	Create hybrid assembly from long-read assembly and short read polishing. (requires --r1, --r2, --ont and --sample)
--sample	string		Sample name to use for the input sequences
--accessions	string		A file containing ENA/SRA Experiment accessions or NCBI Assembly accessions to processed
--accession	string		Sample name to use for the input sequences
--assembly	string		A assembled genome in compressed FASTA format. (requires --sample)
--check_samples	boolean	false	Validate the input FOFN provided by --samples

Dataset Parameters

Define where the pipeline should find input data and save output data.

Parameter	Type	Default	Description
--species	string		Name of species for species-specific dataset to use
--ask_merlin	boolean		Ask Merlin to execute species specific Bactopia tools based on Mash distances
--coverage	integer	100	Reduce samples to a given coverage, requires a genome size
--genome_size	integer	0	Expected genome size (bp) for all samples, required for read error correction and read subsampling
--use_bakta	boolean		Use Bakta for annotation, instead of Prokka

Optional Parameters

These optional parameters can be useful in certain settings.

Parameter	Type	Default	Description
--outdir	string	bactopia	Base directory to write results to

Nextflow Profile Parameters

Parameters to fine-tune your Nextflow setup.

Parameter	Type	Default	Description
--datasets_cache	string	<HOME>/.bactopia/datasets	Directory where downloaded datasets should be stored.

Helpful Parameters

Uncommonly used parameters that might be useful.

Parameter	Type	Default	Description
--wf	string	bactopia	Specify which workflow or Bactopia Tool to execute
--list_wfs	boolean		List the available workflows and Bactopia Tools to use with '--wf'
--help_all	boolean		An alias for --help --show_hidden_params
--version	boolean		Display version text.

Composition

This workflow uses the following subworkflows:

• bactopia_gather - Search, validate, gather, and standardize input samples.
• teton - Perform taxonomic classification and estimate bacterial genome sizes.

Citations

If you use this in your analysis, please cite the following.

• Bactopia
  Petit III RA, Read TD Bactopia - a flexible pipeline for complete analysis of bacterial genomes. mSystems 5 (2020)

• Bracken
  Lu J, Breitwieser FP, Thielen P, and Salzberg SL Bracken: estimating species abundance in metagenomics data. PeerJ Computer Science, 3, e104. (2017)

• Kraken2
  Wood DE, Lu J, Langmead B Improved metagenomic analysis with Kraken 2. Genome Biology, 20(1), 257. (2019)

• SRA Human Scrubber
  Katz KS, Shutov O, Lapoint R, Kimelman M, Brister JR, and O'Sullivan C STAT: a fast, scalable, MinHash-based k-mer tool to assess Sequence Read Archive next-generation sequence submissions. Genome Biology, 22(1), 270 (2021)

Source

View source on GitHub