Skip to content

module adabmDCA.api.model

Notebook-friendly DCA model object.

Global Variables

  • TYPE_CHECKING

function load_model

load_model(
    path: 'str | Path',
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32'
) → DCAModel

Load DCA parameters from a text parameter file or a PTT archive.

The file type is detected from its content. For a PTT archive (.h5), the final model of the training run is loaded together with its alphabet.

Args:

  • path: Parameter file written by adabmDCA train (params.dat, optionally gzipped) or a PTT archive (ptt.h5).
  • alphabet: "protein", "rna", "dna" or an ordered custom token string. None reads it from a PTT archive and assumes "protein" for text files. An explicit value must match the archive.
  • device: "auto" (CUDA when available, else CPU), "cpu", "cuda" or "mps".
  • dtype: "float32" or "float64". PTT archives keep their precision.

Returns: A DCAModel on the requested device.

Raises:

  • ModelLoadError: If the file is missing or cannot be parsed.
  • InputValidationError: If the alphabet is invalid or conflicts with the file.

Example: 

model = load_model("output/params.dat.gz", alphabet="rna")
model  # DCAModel(L=136, q=5, tokens='-ACGU', ...)

function inspect_model

inspect_model(
    model: 'DCAModel | str | Path',
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32'
) → ModelMetadata

Describe a model without using it: length, alphabet, device and precision.

Args:

  • model: A DCAModel, or a path to a parameter file or PTT archive.
  • 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.

Returns: The model's ModelMetadata.

class DCAModel

DCA parameters and convenience methods for scoring and sampling.

Use load_model for a saved model. Construct DCAModel directly when parameter tensors are already in memory. The bias tensor determines the model length L, number of states q, device, and dtype. The ordered tokens string maps state indices to residue symbols.

Attributes:

  • params: Parameter tensors, including bias with shape (L, q) and coupling_matrix with shape (L, q, L, q).
  • alphabet: Standard alphabet name or custom alphabet passed at creation.
  • tokens: Resolved, ordered token string of length q.
  • source: Source path as a string, or None for an in-memory model.

method __init__

__init__(
    params: 'Mapping[str, Tensor]',
    alphabet: 'str' = 'protein',
    source: 'str | Path | None' = None
) → None

Validate and retain a set of DCA parameter tensors.

Args:

  • params: Mapping containing finite bias and coupling_matrix tensors with compatible shapes.
  • alphabet: "protein", "dna", "rna", or an ordered custom token string whose length equals q.
  • source: Optional path to the file from which the parameters came.

Raises:

  • InputValidationError: If required tensors are missing, nonfinite, incompatible in shape, or inconsistent with alphabet.

property metadata

Portable model description derived from the current bias tensor.

Includes length, alphabet, tokens, source, package version, device, and dtype. num_states is available on the returned metadata.

method compute_contact_map

compute_contact_map() → ndarray

Return the model's APC-corrected contact scores.

Returns: A NumPy array of shape (L, L). Contact prediction requires the "-" gap token in the model alphabet.

method compute_energies

compute_energies(sequences: 'str | Iterable[str]') → ndarray

Compute model energies for one or more aligned sequences.

Args:

  • sequences: One sequence string or an iterable of strings, each of length L and containing only the model's tokens.

Returns: A one-dimensional NumPy array with one energy per input sequence, including when a single string is supplied.

method predict_contacts

predict_contacts() → ContactMapResult

Return contact scores together with method and model metadata.

Returns: A ContactMapResult whose score matrix has shape (L, L). The model alphabet must include "-".

method sample

sample(
    n_sequences: 'int',
    n_sweeps: 'int' = 1000,
    sampler: 'str' = 'metropolized_gibbs',
    beta: 'float' = 1.0,
    seed: 'int' = 0
) → tuple[str, ]

Generate sequences and return only their decoded strings.

Args:

  • n_sequences: Number of sequences to generate.
  • n_sweeps: Sampling sweeps applied to the initial chains.
  • sampler: "metropolis", "gibbs" or "metropolized_gibbs".
  • beta: Positive inverse temperature used for sampling.
  • seed: Random seed for reproducible initialization and sampling.

Returns: A tuple of n_sequences strings, each of length L.

method sample_sequences

sample_sequences(n_sequences: 'int', **kwargs) → SamplingResult

Generate sequences with energies and optional diagnostics.

Args:

  • n_sequences: Number of sequences to generate.
  • **kwargs: Additional options accepted by adabmDCA.api.sampling.sample_sequences, such as n_sweeps, sampler, seed, or reference_fasta.

Returns: A SamplingResult containing generated sequences, energies, model metadata, and any requested diagnostics.

method scan_mutations

scan_mutations(wild_type: 'str', name: 'str' = 'wild_type') → MutationScanResult

Score every single-token substitution of a wild-type sequence.

Args:

  • wild_type: Aligned sequence of length L using model tokens.
  • name: Label attached to the resulting mutation scan.

Returns: A MutationScanResult with wild-type energy and each mutant's energy difference relative to the wild type. Gap substitutions are included when "-" is a model token.

method score_sequences

score_sequences(
    sequences: 'str | Iterable[str]',
    local_lambda: 'float' = 1.0
) → EnergyResult

Compute energy and CDE-based local free energy with sequence metadata.

Args:

  • sequences: One aligned sequence or an iterable of aligned sequences compatible with this model.
  • local_lambda: Coefficient of summed CDE; defaults to 1.

Returns: An EnergyResult containing the sequences, energy and local-free-energy vectors, and model metadata.

This file was automatically generated via lazydocs.