Manual

The following sections briefly describe how to run Bodies from the command-line, details the dialog mode as well as the required input and output files.

Introduction

BODIES is a program that evaluates the theoretical scattering from geometric bodies. In addition, it is possible to fit this scattering to experimental curves or to create dummy-atom models of the body in question, as well as generate search volumes, possibly pre-populated, suitable for the use with ab-initio modelling applications like DAMMIN and MONSA. Input is therefore either experimental data or the dimensions of the body. The currently supported body types are:

  • ellipsoid (semiaxes, a, b, c)
  • rotation-ellipsoid (semiaxes, a, c)
  • cylinder (radius \(r\), height \(h\))
  • elliptic-cylinder (radii semiaxes a, c, height \(h\))
  • hollow-cylinder (outer radius \(r_o\), inner radius \(r_i\), height \(h\))
  • parallelepiped (sides a, b, c)
  • hollow-sphere (outer radius \(r_o\), inner radius \(r_i\))
  • dumbbell (radius of the first ball, \(r_1\), radius of the second ball, \(r_2\), and their center-to-center distance \(d\))
  • liposome (parameters \(a\) through \(f\))
  • membrane protein (rmemb, rtail, rhead, delta, z-corona)

Running bodies

Usage:

$ bodies [OPTIONS] [EXPDATA]

OPTIONS known by BODIES are described in next section, the optional argument EXPDATA in the section on input files. If no options are provided, default values are used.

If EXPDATA is omitted, interactive configuration is initiated. Interactively, BODIES may be run in four different modes:

  • fit - fit a geometric body to experimental data
  • predict- predict the scattering pattern of a geometric body
  • dam - generate a Dummy Atom Model of a geometric body
  • search-volume - generate a search volume suitable for use with ab initio modelling programs.

If started without arguments and options, the mode may be selected, further interactive configuration options depend on the selected mode.

Screen Text Default Description
Operation mode? Select one of: (f) fit, (p) predict, (d) dam, (v) search volume fit Select operation mode: fit, predict, dam or search-volume.

Fit Mode

Command-Line Arguments and Options

When running BODIES from the command-line only the default mode, fitting, is possible. The remaining modes can be accessed in the interactive configuration.

Argument Description
EXPDATA Experimental data in any of the supported file formats.

BODIES accepts the following command line options:

Short Option Long Option Description
-p --prefix <PREFIX> The prefix to prepend to output filenames. May include absolute or relative paths, all directory components must exist. Default is the basename of EXPDATA.
  --body <BODY> The type of the geometric body to fit to the experimental data. If this option is not specified, the fit of all the geometric bodies will be calculated.
  --rg <X> The expected \(R_g\), by default this is estimated from the data.
  --i0 <X> The expected \(I(0)\), by default this is estimated from the data.
  --volume <X> The expected volume, by default this is estimated from the data.
  --first <N> The first point of the Guinier range, by default this is taken to be 1.
  --last <N> The last point of the Guinier fit range. The default is 4 Shannon channels.
  --model-format <FMT> Format of the output models, one of: cif, pdb (default: cif)
  --seed <N> Allows to specify a random seed. Particularly useful to recalculate previous runs.
-q --quiet Suppress screen output, but still write a .log-file. By default, all runtime information is printed to both, screen and .log file.
-v --version Print version information and exit.
-h --help Print a summary of arguments, options, and exit.

Interactive Configuration

Screen Text Default Description
Experimental data file name? N/A Same as EXPDATA-argument.
Type of Body? 1, ellipsoid The type of the geometric body to fit to the experimental data.
Expected Radius of Gyration of experimental data? variable Same as rg-option.
Expected Intensity at s=0.0 of experimental data? variable Same as i0-option.
Expected volume at s=0.0 of experimental data? variable Same as volume-option.
First point of fit range? 1 Same as first-option.
Last point of fit range? variable Same as last-option.
Initial random seed? variable Same as seed-option.
Output prefix? N/A Same as prefix-option.
DAMSTART model output format? N/A Same as model-format-option.

Runtime Output

On runtime in fit-mode, the following lines will be generated for each geometric body.

  Initial random seed .................................... : 0
  Input file name ........................................ : adh_136.dat
  First point of fit region .............................. : 1
  Last point of fit region ............................... : 447
  Expected Radius of Gyration ............................ : 3.050
  Expected I0 ............................................ : 75.00
  Expected Volume ........................................ : 188.0

A statement of parameters used by BODIES to perform the calculation (see above)

  Body type .............................................. : ellipsoid
  Parameter 'a' .......................................... : 2.745
  Parameter 'b' .......................................... : 4.595
  Parameter 'c' .......................................... : 4.596

Type of geometric body, and its dimensions.

  Parameter 'scale' ...................................... : 1.294e-30

The scaling factor used to scale the theoretical intensities to the experimental data.

  Fit Radius of Gyration ................................. : 3.199
  Fit I0 ................................................. : 76.54
  Fit Volume ............................................. : 229.1
  Goodness of Fit (Chi^2) ................................ : 13.16

The evaluated \(R_g\), \(I(0)\), Volume and \(\chi^2\) for the submitted experimental data.

Output Files

For each selected body type to fit, three output files are created, each with the defined prefix:

Extension Description
.log A copy of the screen output
.fir Fit of the simulated scattering curve versus the experimental data.
.pdb or .cif A Dummy Atom Model representation of the body. Output format depends on the output-format option. The model is identical to a model obtained in search-volume mode, with the fit results as parameters and is suitable to be used as a search volume for DAMMIN.

Please note that existing files with the same file name will be overwritten without further notice.

Predict Mode

Interactive Configuration

Screen Text Default Description
Type of Body? 1, ellipsoid The type of the geometric body to predict scattering pattern of.
Value of parameter …? N/A The dimensions of the selected geometric body.
Value of parameter scale? N/A Intensity scaling factor, usually 1.0 in predict mode.
Rescale to absolute scale [cm^-1]/c[mg/ml]? N/A Scales from arbitrary to absolute scale, requires contrast.
Contrast of the body [cm^-2]? N/A Contrast of the body, only required if scaled to absolute scale.
Structure Factor type? 1, none An optional (sticky) hard sphere structure factor to consider.
Minimum s [Angstrom^-1]? 0 The minimum scattering vector in inverse angstroms.
Maximum s [Angstrom^-1]? 0.5 The maximum scattering vector in inverse angstroms.
Number of points in s-range? 201 The number of points in the theoretical curve.
Output filename? N/A Output file name.

Output Files

Extension Description
user defined The theoretical scattering from a geometric body created in predict mode is written with the following columns: \(s\), \(I_{\text{exp}}\). First line contains the name and dimensions of the geometric body.

Please note that existing files with the same file name will be overwritten without further notice.

DAM mode

Interactive Configuration

Screen Text Default Description
Type of Body? 1, ellipsoid The type of the geometric body to create Dummy Atom Model of.
Value of parameter …? N/A The dimensions of the selected geometric body.
Value of parameter scale? N/A Unused; set 1.
Search volume symmetry? P1 The overall symmetry of the DAM. Possible options depend on the selected body type.
Number of dummy atoms? 2000 The approximate number of dummy atoms in the model.
DAM output file name? N/A Output file name. Output format depends on extension, supported are .pdb and .cif.

Output Files

Extension Description
.pdb or .cif A Dummy Atom Model representation of the geometric body. The file format depends on the extension provided during interactive configuration. The header contains the name and dimensions of the geometric body.

Please note that existing files with the same file name will be overwritten without further notice.

Search Volume Mode

Interactive Configuration

Screen Text Default Description
Search volume shape? 1, ellipsoid The outer shape of thegeometric bodyto use as a search volume.
Value of parameter …? N/A The dimensions of the selectedgeometric body.
Value of parameter scale? N/A Unused; set 1.
Shall the search volume include a start model? Y If yes, the shape and shape parameters of the start model will be queried.
Search volume symmetry? P1 The overall symmetry of the search volume. Possible options depend on the included start model.
Number of phases in the search volume? 1 The number of phases that are allowed in this start model, usually between 1 and 4.
Number of dummy atoms? 2000 The approximate number of total dummy atoms in this start model.
DAM output file name? N/A Output file name. Output format depends on extension, supported are .pdb and .cif.

Output Files

Extension Description
.pdb or .cif A Dummy Atom Model representation of the search volume. The file format depends on the extension provided during interactive configuration. The header contains the name and dimensions of the search volume.

Please note that existing files with the same file name will be overwritten without further notice.

bodies Input Files

BODIES fits the scattering of a geometric body to an experimental curve. See EXPDATA-argument. In predict/dam mode only the dimensions of the body needs to be supplied.