nf-core/taxmarker

Edit

Introduction

nf-core/taxmarker is a re-implementation of the Sativa pipeline by Kozlov et al. [2016] that identifies taxonomically mislabelled sequences. It takes as input a sequences file (aligned or unaligned) and a file describing the proposed taxonomy of each sequence. Using evolutionary placement, it identifies sequences in the alignment that do not have a phylogenetic signal that corresponds to their taxonomies.

1. Resolve taxonomy: from --taxonomy if given, otherwise derived from --sequences record headers instead (GTDB-style: >id taxonomy;string); if both are present, the file wins, with a warning rather than silently ignoring the header text
2. Check that names in the two are consistent and do not contain problematic characters
3. If the sequences are unaligned, align them via hmmalign against an HMM profile (--hmm, --hmm_name); already-aligned input passes straight through, detected automatically – no separate mode-switch parameter needed
4. Filter out sequences too short/incomplete to place reliably, reporting them separately rather than silently dropping them: by non-gap proportion for already-aligned input (disable with --skip_gapfilter; tune with --min_nongap), or by HMM profile coverage for hmmalign-derived input (disable with --skip_profile_cover; tune with --min_profile_cover)
5. Optionally flag likely mislabels with raxtax: quickly self-classify the reference set against its own taxonomy and report sequences it’s already confident are mislabeled – a fast mislabel-detection method in its own right, which also prefilters the much more expensive phylogenetic-placement step below by skipping sequences it has already flagged (disable with --skip_raxtax; tune sensitivity with --raxtax_filter_rank)
6. Optionally perform phylogenetic placement (disable entirely with --skip_sativa, turning the pipeline into a taxonomy-resolution/alignment/prefilter QC tool – steps 1-5 above still run as configured), as the SATIVA subworkflow:
   1. Create a bifurcating phylogeny with branch-lengths corresponding to the alignment from the taxonomy tree induced by the taxonomy file (RAxML-NG)
   2. Perform a leave-one-out test, placing each sequence back into the phylogeny after removing it, and score each sequence’s placement against its declared taxonomy to flag likely mislabels (sativa-epang)
7. Optionally export ranked reference FASTA files for downstream classifiers – e.g. DADA2’s assignTaxonomy/addSpecies – subsetting sequences per taxon and prioritising type-strain sequences, then other isolates, then MAGs/SAGs
8. Summarise the run (MULTIQC)

Usage

First, prepare a sequences file and a taxonomy file:

      5     50
UnpCCeti   ?????????? ?????????? ?????????? ?????????? G??AGAGUUU
UnpSomer   ?????????? ?????????? ?????????? ?????????? ??AAGAGUUU
UpbRectu   ?????????? ?????????? ?????????? ?????NNNNN N?GAGAGUUU
UxjAloci   ?????????? ?????????? ?????????? ?????????? ?????????U
UyvCanif   ?????????? ?????????? ?????????? ?????????? ?????????C

The sequences file can be phylip, clustal or fasta formatted, aligned or not. Unaligned input is aligned automatically via hmmalign; pass --hmm (and --hmm_name, if that profile database holds more than one profile) to say which HMM profile to align against. The taxonomy file should contain the same sequence names as the sequences file, be tab-separated without a header:

UnpCCeti        Bacteria;Fusobacteria;Fusobacteriia;Fusobacteriales;Fusobacteriaceae;Cetobacterium;Cetobacterium ceti
UnpSomer        Bacteria;Fusobacteria;Fusobacteriia;Fusobacteriales;Fusobacteriaceae;Cetobacterium;Cetobacterium somerae
UpbRectu        Bacteria;Firmicutes;Clostridia;Clostridiales;Clostridiaceae;Clostridium;Clostridium rectum
UxjAloci        Bacteria;Firmicutes;Clostridia;Clostridiales;Peptostreptococcaceae;Filifactor;Filifactor alocis
UyvCanif        Bacteria;Fusobacteria;Fusobacteriia;Fusobacteriales;Fusobacteriaceae;Fusobacterium;Fusobacterium canifelinum

--taxonomy is optional: if it’s omitted, each --sequences FASTA record’s header must instead carry the taxonomy directly after its id, GTDB’s own single-file convention:

>UnpCCeti Bacteria;Fusobacteria;Fusobacteriia;Fusobacteriales;Fusobacteriaceae;Cetobacterium;Cetobacterium ceti

(Only possible for FASTA input, since phylip/clustal records have no room for it.) If both --taxonomy and embedded header text are present, the file wins, and a warning is logged rather than the header text being silently ignored.

(Sequence name characters other than letters, digits, _, ., -, | and / will be replaced by underscores.)

Now, you can run the pipeline using:

nextflow run nf-core/taxmarker \
   -profile <docker/singularity/.../institute> \
   --sequences sequences.phy \
   --taxonomy taxonomy.tsv \
   --outdir <OUTDIR>

For more details and further functionality, please refer to the usage documentation and the parameter documentation.

Pipeline output

To see the results of an example test run with a full size dataset refer to the results tab on the nf-core website pipeline page. For more details about the output files and reports, please refer to the output documentation.

Credits

The Sativa tool was originally written by Alexey Kozlov et al. (see citation below) and ported to Nextflow as nf-core/taxmarker by Daniel Lundin.

We thank the following people for their extensive assistance in the development of this pipeline:

Contributions and Support

If you would like to contribute to this pipeline, please see the contributing guidelines.

For further information or help, don’t hesitate to get in touch on the Slack #taxmarker channel (you can join with this invite).

Citations

If you use nf-core/taxmarker for your analysis, please cite the original article for the algorithm:

Phylogeny-Aware Identification and Correction of Taxonomically Mislabeled Sequences.

Kozlov, Alexey M., Jiajie Zhang, Pelin Yilmaz, Frank Oliver Glöckner, and Alexandros Stamatakis.

Nucleic Acids Research 44, no. 11 (2016): 5022–33. https://doi.org/10.1093/nar/gkw396.

An extensive list of references for the tools used by the pipeline can be found in the CITATIONS.md file.

You can cite the nf-core publication as follows:

The nf-core framework for community-curated bioinformatics pipelines.

Philip Ewels, Alexander Peltzer, Sven Fillinger, Harshil Patel, Johannes Alneberg, Andreas Wilm, Maxime Ulysse Garcia, Paolo Di Tommaso & Sven Nahnsen.

Nat Biotechnol. 2020 Feb 13. doi: 10.1038/s41587-020-0439-x.