Skip to content

Overview

MetaFlux is a Snakemake workflow that takes raw paired-end short reads through to a taxonomically annotated abundance table. It covers two kinds of study — marker-gene metabarcoding and shotgun metagenomics — and a single key in the config file, mode, decides which of the two runs. This site documents version v2.6.1.

MetaFlux belongs to the BioFlux family of pipelines.

The workflow at a glance

Detailed metro map of the MetaFlux workflow, with six amplicon marker lines and two shotgun profiler lines. Runs begin at the config and start-up checks, then follow the stages of their mode to read tracking and MultiQC. Dashed branches show the optional 16S phylogeny and per-taxon reads; hollow stops are steps you can switch on or off in the config. Detailed metro map of the MetaFlux workflow, with six amplicon marker lines and two shotgun profiler lines. Runs begin at the config and start-up checks, then follow the stages of their mode to read tracking and MultiQC. Dashed branches show the optional 16S phylogeny and per-taxon reads; hollow stops are steps you can switch on or off in the config.

Each solid line represents one amplicon marker or shotgun profiler. Both modes end with read tracking and a MultiQC report. COI is classified with SINTAX against MIDORI2 and is then checked by two screens, enabled by default, before the taxon filter. Dashed branches mark the optional 16S phylogeny and per-taxon read extraction. Hollow markers indicate steps that can be switched on or off in the config. Select the map to open it larger; select it again to see it at full size, and close it with x or Esc.

The two modes

amplicon shotgun
Input PCR products from one marker gene untargeted whole-genome sequencing reads
Core tools DADA2 Kraken2 + Bracken, or sylph (shotgun.profiler)
Markers 16S rRNA, ITS, 18S rRNA, gyrB, rpoB, COI not applicable
Main steps PhiX removal, primer trimming, exact ASV inference, optional marker-region extraction, length filtering, taxonomy decontamination, quality trimming, read classification, abundance re-estimation, OTU-table construction
Reference data SILVA (16S), UNITE (ITS), PR2 (18S), DD7RZ8 (gyrB), FROGS (rpoB), MIDORI2 and a set of bacterial COI homologues (COI) — fetched automatically on first use a Kraken2 database (profiler: kraken2), sylph databases and their lineage tables (sylph), or both (both), supplied by the user
Final table 06.taxonomy/asv_table.txt 03.abundance/otu_table.tsv (Kraken2) or 03.abundance/sylph_table.tsv (sylph)

Amplicon mode resolves sequences exactly rather than clustering them at an arbitrary similarity threshold: DADA2 infers amplicon sequence variants (ASVs), which are then length-filtered and classified against the reference database that matches the marker. See the amplicon overview and the per-marker pages.

Shotgun mode skips amplification altogether and assigns whole-genome reads directly against a Kraken2 index, with Bracken re-estimating abundances at the chosen taxonomic level. With shotgun.profiler: sylph, sylph profiles the same reads against sketches of reference genomes instead, and with both the two run side by side. See the shotgun overview and sylph.

Launching a run

Both modes are launched the same way, from the repository root:

snakemake --sdm conda --cores 16 --configfile config/config.yaml

--sdm conda (short for --software-deployment-method) tells Snakemake to build each rule's own conda environment on first run, so only Snakemake itself (version 9 or newer) has to be installed by hand.

Everything else — mode, input and output paths, marker, primers, databases, per-rule CPU and memory — lives in config/config.yaml. Both modes finish by writing read-tracking statistics and a single MultiQC report under multiqc/multiqc_report.html, so a run can be checked end to end from one HTML file.

What has to be prepared in advance

Amplicon runs need only the primer FASTAs: the marker reference databases download themselves the first time they are needed and are cached under refdb/. Shotgun runs need their databases on disk before the first launch: a Kraken2 database with the default shotgun.profiler: kraken2, sylph databases and their lineage tables with sylph, and both with both. These are large and version-sensitive, so MetaFlux never fetches them automatically. See Installation, Reference databases and sylph.

Where to go next

Page Read it for
Installation cloning the repository, the Snakemake launcher environment, reference databases
Quick start the shortest path from a clone to a finished run
Choosing a mode which mode a given dataset belongs in, and what happens if the wrong one is set
Amplicon mode the DADA2 path step by step, marker by marker
Shotgun mode the Kraken2 + Bracken and sylph paths step by step
Configuration every config key, what consumes it, and its default
Output files what each output directory holds and which files are the deliverables
Running MetaFlux dry runs, resuming, cluster execution
Troubleshooting the failure modes that come up in practice, and how to get past them
Rationale why the workflow makes the choices it does
Citation and references how to cite MetaFlux and the tools it calls

MetaFlux is released under the MIT License. The tools it invokes carry their own licenses.