datamonkey/hyphaeon

HyphAeon

Ultra-fast neural inference of episodic positive selection in molecular sequences.

HyphAeon detects site-level episodic diversifying positive selection (dN/dS > 1) across arbitrary codon alignments and phylogenetic trees. It replaces numerical Maximum Likelihood Estimation with an axial geometric transformer using Continuous 4D Tree Rotary Position Embeddings (Tree-RoPE), reaching a 100x-1,000x speedup over HyPhy MEME and PAML CodeML while matching or exceeding their empirical statistical power at a strictly controlled false positive rate.

• —Repository: https://github.com/veg/HyphAeon
• —Architecture notes: ARCHITECTURE.md
• —Developed by: Sergei L. Kosakovsky Pond and collaborators
• —License: MIT

Capabilities

The same model weights power three analyses, exposed as CLI subcommands:

epistasis and phenotype are derived analyses built on the selection model (its per-site drive and branch-level attributions); they do not require separate weights. The results below and the variants concern the core meme model (aliases: predict, site-selection), which the other two consume.

Model variants

This repository provides two weight sets with the same architecture:

The base model is trained on mammals and transfers poorly to viral / shallow-tree alignments; the viral variant fixes this. Both load into the same PhyloAxialTransformer class. .safetensors is recommended; .pt is provided for the upstream loader, and model.viral.onnx for ONNX / browser deployment.

Model details

The model consumes a codon alignment plus a phylogeny and emits, per codon site, a likelihood ratio test statistic for episodic diversifying selection. Asymptotic p-values follow the standard MEME null mixture, 0.5 * delta(0) + 0.5 * chi^2(1).

Usage

Install the package, which pulls these weights automatically on first use:

pip install git+https://github.com/veg/HyphAeon.git

Command line

hyphaeon meme \
  --alignment my_genes.fasta \
  --tree my_genes.nwk \
  --output results.json \
  --csv results.csv

If --tree is omitted, HyphAeon extracts an embedded tree from a NEXUS or FASTA alignment.

Python

from hyphaeon import PhyloAxialTransformer, load_alignment_and_tree

model = PhyloAxialTransformer.from_pretrained("datamonkey/hyphaeon").eval()
codons, aas, dists, mds, invariable, taxa, num_sites = load_alignment_and_tree(
    "my_genes.fasta", "my_genes.nwk"
)

To load the viral fine-tuned variant explicitly:

import torch
from safetensors.torch import load_file
from hyphaeon import PhyloAxialTransformer

model = PhyloAxialTransformer(embed_dim=384, num_layers=6, num_heads=12,
                              window_size=1, num_thresholds=16)
model.load_state_dict(load_file("model.viral.safetensors"))  # hf_hub_download this file
model.eval()

See the repository README for a complete inference loop, including site batching and p-value computation.

Inputs and outputs

Inputs. An in-frame codon alignment (FASTA or NEXUS) and a phylogenetic tree (Newick or NEXUS) with branch lengths. Trees lacking branch lengths are estimated via HyPhy under HKY85 when HyPhy is on the PATH; otherwise strictly positive lower bounds of 1e-4 are enforced, which degrades accuracy.

Outputs. Per codon site: an LRT statistic, an asymptotic p-value, and an invariable-site flag. Sites that are invariable across the alignment are assigned an LRT of 0.

Evaluation

Taking HyPhy MEME (p <= 0.10, asymptotic LRT >= 4.605) as ground truth across 84 empirical datasets from 9 independent literature studies (43,302 codons, up to 476 taxa):

Validation metrics recorded in the base model's training checkpoint: Spearman rho 0.5974, MSE 3.6411, at epoch 16.

(The evaluation above is the base model. For viral / shallow-tree data, see the viral fine-tuned variant below.)

Viral fine-tuned variant

The base model is trained on mammalian (deep-tree) alignments and transfers poorly to viral, shallow-tree data. model.viral.safetensors fine-tunes the base on viral data (with viral sites up-weighted) to fix this, while preserving mammalian performance.

The table below is a controlled comparison of the base model against the fine-tuned model on the same held-out evaluation sets, reporting site-ranking Spearman rho against HyPhy MEME LRT. The numbers are meaningful relative to each other (same data, same metric); they are measured on a viral-focused internal split and are not directly comparable to the literature-benchmark aggregate above, which uses different datasets.

Two takeaways:

1. 1.Viral generalization. On the base model, viral site rankings barely correlate with MEME (rho near zero). After fine-tuning they correlate substantially, and this holds on six viral families that were excluded from fine-tuning entirely, so it is genuine cross-family generalization rather than memorization.
2. 2.No catastrophic forgetting. Re-evaluated on the same held-out mammalian set, the fine-tuned model matches the base model (no measurable drop), so the viral gains do not come at the expense of the mammalian regime the base model was trained for.

On shallow viral alignments MEME's own statistical power is limited, so the fine-tuned model is best used as a fast triage / pre-screen for candidate sites, not as a replacement for a full MEME run.

ONNX deployment note

model.viral.onnx (opset 17) contains the model only. It maps five already-computed input tensors (msa_codons, msa_aas, dist_matrix, mds_coords) to per-site LRT, and is verified to match the PyTorch model to within about 1e-6. The caller must compute the inputs; they are not part of the graph. In particular, mds_coords comes from a classical-MDS eigendecomposition of the patristic distance matrix performed before the model. Reproducing those coordinates bit-for-bit across different eigensolvers is non-trivial, because eigenvector signs and degenerate-subspace rotations are ambiguous, so browser or cross-language ports should account for this.

Limitations and intended use

HyphAeon is a research tool for comparative molecular evolution, intended as a fast screen for sites under episodic diversifying selection.

• —It is trained to approximate HyPhy MEME, so it inherits that method's assumptions and is evaluated against it rather than against ground-truth selection. It is an approximation of MEME, not an independent test of it.
• —Precision falls on large, diverse gene families. On the Hilbert & Elde Siglec/C-lectin set the positive predictive value is 44.8%, so roughly half of flagged sites are not MEME positives. Treat hits as candidates for confirmatory analysis, not conclusions.
• —Aggregate PR-AUC of 0.286 reflects strong class imbalance; positive sites are rare.
• —Accuracy depends on branch lengths being present and meaningful. Topology-only trees are handled but degrade results.
• —Alignments must be in frame. Frameshifted or misaligned input produces silently wrong output.
• —The model has not been evaluated on non-coding sequence, recombinant alignments, or alignments with pervasive sequencing error.

Citation

A publication is in preparation. Until it appears, cite the repository:

@software{hyphaeon,
  title = {HyphAeon: Ultra-Fast Neural Inference of Episodic Positive Selection in Molecular Sequences},
  author = {Kosakovsky Pond, Sergei L. and collaborators},
  url = {https://github.com/veg/HyphAeon},
  year = {2026}
}