The encoding table¶

The encoding table is a pandas DataFrame, one row per (site, mutation_letter) combination, that says how a string genotype maps to its packed binary form. It is the load-bearing contract between gpmap-v2 and any package that builds models on top of it.

Schema¶

Worked example¶

For wildtype="AX" and mutations={0: ["A","C","G"], 1: None} (site 1 frozen):

Site 0 has alphabet size 3, so n_bits = 2. Site 1 is frozen and contributes 0 bits. The total n_bits for the map is 2.

Unary-minus-one encoding¶

Each active site contributes alphabet_size - 1 bits. The wildtype letter is the all-zero string. Each non-WT letter sets exactly one bit:

The full binary representation of a genotype is the concatenation of the per-site binary_repr strings, in site_index order. binary_index_start and binary_index_stop give you the slice indices into that concatenation.

Reading from the encoding table¶

gpm.encoding_table[
    ["site_index", "site_label", "mutation_letter", "mutation_index"]
].dropna()

This is the canonical query pattern for downstream consumers like epistasis-v2: drop frozen-site rows and WT rows, then group by site_index to build the per-site mutation index used in the design matrix.

Legacy alias¶

The v1 schema had a column named genotype_index that was actually a site index. The v2 schema renames it to site_index. The old name is still available as a read-only alias for one minor version:

gpm.encoding_table["genotype_index"]  # DeprecationWarning, returns site_index

Writes only go to site_index. The alias issues a DeprecationWarning and will be removed in a future minor release.

Building one manually¶

For most uses you do not need to build the encoding table yourself; it is computed lazily by GenotypePhenotypeMap when you first access gpm.encoding_table. If you need it as a standalone artifact:

from gpmap import get_encoding_table

table = get_encoding_table(
    wildtype="AXG",
    mutations={0: ["A", "T"], 1: None, 2: ["G", "C"]},
)

Validating an externally-built table¶

from gpmap import validate_encoding_table

validate_encoding_table(table)  # raises SchemaError if anything is off

validate_encoding_table checks that all required columns are present, that site_index has no NaN, and that binary_index_stop agrees with the implied n_bits.

Going from strings to packed binary¶

from gpmap import genotypes_to_binary_packed

packed = genotypes_to_binary_packed(["ATG", "ATC"], table)  # shape (2, n_bits), dtype uint8

This is the fastest path from a list of genotype strings to the packed binary representation. Unknown letters raise UnknownLetterError. Under the hood this dispatches to the Rust genotypes_to_binary_packed kernel, parallelized over rows with rayon.

The string-form sibling genotypes_to_binary(...) returns a NumPy object array of '0'/'1' strings. Prefer the packed form for any hot path; the string form is kept for back-compat with v1 consumers.