Skip to content

module adabmDCA.api.mutations

High-level mutation-scanning operations.

function scan_mutations

scan_mutations(
    wild_type: 'str',
    model: 'DCAModel | str | Path',
    name: 'str' = 'wild_type',
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32',
    include_gap: 'bool' = True
) → MutationScanResult

Score every single-site substitution of an aligned wild-type sequence.

For each position and each alternative token, the mutant's energy is compared with the wild type's. With the convention E = -sum h - sum J, a negative delta_energy means the model favours the mutant.

Args:

  • wild_type: Aligned sequence of length L using the model's tokens.
  • model: A DCAModel, or a path to a parameter file or PTT archive.
  • name: Label stored in the result and used in exported files.
  • alphabet: Alphabet of a text parameter file: "protein", "rna", "dna" or an ordered custom token string. None reads it from a PTT archive and assumes "protein" for text files. Ignored when model is already a DCAModel.
  • device: "auto" (CUDA when available, else CPU), "cpu", "cuda" or "mps". Ignored for an in-memory model.
  • dtype: "float32" or "float64" for loaded parameters. Ignored for an in-memory model.
  • include_gap: Whether substitutions to the gap token "-" are scored.

Returns: A MutationScanResult with the wild-type energy and one MutationRecord per mutant, L * (q - 1) in total (fewer when gaps are excluded).

Raises:

  • InputValidationError: If wild_type has the wrong length or unknown tokens, or fewer than two tokens are eligible.

Example: 

scan = scan_mutations("MKT...", model="params.dat.gz")
scan.to_dataframe().sort_values("delta_energy").head()

This file was automatically generated via lazydocs.