nu-dependent self-avoiding walk

Usage examples and full code reference for NuDepSAW. For the underlying theory, see nu-dependent self-avoiding walk.

Quick start

from afrc.polymer_models.nudep_saw import NuDepSAW

model = NuDepSAW('MASNDYTQQATQSYGAYPTQPGQGYSQQSSQPYG')

# the scaling exponent nu is supplied per call (default nu = 0.5)
model.get_mean_end_to_end_distance(nu=0.5)
model.get_root_mean_squared_end_to_end_distance(nu=0.5)
model.get_mean_radius_of_gyration(nu=0.5)

# full end-to-end distribution (distances, probabilities)
r, p = model.get_end_to_end_distribution(nu=0.5)

# draw a size-matched sample
samples = model.sample_end_to_end_distribution(n=1000, nu=0.5)

Sweep the scaling exponent from collapsed (nu ~ 1/3) to fully expanded (nu ~ 0.588):

for nu in (0.40, 0.50, 0.59):
    print(nu, model.get_mean_end_to_end_distance(nu=nu))

See also the demo/demo_NuDepSAW.ipynb notebook for a worked, plotted example.

Generating 3D ensembles

Generate explicit conformations (one bead per residue), write them to disk, and check how well they reproduce the model:

model = NuDepSAW('MASNDYTQQATQSYGAYPTQPGQGYSQQSSQPYG')

xyz = model.sample_conformations(n=5000, seed=1, nu=0.55, prefactor=5.5)                 # [n x N x 3] array, Angstroms
model.save_ensemble('ens', n=5000, seed=1, nu=0.55, prefactor=5.5)                       # ens.pdb + ens.xtc (needs mdtraj)
print(model.check_ensemble(xyz, nu=0.55, prefactor=5.5).format())                  # the model-check report

A Gaussian approximation: the mean-squared distances are exact, but the distance distributions are Gaussian and there is no excluded volume (see nu-dependent self-avoiding walk).

Or from the command line: afrc-ensemble -s <sequence> -m saw-nu (see Command-line tools).

Code reference

class afrc.polymer_models.nudep_saw.NuDepSAW(seq: str, p_of_r_resolution: float = 0.05)

Self-avoiding walk with the Flory scaling exponent \(\nu\) as a free parameter, as developed by Zheng et al. [1] and written by Soranno [2].

This is the same universal scaling form used by the fixed-exponent SAW, but with \(\nu\) left free, so a single model spans a collapsed globule (\(\nu \approx 1/3\)), the ideal chain (\(\nu = 0.5\)) and a good-solvent coil (\(\nu \approx 0.588\)). Both nu and prefactor are passed to each method rather than set on the object.

This is a composition-independent reference model: the sequence is only used to set the number of residues.

References

[1] Zheng, W., Zerze, G. H., Borgia, A., Mittal, J., Schuler, B., & Best, R. B. (2018). Inferring properties of disordered chains from FRET transfer efficiencies. The Journal of Chemical Physics, 148(12), 123329.

[2] Soranno, A. (2020). Physical basis of the disorder-order transition. Archives of Biochemistry and Biophysics, 685, 108305.

__init__(seq: str, p_of_r_resolution: float = 0.05) → None

Create a NuDepSAW object.

Parameters:

seq (str) – Amino acid sequence. Only its length is used, and it is not validated.
p_of_r_resolution (float) – Grid spacing (in Angstroms) used for the distribution. Default is 0.05 A.

check_ensemble(conformations: NDArray[float64], nu: float = 0.5, prefactor: float = 5.5) → EnsembleReport

Check how well an ensemble reproduces the nu-dependent self-avoiding walk.

The exact checks are the mean-squared distance of every residue pair (in bands of separation) and the root-mean-square radius of gyration and first-to-last distance that follow from them. The SAW’s analytical (des Cloizeaux) end-to-end distribution and its radius of gyration from the universal SAW ratio are reported as context, together with a note that ensembles from sample_conformations() are a Gaussian approximation.

Parameters:

conformations (np.ndarray) – Array of shape [n_conformations x N x 3] (in Angstroms).
nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms, so that the root-mean-square distance between residues k apart is prefactor * k**nu. Default is 5.5 A.

Returns:

The checks; report.passed says whether the ensemble is model-like and report.format() gives a printable report.

Return type:

EnsembleReport

Raises:

AFRCException – If the conformations do not match this chain.
NuDepSAWException – If a parameter is out of range.

get_end_to_end_distribution(nu=0.5, prefactor=5.5)

Return the end-to-end distance distribution.

Because nu and prefactor can change between calls, the distribution is recomputed every time rather than cached.

Parameters:

nu (float) – Flory scaling exponent. Must lie strictly between 0 and 1; physically meaningful values run from ~0.33 to ~0.6. Default is 0.5.
prefactor (float) – Size scale in Angstroms, such that the root-mean-square end-to-end distance is prefactor * N**nu. Default is 5.5 A. Must be > 0.

Returns:

(distances, probabilities), where distances are in Angstroms and the probabilities are a normalized probability mass function (they sum to 1).

Return type:

tuple of np.ndarray

Raises:

NuDepSAWException – If nu is not strictly between 0 and 1, or prefactor is not positive.

get_mean_end_to_end_distance(nu=0.5, prefactor=5.5)

Return the mean end-to-end distance, \(\langle R_e \rangle\).

This is the expectation over the end-to-end distribution, \(\sum r P(r)\).

Parameters:

nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms. Default is 5.5 A.

Returns:

The mean end-to-end distance (in Angstroms).

Return type:

float

Raises:

NuDepSAWException – If nu or prefactor is out of range.

get_mean_radius_of_gyration(nu=0.5, prefactor=5.5)

Return the root-mean-square radius of gyration, \(\sqrt{\langle R_g^2 \rangle}\).

This is obtained from the root-mean-square end-to-end distance via the universal ratio

\[\frac{\langle R_g^2 \rangle}{\langle R_e^2 \rangle} = \frac{\gamma(\gamma + 1)}{2(\gamma + 2\nu)(\gamma + 2\nu + 1)}\]

evaluated at the chosen \(\nu\). Note that despite the method name this is the root-mean-square radius of gyration, not \(\langle R_g \rangle\). The name is kept for consistency with the other models.

Parameters:

nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms. Default is 5.5 A.

Returns:

The root-mean-square radius of gyration (in Angstroms).

Return type:

float

Raises:

NuDepSAWException – If nu or prefactor is out of range.

get_mean_squared_distance_map(nu: float = 0.5, prefactor: float = 5.5) → NDArray[float64]

Return the model’s mean-squared distance between every pair of residues.

Applying the model’s size scaling to every pair of residues, \(\langle r_{ij}^2 \rangle = (\texttt{prefactor}\, |i - j|^{\nu})^2\).

Parameters:

nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms, so that the root-mean-square distance between residues k apart is prefactor * k**nu. Default is 5.5 A.

Returns:

Symmetric [N x N] matrix of mean-squared distances (in Angstroms squared), with zeros on the diagonal.

Return type:

np.ndarray

Raises:

NuDepSAWException – If a parameter is out of range.

get_root_mean_squared_end_to_end_distance(nu=0.5, prefactor=5.5)

Return the root-mean-square end-to-end distance, \(\sqrt{\langle R_e^2 \rangle}\).

This is the square root of \(\sum r^2 P(r)\) over the end-to-end distribution, and equals prefactor * N**nu.

Parameters:

nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms. Default is 5.5 A.

Returns:

The root-mean-square end-to-end distance (in Angstroms).

Return type:

float

Raises:

NuDepSAWException – If nu or prefactor is out of range.

sample_conformations(n: int = 1000, seed: int | Generator | None = None, nu: float = 0.5, prefactor: float = 5.5) → NDArray[float64]

Generate 3D conformations (one bead per residue) approximating the nu-dependent self-avoiding walk.

This is a Gaussian approximation: the bead coordinates are drawn exactly from the Gaussian chain whose mean-squared inter-residue distances are the model’s, \((\texttt{prefactor}\, |i - j|^{\nu})^2\), so the size and scaling of every inter-residue distance are right. The distance distributions are Gaussian rather than the SAW’s des Cloizeaux form, and there is no excluded volume, so beads can overlap. (Genuine self-avoiding conformations would need an explicit simulation.)

Parameters:

n (int) – Number of conformations. Default is 1000.
seed (int, np.random.Generator or None) – Seed (or generator) for reproducible ensembles. If None (default) a fresh, unpredictable seed is used.
nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms, so that the root-mean-square distance between residues k apart is prefactor * k**nu. Default is 5.5 A.

Returns:

Array of shape [n x N x 3] with the bead coordinates, in Angstroms, each conformation centred on the origin.

Return type:

np.ndarray

Raises:

AFRCException – If n is not a positive integer.
NuDepSAWException – If a parameter is out of range.

sample_end_to_end_distribution(n=1000, nu=0.5, prefactor=5.5)

Draw random end-to-end distances from the distribution.

Useful for building a size-matched sample to compare against simulation data.

Parameters:

n (int) – Number of values to draw. Default is 1000.
nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms. Default is 5.5 A.

Returns:

n independent end-to-end distances (in Angstroms). For a zero-length chain every value is 0.

Return type:

np.ndarray

Raises:

NuDepSAWException – If nu or prefactor is out of range.

save_ensemble(filename: str, n: int = 1000, seed: int | Generator | None = None, pdb_only: bool = False, nu: float = 0.5, prefactor: float = 5.5) → NDArray[float64]

Generate a nu-dependent self-avoiding walk ensemble (Gaussian approximation) and write it to disk.

Writes <filename>.pdb (topology and first conformation) and <filename>.xtc (every conformation; needs mdtraj), or with pdb_only=True a single multi-model <filename>.pdb. See sample_conformations() for how the conformations are generated.

Parameters:

filename (str) – Output path without an extension (a trailing .pdb or .xtc is dropped).
n (int) – Number of conformations. Default is 1000.
seed (int, np.random.Generator or None) – Seed (or generator) for reproducible ensembles.
pdb_only (bool) – Write a single multi-model PDB instead of a PDB/XTC pair. Default is False.
nu (float) – Flory scaling exponent, strictly between 0 and 1. Default is 0.5.
prefactor (float) – Size scale in Angstroms, so that the root-mean-square distance between residues k apart is prefactor * k**nu. Default is 5.5 A.

Returns:

The conformations that were written, shape [n x N x 3] (Angstroms).

Return type:

np.ndarray

Raises:

AFRCException – If n is invalid, the sequence has non-standard amino acids, mdtraj is missing (for a PDB/XTC pair), or the PDB format limits are exceeded.
NuDepSAWException – If a parameter is out of range.