DAMAVER manual

Written by D. Svergun and M. Petoukhov.
Post all your questions about DAMAVER to the ATSAS Forum.

© ATSAS Team, 2001-2007

This is the manual for the program suite DAMAVER, a set of programs to align ab initio models, select the most typical one and build an averaged model. The following sections briefly describe the different programs that are part of DAMAVER, how to run them and what the input and output files are. If you use results from DAMAVER in your own publication, please cite:

V. V. Volkov and D. I. Svergun (2003). Uniqueness of ab-initio shape determination in small-angle scattering. J. Appl. Cryst. 36, 860-864.

DAMAVER is a set of programs to align ab initio low resolution models (e.g. provided by DAMMIN and/or GASBOR), select the most typical ("probable") one and build an averaged model.The program package requires SUPCOMB20. In the following DAMAVER means the program suite, whereas damaver refers to the actual program that is part of it. This suite contains the following programs:

• damsel: compare all models, find most probable one and outliers (uses SUPCOMB)
• damsup: align all models with the most probable one (uses SUPCOMB)
• damaver: average aligned models and compute probability map
• damfilt: filter the averaged model at a given cut-off volume
• damstart: generates from the averaged model an input file with fixed core for DAMMIN (for those who want to refine the averaged model)

Note that the most typical usage of this suite is to "let damaver do all the work". Thus, in most cases you only need damaver and therefore one can go to the damaver manual straight away from here. Alternatively, you can use the different programs separately and the order of the programs as listed above reflects the typical order in which they are normally run in order to obtain an averaged model. The examples shown are all based on the same models and therefore essentially describe a full session of DAMAVER. Please refer to the paper cited above for further details about the implemented algorithm.

Damsel

Table of Contents

• Manual
  • Introduction
  • Running damsel
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • damsel Input Files
  • damsel Output Files
• Example

Manual

Introduction

Damsel is a program that compares a set of models, finds the most probable one and outliers (uses SUPCOMB). Given several structures in PDB format, the program superimposes all possible pairs by calling SUPCOMB (either SUPCOMB20 or SUPCOMB13, the latter of which is slower but more accurate, see Command-Line and Options). It then writes a table to select the most probable structure and to discard most divergent models. This table contains the values of agreement between the pairs of models and also the average agreement for each model with the others. The agreement is expressed in terms of a normalized spatial discrepancy ( NSD, see also Kozin & Svergun (2001) Automated matching of high- and low-resolution structural models. J. Appl. Cryst. 34, 33-41). During superposition, enantiomorphs are allowed and only CA atoms are used to compute the NSD. The model with the lowest average NSD is considered the most probable one, those with the highest NSDs are considered outliers. The table is written to the file damsel.log, which can be further used as input for damsup (see damsel output files)

NOTE: For DAMMIN or GASBOR averaging, 10 models are recommended. The maximum number of input models is 50. Models whose NSD exceeds 2 standard deviations from the mean are considered outliers.

Running damsel

Usage:

$> damsel [[INPUTFILE] [OPTIONS]]

Here, INPUTFILE is an input file containing a list of N file names to be analyzed in the format as described in Input Files . If no INPUTFILE or OPTIONS are given, the interactive dialog mode is invoked. OPTIONS for damsel are described in the following section.

Command-Line Arguments and Options

Damsel recognizes the following command-line options.

Interactive Configuration (Dialog mode)

The only question being asked in dialog mode is for the INPUTFILE, i.e., it is equivalent to typing damsel INPUTFILE.

damsel interactive prompt:

Runtime Output

As described in the introduction, SUPCOMB is called for all pairs of models. Consequently, for N models there are N*(N-1)/2 such calls. In essence, for each call the output is that from SUPCOMB. Therefore, please refer to its manual for a description of the runtime output.

damsel input files

Damsel input file contains a list of PDB files with the following format:

filename1.pdb
filename2.pdb
.
.
.
filenameN.pdb

Default file name is damsel.inp. The input file name can be specified from the command line by typing damsel INPUTFILE.

damsel output files

The damsel ouput file is called damsel.log. This file contains the above mentioned cross-correlation NSD. See damsel examples.

Example

Suppose, you have 10 ab initio models as created from DAMMIN. Then, using damsel in batch mode, i.e., typing

$> damsel /b

creates its own input file damsel.inp which looks like this:

model1-1.pdb
model2-1.pdb
model3-1.pdb
model4-1.pdb
model5-1.pdb
model6-1.pdb
model7-1.pdb
model8-1.pdb
model9-1.pdb
model10-1.pdb

The result of this damsel run, i.e, the contents of the output file damsel.log looks like this:

  ---  Created by DAMSEL     Mon Jul 27 18:17:41 2009 ---
 List file name ......................................... : damsel.inp
    -------------------------------------------
     Cross-correlation NSD table by SUPCOMB
    -------------------------------------------
 File  Aver  0-1  1-1  2-1  3-1  4-1  5-1  6-1  7-1  8-1  9-1
model1 0.48  0.00 0.50 0.48 0.50 0.49 0.50 0.48 0.48 0.43 0.44
model1 0.46  0.50 0.00 0.46 0.48 0.50 0.44 0.36 0.48 0.42 0.48
model2 0.48  0.48 0.46 0.00 0.49 0.48 0.48 0.48 0.47 0.49 0.47
model3 0.47  0.50 0.48 0.49 0.00 0.47 0.41 0.43 0.46 0.49 0.50
model4 0.47  0.49 0.50 0.48 0.47 0.00 0.50 0.49 0.37 0.47 0.48
model5 0.47  0.50 0.44 0.48 0.41 0.50 0.00 0.46 0.49 0.45 0.49
model6 0.46  0.48 0.36 0.48 0.43 0.49 0.46 0.00 0.44 0.47 0.49
model7 0.46  0.48 0.48 0.47 0.46 0.37 0.49 0.44 0.00 0.48 0.47
model8 0.46  0.43 0.42 0.49 0.49 0.47 0.45 0.47 0.48 0.00 0.45
model9 0.48  0.44 0.48 0.47 0.50 0.48 0.49 0.49 0.47 0.45 0.00
  Aver 0.47  0.48 0.46 0.48 0.47 0.47 0.47 0.46 0.46 0.46 0.48

 Mean value of  NSD =      0.467
 Variation  of  NSD =      0.008
 Recommend to discard files fith NSD > Mean + 2*Variation

        model6-1.pdb  --- Reference // Aver NSD =  0.455
        model1-1.pdb  --- Include   // Aver NSD =  0.456
        model7-1.pdb  --- Include   // Aver NSD =  0.459
        model8-1.pdb  --- Include   // Aver NSD =  0.460
        model3-1.pdb  --- Include   // Aver NSD =  0.467
        model5-1.pdb  --- Include   // Aver NSD =  0.469
        model4-1.pdb  --- Include   // Aver NSD =  0.471
        model9-1.pdb  --- Include   // Aver NSD =  0.476
       model10-1.pdb  --- Include   // Aver NSD =  0.476
        model2-1.pdb  --- Include   // Aver NSD =  0.477

Here, model6-1.pdb, having the smallest NSD differs the least from the others and will therefore be used as the reference model for the subsequent damsup run.

Damsup

Table of Contents

• Manual
  • Introduction
  • Running damsup
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • damsup Input Files
  • damsup Output Files
• Example

Manual

Introduction

Damsup is a program that aligns a set of models with one model that is considered the most probable one (as obtained from damsel). Given a list of models in PDB format, the program superimposes them with the reference model by calling SUPCOMB (either SUPCOMB20 or SUPCOMB13, the latter of which is slower but more accurate, see Command-Line and Options). Damsup requires an input file containing the file names to be analyzed. The first file in the list is considered to be the reference model with which all other models will be aligned. During superposition, enantiomorphs are allowed and only CA atoms are used to compute an NSD (see damsel introduction). For DAMMIN or GASBOR averaging, 10-15 models are recommended. Maximum number of files is 50.

Running damsup

Usage:

$> damsup [[INPUTFILE] [OPTIONS]]

Here, INPUTFILE is an input file containing the file names to be analyzed in the format as described in damsup input files or simply the output from damsel. If neither INPUTFILE nor any OPTIONS are given then dialog mode is invoked. OPTIONS known by damsup are described in the next section.

Command-Line Arguments and Options

Damsup recognizes the following command-line options.

Interactive Configuration (Dialog mode)

In dialog mode, damsup only asks for an input file. It then asks to confirm by pressing return in order to start.

damsup interactive prompt:

Runtime Output

As described in the introduction, SUPCOMB is called for all pairs "reference-model". Consequently, for N models there are (N-1) such calls. In essence, for each call the output is the one from SUPCOMB. Therefore, please refer to its manual for a description of the runtime output.

damsup input files

Default input file name is damsel.log, i.e., the output file from damsel can be directly used as input for damsup. In this case, the files marked as "--- Discard" are skipped. An example is given in damsel examples, in which case all models are to be included that are indicated by "--- Include". The user can also make the input file for damsup manually (filename maximum 30 characters). Such an input file contains the list of PDB files with the following format:

reference.pdb
filename2.pdb
.
.
.
filenameN.pdb

The first file is considered to be the reference model with which all other models will be aligned.

damsup output files

Damsup writes a file damsup.log which contains a list of superimposed PDB files. Each PDB file name is appended with an 'r'. E.g., file1.pdb is renamed file1r.pdb following superposition with the reference structure.

See damsup examples.

Example

Suppose, you have 1 reference model and 9 additional models. Then, using damsup in batch mode, i.e., typing

$> damsup /b

reads damsel.log and creates the output file damsup.log which looks like this:

model6-1.pdb                            !! Reference file
model1-1r.pdb                           !! NSD =   0.360
model7-1r.pdb                           !! NSD =   0.481
model8-1r.pdb                           !! NSD =   0.470
model3-1r.pdb                           !! NSD =   0.427
model5-1r.pdb                           !! NSD =   0.462
model4-1r.pdb                           !! NSD =   0.486
model9-1r.pdb                           !! NSD =   0.491
model10-1r.pdb                          !! NSD =   0.483
model2-1r.pdb                           !! NSD =   0.478

Damaver

Table of Contents

• Manual
  • Introduction
  • Running damaver
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • damaver Input Files
  • damaver Output Files
• Example

Manual

Introduction

The program damaver averages aligned models and computes a probability map. More specifically, given a list of models in PDB format which are aligned to yield the best overlap (as a result from damsup), the program remaps those onto a grid of densely packed beads in order to compute a frequency map (by default, only CA atoms are used to compute the map). For each bead, the cross volume with proximal dummy atoms in the input models (occupancy) is computed and saved into the output file damaver.pdb in columns 56-60. This output file can be processed further by the program damfilt.For DAMMIN or GASBOR averaging, 10-15 models are recommended. Maximum number of files is 50.

Running damaver

Usage:

$> damaver [[OPTIONS] [INPUTFILE]]

Here, INPUTFILE is an input file containing the file names to be aligned in the format as described in damaver input files or simply the output from damsup. If neither INPUTFILE nor any OPTIONS are given then dialog mode is invoked. OPTIONS known by damaver are described in the next section.

Command-Line Arguments and Options

Damaver recognizes the following command-line options.

Interactive Configuration

If the OPTIONS and INPUTFILE are omitted, additional parameters which are pre-calculated by the program (as default values) can be modified interactively as shown in the table below. Otherwise these questions are skipped.

damaver interactive prompt:

Runtime Output

In the case of automatic mode, i.e., when all of the different programs of the suite are called, please refer to their respective runtime output sections, e.g. damsel runtime ouput. In batch and dialog mode runtime ouput comprises information about the files being read, the total number of structures, total number of atoms, overall dimensions (refered to as "gabarites") of the box in which the models fit, number of knots in the grid, number of remote atoms and number of atoms written. An example from a run in batch mode is shown here.

damaver Input Files

Default input file name is damsup.log, i.e., the output file from damsup can be directly used as input for damaver. An example is given in damsup examples. The user can also make the input file for damaver manually (filename maximum 30 characters). Such an input file contains a list of PDB files to be aligned. It has the the following format:

filename1.pdb
filename2.pdb
.
.
.
filenameN.pdb

damaver Output Files

After finishing, damaver creates the output file damaver.pdb. For DAMMIN models, the excluded volumes are read from the input file and an average excluded volume is written to the file damaver.pdb in order to define the default cut-off for further processing (filtering) with damfilt.

Example

Suppose, you have an input file damsup.log for damaver as created by damsup and as shown e.g. in damsup examples. Then, using damaver in batch mode by typing

$> damaver /b

reads damsup.log and creates the following runtime output:

  ***   Computes a probability map from aligned models   ***
  ***   Command line switches:                           ***
  ***   /h for help                                      ***
  ***   /b for batch mode (input from damsup.log)        ***
  ***   /a [<Symmetry>] for automated mode (runs all)    ***
  ***   Written by D.Svergun & M.Petoukhov ---  V. 3.2   ***
  ***   Last revised         ---  25/07/2007 18:45       ***
  ***   Copyright (c) ATSAS Team                         ***
  ***   EMBL, Hamburg Outstation, 2001 - 2007            ***

  Reading file  model6-1.pdb
 Excluded volume read ................................... : 3.400e+4
 Number of atoms read in ................................ : 1030
  Reading file  model1-1r.pdb
 Excluded volume read ................................... : 3.400e+4
 Number of atoms read in ................................ : 2059
  Reading file  model7-1r.pdb
 Excluded volume read ................................... : 3.400e+4
 Number of atoms read in ................................ : 3090
  Reading file  model8-1r.pdb
 Excluded volume read ................................... : 3.390e+4
 Number of atoms read in ................................ : 4118
  Reading file  model3-1r.pdb
 Excluded volume read ................................... : 3.380e+4
 Number of atoms read in ................................ : 5142
  Reading file  model5-1r.pdb
 Excluded volume read ................................... : 3.380e+4
 Number of atoms read in ................................ : 6167
  Reading file  model4-1r.pdb
 Excluded volume read ................................... : 3.360e+4
 Number of atoms read in ................................ : 7186
  Reading file  model9-1r.pdb
 Excluded volume read ................................... : 3.410e+4
 Number of atoms read in ................................ : 8219
  Reading file  model10-1r.pdb
 Excluded volume read ................................... : 3.380e+4
 Number of atoms read in ................................ : 9242
  Reading file  model2-1r.pdb
 Excluded volume read ................................... : 3.360e+4
 Number of atoms read in ................................ : 10261
    - - - - - - - - - - - - - - - - - - - - -
 Total number of structures ............................. : 10
 Total number of atoms .................................. : 10261
 Average excluded volume ................................ : 3.386e+4
                   Overall gabarites
  Xmin =   -19.882999999999999           Xmax =    20.638000000000002
  Ymin =   -21.834000000000000           Ymax =    21.239000000000001
  Zmin =   -27.324000000000002           Zmax =    25.584000000000000
 Number of knots in the grid ............................ : 5837
 Number of remote atoms ................................. : 0
 Number of atoms written ................................ : 2997

Damfilt

Table of Contents

• Manual
  • Introduction
  • Running damfilt
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • damfilt Input Files
  • damfilt Output Files
• Example

Manual

Introduction

Damfilt is a program that filters an averaged model as created by damaver at a given cut-off volume. Given the frequency map computed by damaver and the value of a cut-off volume, damfilt removes low occupancy and loosely connected atoms and writes a compact - most probable - model into the output file damfilt.pdb . The output volume is selected to be close to the cut-off volume (expected excluded volume of the particle). This value is either read from the input file (default file name is damaver.pdb) or prompted interactively.

Running damfilt

$> damfilt [[INPUTFILE] [OPTIONS]]

Here, INPUTFILE is an input PDB file of the model to be filtered (by default: damaver.pdb). The cut-off value for filtering is taken to be half of the volume of this model. If neither INPUTFILE nor any OPTIONS are given then dialog mode is invoked where it is possible to specify one's own cut-off value. OPTIONS known by damfilt are described in the next section .

Command-Line Arguments and Options

Damfilt recognizes the following command-line options.

Interactive Configuration (Dialog mode)

In dialog mode, i.e., when neither INPUTFILE nor OPTIONS are given, damfilt asks for the following input:

damfilt interactive prompt:

Runtime Output

When running damfilt in batch mode (see Command-Line Arguments and Options) or in Dialog Mode, the program prints on the screen information about the number of atoms read, the center of the dummy atom model, maximum radius, number of phases, atomic radius, excluded volume per atom, average excluded volume read, minimum and maximum number of contacts, number of atoms written and final excluded volume. For an example,see damfilt examples.

damfilt input files

Input file for damfilt is a pdb file which one wants to filter. The default input file is damaver.pdb which is the output file from damaver.

damfilt output files

The output file from damfilt is the filtered model written to damfilt.pdb. The header contains information about the initial dummy model name, the total number of atoms, the atomic radius, excluded volume per atom, averaged excluded volume, reduced number of atoms, radius of the coordination sphere, cut-off volume and contact threshold to discard. The footer shows the number of atoms written and the final excluded volume of the filtered model. An example is shown in the damfilt examples.

damfilt examples

An example of a damfilt run in batch mode, i.e, by typing damfilt /b looks like this:

  ***   Filters a probability map from DAMAVER           ***
  ***   Command line switches:                           ***
  ***       /h for help                                  ***
  ***       /b for batch mode (input from damaver.pdb)   ***
  ***   Written by D.Svergun & M.Petoukhov ---  V. 4.1   ***
  ***   Last revised         ---  24/07/2007 16:30       ***
  ***   Copyright (c) ATSAS Team                         ***
  ***   EMBL, Hamburg Outstation, 2001 - 2007            ***

 Number of atoms read ................................... : 3196
 DAM center    :     0.0150  -0.2356   0.2416
 Maximum radius ......................................... : 30.11
 Number of phases ....................................... : 1
 Atomic radius .......................................... : 1.500
 Excluded volume per atom ............................... : 19.10
 Average excluded volume read ........................... : 3.386e+4
 Minimum number of contacts ............................. : 3
 Maximum number of contacts ............................. : 12
  Number of atoms written ............................... : 1774
  Excluded volume ....................................... : 3.389e+4

The header of the resulting filtered model in damfilt.pdb looks like this:

 ---  Created by DAMFILT    Thu Jul 30 16:32:12 2009 ---
 Initial DAM name ....................................... : damaver.pdb
    - - - - - - - - - - - - - - - - - - - - -
 Total number of atoms .................................. : 3196
 Atomic radius .......................................... : 1.500
 Excluded volume per atom ............................... : 19.10
    - - - - - - - - - - - - - - - - - - - - -
 Average excluded volume ................................ : 3.386e+4
 Reduced number of atoms ................................ : 1816
 Radius of the coordination sphere ...................... : 3.795
 Cut-off volume ......................................... : 3.386e+4
 Contact threshold to discard ........................... : 5
    - - - - - - - - - - - - - - - - - - - - -

And here is the footer of the resulting filtered model in damfilt.pdb:

   Number of atoms written ............................... : 1774
  Excluded volume ....................................... : 3.389e+4

Damstart

Table of Contents

• Manual
  • Introduction
  • Running damstart
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • damstart Input Files
  • damstart Output Files
• Example

Manual

Introduction

Given the frequency map computed by damaver and the value of a cut-off volume, damstart generates a modification of the damaver model with fixed core for further use in DAMMIN as an initial approximation. The core indices of high occupancy atoms with fair number of contacts are set to 1 so that their phases will not change in a DAMMIN run. The program writes this model to the file damstart.pdb. The core volume is selected to be close to the cut-off volume (one half of expected excluded volume of the particle). This value is either read from the input file (default file name is damaver.pdb, see damaver) or prompted interactively. If the information on the expected particle volume is missing in the input pdb file then the cuf-off value is taken to be one quarter of the volume of the model.

Running damstart

$> damstart [[INPUTFILE] [OPTIONS]]

Here, INPUTFILE is an input PDB file of the model to be modified (by default: damaver.pdb). If neither INPUTFILE nor any OPTIONS are given then dialog mode is invoked where it is possible to specify one's own cut-off value. OPTIONS known by damstart are described in the next section.

Command-Line Arguments and Options

Damstart recognizes the following command-line options.

Interactive Configuration (Dialog mode)

In dialog mode, i.e., when neither INPUTFILE nor OPTIONS are given, damstart asks for the following input:

damstart interactive prompt:

Runtime Output

When running damstart in batch mode (see Command-Line Arguments and Options) or in Dialog Mode, the program prints on the screen information about the number of atoms read, the center of the dummy atom model, maximum radius, number of phases, atomic radius, excluded volume per atom, average excluded volume read, minimum and maximum number of contacts, number of atoms written and final excluded volume of the created model. For an example, see damstart examples.

damstart input files

Input file for damstart is a pdb file which one wants to modify in order to obtain a model with fixed core. The default input file is damaver.pdb which is the output file from damaver.

damstart output files

The output file from damstart is the fixed core model written to damstart.pdb. The header contains information about the initial dummy model name, the total number of atoms, the atomic radius, excluded volume per atom, averaged excluded volume, reduced number of atoms, radius of the coordination sphere, cut-off volume and contact threshold to discard. The footer shows the number of atoms written and the final excluded volume of the fixed core model. An example is shown in damstart examples.

damstart examples

An example of a damstart run in batch mode, i.e, by typing damstart /b looks like this:

  ***   Generates an input file for DAMMIN from DAMAVER  ***
  ***   Command line switches:                           ***
  ***       /h for help                                  ***
  ***       /b for batch mode (input from damaver.pdb)   ***
  ***   Written by D.Svergun & M.Petoukhov ---  V. 1.0   ***
  ***   Last revised         ---  18/06/2004 12:30       ***
  ***   Copyright (c) ATSAS Team                         ***
  ***   EMBL, Hamburg Outstation, 2001 - 2004            ***

 Number of atoms read ................................... : 3196
 DAM center    :     0.0150  -0.2356   0.2416
 Maximum radius ......................................... : 30.11
 Number of phases ....................................... : 1
 Atomic radius .......................................... : 1.500
 Excluded volume per atom ............................... : 19.10
 Average excluded volume read ........................... : 3.386e+4
 Minimum number of contacts ............................. : 3
 Maximum number of contacts ............................. : 12
  Number of atoms written ............................... : 3196
  Excluded volume ....................................... : 6.106e+4

The header of the resulting fixed core model in damstart.pdb looks like this:

  ---  Created by DAMSTART   Fri Jul 31 11:55:58 2009 ---
 Initial DAM name ....................................... : damaver.pdb
    - - - - - - - - - - - - - - - - - - - - -
 Total number of atoms .................................. : 3196
 Atomic radius .......................................... : 1.500
 Excluded volume per atom ............................... : 19.10
    - - - - - - - - - - - - - - - - - - - - -
 Average excluded volume ................................ : 3.386e+4
 Reduced number of atoms ................................ : 1048
 Radius of the coordination sphere ...................... : 3.795
 Cut-off volume ......................................... : 1.693e+4
 Contact threshold to discard ........................... : 5
    - - - - - - - - - - - - - - - - - - - - -

And here is the footer of the resulting fixed core model in damstart.pdb:

  Number of atoms written ............................... : 3196
  Excluded volume ....................................... : 6.106e+4