CRYSOL 3 manual

CRYSOL3

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

Manual
Introduction
Running CRYSOL3
Examples

Manual

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

If you use results from CRYSOL3 in your own publication, please cite:
Franke, D., Petoukhov, M.V., Konarev, P.V., Panjkovich, A., Tuukkanen, A., Mertens, H.D.T., Kikhney, A.G., Hajizadeh, N.R., Franklin, J.M., Jeffries, C.M. and Svergun, D.I. (2017) ATSAS 2.8: a comprehensive data analysis suite for small-angle scattering from macromolecular solutions J. Appl. Cryst. 50.

Introduction

CRYSOL3 is a tool based on and complementary to CRYSOL. It 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 is different from CRYSOL in the way how the hydration shell and its scattering are evaluated. Instead of representation the shell as envelope function CRYSOL3 "incrusts" the surfaces and interiors (were possible) of atomic structure with the dummy water beads like raisins in a muffin. This way of the shell representation is more suitable for macromolecules with complex non-globular shapes and/or with cavities. Based on the location, the beads are split into three types: (i) Outer (convex) surface (ii) Concave surface (iii) Small internal cavities

The third type of the beads can in fact account for two cases where water is actually present in a cavity or, the other way around, the area is actually remains inaccessible to water and additional excluded volume should be taken into consideration (by the negative contrast of these kind of beads). Given SAXS experimental data, CRYSOL3 can fit the theoretical scattering curve by minimizing the discrepancy (chi-square value). Fitting is done by varying the contrasts of the three bead types, whereby all other parameters (e.g. everage radius of atomic group or the total volume) are taken by default. The default parameters of the contrasts for the three types of water beads are 1, 1, 0 in relative units (where 1 corresponds to dro = 0.03 e/A³), i.e. the outer and inner surfaces are hydrated similarly and the internal cavities are not contributing. The limits during the fitting are -10 to 2, where negative value corresponds to the space in fact inaccessible to water and therefore indirectly contributing to the total excluded volume (that's why the absolute value of the lower limit is higher then the upper one).

Running CRYSOL3

Usage:

$> crysol_30 [PDBFILE] [EXPDATA] [OPTIONS]

CRYSOL3 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.

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.
`-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.
`-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.
`-def`	N/A	Compute the fit with default parameters. No value is required.
`-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.

CRYSOL3 offers two modes: with and without fitting. The table below shows a list of questions for fitting mode.

Screen Text	Default	Description
`Brookhaven file name`	`N/A`, compulsory argument	CRYSOL3 reads the atomic coordinates of the structure in a Protein Data Bank format.
`Use 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
`Enter data file, CR for none`	`N/A`	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). If no data file name is provided, CRYSOL3 will run in prediction mode, i.e. without the fitting.
`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)`	`1`	Angular units in the file with experimental data. The question is only asked in the fitting mode.
`Adjust constant`	`Yes`	The option accounts for a background constant (e.g. due to slightly mismatched buffer) in the experimental data. The question is only asked in the fitting mode.
`Maximum s value`	in prediction mode: `0.5`, in fitting mode: max experimental s-value (rounded up)	Maximum scattering vector in inverse Angstroems for intensity calculations
`Number of points`	`s-max/0.005+1`	Number of points in theoretical curve
`Maximum order of harmonics`	`15`, if `s-max` < `0.5` `50`, if `s-max` > `1.0` `20` otherwise	Maximum order of harmonics (min = 5, 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.
`Electron density of the solvent, e/A***3`	`0.3340`	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.

CRYSOL3 Input Files

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

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

CRYSOL3 Output Files

Successive runs for the same PDB file will generate output files with increasing number, e.g. 6lyz00.log, 6lyz01.log, 6lyz02.log, etc.

Extension	Type	Description
`.log`	ASCII	Contains the summary of the run
`.int`	ASCII	The first line is a title. Seven columns contain: (1) experimental scattering vector in inverse Angstroems (2) resulting intensity in solution (3) atomic scattering in vacuo (4) scattering from excluded volume (5) convex border layer (6) concave border layer (7) waters in internal cavities
`.fit`	ASCII	Contains the fit to the experimental data in inverse Angstroems. Generated in the fitting mode only.
`.alm`	BINARY	Sum of the scattering amplitudes for atoms and hydration shells. It can be used in subsequent rigid body modelling with MASSHA, SASREF and BUNCH
`-water.pdb`	ASCII	Dummy water beads representing the hydration shells

Runtime Output

The following lines of output will be typically generated in the prediction mode

Brookhaven file name ................... <         .pdb >: 6lyz
Use explicit hydrogens ................. <           no >:
Enter data file, CR for none ........... <         .dat >:
Maximum s value ........................ <       0.5000 >:
Number of points ....................... <          101 >:
Maximum order of harmonics ............. <           20 >:
Electron density of the solvent, e/A**3  <       0.3340 >:
Generating waters ...
Classifying waters ...
Computing atomic amplitudes ...
Computing shell amplitudes ...
Writing the files ...

The following lines of output will be typically generated in the fitting mode

Brookhaven file name ................... <         .pdb >: 6lyz
Use explicit hydrogens ................. <           no >:
Enter data file, CR for none ........... <         .dat >: lyz_014
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) ..... <            1 >: 2
Adjust constant ........................ <          yes >:
Maximum s value ........................ <       0.5000 >:
Number of points ....................... <          101 >:
Maximum order of harmonics ............. <           20 >:
Electron density of the solvent, e/A**3  <       0.3340 >:
Generating waters ...
Classifying waters ...
Computing atomic amplitudes ...
Computing shell amplitudes ...
Fitting experimental data ...
Writing the files ...

Examples

The files 6lyz.pdb and lyz_014.dat used as examples above are included in the documentation directory of the installation package

CRYSOL 3 manual

Table of Contents