|
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 sine 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.
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: 200].
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 [upper] 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.
[upper] (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.
|
| 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.
|
| 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 finemodes |
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 file:
finemodes:
Newly created python pickle file 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.
|
| 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 |
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.
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 . |
