Sequence Space

After generating candidate sequences with the VAE, ALSEBO converts each sequence into a fixed-length numerical feature vector. These vectors form the sequence space that the Bayesian optimiser navigates.

The entry point is alsebo.seq_space.generate_seq_space(), which writes seq_space.csv to the experiment directory.

from alsebo.seq_space import generate_seq_space

generate_seq_space(
    exp_dir="./experiment/",
    msa_fname="msa.fasta",
    featuarization_method="DCA",   # "DCA" | "ESM" | "latent"
)

Featurization methods

DCA — Direct Coupling Analysis

DCA captures co-evolutionary information between residue positions by fitting a maximum-entropy statistical model to the MSA. For each sequence, ALSEBO computes a per-position feature vector that combines local field terms (single-site preferences) with pairwise coupling terms (residue–residue interactions):

\[f_i = h_{a_i, i} + \frac{1}{2} \sum_{j \neq i} J_{ij, a_i a_j}\]

where \(h_{a_i, i}\) is the local field for amino acid \(a_i\) at position \(i\), and \(J_{ij, a_i a_j}\) is the coupling between positions i and j.

This is implemented in alsebo.seq_space.compute_dca_features() and called via alsebo.seq_space.generate_dca_features().

When to use: Deep MSAs (>1 000 sequences), when residue co-evolution is informative for the target property.

ESM — Protein Language Model Embeddings

ESM embeddings are produced by passing each sequence through a pre-trained transformer model (facebook/esm2_t30_150M_UR50D by default). The per-token representations are mean-pooled over non-padding positions (excluding <cls> and <eos> tokens) to yield a single vector per sequence:

# Internal flow inside generate_esm_features
outputs = model(**inputs)              # shape: (batch, seq_len+2, embed_dim)
actual_tokens = token_reps[1:seq_len-1]  # strip special tokens
embedding = actual_tokens.mean(dim=0)    # shape: (embed_dim,)

When to use: Shallow MSAs, or when you want rich contextual embeddings that encode structural and functional information learned from millions of proteins.

Latent coordinates

When sequences are generated by the ALSEBO VAE, their 2-D latent coordinates (z0, z1) are stored in the FASTA header. The "latent" method reads these directly from the header, bypassing any sequence-level computation:

>1.5991983967935868 -2.1042084168336674
MKVLILGAGFIGSELTARLHESTGD...

When to use: When you want the BO to navigate directly in the VAE latent space. This is the fastest option and makes the optimisation geometry align exactly with the latent generative landscape.

Output format

All three methods write seq_space.csv with the following structure:

feature_0, feature_1, ..., feature_N, seq_id
0.142,     -0.873,   ...,  0.031,    MKVLILGA...
...

feature_0 … feature_N — the numerical feature vector
seq_id — the raw amino acid sequence string used as the unique identifier

This file is consumed by alsebo.training_space.sample_initial_training_sequnces() and alsebo.optimizer.read_seq_files().