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