|
| 1 | +--- |
| 2 | +name: waypoint-bio |
| 3 | +description: Use when working with Outpost Bio's open microbiome foundation models - the Waypoint checkpoints (Waypoint-6m, Waypoint-45m, Waypoint-170m), the Atlas pretraining corpus, the Compass eight-task benchmark, or the `waypoint` CLI from the `waypoint-bio` package. Covers embedding microbiome samples, fine-tuning on taxonomic abundance data, benchmarking a checkpoint on Compass, pretraining a GPT-2 model on taxonomic abundance profiles, and converting MetaPhlAn, Kraken2, QIIME 2, or MGnify abundance tables into waypoint format. |
| 4 | +license: MIT |
| 5 | +compatibility: Requires Python 3.10+ with `waypoint-bio` (pulls torch, transformers, datasets, peft, scikit-learn). Needs network access and a Hugging Face token with access granted to the gated outpost-bio repos. A GPU is strongly recommended for pretraining and benchmarking. |
| 6 | +metadata: |
| 7 | + version: "1.0" |
| 8 | + skill-author: K-Dense Inc. |
| 9 | + upstream-version: "waypoint-bio 1.0.2 (PyPI); GitHub main 1.0.4" |
| 10 | + last-reviewed: "2026-08-17" |
| 11 | + openclaw: |
| 12 | + primaryEnv: HF_TOKEN |
| 13 | + envVars: |
| 14 | + - name: HF_TOKEN |
| 15 | + required: true |
| 16 | + description: Hugging Face read token with access to the gated outpost-bio/Waypoint-*, outpost-bio/Atlas, and outpost-bio/Compass repos. |
| 17 | +--- |
| 18 | + |
| 19 | +# Waypoint: Outpost Bio's Open Microbiome Foundation Models |
| 20 | + |
| 21 | +## Overview |
| 22 | + |
| 23 | +Outpost Bio open-sourced three artefacts under Apache 2.0, described in |
| 24 | +[Treloar et al., bioRxiv 2026.05.02.722381](https://www.biorxiv.org/content/10.64898/2026.05.02.722381v2): |
| 25 | + |
| 26 | +| Artefact | What it is | Hugging Face | |
| 27 | +| --- | --- | --- | |
| 28 | +| **Waypoint** | GPT-2-style causal LMs over taxonomic tokens, 6M–170M params | `outpost-bio/Waypoint-6m`, `-45m`, `-170m` | |
| 29 | +| **Atlas** | 539,308 microbiome samples scraped from MGnify (485,377 pretrain / 53,931 benchmark) | `outpost-bio/Atlas` | |
| 30 | +| **Compass** | Eight downstream tasks over four studies | `outpost-bio/Compass` | |
| 31 | + |
| 32 | +The unifying idea: a microbiome sample is a *sentence*. Each taxon is one token, tokens are ordered |
| 33 | +by descending abundance z-score, and the model is trained with next-token prediction. A pretrained |
| 34 | +checkpoint then supplies sample-level embeddings or a fine-tuning backbone for prediction tasks. |
| 35 | + |
| 36 | +All of it is driven by one CLI, `waypoint`, with five subcommands: `prepare-dataset`, `embed`, |
| 37 | +`finetune`, `benchmark`, `pretrain`. |
| 38 | + |
| 39 | +## When to use |
| 40 | + |
| 41 | +- Embedding 16S/shotgun taxonomic profiles into fixed-size vectors for clustering, visualisation, or |
| 42 | + a downstream classifier. |
| 43 | +- Fine-tuning a Waypoint checkpoint to predict a phenotype, treatment, or continuous readout from |
| 44 | + community composition. |
| 45 | +- Scoring your own microbiome model against Compass so the number is comparable to the paper. |
| 46 | +- Pretraining a taxonomic language model on Atlas or on your own corpus. |
| 47 | +- Converting profiler output (MetaPhlAn, Kraken2/Bracken, QIIME 2, MGnify TSVs) into the input format |
| 48 | + these tools expect. |
| 49 | + |
| 50 | +**Do not reach for this** when you have fewer than ~1,000 labelled samples — see |
| 51 | +[Scientific caveats](#scientific-caveats). A random forest on relative abundances is the better tool |
| 52 | +there, and the paper says so. |
| 53 | + |
| 54 | +## Setup |
| 55 | + |
| 56 | +```bash |
| 57 | +pip install waypoint-bio # installs the `waypoint` command |
| 58 | +``` |
| 59 | + |
| 60 | +Atlas, Compass, and every Waypoint checkpoint are **gated**. Access is auto-approved, but you must |
| 61 | +click through once per repo and then authenticate: |
| 62 | + |
| 63 | +1. Request access on each repo page you need: [Waypoint-6m](https://huggingface.co/outpost-bio/Waypoint-6m), |
| 64 | + [Waypoint-45m](https://huggingface.co/outpost-bio/Waypoint-45m), |
| 65 | + [Waypoint-170m](https://huggingface.co/outpost-bio/Waypoint-170m), |
| 66 | + [Atlas](https://huggingface.co/datasets/outpost-bio/Atlas), |
| 67 | + [Compass](https://huggingface.co/datasets/outpost-bio/Compass). |
| 68 | +2. Authenticate locally: |
| 69 | + |
| 70 | + ```bash |
| 71 | + hf auth login # or: export HF_TOKEN=hf_... |
| 72 | + ``` |
| 73 | + |
| 74 | +A 401/403 from any subcommand almost always means access was never requested on that specific repo — |
| 75 | +a token alone is not enough. Use a read-scoped token. The tokenizer loads via |
| 76 | +`trust_remote_code=True`, so pin a `revision` if you need the remote code fixed across runs. |
| 77 | + |
| 78 | +## The waypoint data format |
| 79 | + |
| 80 | +Everything except `prepare-dataset` consumes **waypoint format**: a `.parquet` / `.csv` / `.tsv` |
| 81 | +whose rows are samples, with two aligned list-columns plus any label columns you need. |
| 82 | + |
| 83 | +| Column | Type | Notes | |
| 84 | +| --- | --- | --- | |
| 85 | +| `Taxa` | `list[str]` | Full lineage strings, `;`-separated: `k__Bacteria; p__Firmicutes; ...; g__Lactobacillus` | |
| 86 | +| `Relative Abundances` | `list[float]` | Same length as `Taxa`, same order | |
| 87 | +| *(any)* | scalar | Targets, covariates, or a `Split` column | |
| 88 | + |
| 89 | +Prefer parquet. CSV/TSV stores the lists as `repr` strings and round-trips through `ast.literal_eval`. |
| 90 | + |
| 91 | +**Give full lineages, not bare names.** The tokenizer extracts the genus segment (`g__`) from each |
| 92 | +lineage and falls back to the most specific higher rank when genus is missing. Bare names disable |
| 93 | +that fallback entirely. |
| 94 | + |
| 95 | +## Workflow |
| 96 | + |
| 97 | +### 1. Get your data into waypoint format |
| 98 | + |
| 99 | +If you already have a sample × taxa (or taxa × sample) abundance matrix with lineage labels: |
| 100 | + |
| 101 | +```bash |
| 102 | +waypoint prepare-dataset \ |
| 103 | + --input abundance_matrix.tsv \ |
| 104 | + --metadata sample_labels.csv \ |
| 105 | + --output dataset.parquet |
| 106 | +``` |
| 107 | + |
| 108 | +Orientation is auto-detected from the first column header (`taxonomy`, `lineage`, `taxon`, `otu`, |
| 109 | +`#otu id` ⇒ taxa-as-rows); override with `--orientation`. Rows are normalised to sum to 1 unless you |
| 110 | +pass `--no_normalize`, and zeros are dropped unless you pass `--keep_zeros`. |
| 111 | + |
| 112 | +`prepare-dataset` cannot read profiler output directly — MetaPhlAn uses `|` separators, Kraken2 |
| 113 | +reports encode the hierarchy as indentation, and QIIME 2/SILVA prefixes the domain `d__` instead of |
| 114 | +`k__` (which the tokenizer silently ignores). Use the bundled converter for those: |
| 115 | + |
| 116 | +```bash |
| 117 | +python scripts/profiler_to_waypoint.py \ |
| 118 | + --input merged_metaphlan.tsv --format metaphlan \ |
| 119 | + --output dataset.parquet |
| 120 | + |
| 121 | +python scripts/profiler_to_waypoint.py \ |
| 122 | + --input reports/*.kreport --format kraken \ |
| 123 | + --output dataset.parquet |
| 124 | + |
| 125 | +python scripts/profiler_to_waypoint.py \ |
| 126 | + --input feature-table.tsv --format qiime2 \ |
| 127 | + --output dataset.parquet |
| 128 | +``` |
| 129 | + |
| 130 | +See `references/data-preparation.md` for every input layout, rank handling, and the `d__`/`|` gotchas. |
| 131 | + |
| 132 | +### 2. Check vocabulary coverage before anything else |
| 133 | + |
| 134 | +Waypoint's vocabulary is fixed at pretraining time from Atlas. Taxa absent from it become `<unk>` and |
| 135 | +are **silently dropped** by `waypoint embed`; the paper names this as the models' main limitation. A |
| 136 | +sample whose taxa are all out-of-vocabulary yields a degenerate `[BOS][EOS]` embedding. |
| 137 | + |
| 138 | +```bash |
| 139 | +python scripts/vocab_coverage.py --model outpost-bio/Waypoint-6m --data dataset.parquet |
| 140 | +``` |
| 141 | + |
| 142 | +It reports per-sample and abundance-weighted coverage and flags samples below a threshold. Treat |
| 143 | +median abundance-weighted coverage under ~0.8 as a reason to re-examine your taxonomy labels before |
| 144 | +trusting any downstream number. |
| 145 | + |
| 146 | +### 3. Embed samples |
| 147 | + |
| 148 | +```bash |
| 149 | +waypoint embed \ |
| 150 | + --model outpost-bio/Waypoint-6m \ |
| 151 | + --data dataset.parquet \ |
| 152 | + --output embeddings.parquet |
| 153 | +``` |
| 154 | + |
| 155 | +Output is indexed by sample ID with columns `dim_0 … dim_{H-1}` (`H` = 256 for 6m, 512 for 45m, |
| 156 | +768 for 170m). Defaults: `--pooling last_token`, `--batch_size 32`, `--max_length 512`, device |
| 157 | +auto-detected (`cuda` → `mps` → `cpu`). |
| 158 | + |
| 159 | +Keep `--pooling last_token` unless you have a reason to change it: it matches how the checkpoints |
| 160 | +were pretrained and how `benchmark` and `finetune` pool. `mean` is a reasonable alternative for |
| 161 | +unsupervised use; `first_token`/`cls_token` return the BOS position and carry little signal in a |
| 162 | +causal LM. |
| 163 | + |
| 164 | +### 4. Fine-tune on your labels |
| 165 | + |
| 166 | +```bash |
| 167 | +# classification |
| 168 | +waypoint finetune \ |
| 169 | + --model outpost-bio/Waypoint-45m \ |
| 170 | + --data dataset.parquet \ |
| 171 | + --output_dir outputs/ft_disease \ |
| 172 | + --task_type classification \ |
| 173 | + --target "Disease Status" \ |
| 174 | + --config configs/finetune_classification.yaml |
| 175 | + |
| 176 | +# regression, with a categorical covariate one-hot appended to the pooled embedding |
| 177 | +waypoint finetune \ |
| 178 | + --model outpost-bio/Waypoint-45m \ |
| 179 | + --data dataset.parquet \ |
| 180 | + --output_dir outputs/ft_degradation \ |
| 181 | + --task_type regression \ |
| 182 | + --target "Degradation Rate" \ |
| 183 | + --covariate_column Drug \ |
| 184 | + --config configs/finetune_regression.yaml |
| 185 | +``` |
| 186 | + |
| 187 | +Config paths resolve against the bundled `waypoint_bio/configs/` tree, so `configs/...` works from |
| 188 | +any directory without cloning. |
| 189 | + |
| 190 | +Defaults worth overriding for small datasets: `warmup_steps: 1000` (drop to ~50 so warmup finishes |
| 191 | +before early stopping), `num_epochs: 1` in the shipped configs (raise it — early stopping on |
| 192 | +validation loss is what actually terminates training), and `use_lora: true` when VRAM is tight |
| 193 | +(~1% of parameters trained; adapters are merged back before saving, so the checkpoint stays a plain |
| 194 | +`AutoModel`). |
| 195 | + |
| 196 | +Splits default to a random 80/10/10. **Set `split_column` to a `Split` column whenever samples are |
| 197 | +correlated** — repeated measures, one donor sampled over time, technical replicates — or a random |
| 198 | +split leaks and the test score is meaningless. |
| 199 | + |
| 200 | +Outputs land in `--output_dir`: `best_model/` (loadable by `embed`/`benchmark`), |
| 201 | +`test_metrics.json`, `training_log.csv` + `.html`, and `finetune_results.json`. |
| 202 | + |
| 203 | +### 5. Benchmark on Compass |
| 204 | + |
| 205 | +```bash |
| 206 | +waypoint benchmark --model outpost-bio/Waypoint-6m --output_dir outputs/benchmark |
| 207 | +waypoint benchmark --model outputs/pretrain/best_model --tasks 1 6 --output_dir outputs/smoke |
| 208 | +``` |
| 209 | + |
| 210 | +Fine-tunes a fresh head per task and writes `benchmark_results.json`. Classification tasks score |
| 211 | +macro-F1; the one regression task scores R² clamped to [0, 1]; `final_score` is the unweighted mean |
| 212 | +across tasks. Full task table, metric keys, and result-file schema: `references/compass-benchmark.md`. |
| 213 | + |
| 214 | +### 6. Pretrain |
| 215 | + |
| 216 | +```bash |
| 217 | +waypoint pretrain \ |
| 218 | + --model_config configs/models/gpt2-45m.yaml \ |
| 219 | + --pretrain_config configs/pretraining.yaml \ |
| 220 | + --output_dir outputs/pretrain_45m |
| 221 | +``` |
| 222 | + |
| 223 | +Downloads Atlas, builds a taxonomic tokenizer from the corpus, computes per-token abundance |
| 224 | +mean/std for z-score ordering, then trains with next-token prediction and early stopping. Add |
| 225 | +`--data my_corpus.parquet` to pretrain on your own waypoint-format corpus instead, and |
| 226 | +`--max_samples N` for a smoke test. |
| 227 | + |
| 228 | +Nine architectures ship, from `gpt2-6m.yaml` (8 layers, 256 hidden) to `gpt2-170m.yaml` (24 layers, |
| 229 | +768 hidden); per-head dimension is fixed at 64 throughout. `references/cli-reference.md` has the |
| 230 | +full table and every config key. |
| 231 | + |
| 232 | +## Scientific caveats |
| 233 | + |
| 234 | +These are load-bearing. Ignoring them produces numbers that look fine and mean nothing. |
| 235 | + |
| 236 | +- **Below ~1,000 labelled examples, Waypoint underperforms a random forest on raw abundances.** The |
| 237 | + paper's crossover against the RF baseline sits near **10,000** training examples. Fit the baseline |
| 238 | + first; only adopt the transformer if it wins on your data. |
| 239 | +- **Out-of-vocabulary taxa are dropped, not flagged.** Every Compass dataset carries some. Run |
| 240 | + `scripts/vocab_coverage.py` and report the coverage alongside your results. |
| 241 | +- **45M, not 170M, was the best benchmark model.** Pretraining loss keeps falling with scale, but |
| 242 | + downstream Compass score does not — start at 6m or 45m and only scale up if it demonstrably helps. |
| 243 | +- **Genus-level tokenisation is the default**, so species-level distinctions are collapsed. Changing |
| 244 | + `taxon_rank` requires re-pretraining, not just re-tokenising. |
| 245 | +- **Compositional data.** Relative abundances are constrained to sum to 1; differences in one taxon |
| 246 | + induce apparent changes in others. This affects interpretation of any per-taxon attribution. |
| 247 | +- **Batch and study effects dominate microbiome data.** Atlas spans MGnify pipelines v1.0–v5.0 and |
| 248 | + four sequencing modalities. Never let a study or run boundary coincide with your label boundary. |
| 249 | +- **Not a clinical or diagnostic tool.** The model cards state this explicitly. |
| 250 | + |
| 251 | +## References |
| 252 | + |
| 253 | +- `references/cli-reference.md` — every subcommand flag, every config key, the model-size table. |
| 254 | +- `references/compass-benchmark.md` — the eight tasks, filters, metrics, `benchmark_results.json` schema. |
| 255 | +- `references/data-preparation.md` — waypoint format, profiler conversions, taxonomy string rules. |
| 256 | +- `references/python-api.md` — using the tokenizer, datasets, heads, and checkpoints from Python. |
| 257 | + |
| 258 | +## Scripts |
| 259 | + |
| 260 | +- `scripts/profiler_to_waypoint.py` — MetaPhlAn / Kraken2 / QIIME 2 / generic lineage tables → waypoint format. |
| 261 | +- `scripts/vocab_coverage.py` — tokenizer coverage report for a waypoint-format file. |
| 262 | + |
| 263 | +## Upstream |
| 264 | + |
| 265 | +Code [github.com/Outpost-Bio/waypoint](https://github.com/Outpost-Bio/waypoint) · |
| 266 | +package `waypoint-bio` · |
| 267 | +paper [bioRxiv 2026.05.02.722381](https://www.biorxiv.org/content/10.64898/2026.05.02.722381v2) · |
| 268 | +community [Waypoint Slack](https://join.slack.com/t/outpostbio-waypoint/shared_invite/zt-3w6ivgtba-WJOCkdxiISxQpwVq9ZZxTA) · |
| 269 | +contact `waypoint@outpost.bio`. |
| 270 | + |
| 271 | +Cite Treloar, N. J., Ur-Rehman, S., Yang, J., & Outpost Bio (2026). *Learning the Language of the |
| 272 | +Microbiome with Transformers.* bioRxiv. Per-artefact DOIs are listed at |
| 273 | +[outpost.bio/citations](https://www.outpost.bio/citations). |
0 commit comments