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
bfactor.py - B-factor Calculation from Normal Modes
btshunt.py - Bend-Twist-Stretch Elastic Rod Network Model
enmhunt.py - Carbon-Alpha Based Elastic Network Model
extract.py - Extract Fine Modes from Coarse Modes by Interpolation
needles.py - Porcupine Plot Rendering of Normal Modes
overlap.py - Compute the Squared Overlap Between Two Sets of Modes
Library Modules

animate.py - Oscillating Animation of Normal Modes

Purpose:

Animates normal modes smoothly by a cosine wave. The program creates a trajectory of 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 inpickle start end amplitude outname [steps]

Input files and parameters:

inpdb (string): PDB file containing N atoms.
inpickle
(string): Existing python pickle file containing 3M modes for the N atoms.
start (int): User-specified start index of desired mode range (1 <= start <= 3M).
end
(int): User-specified end index of desired mode range (start <= end <= 3M).
amplitude
(float): Mode amplitude as root-mean-square deviation from inpdb (in Angstrom). outname (string): User-defined text string for output file names, see below.
[steps] (int): Optional user defined number of frames in output files below [default: 50].

Output files:
outname_###.pdb: Oscillating trajectories in PDB format, enumerated corresponding to selected mode range. These PDB files hold only the coordinates of sequential frames but no chemical information, so they should be loaded into an already existing molecule when using molecular graphics programs such as VMD.
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 modes freqs [end] outfile

Input files and parameters:

modes (string): Python pickle file containing 3N modes.
freqs
(string): Python pickle file containing 3N-6 corresponding non-trivial frequencies.
[end] (int): Optional upper mode summation limit (7<= upper <= 3N), see equ. 13 in (Stember & Wriggers, 2009)  [default: 3N].

Output file:

outfile:
Text file with the B-factors (order corresponds to atom index, i.e. the order of columns in file 'modes').
btshunt.py - Bend-Twist-Stretch Elastic Rod Network Model

Purpose:

The BTS model applies a continuum mechanical elastic rod model to an arbitrary graph. 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 qvol tool to generate the coarse model and the connectedness in the form of a PDB and PSF file, respectively. Details will follow, but most of these steps are already explained in a Situs tutorial.

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): User-defined text string for output file names, see below. [r1 r2] (float float): Optional user defined (normalized) force constant ratios r1=(16/<d>2)kb/ks and r2=kt/kb. See Section III-C in (Stember & Wriggers, 2009), especially the last paragraph. The modes are not very sensitive to these so we don't recommend to change the default values [default: 0.1 1.0].

Output files:

outname_modes.pkl: Python pickle file containing all (3N) modes, for subsequent processing.
outname_frequencies.pkl: Python pickle file containing 3N-6 non-trivial frequencies.
outname.log: Log file with user readable information, including
modes in NOMAD-Ref format.

enmhunt.py - Carbon-Alpha Based Elastic Network Model

Purpose:

Classic C-alpha based ENM with large distance cutoff. See e.g. (Tama et al., 2002) and (Chacón et al., 2003). Traditional ENMs give rise to unbounded zero-frequency vibrations when atoms are connected to fewer than three neighbors. A large distance cutoff and/or high point density are therefore chosen in an ENM. Here, we have implemented the typical C-alpha based ENM which requires a distance cutoff of 10-15A.

Usage (at shell prompt):

./enmhunt.py inpdb [cutoff] outname 

Input files and parameters:

inpdb (string): PDB file containing N C-alpha coordinates.
[cutoff]
(float): Optional user-defined ENM cutoff distance in Angstrom units [default: 12.0].
outname (string): User-defined text string for output file names, see below.

Output files:

outname_modes.pkl: Python pickle file containing all (3N) modes, for subsequent processing.
outname_frequencies.pkl: Python pickle file containing 3N-6 non-trivial frequencies.
outname.log: Log file with user readable information
, including modes in NOMAD-Ref format.

extract.py - Extract Fine Modes from Coarse Modes by Interpolation

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. 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):

./extract.py coarsepdb finepdb coarsemodes outname

Input files:

coarsepdb (string): PDB file containing N (pseudo-)atoms (coarse grained model).
finepdb
(string): PDB file containing M atoms (typically M>>N, i.e. fine grained model).
coarsemodes (string): Existing python pickle file containing 3N coarse grained modes.

Output files:

outname_modes.pkl: Python pickle file containing containing 3N fine grained modes. Note that the number of modes (i.e. rows) in the new pickle file is the same as in file 'coarsemodes', only the number of atoms (i.e. columns) will be different.

outname.log: Log file with user readable information, including modes in NOMAD-Ref format.

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 inpickle start end amplitude outname type

Input files and parameters:

inpdb (string): PDB file containing N atoms.
inpickle
(string): Existing python pickle file containing 3M modes for the N atoms.
start
(int): User-specified start index of desired mode range (1 <= start <= 3M).
end
(int): User-specified end index of desired mode range (start <= end <= 3M).
amplitude
(float): Mode amplitude as root-mean-square deviation from 'inpdb' (in Angstrom).
outname
(string): User-defined text string for output file names, see below.
type
(string): User-defined text string 'arrows' or 'needles' for desired type of output graphics primitives.

Output files:

outname_###_pos.tcl: VMD-sourcable TCL graphics routines with "arrows" rendered in positive direction.

outname_###_neg.tcl: VMD-sourcable TCL graphics routines with "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): Existing python pickle file containing 3K modes for N atoms.
pickle2
(string): Existing python pickle file containing 3L modes for same N atoms.
start
(int): User-specified start index of desired mode range (1 <= start <= 3*min(L,K)). end (int): User-specified end index of desired mode range (start <= end <= 3*min(L,K)).


Output file: outfile: Text file with the squared overlap matrix.
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 .