/waypoint-bio

name: waypoint-bio
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.
license: MIT
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.
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
  upstream-version: "waypoint-bio 1.0.2 (PyPI); GitHub main 1.0.4"
  last-reviewed: "2026-08-17"
  openclaw:
    primaryEnv: HF_TOKEN
    envVars:
      - name: HF_TOKEN
        required: true
        description: Hugging Face read token with access to the gated outpost-bio/Waypoint-*, outpost-bio/Atlas, and outpost-bio/Compass repos.

Waypoint: Outpost Bio's Open Microbiome Foundation Models

Overview

Outpost Bio open-sourced three artefacts under Apache 2.0, described in [Treloar et al., bioRxiv 2026.05.02.722381](https://www.biorxiv.org/content/10.64898/2026.05.02.722381v2):

| Artefact | What it is | Hugging Face | | --- | --- | --- | | **Waypoint** | GPT-2-style causal LMs over taxonomic tokens, 6M–170M params | `outpost-bio/Waypoint-6m`, `-45m`, `-170m` | | **Atlas** | 539,308 microbiome samples scraped from MGnify (485,377 pretrain / 53,931 benchmark) | `outpost-bio/Atlas` | | **Compass** | Eight downstream tasks over four studies | `outpost-bio/Compass` |

The unifying idea: a microbiome sample is a *sentence*. Each taxon is one token, tokens are ordered by descending abundance z-score, and the model is trained with next-token prediction. A pretrained checkpoint then supplies sample-level embeddings or a fine-tuning backbone for prediction tasks.

All of it is driven by one CLI, `waypoint`, with five subcommands: `prepare-dataset`, `embed`, `finetune`, `benchmark`, `pretrain`.

When to use

• Embedding 16S/shotgun taxonomic profiles into fixed-size vectors for clustering, visualisation, or

a downstream classifier.

• Fine-tuning a Waypoint checkpoint to predict a phenotype, treatment, or continuous readout from

community composition.

• Scoring your own microbiome model against Compass so the number is comparable to the paper.
• Pretraining a taxonomic language model on Atlas or on your own corpus.
• Converting profiler output (MetaPhlAn, Kraken2/Bracken, QIIME 2, MGnify TSVs) into the input format

these tools expect.

**Do not reach for this** when you have fewer than ~1,000 labelled samples — see [Scientific caveats](#scientific-caveats). A random forest on relative abundances is the better tool there, and the paper says so.

Setup

pip install waypoint-bio       # installs the `waypoint` command

Atlas, Compass, and every Waypoint checkpoint are **gated**. Access is auto-approved, but you must click through once per repo and then authenticate:

1. Request access on each repo page you need: [Waypoint-6m](https://huggingface.co/outpost-bio/Waypoint-6m), [Waypoint-45m](https://huggingface.co/outpost-bio/Waypoint-45m), [Waypoint-170m](https://huggingface.co/outpost-bio/Waypoint-170m), [Atlas](https://huggingface.co/datasets/outpost-bio/Atlas), [Compass](https://huggingface.co/datasets/outpost-bio/Compass). 2. Authenticate locally:

   hf auth login          # or: export HF_TOKEN=hf_...

A 401/403 from any subcommand almost always means access was never requested on that specific repo — a token alone is not enough. Use a read-scoped token. The tokenizer loads via `trust_remote_code=True`, so pin a `revision` if you need the remote code fixed across runs.

The waypoint data format

Everything except `prepare-dataset` consumes **waypoint format**: a `.parquet` / `.csv` / `.tsv` whose rows are samples, with two aligned list-columns plus any label columns you need.

| Column | Type | Notes | | --- | --- | --- | | `Taxa` | `list[str]` | Full lineage strings, `;`-separated: `k__Bacteria; p__Firmicutes; ...; g__Lactobacillus` | | `Relative Abundances` | `list[float]` | Same length as `Taxa`, same order | | *(any)* | scalar | Targets, covariates, or a `Split` column |

Prefer parquet. CSV/TSV stores the lists as `repr` strings and round-trips through `ast.literal_eval`.

**Give full lineages, not bare names.** The tokenizer extracts the genus segment (`g__`) from each lineage and falls back to the most specific higher rank when genus is missing. Bare names disable that fallback entirely.

Workflow

1. Get your data into waypoint format

If you already have a sample × taxa (or taxa × sample) abundance matrix with lineage labels:

waypoint prepare-dataset \
    --input abundance_matrix.tsv \
    --metadata sample_labels.csv \
    --output dataset.parquet

Orientation is auto-detected from the first column header (`taxonomy`, `lineage`, `taxon`, `otu`, `#otu id` ⇒ taxa-as-rows); override with `--orientation`. Rows are normalised to sum to 1 unless you pass `--no_normalize`, and zeros are dropped unless you pass `--keep_zeros`.

`prepare-dataset` cannot read profiler output directly — MetaPhlAn uses `|` separators, Kraken2 reports encode the hierarchy as indentation, and QIIME 2/SILVA prefixes the domain `d__` instead of `k__` (which the tokenizer silently ignores). Use the bundled converter for those:

python scripts/profiler_to_waypoint.py \
    --input merged_metaphlan.tsv --format metaphlan \
    --output dataset.parquet

python scripts/profiler_to_waypoint.py \
    --input reports/*.kreport --format krake