TabFlux turns a microbial community profile — amplicon ASV/OTU counts or shotgun taxonomic profiles — into a machine-learning classifier, and into an honest estimate of what that classifier is worth on samples it has never seen. One Quarto notebook and one plain-text configuration file drive the whole run: aggregation to any taxonomic level, depth normalisation, feature selection, tuning, grouped and nested evaluation, calibration, an external test set and SHAP explanations. Built on mlr3, TabFlux runs the classic learners of microbiome machine learning — random forest, XGBoost, penalised regression, k-nearest neighbours, support vector machines — and, beyond them, TabPFN, a foundation model for tabular data that learns from your data in context instead of being trained on it. Every learner is scored on the same unseen samples.
Full documentation: iLivius.github.io/TabFlux
| Installation | the container (recommended) or conda |
| Quick start | a public dataset, one command |
| Your own data | the three input files and the settings that matter |
| Evaluation design | why the reported numbers can be trusted |
| Configuration | every key in config.yaml |
| Case study | 4,000 public food metagenomes, no local data needed |
TabFlux belongs to the BioFlux family of workflows, next to BacFlux and MetaFlux.
The TabPFN 3.5 weights download only after a one-time licence acceptance on a Prior Labs account. Register, accept the licence, and export the API key once in your shell (export TABPFN_TOKEN=...) before the first run: without it the download fails, every TabPFN fit falls back to a majority-class dummy, and the run stops after TabPFN's tuning with an error that counts the failed fits. Once the weights sit in the mounted cache, later runs do not need the token.
mkdir -p out ~/.cache/tabpfn
docker run --rm --gpus all --user "$(id -u):$(id -g)" -e TABPFN_TOKEN \
-v "$HOME/.cache/tabpfn:/work/.cache/tabpfn" -v "$PWD/out:/work/out" \
ghcr.io/ilivius/tabflux:1.6.0The demo downloads eighteen datasets of the curated Food Metagenomic Data and predicts which of four food categories a sample came from, over three folds that keep whole studies together. It writes an HTML report and a metrics/ folder to out/. It shows the machinery end to end; four classes over 891 samples settle nothing. Support for metagenomic taxonomic profiles is at demo stage in this release; fuller support comes with the next one.
For your own data, put three files in input/ (counts, taxonomy, metadata), edit config.yaml, set output.dir: "/work/out" in it, and mount both over the image's own copies:
mkdir -p out ~/.cache/tabpfn
docker run --rm --gpus all --user "$(id -u):$(id -g)" -e TABPFN_TOKEN \
-v "$HOME/.cache/tabpfn:/work/.cache/tabpfn" -v "$PWD/out:/work/out" \
-v "$PWD/input:/work/input:ro" -v "$PWD/config.yaml:/work/config.yaml:ro" \
ghcr.io/ilivius/tabflux:1.6.0 Rscript scripts/run_multi_tax_levels.R config.yamlRelative paths in the config resolve against /work, the project folder inside the image, so the template's input/counts.csv.gz is read from the mounted input/. Leave output.dir empty and the run targets the image's own /work: with --user it stops at once, because that folder is not writable for you; without --user the results land inside the container, and --rm discards them.
Drop --gpus all to run on CPU; TabPFN is several times slower there. Building the image locally and the workstation install with conda are described on the installation page.
- An honest number. Every split keeps whole studies, sites or batches together, and feature selection and tuning are repeated inside every fold, so the reported score is the score on data the whole procedure never saw — with the per-group table and the spread across folds next to it.
- A model you can use. The final models are refit on all training data, saved, and used to predict internal and external test sets, with bootstrap intervals and probability calibration.
- An explanation. SHAP values for the best model: a global ranking and, for each class, the taxa that matter most and whether more of each raises or lowers that class's probability.
Antonielli, L., & Pucher, L. (2026). TabFlux: machine-learning classification of microbial community profiles (v1.6.0). Zenodo. https://doi.org/10.5281/zenodo.23041258
Cite the version you ran: each release has its own DOI, and 10.5281/zenodo.23041257 always resolves to the newest.
Machine-readable metadata is in CITATION.cff. TabFlux stands on other people's methods and software — mlr3, ranger, TabPFN, SHAP, cFMD and more — so cite those too: the full list is on the citation page.
Developed at the AIT Austrian Institute of Technology. TabFlux grew out of the MICROSUPPRESS project (The role of wheat microbiomes in stress suppressiveness), funded by the Austrian Science Fund (FWF), project P 36288.
Much of the road from a single notebook to v1.6.0 — the nested evaluation, the container, the cFMD module and the documentation — was travelled with Claude Code. Anthropic provided six months of Claude Max through their Open Source programme, and the scale of that rewrite would not have been realistic without it. Every line was reviewed by the authors.
Apache License 2.0 — see LICENSE and NOTICE. The TabPFN model weights carry their own licence, separate from this code; no study data ship with this repository.