waypoint-bio

Waypoint：Outpost Bio のオープンなマイクロバイオーム基盤モデル

概要

Outpost Bio は、Treloar et al., bioRxiv 2026.05.02.722381 で説明されている 3 つの成果物を Apache 2.0 の下でオープンソース化しました。

成果物	内容	Hugging Face
Waypoint	分類群トークンを使った GPT-2 スタイルの因果 LM、パラメーター数は 6M～170M	outpost-bio/Waypoint-6m、-45m、-170m
Atlas	MGnify からスクレイピングした 539,308 件のマイクロバイオームサンプル（事前学習用 485,377 件／ベンチマーク用 53,931 件）	outpost-bio/Atlas
Compass	4 つの研究にまたがる 8 つの下流タスク	outpost-bio/Compass

全体を貫くアイデアは、マイクロバイオームのサンプルを 文 として扱うことです。各分類群が 1 つのトークンとなり、トークンは存在量の z スコアが高い順に並べられ、モデルは次のトークン予測で学習されます。事前学習済みチェックポイントは、サンプルレベルの埋め込み、または予測タスクのファインチューニング用バックボーンとして利用できます。

すべての操作は、5 つのサブコマンド（prepare-dataset、embed、finetune、benchmark、pretrain）を備えた 1 つの CLI、waypoint で実行できます。

使用する場面

• 16S／ショットガンの分類プロファイルを固定サイズのベクトルに埋め込み、クラスタリング、可視化、下流分類器に利用する場合。
• Waypoint チェックポイントをファインチューニングし、群集組成から表現型、治療、または連続的な測定値を予測する場合。
• 独自のマイクロバイオームモデルを Compass で評価し、論文の数値と比較できるようにする場合。
• Atlas または独自のコーパスで分類群言語モデルを事前学習する場合。
• プロファイラーの出力（MetaPhlAn、Kraken2/Bracken、QIIME 2、MGnify TSV）を、これらのツールが想定する入力形式に変換する場合。

ラベル付きサンプルが約 1,000 件未満の場合は、これを使わないでください。 科学的な注意事項を参照してください。その場合は相対存在量を使ったランダムフォレストのほうが適しており、論文でもそう述べられています。

セットアップ

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

Atlas、Compass、およびすべての Waypoint チェックポイントはアクセス制限付きです。アクセスは自動承認されますが、各リポジトリで一度承認操作を行ってから、認証する必要があります。

1. 必要な各リポジトリのページでアクセスを申請します：Waypoint-6m、 Waypoint-45m、 Waypoint-170m、 Atlas、 Compass。

2. ローカルで認証します。

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

いずれかのサブコマンドで 401／403 エラーが発生する場合、ほとんどの場合、その特定のリポジトリでアクセスを申請していません。トークンだけでは不十分です。読み取り権限のトークンを使用してください。トークナイザーは trust_remote_code=True で読み込まれるため、実行間でリモートコードを固定する必要がある場合は、revision を指定してください。

Waypoint のデータ形式

prepare-dataset 以外のすべてのサブコマンドは、Waypoint 形式を入力として使用します。これは .parquet／.csv／.tsv ファイルで、各行がサンプルを表し、互いに対応する 2 つのリスト列と、必要に応じたラベル列を含みます。

列	型	備考
Taxa	list[str]	完全な系統文字列。; 区切りです：k__Bacteria; p__Firmicutes; ...; g__Lactobacillus
Relative Abundances	list[float]	Taxa と同じ長さで、同じ順序
(任意)	スカラー	目的変数、共変量、または Split 列

parquet の使用を推奨します。CSV／TSV ではリストが repr 文字列として保存され、ast.literal_eval を使って往復変換されます。

裸の名前ではなく、完全な系統を指定してください。 トークナイザーは各系統から属のセグメント（g__）を抽出し、属が欠落している場合は、より詳細な上位ランクにフォールバックします。裸の名前では、このフォールバックが完全に無効になります。

ワークフロー

1. データを waypoint 形式に変換する

系統ラベル付きのサンプル × 分類群（または分類群 × サンプル）の存在量行列がすでにある場合：

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

向きは最初の列ヘッダー（taxonomy、lineage、taxon、otu、 #otu id ⇒ 分類群が行）から自動検出されます。--orientation で上書きできます。--no_normalize を指定しない限り、行の合計が 1 になるよう正規化され、--keep_zeros を指定しない限り、ゼロは削除されます。

prepare-dataset はプロファイラーの出力を直接読み込めません。MetaPhlAn は | 区切りを使用し、Kraken2 の出力では階層がインデントで表され、QIIME 2/SILVA ではドメインの接頭辞に k__ ではなく d__ が使われます（トークナイザーはこれを警告なく無視します）。これらには、同梱のコンバーターを使用してください。

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 kraken \
    --output dataset.parquet

python scripts/profiler_to_waypoint.py \
    --input feature-table.tsv --format qiime2 \
    --output dataset.parquet

すべての入力レイアウト、ランクの処理、d__/| に関する注意点については、references/data-preparation.md を参照してください。

2. 何よりも先に語彙のカバー率を確認する

Waypoint の語彙は、Atlas に基づいて事前学習時に固定されています。語彙に含まれない分類群は <unk> になり、waypoint embed によって警告なく削除されます。論文では、これをモデルの主な制約として挙げています。分類群がすべて語彙に含まれないサンプルでは、退化した [BOS][EOS] 埋め込みが生成されます。

python scripts/vocab_coverage.py --model outpost-bio/Waypoint-6m --data dataset.parquet

サンプルごとのカバー率と存在量で重み付けしたカバー率を報告し、しきい値を下回るサンプルにフラグを付けます。存在量で重み付けしたカバー率の中央値が約 0.8 を下回る場合は、下流の数値を信頼する前に分類ラベルを見直してください。

3. サンプルを埋め込む

waypoint embed \
    --model outpost-bio/Waypoint-6m \
    --data dataset.parquet \
    --output embeddings.parquet

出力はサンプル ID をインデックスとし、列は dim_0 … dim_{H-1} です（H は 6m で 256、45m で 512、170m で 768）。デフォルトは --pooling last_token、--batch_size 32、--max_length 512 で、デバイスは自動検出されます（cuda → mps → cpu）。

変更する理由がない限り、--pooling last_token を使用してください。チェックポイントの事前学習時の方式、および benchmark と finetune のプーリング方式と一致します。教師なし用途では mean も妥当な選択肢です。first_token/cls_token は BOS の位置を返し、因果 LM ではほとんど情報を持ちません。

4. ラベルを使ってファインチューニングする

# classification
waypoint finetune \
    --model outpost-bio/Waypoint-45m \
    --data dataset.parquet \
    --output_dir outputs/ft_disease \
    --task_type classification \
    --target "Disease Status" \
    --config configs/finetune_classification.yaml

# regression, with a categorical covariate one-hot appended to the pooled embedding
waypoint finetune \
    --model outpost-bio/Waypoint-45m \
    --data dataset.parquet \
    --output_dir outputs/ft_degradation \
    --task_type regression \
    --target "Degradation Rate" \
    --covariate_column Drug \
    --config configs/finetune_regression.yaml

設定ファイルのパスは同梱の waypoint_bio/configs/ ツリーを基準に解決されるため、どのディレクトリからでもクローンせずに configs/... を使用できます。

小規模データセットでは、次のデフォルト値を変更することを検討してください。warmup_steps: 1000（早期停止より前にウォームアップが終わるよう、約 50 に減らします）、同梱の設定ファイルでは num_epochs: 1（エポック数を増やします。実際に学習を終了するのは、検証損失に基づく早期停止です）、VRAM が限られている場合は use_lora: true（パラメーターの約 1% を学習します。保存前にアダプターが再統合されるため、チェックポイントは通常の AutoModel のままです）。

デフォルトの分割はランダムな 80/10/10 です。サンプル間に相関がある場合は、split_column に Split 列を設定してください。繰り返し測定、1 人のドナーを経時的にサンプリングしたデータ、技術的反復などでランダム分割を使うと、データが漏洩し、テストスコアは意味を持たなくなります。

出力は --output_dir に保存されます。内容は best_model/（embed/benchmark で読み込み可能）、test_metrics.json、training_log.csv + .html、および finetune_results.json です。

5. Compass でベンチマークする

waypoint benchmark --model outpost-bio/Waypoint-6m --output_dir outputs/benchmark
waypoint benchmark --model outputs/pretrain/best_model --tasks 1 6 --output_dir outputs/smoke

タスクごとに新しいヘッドをファインチューニングし、benchmark_results.json に書き込みます。分類タスクのスコアはマクロ F1、唯一の回帰タスクのスコアは [0, 1] にクランプされた R² です。final_score はタスク全体の単純平均です。タスクの一覧、メトリクスのキー、結果ファイルのスキーマについては、references/compass-benchmark.md を参照してください。

6. 事前学習する

waypoint pretrain \
    --model_config configs/models/gpt2-45m.yaml \
    --pretrain_config configs/pretraining.yaml \
    --output_dir outputs/pretrain_45m

Atlas をダウンロードし、コーパスから分類学的トークナイザーを構築し、Z スコアによる順序付けのためにトークンごとの存在量の平均/標準偏差を計算してから、次トークン予測と早期停止を使って学習します。代わりに独自の waypoint 形式のコーパスで事前学習するには --data my_corpus.parquet を、動作確認には --max_samples N を追加してください。

同梱されているアーキテクチャは 9 種類です。gpt2-6m.yaml（8 層、隠れ層 256）から gpt2-170m.yaml（24 層、隠れ層 768）まであり、ヘッドごとの次元数はすべて 64 に固定されています。設定の一覧とすべての設定キーについては、references/cli-reference.md を参照してください。

科学的な注意事項

これらは結果を左右する重要な事項です。無視すると、見た目は問題なくても意味のない数値が得られます。

• ラベル付きデータが約1,000件未満の場合、Waypointは生の存在量を使ったランダムフォレストより性能が劣ります。 RFベースラインとの性能が逆転するのは、論文では学習データ約10,000件の時点です。まずベースラインを適合させ、手元のデータで優位性が確認できた場合にのみ、トランスフォーマーを採用してください。
• 語彙にない分類群はフラグ付けされず、除外されます。 どのCompassデータセットにも、語彙にない分類群が含まれています。scripts/vocab_coverage.py を実行し、結果とあわせてカバレッジを報告してください。
• ベンチマークで最良だったのは170Mではなく45Mです。 スケールを大きくすると事前学習損失は下がり続けますが、下流のCompassスコアはそうなりません。まず6mまたは45mから始め、明確な効果が確認できた場合にのみスケールを大きくしてください。
• デフォルトでは属レベルでトークン化されるため、種レベルの違いは統合されます。 taxon_rank を変更するには、トークン化し直すだけでなく、事前学習をやり直す必要があります。
• 組成データです。 相対存在量の合計は1に制約されているため、ある分類群の変化によって、ほかの分類群にも見かけ上の変化が生じます。これは、分類群ごとのアトリビューションの解釈に影響します。
• マイクロバイオームデータでは、バッチ効果や研究間の差が支配的です。 Atlasには、MGnifyのv1.0～v5.0のパイプラインと4種類のシーケンシング手法が含まれています。研究やランの境界がラベルの境界と一致することがないようにしてください。
• 臨床用または診断用のツールではありません。 モデルカードにも明記されています。

参考資料

• references/cli-reference.md — すべてのサブコマンドフラグ、設定キー、モデルサイズの表。
• references/compass-benchmark.md — 8つのタスク、フィルター、メトリクス、benchmark_results.json のスキーマ。
• references/data-preparation.md — waypoint形式、プロファイラーの変換、分類文字列のルール。
• references/python-api.md — Pythonからトークナイザー、データセット、ヘッド、チェックポイントを使用する方法。

スクリプト

• scripts/profiler_to_waypoint.py — MetaPhlAn／Kraken2／QIIME 2／汎用系統テーブルをwaypoint形式に変換します。
• scripts/vocab_coverage.py — waypoint形式のファイルについて、トークナイザーのカバレッジレポートを作成します。

上流プロジェクト

コード github.com/Outpost-Bio/waypoint · パッケージ waypoint-bio · 論文 bioRxiv 2026.05.02.722381 · コミュニティ Waypoint Slack · お問い合わせ [email protected]。

引用：Treloar, N. J., Ur-Rehman, S., Yang, J., & Outpost Bio（2026）。Learning the Language of the Microbiome with Transformers. bioRxiv。アーティファクトごとのDOIは outpost.bio/citations に記載されています。

エージェントの運用手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、および入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 先にパイプラインを小さなサブセット（1サンプル、1染色体、数千細胞）で実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの識別、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の点を記載します。

このような場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に中断し、調整（liftover、ID マッピング）します。
これらの手順に記載された関数、フラグ、またはエンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適切に対応してユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに尋ねるか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 統計が裏付ける範囲を超えて生物学的意義を解釈しないでください。多重検定補正について報告します。
• ここにあるバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU またはクラウドクォータを消費する操作、個人データや患者データを扱う操作、または取り消せない操作の前には、ユーザーに確認します。

関連するスキル

• scikit-bio：生物学的配列および群集生態学の解析に使用する Python ライブラリ scikit-bio。DNA／RNA／タンパク質配列、pair_align アラインメント、系統発生…
• distributed-llm-pretraining-torchtitan：4D 並列処理（FSDP2、TP、PP、CP）を使用した、torchtitan による PyTorch ネイティブの分散 LLM 事前学習を提供します。