ModeHunter Program Package

User Guide

This guide is intended to be used as a reference manual. You can also get usage information by calling the Python programs below without any arguments. In addition, the tutorial gives examples of these utilities. More documentation is also available in the published articles.

Content:

animate.py - Oscillating "Animation" of Normal Modes
augment.py - Change the Coarseness Level of Normal Modes by Interpolation
bfactor.py - B-factor Calculation from Normal Modes
btshunt.py - Bend-Twist-Stretch Coarse Network Model
eldecoy.py - Decoy Generation from Normal Mode Deformations
elforge.py - Flexible Fitting to a Density Map
enmhunt.py - Carbon-Alpha Based Elastic Network Model
needles.py - Porcupine Plot Rendering of Normal Modes
overlap.py - Compute the Squared Overlap Between Two Sets of Modes
traject.py - Generate a Single Trajectory from a Normal Mode Superposition
Library Modules

animate.py - Oscillating "Animation" of Normal Modes

Purpose:

Animates specific normal modes smoothly by a cosine wave. The program creates a trajectory of sequential frames in PDB format for each specified mode. The trajectories can then be animated as movies by any molecular graphics program that supports sequential frames written to a single PDB file. The PDB file holding the frames might become quite large in which case a smaller number of animation steps can be specified. It is also possible to specify only a single frame for structural comparison of the modes to the start structure using external bioinformatics tools.

Usage (at shell prompt):

./animate.py inpdb modes start end amplitude outname [steps]

Input files and parameters:

inpdb (string): PDB file containing N atoms
modes (string): Python pickle file containing M modes and their corresponding frequencies
start (int): Start index of desired mode range (1 <= start <= M; minimum of 7 is recommended)
end (int): End index of desired mode range (start <= end <= M)
amplitude (float): Requested mode amplitude entered as a root-mean-square deviation from inpdb in Angstrom:

positive value: all modes will be scaled alike to this amplitude
negative value: non-trivial modes above reference mode max(start,7) will be rescaled by inverse frequencies (this "natural" rescaling avoids large deformations in the more localized higher frequency modes).

outname (string): Text string for the output file names, see below
[steps] (int): Optional number of sampling steps for one period [default: 20]

Output files:

outname_###.pdb: Oscillating trajectories in PDB format, enumerated by the selected mode numbers. These PDB files hold only the coordinates of sequential frames but no other records. The files can be visualized as movies and converted into a number of other trajectory formats in VMD.

augment.py - Change the Coarseness Level of Normal Modes by Interpolation

Former name: extract.py

Purpose:

Enables the interpolation of sparsely sampled normal modes to a full atomic level of detail. The program uses the Bookstein Thin Plate Spline method with the 3D kernel (Bookstein, Morphometric Tools for Landmark Data, Cambridge U. Press 1991). This is necessary when modes from a C-alpha based ENM (created with enmhunt.py) or from a coarse BTS network (created with btshunt.py) should be resampled at a higher level of detail using more atoms. There are no restrictions on the atom numbers, so in principle one could also create a coarse representation from a fine one by reversing the role of the input files below.

Usage (at shell prompt):

./augment.py sourcepdb sourcemodes targetpdb targetname [end]

Input files:

sourcepdb (string): PDB file with existing sample points (i.e., atoms) .
sourcemodes (string): Python pickle with N modes (and their frequencies), sampled at the atoms in sourcepdb.
targetpdb (string): PDB file with the target (query) points for the interpolation.
targetname (string): Text string for the interpolation results, see below .
[end] (int): Optional target mode number limit, 7 <= end <= N, to expedite the run [default: N].

Output files:

targetname_modes.pkl: Python pickle with interpolated modes (and their frequencies), sampled at the atoms in targetpdb.
targetname.log: Log file with useful information such as eigenvalues, frequencies, and modes in NOMAD-Ref format.

bfactor.py - B-factor Calculation from Normal Modes

Purpose:

Computes the "B-factors" from the normal modes and frequencies following equ. 13 in (Stember & Wriggers, 2009). The global scaling of the resulting B-factor values is arbitrary. When comparing multiple B-factor plots in an external plotting program, the values should be normalized (e.g. by the area under the graph) and rescaled accordingly.

Usage (at shell prompt):

./bfactor.py inpdb modes [end] outname

Input files and parameters:

inpdb (string): PDB file which contains N C-alpha atoms of a protein (other atoms will be ignored).
modes (string): Python pickle file containing M modes and their corresponding frequencies.
[end] (int): Optional upper mode summation limit [default: M]. See equ. 13 in (Stember & Wriggers, 2009)
outname (string): Text string for output file names, see below.

Output file:

outname_bfactors.txt: Text file with N raw, unscaled B-factors (order corresponds to Carbon-alpha order in inpdb).
outname_bfactors.pdb: PDB file containing N C-alpha atoms with their B-factors scaled to [0 100]. This file can be visualized and color coded using molecular graphics programs such as VMD (order of Carbon-alpha atoms same as in inpdb).

btshunt.py - Bend-Twist-Stretch Coarse Network Model

Purpose:

The BTS model applies a continuum mechanical elastic rod model to an arbitrary graph. This is useful if one wishes to perform normal mode analysis to very coarse grained systems, included user-drawn stick figures! The model adds 3- and 4-body interactions to the potential function used for normal mode analysis. The motivation for this model and algorithmic details are given in (Stember & Wriggers, 2009). The input coarse grained model (PDB and PSF file) can be created with vector quantization, implemented in Situs. If necessary, a volumetric density mask is first created from an atomic structure using the Situs pdb2vol utility. Then the density mask (or alternatively, volumetric data from low-resolution structures) is processed with the Situs quanvol tool to generate the coarse model and the connectedness in the form of a PDB and PSF file, respectively. Most of these steps are explained in a Situs tutorial. Users should note that our BTS model was designed for trigonal or tetrahedral meshes or trees (such as those arising from centroidal Voronoi tessellation and volume-optimal mesh generation in Situs quanvol). BTS was not designed for square or cubic meshes or any stick figures that have linear bond angles (try enmhunt.py instead for these).

Usage (at shell prompt):

./btshunt.py inpdb inpsf outname [r1 r2]

Input files and parameters:

inpdb (string): PDB file containing N pseudo-atoms (coarse grained model)
inpsf (string): PSF file containing connectivities (coarse grained model)
outname (string): Text string for output file names, see below
[r1 r2]: Optional user defined (normalized) force constant ratios r1=(16/<d>^2)k_b/k_s and r2=k_t/k_b. See Section III-C in (Stember & Wriggers, 2009) (last paragraph). The modes are not very sensitive to these parameters, so we don't recommend to change the default values [default: 0.1 1.0].

Output files:

outname_modes.pkl: Python pickle file containing 3N modes and the corresponding frequencies for subsequent processing.
outname.log: Log file with useful information such as force field details and resulting modes in NOMAD-Ref format.

General features of the created normal modes (applies to both BTS and ENM):

The first non-trivial mode (for elastic deformations) is number 7. The first 6 modes form a basis set for rigid-body movements, but they are mixed (not separated into 3 translations and 3 rotations) because they have the same zero frequency (null space of Hessian) and are not numerically separated by the diagonalization of the Hessian. You should always inspect the log files to ensure that only the first six modes have near zero frequency and there is a jump from mode 6 to mode 7 towards significantly larger values. If the model breaks down and there are additional unresisted degrees of freedom, additional zero frequency modes appear that mix with the first 6 modes. Typically, this will also result in negative eigenvalues that trigger a warning.
The absolute scale of frequencies in our tools is arbitrary because there is no thermodynamic justification for the models. Therefore, only relative frequencies are used in our tools (e.g., to produce an optional inverse frequency scaling of mode amplitudes).

eldecoy.py - Decoy Generation from Normal Mode Deformations

Purpose:

Generates structure decoys from a systematic combination of multiple normal modes that are sampled at specific phases of their cosine waves. The program outputs all decoys in the form of a single trajectory that contains sequential frames in PDB format. The trajectory can then be animated as a movie by any molecular graphics program that supports sequential frames written to a single PDB file. The PDB file holding the frames holds (phases^modes) decoys and might become quite large in which case a smaller number of modes or phase sampling steps can be specified. Constant and inverse frequency scaling of amplitudes are both supported. Inverse frequency scaling creates more natural looking decoys whereas constant amplitude scaling is sometimes more suitable for systematic searches of conformational space.

Usage (at shell prompt):

./eldecoy.py inpdb modes start end amplitude outname [phases]

Input files and parameters:

inpdb (string): PDB file containing N atoms.
modes (string): Python pickle file containing M modes and their corresponding frequencies.
start (int): Start index of desired mode range (1 <= start <= M; minimum of 7 is recommended).
end (int): End index of desired mode range (start <= end <= M).
amplitude (float): Requested mode amplitude entered as a root-mean-square deviation from inpdb in Angstrom:

positive value: all modes will be scaled alike to this amplitude
negative value: non-trivial modes above reference mode max(start,7) will be rescaled by inverse frequencies (this "natural" rescaling avoids large deformations in the more localized higher frequency modes).

outname (string): Text string for the output file name, see below.
[phases] (int): Optional number of sampling phases for each mode modeled as a cosine wave from 0 to pi [default: 4]

Output file:

outname_superposition.pdb: Trajectory containing a total of phases^(end-start+1) decoys in sequential PDB format in PDB format. The PDB file holds only the coordinates of sequential frames but no other records. The file can be visualized as a movie and converted into a number of other trajectory formats (or sequential PDB files) with VMD.

elforge.py - Flexible Fitting to a Density Map

Purpose:

Performs a flexible fitting of an atomic structure to a density map (e.g. from cryo-EM) using selected low-frequency normal modes of an elastic network model as basis functions for the displacement. The optimization finds the nearest maximum of a cross-correlation (CC) coefficient (inner product or Pearson). Internally, the negative CC is minimized. Powell minimization is applied, which is a basic gradient descent method to find the nearest local minimum. This method, albeit local, was most effective in our testing.

Usage (at shell prompt):

./elforge.py inpdb invol res modes start end [ccpad] outname

Input files and parameters:

inpdb (string): PDB file containing N atoms (for best results, rigid-body fit this first to invol using Situs tools)
invol (string): Input density map. The tool currently only supports Situs-formatted input map files. You can convert other map formats to this format using the Situs map2map tool. (We plan to support additional map formats directly in the future).
res (float): Resolution of invol in Angstrom units (following the Situs convention; for details and relationships with other resolution conventions see section 4 in Wriggers, 2012). You need to specify the resolution, because internally a resolution lowered simulated map is generated from this value after projecting the flexed atomic structure to the voxel grid. The CC is then computed between this simulated map and invol.
modes (string): Python pickle file containing M modes and their corresponding frequencies.
start (int): Start index of desired mode range (1 <= start <= M). A value of 1 is recommended to include the first six (rigid-body) modes, which gives more accurate results (although using the rigid-body modes in the flexing will also increase dimensionality by six and slow down convergence). When beginning to explore this tool, you could use a start index of 7 (to speed up results) and lower this value to 1 later once you have established the work flow.
end (int): End index of desired mode range (start <= end <= M). We suggest to begin exploring the mode range with a relatively small end index value, e.g. 12, to limit the dimensionality of the search.
[ccpad] (int): Optional tuning of the CC measure and zero-padding [default: 0]:

zero (or no value set): CC measure is the inner product (zero-padding not needed)
positive value: Pearson CC with strict ccpad voxel wide padding about invol. There is no guarantee that the zero-padding will enclose inpdb.
negative value: Pearson CC with at least abs(ccpad) voxel wide padding about inpdb. The padding will only extend but not shrink invol, so invol will also be enclosed, but a minimum margin about inpdb is guaranteed (if the value is entered as a negative integer).

outname (string): Text string for the output file name, see below.

Output file:

outname.pdb: Flexibly fitted output structure in PDB format.

enmhunt.py - Carbon-Alpha Based Elastic Network Model

Purpose:

The traditional C-alpha based ENM with large distance cutoff. See e.g. (Tama et al., 2002) and (Chacón et al., 2003). ENMs only include Hookean spring interactions between adjacent pairs of C-alpha atoms. The distance cutoff that defines adjacency is the most important parameter. ENMs can give rise to unresisted (zero-frequency motions) when atoms are connected to fewer than three neighbors. Therefore, a large distance cutoff and/or high point density are chosen in an ENM. For C-alpha based ENM, a distance cutoff of 10-15A is recommended. Our implementation follows the traditional approach, except we have also implemented an optional tuning of the spring constants that can be explored in specific applications where the model should be made stiffer or more flexible in some user-defined locations.

Usage (at shell prompt):

./enmhunt.py inpdb cutoff outname [wid wfx]

Input files and parameters:

inpdb (string): PDB file with protein atoms, including N C-alpha atoms required for constructing the ENM.(If you wish to use an input graph or mesh that does not contain any C-alpha atoms, e.g. a "density" PDB generated by Situs vol2pdb, you need to change the atom names in that file to " CA " in a text editor.)
cutoff (float): ENM cutoff distance in Angstrom units. The typical distance for C-alpha nodes is 10-15 (Angstrom). Suggested: 12. Minimum: 7.
outname (string): Text string for output file names, see below
[wid wfx]: Optional pair of Hessian matrix perturbation parameters (see enmhunt.py code for algorithmic details):

wid >0: local rescaling by factor wfx at a C-alpha index wid (counting the order in inpdb from 1). This is useful to make a specific C-alpha atom softer or stiffer (local perturbation).
wid -1: global rescaling of spring constants by the PDB "B-factor" field of inpdb using a normalized power (B-factor^wfx). The exponent wfx can be positive (useful e.g. for AlphaFold2 pLDDT in the B-factor field, lower confidence regions can be made softer). The exponent can also be negative (useful e.g. for a softening of high crystallographic B-factor regions). Note: Use exponents wfx with magnitude close to 1 to avoid breaking the ENM numerically.

Output files:

outname_modes.pkl: Python pickle file containing 3N modes and the corresponding frequencies for subsequent processing.
outname.log: Log file with useful information such as eigenvalues, frequencies, and modes in NOMAD-Ref format.
[outname_pure_ca.pdb]: Filtered "pure" PDB with only N C-alpha atoms (created only if inpdb is "impure" i.e. it has more than just C-alpha atoms). For subsequent processing.

General features of the created normal modes (applies to both ENM and BTS):

The first non-trivial mode (for elastic deformations) is number 7. The first 6 modes form a basis set for rigid-body movements, but they are mixed (not separated into 3 translations and 3 rotations) because they have the same zero frequency (null space of Hessian) and are not numerically separated by the diagonalization of the Hessian. You should always inspect the log files to ensure that only the first six modes have near zero frequency and there is a jump from mode 6 to mode 7 towards significantly larger values. If the model breaks down and there are additional unresisted degrees of freedom, additional zero frequency modes appear that mix with the first 6 modes. Typically, this will also result in negative eigenvalues that trigger a warning.
The absolute scale of frequencies in our tools is arbitrary because there is no thermodynamic justification for the models. Therefore, only relative frequencies are used in our tools (e.g., to produce an optional inverse frequency scaling of mode amplitudes).

needles.py - Porcupine Plot Rendering of Normal Modes

Purpose:

Allows one to superimpose 3D "arrows" or "needles" over the molecular structure in the mode displacement directions. This takes advantage of VMD's graphics scripting capabilities. The VMD specific graphics options are documented in the needles.py file and can be tuned in function 'render_needles' .

Usage (at shell prompt):

./needles.py inpdb modes start end amplitude outname type

Input files and parameters:

inpdb (string): PDB file containing N atoms.
modes (string): Python pickle file containing M modes and their corresponding frequencies.
start (int): Start index of desired mode range (1 <= start <= M; minimum of 7 is recommended).
end (int): End index of desired mode range (start <= end <= M).
amplitude (float): Requested mode amplitude (length of needles or arrows) entered as a root-mean-square deviation from inpdb in Angstrom:

positive value: all modes will be scaled alike to this amplitude.

negative value: non-trivial modes above reference mode max(start,7) will be rescaled by inverse frequencies (this "natural" rescaling avoids large deformations in the more localized higher frequency modes).

outname (string): Text string for output file names, see below.
type (string): Text string "arrows" or "needles" for desired type of output graphics primitives.

Output files:

outname_###_pos.tcl: VMD-sourcable TCL graphics commands with needles or arrows rendered in positive direction.
outname_###_neg.tcl: VMD-sourcable TCL graphics commands with needles or arrows rendered in negative direction.

overlap.py - Compute the Squared Overlap Between Two Sets of Modes

Purpose:

Compares two sets of normal modes by their squared overlap matrix, see equ. 12 in (Stember & Wriggers, 2009). The two mode pickle files may have unequal number of modes but the number of columns (corresponding to 3 times the atom number) must be identical. The resulting text file containing the squared overlap matrix can be inspected in a plotting program.

Usage (at shell prompt):

./overlap.py pickle1 pickle2 start end outfile

Input files and parameters:

pickle1 (string): Python pickle file containing K modes for N atoms
pickle2 (string): Python pickle file containing L modes for same N atoms
start (int): Start index of desired mode range (1 <= start <= min(L,K))
end (int): End index of desired mode range (start <= end <= min(L,K))

Output file: outfile (string): Text file with the squared overlap matrix for the desired mode range.

traject.py - Generate a Single Trajectory from a Normal Mode Superposition

Purpose:

Superimposes multiple normal modes as cosine waves of mode-specific frequencies. The program creates a single trajectory of sequential frames in PDB format . The trajectory can then be animated as a movie by any molecular graphics program that supports sequential frames written to a single PDB file. The PDB file holding the frames might become quite large in which case a smaller number of sampling steps or frames can be specified. Constant and inverse frequency scaling of amplitudes are both supported. Inverse frequency scaling creates very natural looking trajectories with that can be used for testing Molecular Dynamics analysis scripts.

Usage (at shell prompt):

./traject.py inpdb modes start end amplitude outname periods [steps]

Input files and parameters:

inpdb (string): PDB file containing N atoms.
modes (string): Python pickle file containing M modes and their corresponding frequencies.
start (int): Start index identifying the slowest mode used in the superposition (7 <= start <= M).
end (int): End index identifying the fastest mode used in the superposition (start <= end <= M).
amplitude (float): Requested mode amplitude entered as a root-mean-square deviation from inpdb in Angstrom:

positive value: all modes will be scaled alike to this amplitude
negative value: non-trivial modes above reference mode max(start,7) will be rescaled by inverse frequencies (this "natural" rescaling avoids large deformations in the more localized higher frequency modes).

outname (string): Text string for the output file names, see below.
periods (float): Number of desired slowest mode periods in the superposition trajectory.
[steps] (int): Optional number of sampling steps for one period of the fastest mode [default: 20]

Output files:

outname_superposition.pdb: Mode superposition trajectory in PDB format. The PDB file holds only the coordinates of sequential frames but no other records. The file can be visualized as a movie and converted into a number of other trajectory formats in VMD.

Library Modules

The suite of programs is supported by two auxiliary library modules. The library modules handle input and output of atomic coordinates in PDB format (m_inout.py) as well as potential energy calculations (m_poten.py).

Return to the front page .