.. _seq_space:

==============
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 :func:`alsebo.seq_space.generate_seq_space`, which writes
``seq_space.csv`` to the experiment directory.

.. code-block:: python

    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):

.. math::

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

where :math:`h_{a_i, i}` is the local field for amino acid :math:`a_i` at
position :math:`i`, and :math:`J_{ij, a_i a_j}` is the coupling between
positions *i* and *j*.

This is implemented in :func:`alsebo.seq_space.compute_dca_features` and
called via :func:`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:

.. code-block:: python

    # 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:

.. code-block:: text

    >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:

.. code-block:: text

    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 :func:`alsebo.training_space.sample_initial_training_sequnces`
and :func:`alsebo.optimizer.read_seq_files`.