PhiPsi_restraints (CNS; backbone torsion angle).

Section author: Michael S. Chapman <chapmanms@missouri.edu>

Module author: Michael S. Chapman <chapmanms@missouri.edu>

Authors:

Michael S. Chapman <chapmanms@missouri.edu>,

Oregon Health & Science University and University of Missouri

Version:

1, Nov 18, 2025

usage:

phipsi_restraints.py [-h] -t <phi_min, phi_max, psi_min, psi_max> -n <name> [-t <phi_min, phi_max, psi_min, psi_max> -n <name> …] -g <phi_min, phi_max, psi_min, psi_max> -N <name> [-g <phi_min, phi_max, psi_min, psi_max> -N <name> …] [-G ] <input-pdb-file> <output-file>

where <output-file> is a CNS additional restraints file that can be edited.

Synopsis

Generates a text file of CNS supplementary retraints to penalize variation of backbone torsion angles outside user-defined (φ, ψ) regions of a Ramachandran plot.

CNS’ restraints were designed to penalize deviations from a known homologous structure, and is adapted here to drive generally to favored (φ, ψ) angles. This is done by restraining not towards a single angle, but towards the (φ, ψ) angles of the closest favored area of the Ramachandran plot. There is no longer a need for a target homologous structure: one can use the (φ, ψ) targets at the centers of the favored Ramachandran regions closest to the current structure. By using a flat bottom potential well, it is possible to allow equally any (φ, ψ) that is within the limits of the favored area, penalizing only deviations that take a residue outside the boundaries of a favored area.

Usage

Using command-line arguments, the user defines square regions on the Ramachandran plot that are allowable. These might correspond to the α and β regions that are commonly marked as favorable on a Ramachandran plot. Non-square areas are supported by the user supplying multiple overlapping boxes, with residues allowed to have (φ, ψ) in any of the boxes (logical OR).

Optionally, the user can provide separate box definitions for glycine residues, and dictate whether these are to be expanded centrosymmetrically to account for the increased (φ, ψ) combinations allowed. (Distinctions between other types of residues are not supported.)

The output text file can be read as commands of supplementary restraints by a CNS job. Typically, one would want to edit the top of the file to adjust the weighting.

Command-line options
====================

The most up-to-date documentation is generated from :command:`cns.phipsi_restraints.py -h`:

Command: /trihome/chapmanms/Devel/PaStO/pasto/cns/phipsi_restraints.py -h (Mon Nov 17 19:21:53 2025)

usage: phipsi_restraints.py [-h] [--segid SEGID] [--name NAME] [--target TARGET TARGET TARGET TARGET] [--glycine GLYCINE GLYCINE GLYCINE GLYCINE]

[--Name NAME] [--Glycine]
                            PDB_FILE [RESTRAINTS_FILE]

For each residue, determines which target area is closest (to boundary), then writes a restraint that CNS will impose as a flat-bottom well within the
target area.

positional arguments:
  PDB_FILE              Input coordinates.
  RESTRAINTS_FILE       Output phi-psi restraints for CNS.

options:
  -h, --help            show this help message and exit
  --segid SEGID, -S SEGID
                        Segid (chain) 4-character [ ]
  --name NAME, -n NAME  Name for each non-Gly target, repeated each target.
  --target TARGET TARGET TARGET TARGET, -t TARGET TARGET TARGET TARGET
                        non-Gly: phi_min, phi_max, psi_min, psi_max [None] option repeatable.
  --glycine GLYCINE GLYCINE GLYCINE GLYCINE, -g GLYCINE GLYCINE GLYCINE GLYCINE
                        Gly: phi_min, phi_max, psi_min, psi_max [None] option repeatable.
  --Name NAME, -N NAME  Name for each explicit Gly target, repeated each target.
  --Glycine, -G         Gly: implicit: add inverted general targets [False]

Known issues: Target regions approximated as squares. Determination of nearest target is somewhat simplistic.

Example

The following bash script will restrain to an approximation of the favored areas of a Ramachandran plot, giving glycines more freedom:

python -u -m pasto.cns.phipsi_restraints \\
   -n alpha -t  -95 -65 -43 -7 \\
   -n beta -t -160 -80 120 170 \\
   -n left_helix -t 40 60 25 45 \\
   -N gly_alpha -g -95 -65 -43 -7 \\
   -N gly_beta -g 100 -80 140 -160 \\
   -N gly_left_helix -g 65 125 -25 25 \\
   Start/3j4p_sub_nto_for_sos.pdb start_phipsi_freq.cns

These target ranges are centered at eye-balled peak centroids from the frequency of residues in a Ramachandran plot of the AAV-DJ structure refined without φ/ψ restraints at 1.56 Å resolution (PDB 7KFR). Widths were chosen to enclose most of the residues, without exceeding the bounds of allowable in in Coot’s Dynarama plots (Validate >> Ramachandran). For peaks with few AAV residues, consistency with the Dynarama plot was enforced.

Best practices

Benchmarking with examples at resolutions worse than 2.8 Å resolution shows that φ/ψ restraints are needed to avoid significant fractions of outliers. Many outliers might be only marginally outside favored regions, so below 3.5 Å resolution, the impact might be mostly cosmetic. However, it is now common practice to apply backbone restraints in EM refinements, even though this undermines the premise of using the fraction of Ramachandran outliers as a validation metric. (It has become an unfortunate standard for publication that EM structures have idealized (φ, ψ) and to quote now-meaningless statistics.) Note that pre-publication, it can be useful to refine without (φ, ψ)-restraints to identify outliers as regions needing attention in model-building.

Exact choice of target parameters is not critical. There is enough slop in these flat-bottom potentials to compensate for most local errors.

The benchmarking did show that the above frequency-based targets are marginally better than those chosen to maximize the rectangular areas that would fit within the allowable regions of a Ramachandran plot (used through 2024).

At the top of the output cns file, the variable exp is set. One might predict that exp=1 would smooth the convergence of starting models with high deviations, but the LBGFS optimizer often failed in its line search, so exp=2 is really the only option. The scale parameter should be adjusted empirically to bring the right balance between favored φ, ψ and other restrained stereochemistries.

History

Changed in version 0.1: 08/19/11

Changed in version 0.2: 11/25/12 Use PDB file directly instead of MoleMan phipsi output.

Changed in version 0.5: 05/20/2015 ReStructuredText docs

Changed in version 1.0.0: 11/19/20 Python 2.7 –> 3.6 incl. optparse –> argparse

Changed in version 1.0.7: 12/29/24 debug: phipsi=(phi,phi) –> (phi,psi) [consequential!]; -g option; add main()