DAMMIF, a tool for rapid ab-initio shape determination in small angle
scattering, is a reimplementation of the well known bead-modelling program
DAMMIN.
In bead modeling a particle is represented as a collection of a large
number of densely packed beads inside a search volume. Each bead belongs
either to the particle or to the solvent. Starting from an arbitrary
initial model DAMMIF utilizes simulated annealing to construct a compact
interconnected model yielding a scattering pattern that fits the experimental
data.
Please refer to the paper cited above for further details about
the implemented algorithm.
OPTIONS known by DAMMIF are described in next section, the
optional argument 'GNOMFILE' in the section on
input files.
In general, command-line options can be used to make choices about the
properties of the particle to reconstruct, while the interactive configuration
is used to govern the annealing process.
If neither OPTIONS nor GNOMFILE is given, the
configuration is done in full interactive mode.
Configuration of the annealing procedure, one of FAST
(bigger beads, cooling down quickly), SLOW (smaller
beads, cooling down slowly), or INTERACTIVE.
Default is 'INTERACTIVE'.
See example.
Specify the symmetry to enforce on the particle. Any P-n-m
symmetry known by
DAMMIN is supported (Pn, n=1, ..., 19 and
Pn2, n=2, ..., 12). Cubic and icosahedral symmetries
are not available. By default, no symmetry is enforced (P1).
If, due to prior studies, it is known that the particle's shape
shall be either PROLATE or OBLATE, one may use
the anisometry option to enforce a penalty on particles that do
not correspond with the expected anisometry. By default,
anisometry is 'UNKNOWN'.
By default, dummy atom models are written to
.pdb-files in random order. The maintainers of the Protein
Data Bank expect the atoms to be ordered in (pseudo-)chains prior
to submission. With this flag DAMMIF attempts to order the output
according to this requirement. See also the example on
how to reproduce results. Please note:
the implemented chaining algorithm is quite basic and may take a
long time for large models.
--constant=<VALUE>
Specify a user defined constant to subtract; 0 to disable constant
subtraction. If unspecified, a constant to subtract is automatically
determined.
If the optional argument 'GNOMFILE' is omitted, settings
available through command-line arguments and options
may also be configured interactively as shown in the table below.
Otherwise these questions are skipped.
The parameters of the starting model are based on the shape classification. An appropriate classification may significantly improve the
reconstruction speed and accuracy as annealing parameters are adjusted by shape,
e.g. extended particle generally require more summands in the spherical harmonics
calculations.
The estimate for the dummy atom radius is based on
Dmax to result in a search volume of about 2.000
(FAST-mode) to about 10.000 (SLOW-mode) beads.
The smaller this radius is set, the more beads are generated, the
slower the process.
The more harmonics, the more accurate the reconstruction becomes,
but the slower the process. Very elongated particles may require
up to 50 harmonics, quick screening can be done as low as 10-15.
The default values may be adjusted by shape classification.
Experimental data is smoothed by spline interpolation before
fitting. This defines the number of supporting points of the
spline. By default, twice the number of Shannon Channels is
used, but a minimum of 20.
To reproduce results, re-use the random seed. Default value is
time-based. If multiple runs of DAMMIF shall be started at the
same time, use an input file with different random seeds.
Stop if simulated annealing is not finished after this many steps.
The more iterations per step and the
slower the system is cooled, the more
temperature steps are required.
Factor by which the temperature is decreased; 0.95 is a good
average value. Faster cooling for smaller systems is possible
(0.9), but slower cooling (0.99) needs to be applied more
often. The default factor is increased for extended particles.
How much the Rg Penalty shall influence the acceptance
or rejection of phase changes. A value of 0.0 disables the penalty.
If unsure, use the default value.
How much the Center Penalty shall influence the acceptance
or rejection of phase changes. A value of 0.0 disables the
penalty. If unsure, use the default value.
How much the Looseness Penalty shall influence the acceptance
or rejection of phase changes. A value of 0.0 disables the
penalty. If unsure, use the default value. If unlike smooth
surfaces and sharp edges are observed, try decreasing this
penalty weight.
How much the Anisometry Penalty shall influence the acceptance
or rejection of phase changes. A value of 0.0 disables the
penalty. If unsure, use the default value, 0.0 if no
anisometry was specified,
0.5 otherwise.
The fields can be interpreted as follows, top-left to bottom-right:
Field
Description
Step
Step number. Starts at 1, increases monotonically.
T
Temperature measure, starts at an arbitrary high value, decreases
each step by the temperature schedule
factor.
N/M
N beads in phase particle in M beads overall.
Succ
Number of successful phase changes in this temperature step.
Limited by the minimum and
maximum number of successes.
The number of successes should slowly decrease, the first couple of
steps should be terminated by the maximum
number of successes criterion. If instead the
maximum number of iterations per step are done, or the number
of successes drops suddenly by a large amount, the system should
probably be cooled more slowly.
Eval
Accumulated number of function evaluations.
CPU
Elapsed wall-clock time since the annealing procedure was started.
Rf
Goodness of fit of simulated data versus experimental data, does
not take penalties into account.
With each successful run, DAMMIF creates a set of output files, each
filename starts with a customizable prefix
that gets an extension appended. If a prefix has been used before, existing
files will be overwritten without further note.
The model is written in two parts: '-0.pdb' contains the
beads of the solvent (a.k.a. the search volume), '-1.pdb'
represents the modelled particle. The REMARK sections of
latter file contain information about the application used and
about invariants of the particle, e.g. Rg (in Å), volume (in Å3) and
a molecular weight estimate for proteins (in Da). If
omit-solvent was specified the output of the -0.pdb
file is omitted. If chained output
was requested, the dummy beads in '-1.pdb' are laid out
in pseudo-chains.
Fit of the simulated scattering curve versus a smoothed-out version
of the real-data. See dialog mode
how to change the number of supporting points in the spline
interpolation. Columns in the output file are: 's',
'Iexp' and 'Isim'.
This file provides an easy way to re-run DAMMIF with the same set of
input parameters (including random
seed) to verify the effects of options or to re-run DAMMIF to get
a chained PDB output.
Thus, if DAMMIF is started as
$ dammif --prefix=../foo/bar gnom.out
the files 'bar.log', 'bar-0.pdb', 'bar-1.pdb',
'bar.fit', 'bar.fir' and , 'bar.in' will be
written in the directory '../foo', relative to the current
working directory.
All examples use lyz.out as an input file, it is also included in the documentation
directory of the installation package. Please note that the prefixes may be chosen
arbitrarily. The values below are chosen for maximum clarity only.
$ for i in `seq 1 10` ; do dammif --prefix=lyz-$i --mode=slow lyz.out; done
Make sure to use different prefixes when
running DAMMIF multiple times in the same working directory. Further, if
multiple DAMMIF-runs are started in parallel, e.g. on a cluster, make sure
that the random seeds differ, otherwise
identical results will be obtained.
Input-redirection can be used to let DAMMIF read settings
from a configuration file
This example uses the .in-file of a previous run
to obtain the exact same result, but this time, the dummy atoms shall be
sorted to form pseudo-chains:
