dammif
Manual
The following sections shortly describe the method implemented in DAMMIF, how to run DAMMIF from the command-line, detail the dialog mode as well as the required input and the produced output files.
Introduction
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.
Running dammif
Usage:
$ dammif [OPTIONS] [GNOMFILE]
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.
Command-Line Arguments and Options
DAMMIF accepts the following command line arguments:
| Argument | Description |
|---|---|
| GNOMFILE | A relative or absolute path to regularised SAS data (.out) |
DAMMIF recognizes the following command-line options. Mandatory arguments to long options are mandatory for short options too.
| Short Option | Long Option | Description |
|---|---|---|
| -u | --unit=<UNIT> | Angular units of theinput file, one ofANGSTROMorNANOMETER. By default, an attempt is made to estimate the unit scale. |
| -p | --prefix=<PREFIX> | Prefix to prepend tooutput filenames. May include absolute or relative paths, all directory components must exist. Default is ‘dammif’. |
| --model-format=<FMT> | Format of 3D models, one of: cif, pdb (default: cif) | |
| -a | --anisometry=<NAME> | If, due to prior studies, it is known that the particle’s shape shall be eitherPROLATEorOBLATE, 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’. |
| --shape=<SHAPE> | Expected particle shape to use as a start model (default: use classifier). Valid values are: ‘unknown’, ‘compact’, ‘extended’, ‘flat’, ‘ring’, ‘compact-hollow’, ‘hollow-sphere’, ‘random-chain’. The parameters of the starting model are based on theshape 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. | |
| -s | --symmetry=<NAME> | Specify the symmetry to enforce on the particle. Any_P-n-m_symmetry known byDAMMINis supported (P_n_,n=1, …, 19 and P_n_2,n=2, …, 12). Cubic and icosahedral symmetries are not available. By default, no symmetry is enforced (P1). |
| -m | --mode=<MODE> | Configuration of the annealing procedure, one ofFAST(bigger beads, cooling down quickly),SLOW(smaller beads, cooling down slowly), orINTERACTIVE. Default is ‘INTERACTIVE’. Seeexample. |
| --constant=<VALUE> | Specify a user defined constant to subtract; 0 to disable constant subtraction. If unspecified, a constant to subtract is automatically determined. | |
| -q | --max-bead-count=<N> | Mmaximum number of beads in the expanding search space (unlimited if undefined). |
| -q | --quiet | Suppress screen output, write a.log-fileonly. By default, all runtime information is printed to screen and the .log-file. |
| --seed=<INT> | Set the seed for the random number generator | |
| -h | --help | Print a summary of arguments, options, and exit. |
| -v | --version | Print version information and exit. |
Interactive Configuration
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.
| Screen Text | Default | Description |
|---|---|---|
| GNOM input file? | N/A | Same asGNOMFILE-argument. |
| Angular unit? | UNKNOWN | Same asunit-option. |
| Output file prefix? | dammif | Same asprefix-option. |
| Model output format? | cif | Same asmodel-format-option. |
| Expected/assumed shape? | unknown | Same asshape-option. |
| Expected particle symmetry? | P1 | Same assymmetry-option. |
| Expected particle anisometry? | UNKNOWN | Same asanisometry-option. |
| Constant to subtract? 0 to disable constant subtraction, undefined for automatic (default)? | UNKNOWN | Same asconstant-option. |
| Simulated annealing setup? | SLOW | Same asmode-option. |
In ‘ INTERACTIVE ‘-mode a list of parameters governing the annealing process may be fine-tuned:
| Screen Text | Default | FAST-mode Setting | SLOW-mode Setting | Description |
|---|---|---|---|---|
| Maximum bead count (default: unlimited)? | var | var | var | Same asmax-bead-count-option. |
| Dummy atom radius? [1.0-?] [Angstrom] | var | var | var | The estimate for the dummy atom radius is based on_D~max~_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. |
| Maximum number of spherical harmonics? [1-50] | 20 | 15 | 20 | 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. |
| Proportion of the curve to be fitted? (0.0-1.0] | 1.0 | 1.0 | 1.0 | Proportion of the scattering curve to fit, starting at the first point. |
| Curve weighting function? Select one of: [l]og, [p]orod, [e]mphasised porod, [n]one | emph. porod | emph. porod | emph. porod | Weighting function to ensure a better fit at lower angles. If unsure, use the default. |
| Initial random seed? | var | var | var | 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. |
| Maximum number of temperature steps in annealing procedure? [1-?] | 200 | 200 | 400 | Stop if simulated annealing is not finished after this many steps. The moreiterations per stepand the slower the systemis cooled, the more temperature steps are required. |
| Maximum number of iterations within a single temperature step? [1-?] | 200.000 | 20.000 | 100.000 | Finalize temperature step and cool after this many iterations at the latest. |
| Maximum number of successes per temperature step before temperature is decreased? [1-?] | 20.000 | 2.000 | 10.000 | Finalize temperature step and cool after at most this many successful phase changes. |
| Minimum number of successes per temperature step before temperature is decreased? [1-?] | 200 | 20 | 50 | Stop if not at least this many successful state changes within a single temperature step can be done. |
| Temperature schedule factor? [0.0-1.0) | 0.95 | 0.9 | 0.95 | 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. |
| Rg penalty weight? [0.0-…) | 0.001 | 0.001 | 0.001 | How much the R~g~Penalty shall influence the acceptance or rejection of phase changes. A value of 0.0 disables the penalty. If unsure, use the default value. |
| Center penalty weight? [0.0-…) | 0.00001 | 0.00001 | 0.00001 | 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. |
| Looseness penalty weight? [0.0-…) | 0.01 | 0.01 | 0.01 | 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. |
| Anisometry penalty weight? [0.0-…) | 0.0/0.5 | 0.0/0.5 | 0.0/0.5 | 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 noanisometrywas specified, 0.5 otherwise. |
Runtime Output
On runtime, two lines of output will be generated for each temperature step :
Step: 1, T: 0.368E-03, 23/2287, Succ: 1062, Eval: 20002, CPU: 00:00:06
Rf: 0.1504, Los: 0.39, Rg: 0.00, Cen: 0.00, Ani: 0.00, Fit: 0.1504
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 thetemperature 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 theminimumandmaximumnumber of successes. The number of successes should slowly decrease, the first couple of steps should be terminated by themaximumnumber of successes criterion. If instead themaximum number of iterations per stepare 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. |
| Los | Contribution of Looseness Penalty, not taking theLooseness Penalty Weightinto account. |
| Rg | Contribution of R~g~Penalty, not taking theRg Penalty Weightinto account. |
| Cen | Contribution of Center Penalty, not taking theCenter Penalty Weightinto account. |
| Ani | Contribution of Anisometry Penalty, not taking theAnisometry Penalty Weightinto account. |
| Fit | A function ofRfincluding all penalties and their respective weights. Decreases towards zero, the smaller the value, the better the fit. |
dammif Input Files
Like DAMMIN, DAMMIF uses the distance distribution functions computed by GNOM as input files.
dammif Output Files
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.
| Extension | Description |
|---|---|
| .log | Contains the same information as the screen output and is updated during execution of the program. |
| -1.pdbor-1.cif | The model is provedin either PDB or mmCIF format, depending on themodel-formatoption. |
| .fit | Fit of the simulated scattering curve versus a smoothed-out version of the real-data. Seedialog modehow to change the number of supporting points in the spline interpolation. Columns in the output file are: ‘s’, ‘I~exp~’ and ‘I~sim~’. |
| .fir | Fit of the simulated scattering curve versus the experimental data. Columns in the output file are: ‘s’, ‘I~exp~’, ‘Err~exp~’ and ‘I~sim~’. |
| .in | This file provides an easy way to re-run DAMMIF with the same set of input parameters (includingrandom seed) to verify the effects of options or to re-run DAMMIF to get achainedPDB 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.
Examples
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.
A Quick Look
Use DAMMIF in FAST -mode to obtain a first model quickly:
$ dammif --prefix=lyz-fast --mode=fast lyz.out
More Detailed Reconstruction
Use DAMMIF in SLOW -mode get an improved reconstruction:
$ dammif --prefix=lyz-slow --mode=slow lyz.out
Customizing the Annealing Procedure
For best results, run DAMMIF in INTERACTIVE mode, customizing annealing parameters as required:
$ dammif --prefix=lyz-custom --mode=interactive lyz.out
Running dammif Multiple Times
On Linux, in bash syntax:
$ 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.
Reproducing Results
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 :
$ dammif --prefix=lyz-slow-chained --chained --mode=interactive < lyz-slow.in