Biological
Small Angle Scattering

ATSAS online | Forum | User information | EMBL Hamburg

CRYSOL manual

crysol

Written by D. Svergun, C. Barberato, M. Malfios, V. Volkov, P. Konarev, M. Petoukhov, and A. Shkumatov.
Post all your questions about CRYSOL to the ATSAS Forum.

Manual
Examples

Manual

The following sections shortly describe the method implemented in CRYSOL, how to run CRYSOL from the command-line on any of the supported platforms, describe the dialog mode as well as the required input and the produced output files.

If you use results from CRYSOL in your own publication, please cite:
Svergun D.I., Barberato C. & Koch M.H.J. (1995) J. Appl. Cryst. 28, 768-773.

Introduction

CRYSOL is a program for evaluating the solution scattering from macromolecules with known atomic structure and fitting it to experimental scattering curves from Small-Angle X-ray Scattering (SAXS). As an input one can use a PDB file with an X-ray or NMR structure of a protein or a protein-DNA(RNA) complex.

The program uses multipole expansion of the scattering amplitudes to calculate the spherically averaged scattering pattern and takes into account the hydration shell. Given SAXS experimental data, CRYSOL can fit the theoretical scattering curve by minimizing the discrepancy (chi-square value).

Fitting is done by varying three parameters: (i) average displaced solvent volume per atomic group (ii) contrast of the hydration shell (iii) relative background

Running crysol

Usage:

$> crysol [PDBFILE] [EXPDATA] [OPTIONS]

CRYSOL accepts absolute as well as relative path to PDBFILE and EXPDATA

If no input files are given, the configuration is done in interactive mode.

If no options are provided, default values are used.

Command-Line Arguments and Options

It is possible to provide one or multiple arguments to CRYSOL. Regular expressions, e.g. *.pdb or exp*.dat are supported and should be surrounded by double quotes (e.g. "m*.pdb" or "a??.dat").

Argument	Description
`file1.pdb`	CRYSOL reads the atomic coordinates of the structure in a Protein Data Bank format.
`exp.dat`	Experimental data. The first line is always treated as a title. The following lines should contain momentum transfer, non-zero intensity and standard deviation in a free format (separated by blanks or commas). If standard deviations are not present, the errors are estimated automatically with the help of a polynomial smoothing procedure.
`data.sav`	CRYSOL saves all the relevant information including scattering amplitudes into the '.sav' file, which saves the time in the successive calculations with the same PDB file.

Option	Default	Description
`-lm`	15	Maximum order of harmonics (min = 1, max = 50). Defines the resolution of the calculated curve. Default value should be sufficient in most of the cases. For large particles high orders could improve the results, but more CPU time is required. Fractional values are not allowed.
`-fb`	17	Order of Fibonacci grid (min = 10, max = 18). The order of Fibonacci grid defines the number of points describing the surface of the macromolecule. Higher grid orders give a more accurate surface representation, but more CPU expensive. Default value is sufficient for most of the cases.
`-sm`	0.5	Maximum scattering vector in reverse angstroms (max = 1.0 Å^-1) either for calculating the theoretical curve up to sm or for fitting till sm.
`-ns`	51	Number of points in the theoretical curve (max = 5000).
`-un`	N/A	Angular units of the experimental data: 1 = 1/Å, s = 4πsin(θ)/λ 2 = 1/nm, s = 4πsin(θ)/λ 3 = 1/Å, s = 2sin(θ)/λ 4 = 1/nm, s = 2sin(θ)/λ By default, an attempt is made to estimate the unit scale.
`-dns`	0.334	Solvent density (e/Å³). Default value is the electron density of pure water. Solvents with high salt concentration may have a somewhat higher electron density. User can adjust the value accordingly.
`-dro`	0.03	Contrast of hydration shell (e/Å³).
`-kp`	N/A	Creates optional output files: (i) in prediction mode: .sav and .flm (ii) in fitting mode: .int, .alm, .sav and .flm. No value is required
`-cst`	N/A	Constant subtraction. This operation accounts for possible systematic errors due to mismatched buffers in the experimental data. Constant is a sum of intensities over high-angle part of the experimental data divided by number of experimental points in this part. By default, lower and upper limit for constant subtraction is -0.5 and 0.5 respectively. Limit is a multiplier for the constant subtraction. Limits can be manually adjusted when minimization with new limits is selected. Constant subtraction may improve the fit. No value is required
`-eh`	N/A	Account for explicit hydrogens. No value is required.
`-err`	N/A	Write experimental errors to the .fit file. No value is required.
`-old`	N/A	Read a PDB file with an old atom naming (pre 2008). No value is required.
`-nmr`	1	Sequential number of a model or an NMR conformer to process. Models in PDBFILE should be separated by MODEL and ENDMDL fields.
`-cid`	N/A	Compute theoretical scattering only for certain chain identifier(s). By default, all chains are processed. If there is "_" before chain identifier, all chains except for specified will be processed
`-h`	N/A	Print help information on running CRYSOL in batch mode and exit
`-v`	N/A	Print version information and exit

Interactive Configuration

If the optional arguments are omitted, settings available through command-line arguments and options may also be configured interactively as shown in the table below.

CRYSOL offers several options. They can be subdivided into two groups: with and without fitting. The table below shows a list of questions for fitting mode.

Screen Text	Default	Description
`Enter your option?`	0	The default option (0) evaluates the scattering curve from a PDB file, optionally fits the experimental data and saves the results. Option (1) evaluates only the envelope function of the macromolecule and saves it into the .flm file. Option (2) retrieves the information previously saved in the file with extension ".sav". This option can be used, e.g. to compare the same atomic structure against several sets of experimental data.
`Brookhaven file name?`	`N/A`	Same as `PDBFILE`-argument. Default extension is ".pdb".
`Process model number?`	`N/A`	This question is asked if there are several models present in the PDBFILE (e.g.: NMR ensemble). Same as `nmr`-option.
`Process chain (0: all chains)`	`N/A`	This question is asked in case of multi-chain proteins. Same as `cid`-option.
`Maximum order of harmonics?`	`15`	Same as `lm`-option.
`Maximum s value?`	`0.5`	Same as `sm`-option.
`Number of points?`	`51`	Same as `ns`-option.
`Account for explicit hydrogens?`	`NO`	The hydrogen atoms are automatically taken into account as a part of atomic group. It means that any ATOM/HETATM line in the input PDB file, which has a string 'H' in the 13 or 14th column will be discarded. If hydrogens generated by third party program are explicitly taken into account, they must conform with PDB conventions or simply have "H" in the 14th column, whereas 13th, 15th and 16th column should be empty
`Fit the experimental curve?`	`YES`	Performs fitting of theoretical curve to experimental data.
`Enter data file?`	`N/A`	Same as `EXPDATA`-argument. Default extension is ".dat"
`Subtract constant?`	`NO`	Same as `cst`-option.
`Angular units in the input file: 4pisin(theta)/lambda [1/angstrom](1) 4pisin(theta)/lambda [1/nm] (2) 2 * sin(theta)/lambda [1/angstrom] (3) 2 * sin(theta)/lambda [1/nm] (4)`	`2`	Same as `un`-option.
`Electron density of the solvent, e/A***3?`	`0.3340`	Same as `dns`-option.
`Plot the fit?`	`YES`	Plots the fit.
`Another set of parameters?`	`NO`	Allows to perform new fitting using manually defined limits for the minimization procedure.
`Minimize again with new limits?`	`NO`	Allows to use standard limits for minimization or manually define new limits.
`Minimum radius of atomic group?`	`1.4`	Defines minimum radius of atomic group.
`Maximum radius of atomic group?`	`1.8`	Defines maximum radius of atomic group.
`Smax in the fitting range?`	`var`	Maximum value of scattering vector. By default, CRYSOL takes the last point.
`Minimum contrast in the shell`	`0.0`	Minimum contrast of the shell.
`Maximum contrast in the shell`	`0.075`	Maximum contrast of the shell.
`Minimum excluded volume`	`var`	Minimum excluded volume. Default value is calculated on the fly.
`Maximum excluded volume`	`var`	Maximum excluded volume of the shell. Default value is calculated on the fly.
`Minimum relative background`	`-0.5`	Lower limit for constant minimization.
`Maximum relative background`	`0.5`	Upper limit for constant minimization.

Runtime Output

On runtime, the following lines of output will be generated for each PDB file:

  ------------------------------------------------
          Following file names will be used:
 6lyz00.log -- CRYSOL log-file          (ASCII)
 6lyz00.sav -- save CRYSOL information  (binary)
 6lyz00.flm --   multipole coefficients (ASCII)
 6lyz00.int --   scattering intensities (ASCII)
 6lyz00.fit -- fit to experimental data (ASCII)
 6lyz00.alm --   net partial amplitudes (binary)
  ------------------------------------------------

Successive runs for the same PDB file will generate output files with increasing number, e.g. 6lyz01.log, 6lyz01.sav, etc. The size of the output file names is limited to 12 characters. If the PDB file name (without extension) is longer than 5 characters the output file names will be truncated, e.g.: output file names for the PDB file atw2rsta.pdb will be atw2rs00.log, atw2rs00.sav, etc. The program also truncates the string "pdb" at the beginning of the PDB files.

 Number of atoms read .................................. : 1001

Number of atoms read from PDB file.

 Number of discarded waters ............................ : 101

Number of discarded water molecules.

 Center of the excess electron density:  0.446 -0.004  0.272

Coordinates of the center of excess electron density.

 Electron   rg   :  13.99       Envelope   Rg      :  14.01
 Shape      Rg   :  13.97       Envelope  volume   : 0.1842E+05
 Shell    volume : 0.1158E+05   Envelope  surface  :  3232.
 Shell      Rg   :  18.89       Envelope  radius   :  25.49
 Shell    width  :  3.000       Envelope  diameter :  49.04
 Molecular weight: 0.1432E+05   Dry volume         : 0.1735E+05
 Displaced volume: 0.1741E+05   Average atomic rad.:  1.607

Calculated structural parameters (sizes in angstroms)

 Number of residuals :   129

Number of amino acid residues in PDBFILE

 Title:  02-Oct-2006       (lysB_014.da - 1.000 *Avrag05.dat) /  4.1300

The first line of EXPDATA file

 Maximum angle in the data file ........................ : 4.861

Maximum value of scattering vector in the data file

 Number of experimental points ......................... : 2048

Total number of experimental points found

 Angular units multiplied by ........................... : 0.1000

See un-option

 Number of points after regriding ...................... : 204

Experimental curve is divided into bins. Number of bins depends on the number of experimental points. For each bin (point) scattering intensity and error is calculated. This allows to speed up fitting step.

 Number of experimental points used .................... : 204

Number of experimental points used for fitting.

 6lyz.pdb  Dro:0.015  Ra:1.560  RGE:15.11  RGT:14.91  Vol: 17322.  Chi:1.311

Results of fitting '6lyz.pdb' to experimental data:

Field Description

Dro Optimal contrast of hydration shell.

Ra Optimal radius of atomic group.

RGE Radius of gyration estimated from experimental curve.

RGT Radius of gyration estimated from theoretical curve.

Vol Optimal excluded volume.

Chi Discrepancy between theoretical and experimental curves.

 Rg from the slope of net intensity ..................... : 14.94

Radius of gyration calculated from the slope of net intensity

 Average electron density ............................... : 0.4714

Calculated average of electron density

crysol Input Files

CRYSOL reads the atomic coordinates of the structure in Protein Data Bank format

Optionally an experimental curve can be supplied. See EXPDATA-argument.

crysol Output Files

Extension	Type	Description
`.log`	ASCII	Contains the screen output and the detailed warning messages.
`.sav`	BINARY	Contains the amplitudes among other necessary information to evaluate the intensities curves.
`.flm`	ASCII	Contains the multipole coefficients Flm which describe the particle envelope. It can be visualized in MASSHA.
`.int`	ASCII	The first line is a title. Five columns contain: (1) experimental scattering vector in reverse angstroms, (2) theoretical intensity in solution, (3) in vacuo, (4) the solvent scattering and (5) the border layer scattering.
`.fit`	ASCII	Contains the fit to the experimental data in reverse angstroms.
`.alm`	BINARY	Sum of the scattering amplitudes for atoms, excluded volume and border. It can be used for rigid body modelling with MASSHA, SASREF and BUNCH later.

Examples

All examples use 6lyz.pdb, lyz_014.dat and lyzexp.dat. They are included in the documentation directory of the installation package

Calculating scattering intensity without fitting

$ crysol 6lyz.pdb -lm 18

Use CRYSOL to calculate the scattering intensity from the PDB file. Maximum order of harmonics = 18

Processing of PDB file with fitting.

$ crysol 6lyz.pdb *.dat -cst

Use CRYSOL to calculate the scattering intensity from the PDB file, fit to all available experimental data, use constant subtraction to improve fit.

Processing multiple PDB files with fitting.

$ crysol "6lyz?.pdb" lyzexp.dat -cst

Use CRYSOL to calculate the scattering intensities from PDB files: 6lyz1.pdb, 6lyz2.pdb, 6lyz3, etc and fit to all experimental data, use constant subtraction to improve fit.

$ crysol *.pdb lyzexp.dat -sm 0.25

Use CRYSOL to process all PDB files in current directory, calculate scattering intensity till 0.25 and fit to experimental data

$ crysol 1f6g.pdb exp_file.dat -nmr 5 -cid _A

Use CRYSOL to process all chains except A of conformer #5 from NMR ensemble (1f6g.pdb) and fit to experimental data

For more examples, try

$ crysol -help

CRYSOL manual

Table of Contents