Skip to content

module adabmDCA.api.scoring

High-level sequence-energy operations.

function summed_cde

summed_cde(
    data: 'Tensor',
    params: 'dict[str, Tensor]',
    batch_size: 'int' = 64
) → ndarray

Return summed conditional entropy for each one-hot sequence, in nats.

function fit_local_lambda

fit_local_lambda(
    energies: 'ndarray',
    cde_sum: 'ndarray'
) → dict[str, float | int]

Fit E = intercept + lambda * summed CDE by ordinary least squares.

function score_sequences

score_sequences(
    sequences: 'str | Iterable[str] | None' = None,
    model: 'DCAModel | str | Path',
    fasta_path: 'AlignmentInput | None' = None,
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32',
    remove_duplicates: 'bool' = False,
    local_lambda: 'float | None' = 1.0
) → EnergyResult

Compute DCA energies of aligned sequences, with their local free energies.

Energies follow E(s) = -sum_i h_i(s_i) - sum_{i<j} J_ij(s_i, s_j): lower is more probable under the model. Unless local_lambda is None, each sequence also gets its summed context-dependent entropy (CDE) and the local free energy E - local_lambda * CDE.

Args:

  • sequences: One aligned sequence or an iterable of them, each of length L over the model's tokens. Provide exactly one of sequences and fasta_path.
  • model: A DCAModel, or a path to a parameter file or PTT archive.
  • fasta_path: Alignment to score (path, Alignment or sequences); sequence names are kept in the result.
  • 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.
  • remove_duplicates: With fasta_path, score each distinct sequence once.
  • local_lambda: Weight of the summed CDE in the local free energy, or None to skip the CDE computation.

Returns: An EnergyResult with one energy per sequence, in input order.

Raises:

  • InputValidationError: If both or neither of sequences and fasta_path are given, a sequence is incompatible with the model, or local_lambda is not finite.

Example: 

result = score_sequences(fasta_path="designs.fasta", model="params.dat.gz")
result.to_dataframe().sort_values("energy").head()

function compute_energies

compute_energies(
    sequences: 'str | Iterable[str] | None' = None,
    model: 'DCAModel | str | Path',
    fasta_path: 'AlignmentInput | None' = None,
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32',
    remove_duplicates: 'bool' = False
) → ndarray

Return only the DCA energies of score_sequences, without CDE.

Takes the same arguments as score_sequences except local_lambda.

Returns: A one-dimensional NumPy array with one energy per sequence, also for a single sequence string.

Example: 

compute_energies(["ACGU...", "ACGA..."], model=model)  # array([-212.4, -208.9])

This file was automatically generated via lazydocs.