rdc Module

The synth_pdb.rdc module provides tools for computing and validating Residual Dipolar Couplings (RDCs) — a powerful class of NMR observables that encode the orientation of bond vectors relative to a global molecular alignment frame.

[!NOTE] Core RDC back-calculation is delegated to the synth-nmr package (from synth_nmr.rdc import calculate_rdcs). This module re-exports that engine and adds structural validation tools (Q-factor, file I/O) that live within the synth-pdb ecosystem.

Background

In solution NMR, rapid isotropic tumbling averages magnetic dipole–dipole interactions to zero. When a protein is placed in an anisotropic alignment medium (liquid crystals, phage particles, strained gels), a small residual coupling survives. For a backbone N–H bond vector, this coupling is:

\[D(\theta, \phi) = D_a \left[ (3\cos^2\theta - 1) + \frac{3}{2} R \sin^2\theta \cos(2\phi) \right]\]

where:

Symbol	Meaning
\(\theta\)	Polar angle of the N–H vector relative to the principal alignment axis (Z)
\(\phi\)	Azimuthal angle in the XY plane of the tensor
\(D_a\)	Axial component of the alignment tensor (Hz); typical protein values: 5–25 Hz
\(R\)	Rhombicity, \(0 \leq R \leq 2/3\); \(R=0\) = axially symmetric, \(R=2/3\) = maximum

Why RDCs matter: Unlike NOEs (purely local distances), RDCs encode global fold topology — the orientation of each bond vector in a shared molecular frame. Combined with NOEs, they dramatically improve the accuracy of NMR structure determination.

See Science: NMR Theory and the RDC Alignment Explorer tutorial for interactive demonstrations.

---

API Reference

calculate_rdcs

Back-calculates RDC values from a 3D structure given an alignment tensor. Re-exported from synth-nmr.

from synth_pdb.rdc import calculate_rdcs

rdcs = calculate_rdcs(
    structure,          # biotite AtomArray
    da=15.0,            # Axial component (Hz)
    r=0.1,              # Rhombicity (dimensionless, 0 ≤ R ≤ 2/3)
    euler_angles=(0.0, 0.0, 0.0),  # Rotation into alignment tensor PAS (radians)
)
# Returns: List[Dict] with keys: res_id, atom_1, atom_2, rdc_calc (Hz)

---

calculate_rdc_q_factor

calculate_rdc_q_factor(observed, calculated)

Calculates the Cornilescu Q-factor for RDC validation.

SCIENTIFIC RATIONALE:

The Q-factor provides a quantitative measure of the agreement between experimentally observed RDCs and those back-calculated from a structural model. It is analogous to the R-factor used in X-ray crystallography, measuring the normalized residual of the data fit.

FORMULA (Cornilescu et al., 1998):

Q = sqrt( sum((D_obs - D_calc)^2) / sum(D_obs^2) )

This formulation emphasizes large RDC values, making it highly sensitive to the global orientation of the principal structural motifs.

INTERPRETATION OF RESULTS:

• Q = 0.0: Perfect mathematical agreement (rare in real solutions).
• Q < 0.2: Excellent agreement; typical of high-quality NMR structures.
• Q ~ 0.3-0.5: Moderate agreement; suggests local geometry errors or tensor mismatches.
• Q > 0.5: Poor agreement; indicates potential misfolding or assignment errors in the restraint file.

BIOPHYSICAL SIGNIFICANCE: The Q-factor is the 'gold standard' for NMR structure validation. Because RDCs are so sensitive to global topology, a low Q-factor is strong evidence that the overall protein fold is correct. Conversely, a high Q-factor in the presence of low NOE violations often suggests a mis-orientation of domains or an incorrect alignment tensor.

Parameters:

Name	Type	Description	Default
observed	ndarray	Array of experimentally measured RDC values (Hz).	required
calculated	ndarray	Array of RDCs back-calculated from the model (Hz).	required

Returns:

Name	Type	Description
float	float	The Cornilescu Q-factor (dimensionless ratio).

Q-factor Interpretation

Q-factor	Interpretation
< 0.20	Excellent agreement — high-quality NMR structure
0.20–0.35	Good agreement — minor local geometry errors or dynamics
0.35–0.50	Moderate — investigate alignment tensor or dynamics
> 0.50	Poor — likely misfolding, wrong assignments, or tensor mismatch

import numpy as np
from synth_pdb.rdc import calculate_rdcs, calculate_rdc_q_factor

# Simulate RDCs from a synthetic structure
rdcs_calc = calculate_rdcs(structure, da=15.0, r=0.1)
d_calc = np.array([r["rdc_calc"] for r in rdcs_calc])

# Load experimental RDCs (e.g. from a .rdc file)
from synth_pdb.rdc import read_rdc_file
rdcs_obs = read_rdc_file("ubiquitin_nh.rdc")
d_obs = np.array([r["value"] for r in rdcs_obs])

q = calculate_rdc_q_factor(d_obs, d_calc)
print(f"Q-factor: {q:.3f}")  # e.g. Q-factor: 0.142

---

read_rdc_file

read_rdc_file(file_path)

Reads RDC values from a whitespace-separated file.

SCIENTIFIC RELEVANCE:

RDC data is typically provided as a list of residues and their associated coupling values in Hz. synth-pdb supports the standard NESG/PDB format. This ensures compatibility with legacy NMR data processing pipelines like TALOS+, PALES, and CYANA.

EXPECTED FILE FORMAT (5 Columns):

Column 1: Residue ID of the first nucleus (integer) Column 2: Atom name of the first nucleus (e.g., 'N') Column 3: Residue ID of the second nucleus (integer) Column 4: Atom name of the second nucleus (e.g., 'H') Column 5: The measured RDC value (float, in Hz)

BIOINFORMATICS CONTEXT - Column Alignment: In structural biology, legacy formats often rely on fixed-width or whitespace-delimited columns. While modern databases use XML or JSON, NMR data remains largely text-based for interoperability with C/Fortran simulation kernels. This function provides a robust bridge to those tools.

RESEARCH NOTE: Ensure atom names match the structure object (e.g. 'HN' vs 'H'). Mismatched atom names will lead to KeyError in the structural mapping phase. The file is expected to be a flat text file without binary formatting. Empty lines and lines starting with '#' are ignored.

Parameters:

Name	Type	Description	Default
file_path	str	System path to the RDC file on disk.	required

Returns:

Type	Description
list[dict[str, Any]]	List[Dict[str, Any]]: List of dictionaries containing residue/atom info and the measured coupling value (Hz).

Expected File Format

# N-H RDCs for Ubiquitin in Pf1 phage (Hz)
# Res1  Atom1  Res2  Atom2  Value
1       N      1     HN     -12.4
2       N      2     HN       5.2
3       N      3     HN      18.7

Lines starting with # are treated as comments. Five whitespace-separated columns are required: res1 atom1 res2 atom2 value_hz.

---

Complete Workflow Example

import numpy as np
from synth_pdb import generate_structure
from synth_pdb.rdc import calculate_rdcs, calculate_rdc_q_factor, read_rdc_file

# 1. Generate a synthetic alpha-helical structure
pdb_text = generate_structure(sequence="LKELEKELEKELEKELEKELEKEL", conformation="alpha")

# 2. Parse into AtomArray (requires biotite)
import biotite.structure.io.pdb as pdbio, io
f = pdbio.PDBFile.read(io.StringIO(pdb_text))
structure = pdbio.get_structure(f, model=1)

# 3. Back-calculate backbone N-H RDCs
#    Da = 15 Hz, R = 0.06 (axially symmetric bicelle alignment)
rdcs_calc = calculate_rdcs(structure, da=15.0, r=0.06)

# 4. Validate against experimental data
rdcs_obs  = read_rdc_file("experimental.rdc")
d_obs  = np.array([r["value"]    for r in rdcs_obs])
d_calc = np.array([r["rdc_calc"] for r in rdcs_calc])

q = calculate_rdc_q_factor(d_obs, d_calc)
print(f"Q = {q:.3f}  ({'PASS' if q < 0.25 else 'REVIEW'})")

---

The Alignment Tensor (Saupe Matrix)

The alignment is fully described by the Saupe matrix — a traceless, symmetric 3×3 tensor parameterised by two scalars:

• Da (axial component) — controls the overall magnitude of the RDCs. Larger |Da| → larger couplings.
• R (rhombicity) — controls the asymmetry. R = 0 gives an axially symmetric tensor; R = 2/3 is maximum rhombicity.

Use the interactive RDC Alignment Explorer tutorial to visually understand how Da and R affect the RDC pattern across a helix or sheet.

---

Alignment Media

Medium	Alignment mechanism	Best for
Bicelles (DMPC/DHPC)	Steric	General proteins
Pf1 phage	Electrostatic	High-pI proteins
Polyacrylamide gel	Mechanical compression	Any pH/salt
Liquid crystals (C12E5)	Steric + electrostatic	Small proteins

---

References

1. Tjandra, N. & Bax, A. (1997). Direct measurement of distances and angles in biomolecules by NMR in a dilute liquid crystalline medium. Science, 278, 1111–1114.
2. Cornilescu, G. et al. (1998). Validation of protein structures derived from NMR data using the Q-factor. J. Am. Chem. Soc., 120, 6836–6837.
3. Prestegard, J.H. et al. (2000). NMR structures using field-oriented media and residual dipolar couplings. Q. Rev. Biophys., 33, 371–424.

See Also

• Science: NMR Theory
• Tutorial: RDC Alignment Explorer
• Tutorial: Ubiquitin RDC Validation
• API: nmr module