aomlomics/tourmaline: v2.2.0

Abstract

Tourmaline v2.2.0 This release adds the tax-credit step: a fourth, optional workflow step that benchmarks reference databases and taxonomic classifiers, based on code from Bokulich et al. 2018. Bokulich NA, Kaehler BD, Rideout JR, Dillon M, Bolyen E, Knight R, Huttley GA, Caporaso JG. Optimizing taxonomic classification of marker-gene amplicon sequences with QIIME 2's q2-feature-classifier plugin. Microbiome. 2018;6(1):90. doi:10.1186/s40168-018-0470-z This release is purely additive. The qaqc, repseqs and taxonomy steps are untouched, and config_01_qaqc.yaml, config_02_repseqs.yaml and config_03_taxonomy.yaml are unchanged. If you do not use the new step, nothing about your workflow changes. Requires installation of https://github.com/ksil-NOAA/tour2-tax-credit/edit/tour2-tax-credit, a modified version of tax-credit (TAXonomic ClassifieR Evaluation Tool). Still requires QIIME 2 2024.10 in an environment named qiime2-amplicon-2024.10. New Features tax-credit step The other three steps process your data. Tax-credit helps answers how should you process your data: which reference database, classify method and parameters should I use for this marker gene? It runs every combination of database, classify method and parameter set you give it, scores the results, and writes summary tables and plots. Evaluation methods | Method | What it does | Answers | |---|---|---| | cross-validated | Taxonomy-aware K-fold splits of a database; classify held-out sequences | How well does this database classify sequences like the ones it contains? | | cross-validated-trad | Traditional random K-fold splits | The same, without taxonomy-aware stratification | | novel-taxa | Hold out whole taxa, so a query's own taxon is absent from the reference | What happens to organisms your database has never seen? | | self-validated | Classify the full database against itself | Best-case ceiling; catches internal inconsistencies | | mock-community | Classify real sequencing data from communities of known composition | How does it do on real reads, including PCR and abundance effects? | The first four are simulated from the reference database itself. mock-community uses real data you supply — a feature table, ASV sequences, and the expected composition and/or the known taxonomy of each ASV. All five classify methods are supported: naive-bayes, consensus-blast, consensus-vsearch, bt2-blca and revamp. Metrics Simulated evaluations report precision, recall and F-measure per fold and rank, plus the classification ratios (match, underclassification, overclassification, misclassification) that show how a method is wrong, not just how often. Mock-community evaluation adds Taxon Accuracy Rate, Taxon Detection Rate and Bray-Curtis dissimilarity between expected and observed composition. Also in this release Documentation for the new step, including the docs/steps/tax_credit.md guide, the full configuration reference, and troubleshooting entries for its common failure modes. The mock-community smoke test fixtures are now included in the repository. The documentation referenced config_04_tax_credit_test_mock.yaml and its 16 KB fixture, but they had never been committed, so the documented smoke test could not be run from a fresh clone. Upgrade notes Nothing to change. config_01_qaqc.yaml, config_02_repseqs.yaml and config_03_taxonomy.yaml are byte-identical to v2.1.0, and the qaqc, repseqs and taxonomy Snakefiles are unchanged. The only edit to existing pipeline code is a one-line comment in rules/taxonomy_assignment.smk. Tax-credit is opt-in: it runs only when you invoke --step tax-credit with a config_04_* file. Verification performed Dry runs confirm valid DAG construction for all four steps — qaqc, taxonomy, tax-credit (101 jobs on the reduced test matrix) and tax-credit mock-community (25 jobs) — and the companion package imports correctly in the QIIME 2 environment. Documentation links, mkdocs navigation targets and YAML syntax were validated. Dry runs verify that the workflow plans correctly; they do not execute the underlying tools. Please report anything unexpected via GitHub issues. Note on AI assistance Parts of this release were prepared with AI assistance: Documentation. The tax-credit documentation, and the surrounding docs updated to include the step, were AI-drafted from the Snakefiles, configuration templates and scripts, then reviewed and edited by the maintainer. Release preparation. Restoring the step after it was held back from v2.1.0. Pipeline and analysis code. The tax-credit step, its evaluation methods and its metrics were written or adapted by the project maintainers, with AI used in a supporting role on some commits. Full changelog Full Changelog: https://github.com/aomlomics/tourmaline/compare/v2.1.0...v2.2.0