0
EMBL Hamburg Biological
Small Angle Scattering
BioSAXS
 
  Home  >  ATSAS software  >  CRYSOL  >  Manual

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.

© ATSAS Team, 1995-2015

Table of Contents

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").

ArgumentDescription
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.
OptionDefaultDescription
-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 inverse 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/Å3). 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/Å3).
-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 Y Write experimental errors to the .fit file (Y or N).
-old N/A Read a PDB file with an old atom naming (pre 2008). No value is required.
-nmr N/A Sequential number of a model or an NMR conformer to process. Models in PDBFILE should be separated by MODEL and ENDMDL fields. By default, all models are processed.
-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 TextDefaultDescription
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:
4*pi*sin(theta)/lambda [1/angstrom] (1)
4*pi*sin(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 regridding ..................... : 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  RGT:14.94  Vol: 17322.  Chi^2: 1.311

Results of fitting '6lyz.pdb' to experimental data (written to the .fit file header as well):

FieldDescription
Dro Optimal hydration shell contrast.
Ra Optimal atomic group radius (in Å).
RGT Radius of gyration (in Å) estimated from the theoretical curve.
Vol Optimal excluded volume (in Å3).
Chi^2 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 inverse 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 inverse 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 4mld.pdb SASDAB7_fit1_model1.pdb SASDAB7.dat 

Use CRYSOL to calculate the fit of the SASDAB7 scattering curve against the ComE protein alone (4mld.pdb) and in complex with its DNA promoter region (SASDAB7_fit1_model1.pdb).

$ 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 

  Last modified: February 4, 2014

© BioSAXS group 2014