sspre

Overview

sspre provides tools for computing synthetic paramagnetic relaxation enhancement (PRE) profiles from MD simulation ensembles and comparing them to experimental NMR data. The module exposes a single class, SSPRE, which wraps an SSProtein object together with the experimental parameters of the PRE measurement.

What PRE profiles measure. In a PRE experiment, a nitroxide spin label (typically a MTSL-labelled cysteine) is introduced at a specific sequence position. The unpaired electron of the spin label accelerates the relaxation of nearby backbone amide protons, reducing their observed NMR signal intensity. The key observables are:

  • Intensity ratio \(I_\text{para} / I_\text{dia}\) — ratio of signal intensities in the paramagnetic vs. diamagnetic sample, ranging from 0 (near the label) to 1 (far away).

  • Transverse relaxation rate \(\Gamma_2\) — the spin-label-induced relaxation rate enhancement (in Hz), a complementary observable.

Physical model. The calculation uses the Solomon–Bloembergen framework: for each residue, the \(r^{-6}\)-weighted mean distance to the paramagnetic centre is averaged over all frames of the trajectory. This ensemble averaging correctly captures the non-linear distance dependence of PRE relaxation and is the approach validated in the references below. As of SOURSOP 2.0.2 the paramagnetic centre is, by default, a coarse-grained spin-label cloud (see below) rather than a point on the spin_label_atom.

Warning

Breaking change in SOURSOP 2.0.2. generate_PRE_profile now defaults to use_label=True, so the paramagnetic centre is modelled as a DEER-PREdict-calibrated spin-label cloud rather than sitting directly on the CB atom. This yields different — and more accurate — profiles than SOURSOP ≤ 2.0.1. To reproduce results from earlier versions exactly, pass use_label=False.

Workflow. An SSPRE object is created by supplying an SSProtein and the four experimental parameters: effective correlation time \(\tau_c\) (ns), INEPT delay \(t_\text{delay}\) (ms), diamagnetic transverse relaxation rate \(R_{2D}\) (Hz), and proton Larmor frequency \(\omega_H\) (Hz). generate_PRE_profile then computes the full-length intensity ratio and \(\Gamma_2\) profiles for a given label position:

from soursop.sstrajectory import SSTrajectory
from soursop.sspre import SSPRE

TrajOb = SSTrajectory('traj.xtc', 'start.pdb')
protein = TrajOb.proteinTrajectoryList[0]

# 600 MHz magnet, tau_c = 5 ns, t_delay = 16 ms, R_2D = 10 Hz
pre = SSPRE(protein, tau_c=5, t_delay=16, R_2D=10, W_H=600000000)

# spin label at residue 42; uses the calibrated label-cloud model by default
intensity_ratio, gamma2 = pre.generate_PRE_profile(label_position=42)

Coarse-grained spin-label cloud (the default since 2.0.2). Rather than placing the paramagnetic centre directly on the spin_label_atom (CB), the nitroxide is modelled as a coarse-grained cloud of beads placed a fixed label_distance (default 7.0 Å) from the anchor atom — the geometry of an MTSL side chain — without requiring an explicit all-atom rotamer library. When a distinct CB is available the cloud is a cone about the CA→CB direction (so it points away from the backbone); on coarse-grained CA-only chains it falls back to a full isotropic sphere, so the same call works at both resolutions. The relaxation is averaged over the whole cloud as well as over frames, so the \(r^{-6}\) non-linearity is preserved across both the conformer cloud and the ensemble. The cloud is generated deterministically (a Fibonacci lattice), so results are reproducible. To recover the classic point-at-CB model used by SOURSOP ≤ 2.0.1, pass use_label=False:

# explicit calibrated label-cloud model (this is now the default)
intensity_ratio, gamma2 = pre.generate_PRE_profile(label_position=42, use_label=True)

# classic point-at-CB model (SOURSOP <= 2.0.1 behaviour)
intensity_ratio, gamma2 = pre.generate_PRE_profile(label_position=42, use_label=False)

Steric exclusion of the label bead against the chain is always applied under use_label=True, either as a 'hard' cutoff (beads within label_bead_radius of any non-label CA are dropped) or a 'soft' WCA-like repulsive wall (the default). The defaults (label_steric='soft', label_bead_radius=5.5 Å, label_wall_stiffness=6.0) were calibrated against DEER-PREdict’s explicit MTSL rotamer PRE profiles across 85 disordered and ~2700 folded label sites; the soft wall is marginally more accurate than the hard cutoff and transfers better between folded and disordered chains. This stops the cloud from being placed through the protein interior, which matters most for folded/compact structures. See the generate_PRE_profile docstring below for the full list of label_* arguments.

Key references. The methodology is described in the supplementary information of:

  • Meng, W., Lyle, N., Luan, B., Raleigh, D.P., and Pappu, R.V. (2013). Proc. Natl. Acad. Sci. U. S. A. 110, 2123–2128.

  • Das, R.K., Huang, Y., Phillips, A.H., Kriwacki, R.W., and Pappu, R.V. (2016). Proc. Natl. Acad. Sci. U. S. A. 113, 5616–5621.

  • Peran, I., Holehouse, A. S., Carrico, I. S., Pappu, R. V., Bilsel, O., & Raleigh, D. P. (2019). Proc. Natl. Acad. Sci. U. S. A. 116(25), 12301–12310.

class soursop.sspre.SSPRE(SSProteinObject, tau_c, t_delay, R_2D, W_H)[source]

Synthetic paramagnetic relaxation enhancement (PRE) calculations.

Wraps an SSProtein ensemble and computes intramolecular PRE intensity ratios and the associated transverse relaxation enhancement (gamma) profiles for a nitroxide spin label placed at an arbitrary sequence position. The model follows the approach used by Meng & Lyle (PNAS 2013), Das et al. (PNAS 2016) and Peran & Holehouse (PNAS 2019), and is fast enough to apply to large (multi-thousand frame) disordered-protein ensembles.

A typical workflow is to extract an SSProtein from an SSTrajectory, construct an SSPRE object with the relevant experimental parameters (effective correlation time, INEPT delay, diamagnetic transverse relaxation rate and proton Larmor frequency) and then call generate_PRE_profile for one or more label positions. The bound SSProtein is treated as read-only and is not modified.

Example

>>> P = traj.proteinTrajectoryList[0]
>>> spre = SSPRE(P, tau_c=5.0, t_delay=10.0, R_2D=10.0, W_H=600000000)
>>> profile, gamma = spre.generate_PRE_profile(label_position=42)
__init__(SSProteinObject, tau_c, t_delay, R_2D, W_H)[source]

Build an SSPRE object bound to a single-chain protein ensemble.

Stores the bound SSProtein and the experimental parameters, runs physiological sanity checks on the inputs (emitting an SSWarning for values far outside their normal range without blocking analysis) and precomputes the spectral-density prefactor used by generate_PRE_profile. The resulting object can then be used to calculate PRE profiles from the underlying ensemble; the calculation is extremely fast.

Parameters:

  • SSProteinObject (soursop.ssprotein.SSProtein) – SSProtein object extracted from an SSTrajectory. This is the main object over which protein-centric analysis is performed in SOURSOP. It is treated as read-only.

  • tau_c (float) – Effective rotational correlation time in nanoseconds, typically between 1 and 30.

  • t_delay (float) – Total duration of the INEPT delays in the PRE experiment, in milliseconds. Depends on the pulse sequence but is typically ~1-30 ms for an HSQC.

  • R_2D (float) – Transverse relaxation rate of the backbone amide protons in the diamagnetic form of the protein, in Hz (per second). A value of around 10 is typical.

  • W_H (float) – Proton Larmor frequency of the magnet, in Hz - i.e. the nominal “MHz” rating of the magnet expressed in Hz (a 600 MHz magnet uses 600000000). The proton Larmor frequency at 1 Tesla is 267530000 per second per Tesla.

Raises:

soursop.ssexceptions.SSException – If SSProteinObject is not an SSProtein instance.

Example

>>> P = traj.proteinTrajectoryList[0]
>>> spre = SSPRE(P, tau_c=5.0, t_delay=10.0, R_2D=10.0, W_H=600000000)
generate_PRE_profile(label_position, spin_label_atom='CB', target_relaxation_atom='N', use_label=True, label_distance=7.0, label_cone_angle=130.0, n_label_conformers=100, label_bead_radius=5.5, label_steric='soft', label_wall_stiffness=6.0)[source]

Compute the PRE intensity ratio and gamma profile for a spin label.

Places a nitroxide spin label on the spin_label_atom of residue label_position and, for every residue that has a cached CA atom, computes the spin-label-induced transverse relaxation enhancement (the gamma profile) and the corresponding paramagnetic/diamagnetic intensity ratio (the PRE profile). By default the label is on CB and relaxation is assessed from the CB-to-backbone-N distances, matching the parameterisation used by Meng, Lyle, Luan, Raleigh & Pappu (PNAS 2013, 110:2123-2128), Das, Huang, Phillips, Kriwacki & Pappu (PNAS 2016, 113:5616-5621) and Peran, Holehouse, Carrico, Pappu, Bilsel & Raleigh (PNAS 2019, 116:12301-12310).

The PRE profile is the intensity ratio (Iparamagnetic / Idiamagnetic) and typically lies between 0 and 1: a ratio near 0 means the spin label dominates relaxation (the residue is, on average, close to the label) while a ratio near 1 means relaxation is dominated by non-spin-label mechanisms (the residue is far from the label). The gamma profile is the spin-label-induced amide-proton relaxation rate in per-second units, a second observable directly comparable with experiment.

The r^-6 distance dependence is averaged after the per-frame relaxation is computed (not by averaging distances first), because the distance-to-relaxation mapping is non-linear. This routine is extremely fast (sub-10 s on a ~6000-frame ensemble).

Note

Breaking change (SOURSOP 2.0.2). use_label now defaults to True, so by default the paramagnetic centre is modelled as a coarse-grained spin-label cloud calibrated against DEER-PREdict (see use_label below) rather than sitting directly on the spin_label_atom. This produces different (and more accurate) profiles than SOURSOP <= 2.0.1. To recover the previous point-at-CB behaviour exactly, pass use_label=False.

Parameters:

  • label_position (int) – Sequence position at which the spin label is located. Should contain a CB atom (i.e. not be glycine) unless spin_label_atom is changed to 'CA' (see below).

  • spin_label_atom (str, optional) – Name of the atom on which the spin label sits. Should be 'CB' but may be changed if the labelled residue lacks a CB (e.g. a glycine in place of the cysteine nitroxide site). Default 'CB'.

  • target_relaxation_atom (str, optional) – Name of the atom at which relaxation is evaluated. This should be 'N' (backbone amide), as that is how the approach is parameterised; an atom of this name is searched for in every residue. Changing it is strongly discouraged. Default 'N'.

  • use_label (bool, optional) – If True (the default as of SOURSOP 2.0.2), the paramagnetic centre is not taken to sit on the spin_label_atom itself but is instead modelled as a coarse-grained cloud of n_label_conformers beads placed a fixed label_distance away from that atom, mimicking the geometry of an MTSL nitroxide side chain without requiring an all-atom rotamer library. For every frame the relaxation is averaged over the whole cloud (and, as always, over frames), so the r^-6 non-linearity is respected across both the conformer cloud and the ensemble. This works on both all-atom and coarse-grained (CA-only) trajectories, and the default label_* parameters below are calibrated against DEER-PREdict. Set use_label=False to recover the classic point-at-spin_label_atom behaviour used by SOURSOP <= 2.0.1.

  • label_distance (float, optional) – Distance, in Angstroms, from spin_label_atom to the cloud of label beads. The default of 7.0 A is the mean CB-to-electron distance of the MTSSL 175K X1X2 rotamer library. Only used when use_label is True.

  • label_cone_angle (float, optional) – Half-angle, in degrees, of the cone (about the CA->CB direction) within which the label cloud is distributed. A wide cone (default 130 deg) reproduces the broad lateral spread of the MTSL side chain while excluding directions that point back into the backbone. If the labelled residue has no CB distinct from the anchor atom (e.g. a CA-only coarse-grained bead, or the anchor is CA), the cloud falls back to a full isotropic sphere and this argument is ignored. Only used when use_label is True.

  • n_label_conformers (int, optional) – Number of beads in the label cloud. The cloud is generated deterministically (a Fibonacci lattice), so results are reproducible. Default 100. Only used when use_label is True.

  • label_bead_radius (float, optional) – Effective steric radius of the coarse-grained label bead, in Angstroms. Steric exclusion is always applied in the label model. For label_steric='hard' any bead whose centre lies within this radius of a CA atom of a different residue is dropped from that frame’s average; for 'soft' it is the distance scale of the repulsive wall (see label_steric). This mimics the steric pruning that DEER-PREdict applies to its rotamer library and stops the cloud being placed through the protein interior (critical for folded/compact structures). The default was calibrated to most closely reproduce DEER-PREdict’s explicit MTSL rotamer PRE profiles; it is not a bare CA-CA contact distance. Only used when use_label is True.

  • label_steric ({'hard', 'soft'}, optional) – How the bead cloud is sterically excluded from the chain. 'hard' (default) keeps a bead only if it clears every non-label CA by label_bead_radius and averages uniformly over the survivors. 'soft' instead weights every bead by a smooth WCA-like repulsive wall against the CA atoms, w_i = exp(-sum_j (label_bead_radius / d_ij)**label_wall_stiffness), and takes the weighted cloud average. The soft wall reduces to the hard cutoff as label_wall_stiffness grows, but is less sensitive to label_bead_radius and transfers better between folded and disordered chains. Only used when use_label is True.

  • label_wall_stiffness (float, optional) – Exponent of the soft repulsive wall (only used when label_steric='soft'). Larger values give a sharper wall that approaches the hard cutoff; smaller values give a softer, longer ranged penalty. Default 6.0 (calibrated against DEER-PREdict). Only used when use_label is True.

Returns:

A 2-tuple (profile, gamma) where profile is the PRE intensity ratio and gamma is the spin-label-induced amide proton relaxation rate (per second), each with one entry per CA-containing residue (in ascending residue order).

Return type:

tuple of (list of float, list of float)

Example

>>> profile, gamma = spre.generate_PRE_profile(label_position=42)
>>> len(profile) == len(gamma)
True