Skip to content

module adabmDCA.api.sampling

High-level sequence-generation operations.

Global Variables

  • DEFAULT_PRIVET_WINDOW

function sample_sequences

sample_sequences(
    model: 'DCAModel | str | Path',
    n_sequences: 'int',
    ptt: 'bool' = False,
    ptt_local_sweeps: 'int' = 10,
    ptt_max_rounds: 'int' = 20000,
    ptt_mixing_method: 'str' = 'renewal',
    ptt_renewal_tolerance: 'float' = 0.01,
    ptt_stationary: 'bool' = False,
    ptt_local_kernel: 'str | None' = 'metropolized_gibbs',
    n_sweeps: 'int' = 1000,
    sampler: 'str | None' = 'metropolized_gibbs',
    beta: 'float' = 1.0,
    seed: 'int' = 0,
    reference_fasta: 'AlignmentInput | None' = None,
    weights_path: 'WeightInput | None' = None,
    test_fasta: 'AlignmentInput | None' = None,
    privet_window: 'tuple[float, float]' = (0.01, 0.5),
    n_measure: 'int' = 10000,
    mixing_multiplier: 'int' = 2,
    pseudocount: 'float | None' = None,
    clustering_seqid: 'float' = 0.8,
    no_reweighting: 'bool' = False,
    alphabet: 'str | None' = None,
    device: 'str' = 'auto',
    dtype: 'str | None' = None,
    steering_potential: 'SteeringPotential | None' = None,
    steering_strength: 'float' = 1.0,
    steering_input: 'SteeringInput' = 'sequences',
    steering_proposal_steps: 'int | None' = None,
    ptt_steering_acceptance: 'float' = 0.3,
    collect_diagnostics: 'bool' = False,
    ptt_return_full_ladder: 'bool' = False,
    progress: 'ProgressCallback | None' = None,
    is_cancelled: 'CancellationHook | None' = None
) → SamplingResult

Generate sequences from a DCA model, with an energy for each.

Ordinary sampling runs n_sequences independent Markov chains. With reference_fasta, their mixing time is first measured (up to n_sweeps sweeps) and generation runs for mixing_multiplier mixing times; otherwise it runs for exactly n_sweeps sweeps.

PTT sampling (ptt=True, a PTT archive, or a PTTSampler as model) instead uses the replica ladder saved during training: the exact profile, the models flagged during training and the endpoint. It runs at beta=1, ignores n_sweeps, and equilibrates until its mixing check passes. A PTTSampler passed as model is forked, not modified. Every result includes the summed context-dependent entropy (CDE) of each sequence and, when identifiable, a least-squares fit of energy against it.

Steered (importance) sampling. With steering_potential, sequences are drawn from p_s(x) ∝ exp(-beta * H(x) - V(x, s)) instead, where V(x, s) = steering_potential(x, s) and s = steering_strength: low V is favoured, so return -s * score to favour high scores. V is called on batches: a list of aligned sequence strings (steering_input="sequences") or a one-hot tensor (n, L, q) on the model's device and precision ("onehot"), and must return one number per sequence, and 0 when s == 0. Each Monte Carlo move proposes steering_proposal_steps Gibbs updates under the DCA model, at random sites visited in palindromic order (which makes the proposal reversible), and accepts them with probability min(1, exp(-ΔV)). This samples p_s exactly while calling V once per chain and move; sampler and ptt_local_kernel do not apply to steered moves.

With PTT, steered rungs of increasing strength are added above the trained endpoint until steering_strength is reached, keeping the swap acceptance between them at least ptt_steering_acceptance; the ladder's bottom is unchanged, so the mixing check still applies, and PTT also estimates log Z_s - log Z_0. The result's log_importance_weights turn averages over the steered sequences into averages under the original model.

Args:

  • model: A DCAModel, a path to a parameter file or PTT archive, or a PTTSampler.
  • n_sequences: Number of sequences to generate.
  • ptt: Sample with PTT from the archive given as model.
  • ptt_local_sweeps: PTT: local sweeps per exchange round.
  • ptt_max_rounds: PTT: largest number of exchange rounds of the mixing check.
  • ptt_mixing_method: PTT: "renewal" waits until the ladder has twice been repopulated by exact profile draws, leaving at most ptt_renewal_tolerance of older configurations at the endpoint; "autocorrelation" measures the replica-index autocorrelation times and spaces output batches by twice the integrated time.
  • ptt_renewal_tolerance: PTT renewal: largest remaining fraction of old configurations.
  • ptt_stationary: PTT renewal: add a stationary renewal after the warmup.
  • ptt_local_kernel: PTT: "metropolized_gibbs", "metropolis" or "gibbs"; None keeps the kernel used in training.
  • n_sweeps: Sweeps of ordinary sampling, or the mixing-time budget when reference_fasta is given.
  • sampler: "metropolized_gibbs", "gibbs" or "metropolis". For PTT, select the local update with ptt_local_kernel instead.
  • beta: Inverse temperature (ordinary sampling only).
  • seed: Random seed.
  • reference_fasta: Natural alignment used to measure mixing and to compare the generated statistics; required for PTT and for collect_diagnostics.
  • weights_path: Optional weights of the reference sequences.
  • test_fasta: Optional held-out alignment (e.g. the validation split). With collect_diagnostics, nearest-neighbour distances from it to the reference give the yardstick for the generated sequences' distances to the training set, and PRIVET compares each generated sequence's distances to both sets (overfitting check).
  • privet_window: Quantiles (q1, q2) of the training nearest-neighbour distances fitted by PRIVET's extreme-value law.
  • n_measure: Largest number of reference sequences used for the comparison.
  • mixing_multiplier: Ordinary sampling: mixing times to run after measuring one.
  • pseudocount: Pseudocount of the reference statistics; 1/Meff if None.
  • clustering_seqid: Identity threshold for reweighting the reference.
  • no_reweighting: Give every reference sequence the same weight.
  • alphabet: Alphabet of a text parameter file; None reads it from a PTT archive and assumes "protein" for text files.
  • device: "auto", "cpu", "cuda" or "mps".
  • dtype: "float32", "float64" or "bfloat16" (CUDA/MPS, unsteered sampling only; CUDA only with PTT); None means "float32", or the archive's precision.
  • steering_potential: Optional potential(batch, strength) added to the DCA energy, returning one value per sequence (list, NumPy array or tensor) and 0 at strength 0. None samples the model itself.
  • steering_strength: Non-zero strength s passed to the potential.
  • steering_input: What the potential receives: "sequences" (a list of aligned strings, convenient for external tools) or "onehot" (a tensor (n, L, q), fastest for potentials written in PyTorch).
  • steering_proposal_steps: Site updates per steered move; None adapts it during warmup (doubling above 50% acceptance, halving below 20%, at most 16 sweeps' worth) and then keeps it fixed. Small values suit strong or rugged potentials; larger ones need fewer potential evaluations per sweep.
  • ptt_steering_acceptance: PTT steering: smallest swap acceptance between adjacent steered rungs; higher values place more rungs.
  • collect_diagnostics: Keep the correlations and PCA projections needed by SamplingResult.save_diagnostic_plots.
  • ptt_return_full_ladder: PTT: also keep n_sequences samples of every model of the ladder, from the profile to the endpoint, in the result's ladder_samples (written by SamplingResult.to_ladder_hdf5).
  • progress: Optional callback receiving SamplingProgress events.
  • is_cancelled: Optional callable; returning True stops sampling.

Returns: A SamplingResult with the sequences, energies and diagnostics.

Raises:

  • InputValidationError: If a setting is invalid or incompatible with PTT.
  • OperationCancelledError: If is_cancelled returns True.

Example: 

result = sample_sequences(model="params.dat.gz", n_sequences=1000,
                          reference_fasta="family.fasta")
result.to_fasta("samples.fasta")

Steering towards sequences with a high GC content (RNA), as strings:

def gc_potential(sequences, strength):
    return [-strength * sum(c in "GC" for c in s) / len(s) for s in sequences]
steered = sample_sequences(model="params.dat.gz", alphabet="rna", n_sequences=500,
                           steering_potential=gc_potential, steering_strength=20.0)
steered.steering["effective_sample_size"], steered.log_importance_weights[:3]

function generate_sequences

generate_sequences(**kwargs: 'Any') → tuple[str, ]

Return only the sequences of sample_sequences.

Args:

  • **kwargs: Keyword arguments of sample_sequences; model and n_sequences are required.

Returns: The generated sequences.

Example: 

generate_sequences(model="params.dat.gz", n_sequences=10, n_sweeps=500)

This file was automatically generated via lazydocs.