waypoint CLI reference

Reviewed 2026-10-01 against waypoint-bio 1.0.2 (PyPI wheel) and GitHub main 1.0.4 (f45eee6d07a480bfc90f84ab8082bbc969dec15d). Flags below are shared; export/logging differences and known failures are recorded in upstream-review.md. Hub-backed training examples are illustrative, without authenticated scientific execution.

waypoint {pretrain,benchmark,finetune,embed,prepare-dataset} ...

Config paths are resolved first against the working directory, then against the bundled waypoint_bio/configs/ tree inside the installed wheel. So --config configs/benchmark.yaml works from anywhere without cloning the repo. The same fallback applies to the bundled example data (examples/abundance_matrix.tsv, examples/finetune_classification.parquet, …).

waypoint prepare-dataset

Converts a sample × taxa abundance matrix into waypoint format.

auto treats the file as taxa-as-rows when the first column header is taxonomy, lineage, taxon, otu, or #otu id (case-insensitive); otherwise samples-as-rows with the first column as the sample ID.

--taxonomy_format genus prefixes bare column names with g__. It disables higher-rank fallback, because a bare name carries no lineage to fall back to — prefer real lineage strings.

waypoint embed

One fixed-size vector per sample from a pretrained checkpoint. No fine-tuning, no labels needed.

Output columns are dim_0 … dim_{H-1}, indexed by sample ID. Hidden size H is 256 (6m), 512 (45m), 768 (170m).

Behaviour worth knowing: tokens that map to <unk> are dropped before ordering, not encoded. A row with no in-vocabulary taxa still produces an output row, but its sequence is [BOS][EOS] and the embedding is meaningless. Run scripts/vocab_coverage.py first.

Ordering: by descending abundance z-score when token_std_means.parquet is present (it ships with every published checkpoint and with waypoint pretrain output), otherwise by descending raw relative abundance.

waypoint finetune

Fine-tunes a checkpoint on your own labelled waypoint-format data.

Fine-tuning config keys

split_column: null        # column holding train/validation/test; null = random split
val_fraction: 0.1
test_fraction: 0.1

max_length: 512           # 2 <= max_length <= checkpoint n_positions
pooling_strategy: last_token
filter_unk_taxa: true     # drop out-of-vocabulary taxa rather than feed <unk>

seed: 42
learning_rate: 0.00003
num_epochs: 1             # raise this; early stopping is what should terminate training
batch_size: 64
warmup_steps: 1000        # lower to ~50 for small datasets
weight_decay: 0.001
eval_strategy: steps
eval_steps: 400
logging_steps: 5
patience: 5               # eval steps without improvement before early stopping
save_total_limit: 1

use_lora: false
lora_r: 8
lora_alpha: 16            # convention: 2 * r
lora_dropout: 0.05
lora_target_modules: [c_attn, c_proj]   # GPT-2 fused QKV and output projection
lora_bias: none
lora_fan_in_fan_out: true               # required for GPT-2 Conv1D layouts

The shipped configs use num_epochs: 1, whereas the paper describes up to 300 fine-tuning epochs with early stopping. The default CLI config does not reproduce that training budget. On small datasets, choose enough epochs and a suitable evaluation interval for validation and early stopping to occur. Likewise eval_steps: 400 may never fire; lower it so early stopping and best-checkpoint selection can actually work.

GitHub 1.0.4 merges LoRA adapters before export. PyPI 1.0.2 saves an adapter-only model when use_lora: true; plain AutoModel.from_pretrained cannot load that export. Keep LoRA disabled for the released-package workflow, or explicitly load/merge via PEFT with the original base model. Both versions also require a tokenizer that actually implements vocabulary serialization.

The fine-tuning config seed affects initial RNG setup and random splits, but its value is not passed to TrainingArguments either. Explicitly wire trainer seeds for controlled repeats.

Outputs

These describe successful exports; see the tokenizer/LoRA limitations above.

waypoint benchmark

configs/benchmark.yaml is the fine-tuning config applied identically to every task: learning_rate: 3e-5, num_epochs: 1, batch_size: 64, warmup_steps: 1000, weight_decay: 0.001, patience: 5, pooling_strategy: last_token, eval_steps: 400, filter_unk_taxa: true, seed: 42. The paper describes up to 300 fine-tuning epochs with early stopping, so the shipped one-epoch config already differs from the paper. Record the actual training budget and completed evaluation steps instead of claiming automatic comparability.

The paper reports repeated runs. The CLI --seed seeds Torch/NumPy before tasks, but TrainingArguments does not receive that value and resets training randomness to its default 42; YAML seed is unused here. Changing --seed alone does not establish independent training seeds. Use an explicitly reviewed local change passing the seed to the trainer for a seed study. Record the dataset/model revisions, package/dependency versions and hardware; unchanged YAML alone is not a claim to reproduce the paper.

waypoint pretrain

Known blocker: both reviewed upstream versions call the local tokenizer save_pretrained() before training; it raises NotImplementedError because save_vocabulary is missing. A repaired tokenizer and save/reload test are prerequisites.

Intended steps: download the Atlas pretrain split → build a taxonomic tokenizer from the corpus → compute per-token abundance mean/std for z-score ordering → train GPT-2 with next-token prediction and early stopping → save best_model/.

configs/pretraining.yaml

training_type: next_token_prediction
taxon_rank: genus              # tokenization rank; changing it means re-pretraining
fallback_to_higher_rank: true  # use the most specific higher rank when genus is absent
max_length: 512
learning_rate: 0.001
warmup_steps: 1000
weight_decay: 0.001
batch_size: 32
num_epochs: 100
patience: 10
eval_steps: 3261
save_steps: 3261
logging_steps: 100
val_split: 0.1
seed: 42

Architectures

All share model_type: gpt2 and n_positions: 512. Per-head dimension is 64 except gpt2-6m-mgm.yaml, where 256 / 8 = 32.

Only 6m, 45m, and 170m are published as checkpoints. The rest exist so the paper's scaling study is reproducible; gpt2-6m-mgm isolates the effect of head count against the MGM baseline.

Parameter counts exclude token and positional embeddings, so the Hub's reported sizes are larger (the 6m checkpoint reports ~10.1M, the 45m ~51.8M).

Pretraining Atlas end to end is a multi-GPU-day job. After resolving serialization, validate the pipeline with a tiny local corpus and architecture before a full run. --max_samples caps rows after load_dataset, so it does not bound the Atlas download size.