Skip to content

Choosing a mode

MetaFlux runs one of two pipelines. The choice follows from how the library was made.

  • amplicon — a marker gene was PCR-amplified with a specific primer pair, and those amplicons were sequenced. 16S rRNA for bacteria and archaea, ITS for fungi, 18S rRNA for eukaryotes, the protein-coding markers gyrB and rpoB for bacteria, or COI for animals.
  • shotgun — total DNA was fragmented and sequenced without any target-specific amplification, so the reads come from everywhere in every genome present.

If the library prep involved primers targeting a gene, it is amplicon data. If it did not, it is shotgun data.

What each mode does with the reads

amplicon shotgun
What was sequenced One marker region, PCR-amplified Whole DNA, no amplification
Core method DADA2 exact ASV inference Kraken2 classification + Bracken re-estimation, or sylph (shotgun.profiler)
Reference Marker database, fetched automatically (SILVA, UNITE, PR2, DD7RZ8, FROGS, MIDORI2 with the set of bacterial COI homologues) A Kraken2 index, sylph databases with their lineage tables, or both, supplied by the user
Primers Required — amplicon.primers.fwd / .rev Not used
Main result 06.taxonomy/asv_table.txt — ASVs × samples, with taxonomy 03.abundance/otu_table.tsv (Kraken2) or sylph_table.tsv (sylph) — taxa × samples, plus the BIOM version
Resolution Exact sequence variants of one gene Whatever the index supports, down to species with Bracken; genomes at about species level with sylph
Input naming {sample}_R1 / {sample}_R2 only {sample}_R1/_R2 or SRA-style {sample}_1/_2
Can fetch its own reads No Yes — from an NCBI BioProject accession

Both modes read the same input and output blocks, honour the same per-rule resources settings, and finish by writing a MultiQC report and a per-sample read-tracking table under out_dir.

What shotgun mode is for, and when to use another profiler

MetaFlux's shotgun path is aimed at environmental communities — soil, sediment, water, enrichment cultures — where no curated marker set covers the habitat and a k-mer classifier with a broad database is the practical option.

For host-associated and food samples, a marker-gene profiler such as MetaPhlAn will usually be more precise, and MetaFlux does not try to replace it. On the ZymoBIOMICS Gut Microbiome Standard (D6331), SRA run SRR29240428 (BioProject PRJNA1118346; see Benchmark data), MetaPhlAn 4 with the database mpa_vJan26_CHOCOPhlAnSGB_202605 reported 14 of the 17 species and no false ones (F1 0.90). MetaFlux at its default settings with PlusPF k2_pluspf_20260626 reported the same 14 species and five false ones, all of them Fusobacterium species related to the mock's F. animalis (F1 0.78). It also reported Homo sapiens, from human DNA in the sample, which MetaPhlAn cannot report (its database holds microbial markers only); it is not scored.

On environmental samples MetaPhlAn classifies far fewer reads. On the four metagenomes of BioProject PRJNA1477390 (runs SRR39106521–SRR39106524; see Shotgun test dataset), microbial consortia enriched on naproxen from wastewater treatment plants, the same MetaPhlAn database left 44–75 % of reads unclassified, against 6.6 % on the gut mock.

The two tools also make different kinds of error. A marker-gene profiler tends to miss taxa; a k-mer classifier tends to report taxa that are not there, which the confidence and threshold settings are meant to limit. (On the D6331 mock both missed the same three rarest members, Salmonella enterica, Enterococcus faecalis and Clostridium perfringens, at 0.0001–0.01 % of the DNA, so this mock shows no difference in missed taxa.) For describing a community, missed taxa do less harm than false ones. For screening, such as testing whether a particular pathogen is present, they matter more: a taxon missing from a marker-gene profile may still be in the sample.

Both tools are limited by their reference database: an organism that is not in it cannot be found with any setting. In the 21 CAMI II rhizosphere samples only about half of the gold-standard species are in PlusPF (k2_pluspf_20260626: 54 % of the 307 species pooled, 42 % per sample on average).

The switch

One key, at the top of config/config.yaml:

mode: amplicon          # amplicon | shotgun

That key decides which set of rules is loaded at all: the Snakefile includes workflow/rules/amplicon/*.smk or workflow/rules/shotgun/*.smk accordingly, plus the shared rules in both cases. It can also be overridden for a single run without touching the file:

snakemake --sdm conda --cores 16 --config mode=shotgun

The other mode's settings are ignored

config/config.yaml carries both halves at all times, and each section is labelled [shared], [amplicon] or [shotgun]. The half that does not belong to the selected mode is simply never read: an amplicon: block full of primer paths and DADA2 parameters has no effect on a shotgun run, and a shotgun: block full of Kraken2 and Bracken parameters — plus the references.kraken_db path, which sits in the shared references: block — has no effect on an amplicon run.

There is no need to comment anything out. One config file can hold a working setup for both and be switched with mode alone.

The one place this is not silent is primers. Shotgun mode prints a note if amplicon.primers.fwd or .rev carries any value at all, then continues:

[MetaFlux] warning: mode=shotgun but amplicon.primers fields are set — they will be ignored

The shipped template fills both fields with placeholder paths, and config/config.yaml is always loaded as a base layer under the --configfile given on the command line, so the note appears on most shotgun runs even when the run config never mentions primers. It can be ignored, or silenced by setting both to null in the run config.

The mode must match the data

Nothing is auto-detected. Both modes accept files named {sample}_R1 / {sample}_R2, so pointing shotgun mode at amplicon reads — or the reverse — does not necessarily fail. It can run to the end and produce a table that looks normal but is meaningless. Set mode to match how the library was made.

What to prepare before running

Amplicon needs, on top of the shared input and output paths:

  • amplicon.type — which marker (16S, ITS, 18S, gyrB, rpoB, COI). This selects the reference databases, whether a region extractor runs, and which taxonomy methods are available.
  • amplicon.primers.fwd and .rev — the primer sequences as FASTA files. Both must exist or the run stops immediately. They are used twice: Cutadapt trims them off the reads, and — when expected_length is left at auto (the default), for markers whose reference is a full-length gene — the same pair is run in silico against that reference to work out how long the amplicon should be.
  • amplicon.taxonomy.filter — the keep/discard lists appropriate to the marker. The lists have no built-in default, so unset lists remove nothing. For 16S the organelle filter is on by default and still removes what Metaxa2 calls mitochondria or chloroplast.

Reference databases come down automatically on first use; nothing else to install. Per-marker detail is in the markers section.

Shotgun needs:

  • With shotgun.profiler: kraken2 (the default) or both: references.kraken_db, the directory of a Kraken2 index. It is not fetched automatically, and the run stops at once if the path does not exist. See reference databases.
  • With sylph or both: references.sylph_databases, the sylph database files, and the lineage tables that name their genomes (usually sylph-tax's, in references.sylph_taxonomy_dir). They are not fetched either, and are checked before the first job starts. A sylph-only run needs no Kraken2 database. See sylph.
  • Optionally shotgun.decontamination.host_genomes — one or more host references for read removal, e.g. a masked human genome. See decontamination.
  • Optionally input.bioproject instead of local FASTQs — MetaFlux resolves the PAIRED runs of an NCBI BioProject accession and downloads them into fastq_dir.

Next