Structural alphabet predictors

Structural alphabet predictors

Use --nonsyn_recode 3di20 and choose the AA-to-3Di predictor with --sa_backend:

Value	Predictor	Notes
prostt5	ProstT5 encoder-decoder	Original sequential generator
prostt5-cnn	ProstT5 encoder plus CNN	Encoder-only prediction; CPU and GPU execution
esm3di-35m (default)	ESM2-35M plus trained ESM3Di classifier	Small model; released weights trained on viral BFVD data; full-length inference tested through 8192 residues

The predictors can return different 3Di sequences. Their effect on ancestral reconstruction and convergence statistics must be evaluated; changing the backend is not a numerically equivalent acceleration of the original model. In particular, general-protein accuracy of the viral-trained ESM3Di checkpoint is not established by its speed. ESM3Di-35M is the default. Use --sa_backend prostt5 to reproduce the previous predictor.

Install and prepare

python -m pip install "csubst[3di] @ git+https://github.com/kfuku52/csubst"
csubst download --resource prostt5-cnn
csubst download --resource esm3di-35m

The extra installs PyTorch (2.6 or newer), Transformers, PEFT, SentencePiece, protobuf, and huggingface-hub. CNN/ESM3Di checkpoint loading uses weights_only=True. The downloaded CNN and ESM3Di resources are pinned and SHA-256 verified. See csubst download for cache locations and offline preparation.

Run on CPU

For a full-length codon alignment and a matching rooted tree:

csubst inspect --full_cds_alignment_file full-cds.fa --rooted_tree_file tree.nwk \
  --nonsyn_recode 3di20 \
  --sa_asr_mode translate --sa_backend esm3di-35m --sa_device cpu \
  --blas_threads 4 --sa_batch_size 4 --sa_no_download yes

With --nonsyn_recode 3di20, --full_cds_alignment_file is the analysis input. Omit --alignment_file; a different path supplied there is rejected. The full CDS file must be an in-frame alignment containing every tree tip, not a single reference sequence. See bundled dataset contents before using an example untrimmed_cds.fa.gz file.

The shared options also apply to search, scan, and sites. --sa_asr_mode direct predicts tip 3Di sequences before IQ-TREE reconstruction; translate predicts 3Di from reconstructed amino-acid sequences. Both use the selected backend. The optional 3Di PCA feature uses it too. See the PGK recoding PCA comparison for a shared PCA containing all three predictors and the amino-acid recodings. IQ-TREE may omit states absent from its input alignment. CSUBST restores these as zero-probability columns and rejects missing columns for observed states.

--sa_batch_size 0 selects automatic batching, independent of the CPU thread count. Encoder backends sort unique uncached sequences by length and use a padded-token budget of 4096, with an automatic cap of 4 sequences on CPU or 16 on accelerators. A single sequence longer than the budget runs alone. --sa_batch_size 1 disables batching; a positive value changes the sequence cap. The original generator still groups identical lengths. CPU library thread counts are controlled by --blas_threads.

--sa_device, --sa_cache, --sa_cache_file, and --sa_no_download are aliases for the corresponding existing --prostt5_* options. Sequence cache files keep the legacy default name csubst_prostt5_cache.tsv; backend and model identity prevent reuse across predictors. Derived 3Di state caches also distinguish the selected model. State caches validate state order and probabilities: --sa_state_cache auto recomputes invalid caches, while --sa_state_cache yes reports an error.

ESM3Di uses rotary positions and has no fixed 1022-residue cap. Full-length inference was verified through 8192 residues on CPU and Apple MPS. Longer inputs require more compute and memory; this tested length is not a model limit or an accuracy guarantee. No truncation or window splicing is performed.

For implementation details, provenance and the reproducible CPU benchmark, see the repository guide. The CPU benchmark report records repeated timings, memory use and differences between model predictions. The functional audit covers the default selection, caches, sequence boundaries and downstream workflows.

Header-only direct ancestral-state files are rejected before analysis. Sequence cache paths expand ~ consistently when reading and writing. Exported FASTA files use csubst_branch_<branch_id> for unnamed nodes, adding a numeric suffix on a name collision. Named nodes retain their names. This applies to codon, amino-acid and 3Di exports; root records remain excluded. Both encoder backends passed actual CUDA inference checks on audrey1's RTX 6000 Ada with PyTorch 2.6/CUDA 12.4. CPU/CUDA predictions matched on the tested inputs; ESM3Di also passed full-length checks through 8192 residues. See the CUDA validation report.