PRIMUS manual

Written by P.V. Konarev, V.V. Volkov, A.V. Sokolova and D.I. Svergun.
Post all your questions about PRIMUS to the ATSAS Forum.

© ATSAS Team, 2003-2009

Table of Contents

• Manual
  • Introduction
  • PRIMUS User Interface
    • Menus
    • Tools Window
  • Using PRIMUS
    • Loading data
    • Data manipulation
    • Determine overall structural parameters and invariants
    • Extrapolation to zero concentration
    • Save a subset of data
  • Calling to external modules
    • AUTORG
    • GNOM
    • SVDPLOT
    • OLIGOMER
    • MIXTURE
    • BODIES
    • PEAK
    • AXIS

Manual

Introduction

Program PRIMUS perfoms the manipulations with experimental small-angle scattering data files such as: averaging, subtraction, merging, extrapolation to zero concentration and curve fitting and evaluates the integral parameters from Guinier and Porod plots such as radius of gyration (for globular, flat and rod-type particles), Porod's volume, zero intensity and molecular weight. PRIMUS is compiled using Intel Fortran v.11.0 with QuickWin graphics library and runs under MS Windows 95/98/NT/2000/XP/Vista or under Windows emulators (like WINE) installed on Linux/MAC.

The program PRIMUS allows one to make interactive manipulations with data, which is convinient for users and that saves a lot of time.

If you use results from PRIMUS in your own publication, please cite:

P.V.Konarev, V.V.Volkov, A.V.Sokolova, M.H.J.Koch and D. I. Svergun (2003). PRIMUS - a Windows-PC based system for small-angle scattering data analysis. J Appl Cryst. 36, 1277-1282.

PRIMUS User Interface

Menus

Tools Window

The dialog box contains the following buttons:

Using PRIMUS

Loading data

To load data one has to select TOOLS menu option, Tools Window for manipulation with data files will appear. One can load up to 13 data files using "SELECT" button. The data files must be in ASCII format, the first column is s-vector axis, the second column is intensity signal. The number of experimental points will be read automatically and written in "nEnd" edit dialog boxes.

If one wants to plot the curve with all experimental points, just set the value for nEnd equal to "0" or to large values "9999" and the program will automatically set "nEnd" value to the actual number of experimental points.

For each data file it is possible to set the scale for the X-axis (S-axis) where scale factor ("Units" edit box) can be equal to:

1. corresponds to the identity transformation (X(i)=X(i), for i=1,NsExp)
2. corresponds to a scaling from [Nanometer]^-1 to [Angstrom]^-1: (transformation X(i) = X(i)/10, for i=1,NsExp)
3. corresponds to a scaling from "S"-vector to "Q"-vector: (transformation X(i) = 2*π*X(i), for i=1,NsExp)
4. corresponds to a scaling from "S"-vector in [Nanometer]^-1 to "Q"-vector in [Angstroem]^-1: ( transformation X(i) = 2*π*X(i)/10, for i=1,NsExp)

It is also possible to set the number of first (nBeg) and last (nEnd) points from the data file (by default it is equal to 1 and 9999 respectively), concentration of the sample (default value 1.0) and multiplier coefficient (default value 1.0).

Whether a loaded file is used in the current computation is indicated by a checkbox before the filename; it is used if checked, and ignored otherwise.

For convenient and fast file selection there is "Range" button in the dialog box for manipulations where one can choose the mask parameters for file selection. In this case the new dialog box appears where one has to specify the values for "First file" ( for example "xxxx_001" ) and for "Last file" ( for example "xxx_007"), the Row number (from which the selection will start) and the Number Increment (the increment in the run numbers to be selected) in the dialog box for manipulations, the first and the last points ("nBeg" and "nEnd" respectively) to be drawn as well as the scale for X-axis ("Iunits" = 1,2,3 or 4). If the edit box for "Last file" is empty then the program will automativcally look for all files beginning from "xxx_NNN"-"First File" up to "xxx_999" and will choose only existing files. It works also for the files with two digits at the end (XXXNN.dat). If the value for "First File" consists of three letters like "i03" without extention then the program will find all files beginning with "i03000.dat" up to "i99000.dat".

Starting from Atsas 2.6 release, the "Range" button works also for the files with four and five digits at the end of file names (e.g. xxx_00001 or xxx_00001.dat). It is also possible to use wild file name masks for the 'First File' box, e.g. one can specify there 'xxx*.dat' value and then all files starting with 'xxx' and having extension 'dat' will be automatically loaded.

Data manipulation

Determine overall structural parameters and invariants

Extrapolation to zero concentration

Save a subset of data

The current region of the loaded (and active) data can be saved using "Save_data" menu option. The names of the output files will be the following: prsave1.dat, prsave2.dat etc. They will correspond to the sequence of the loaded (active) files and will contain three columns (s-axis, intensities, errors (if any) ).

Calling to external modules

AUTORG

AUTORG works with the experimental data files in standard ASCII format. First, the program selects the data range suitable for the Guinier approximation. For this, the initial portion of the data is analysed and any range showing unreasonable upwards or downwards trends (e.g. caused by the beam stop or strong background near the primary beam) is discarded. Then the data range where the scattering intensity decays by an order of magnitude is taken. A cubic parabola is drawn in this range using a log scale of intensity to analyse the curvature and possible inflection points suggesting non-monodisperse behaviour, and the range is refined when necessary. Then a search of all possible intervals for Guinier plots starts in the selected range: for each interval (longer than a given minimum interval length in points, usually, between 5 and 15) a weighted linear fit is calculated by least squares and Rg is computed. For each interval (smin, smax), the conditions sminRg > 1 and smaxRg < 1.3 are checked and the absence of systematic variations is verified, in which case the interval is considered consistent. If no consistent intervals are found, the program tries to find intervals with weakened sRg conditions, but simultaneously reduces the estimate of the data quality. Each consistent interval is rated according to its length (number of points fitted) and discrepancy (root-mean-square deviation of the fit), and the interval with the best rating is selected. The accuracy of Rg is estimated by taking into account not only the error propagation in the selected fit as usual but also by accounting for the deviation of Rg values calculated from other consistent intervals, accounting to some extent for systematic errors in the Rg determination. An estimate of the overall data quality is then expressed by taking into account several criteria:

1. how many consistent intervals were found;
2. whether the sRg conditions were weakened or not;
3. how many starting points were discarded;
4. whether there are indication of effects like aggregation;
5. how accurate is the value of Rg.

This estimate is then made available to other programs in the pipeline, in particular to AUTOSUB for selecting the optimum subtraction of the background. AUTORG tries to translate the perceptual criteria used during interactive Rg analysis by Guinier approximation into an algorithm to compute Rg and to estimate the quality of the fit. The program has several tunable parameters, such the intensity decay in the fitting range, the minimum interval length in points, the worst acceptable sminRg and smaxRg limits, and the length and discrepancy weights used for the interval rating. These parameters are currently tuned to provide the most stable results, but in future releases can be adjusted by the user. The console version of AUTORG using default parameters was tested on numerous data sets and the results were compared with those of manual Rg determination with PRIMUS; in the vast majority of cases the automated system yielded the same results as those obtained interactively by an experienced user. Currently the automated mode covers cases of monodisperse or moderately polydisperse systems with sufficiently high contrast, but further work is planned to extend its range of applicability. For more detailed description, see AUTORG manual.

GNOM

Program GNOM calculates the distance distribution function p(r), The parameters that can be changed by user are in the dialog box which pop up when clicking on GNOM menu.These are the first and the second input files, by default the fisrt file is assigned the name of the output file or the first active file name in the Tools dialog box. The second file by default is empty. The output file name by default is gnom.out. The values Nbeg and Nend define the first and the last points in the input files that will be taken into account, (CAUTION: by default they are the same as in Tools dialog box for output or first actice file and they differ from Nskip1 and Nskip2 values that are usually used by GNOM program alone). Rmin and Rmax values define the bounds for the possible particle sizes in the sample. By defualt they are equal to zero. There is an option to fix zero values of p(r) function at this points. One can choose also the options to show the plot with ALPHA parameter search as well as to show the calculated errors in distribution function. One can reset all parameters to default values using "Reset" button. "Run" button starts the "GNOM" program. For more detailed description, see GNOM manual.

SVDPLOT

Given a matrix A with logical dimensions "m" rows by "n" columns and physical dimensions "MD" by "ND", this routine computes its singular value decomposition (SVD) A = U * S * V (T), where columns of the orthogonal matrix U are the eigenvectors of the matrix A * A(T) , as well as columns of V are the eigenvectors of the matrix A(T) * A, and diagonal matrix S contains ordered singular values of A, that are the nonnegative square roots of eigenvalues of either A(T) * A or A * A(T) .

The method used is a slightly modified procedure by G.H.Golub and C.Reinsh decribed in [1-2]. The procedure consists of two stages. In the first stage A is transformed to an upper bidiagonal matrix B by a sequence of Householder transformations. The second stage is the application of a specially adapted QR algorithm to compute the singular value decomposition of B.

References:

1. Golub G.H., Reinsh C. "Singular Value Decomposition and Least Squares Solution" (1970) Numer. Math., Vol.14, P.403-420.
2. Lawson CH.L., Hanson R.J., "Solving Least Squares Problems" (1974), chapter 18.

OLIGOMER

OLIGOMER fits the experimental scattering curve I(s) from multicompoment mixture of proteins via search the contributions wi of each component Ii(s) to resulting scattering: The experimental data file must be in ASCII format. The basic scattering functions (form-factors) should be either precomputed or measured and then stored in separate file. The latter should contain (K+1) columns. First column is a set of values of momentum transfer (s) and columns from second to last one are the scattering intensity of components. After starting OLIGOMER you will need to specify: Form-factor file (Scattering intensity of form-factors M U S T be contained in Angstroms); Experimental data file in ASCII format; Name of Output .fit file. After finishing OLIGOMER you will get the files: oligomer.log: log file (will be create in folder contained input files) 'name'.fit: calculated fit to the experimental data. The file 'oligomer.log' will contain information about input and output files, information about used method of solution (non-negative conditional or unconstrained least-square solution) and calculated values of molecular weights, radii of gyration and volume fractions for each of component. For more detailed description, see OLIGOMER manual.

MIXTURE

Program MIXTURE makes the fitting to the experimental scattering curve by modelling the multicomponent system represented by simple geometrical bodies taking into account interparticle interactions.

The model scattering intensity may be represented by the linear combination of four several types of particles:

1. spheres
2. cylinders
3. ellipsoids of rotation
4. dumb-bells

The spheres and cylinders may have complicated features: 1. polydispersity on radius with Gauss or Schultz distribution 2. two shells with different contrasts (zero contrast of the inner shell means the hole sphere or cylinder). The interparticle interactions between sphere particles can be described by structure factor calculated within Percus-Yevick approximation for hard-sphere or sticky hard-sphere potential.(see below ref [2] Baxter, 1968) described by two parameters: the hard-sphere interaction radius R_k^hs and the "stickiness" τ_k.

MIXTURE allows one to model mixtures containing up to ten different components (i.e. different types of particles)

Fitting parameters of the individual phases are described in MIXTURE manual

For running the program MIXTURE it is necessary to prepare the command file where one has to specify your model and initial values of parameters for this model, i.e. the number of "phases" (components), the type for each component (SPHERE, CYLINDER, ELLIPSOID, DUMBBELL), dimension parameters (relative volume fraction, average sphere radius, its polydispersity, type of distribution function (Gauss or Schultz) etc., the upper and lower boundary values for all fitting parameters.

Below there is example of command file for the model containing different types of components (spheres+cylinders). One can design the model containing several components of the same type (for example large and small spheres, long and short cylinders etc.), but in all cases one has to follow the thumb rule of describing the model parameters as it is done in this example command file:

Below symbols !! are used for comments. For your convienence it is recommended to keep the comments on each line, the program will automatically detect them.

Example Command File (spheres+cylinders)

Some description         !! Comment Line 1 (done by user )
Some description         !! Comment Line 2 (done by user )
EXPERIMENT               !! MODE FOR FITTING DATA,  "TEST" MODE FOR EXPERTS
2                        !! Number of Phases (2 for this example)
0.20                     !! System Concentration
SPHERE                   !! Type of the first Phase
0.25   0.0      1.0      !! sphere volume Fraction
0.0    0.0      0.0      !! inner shell sphere radius
0.0    0.0      0.0      !! density(contrast) for inner shell  (hollow sphere)
48.0   40.0     60.0     !! outer shell sphere radius
1.0    1.0      1.0      !! density(contrast) for outer shell
5.0    0.1      25.0     !! sphere polydispersity
75.0   55.0     95.0     !! interaction radius for spheres (hard sphere radius)
2                        !! type of distributions for spheres (1 - Gauss, 2 - Schulz)
0.0    0.0      0.0      !! sticky parameter (0.1 .GT. tau .LT. 100), if tau=0 no interactions
CYLINDER                 !! Type of the second Phase
0.25   0.0      1.0      !! cylinder volume Fraction
0.0    0.0      0.0      !! inner shell cylinder radius
0.0    0.0      0.0      !! density(contrast) for inner shell
40.0   30.0     60.0     !! outer shell cylinder radius
1.0    1.0      1.0      !! density(contrast) for outer shell
3.0    2.1      10.1     !! cylinder outer shell radius polydispersity
2                        !! type of distributions for cylinders (1 - Gauss, 2 - Schulz)
300.0                    !! cylinder length
2                        !! type of data (1 - for OTOKO format, 2 - for ASCII format)

PRIMUS has special dialog box for calling Mixture program ("Mixture"), in this dialog one has to specify Command file (see example above), Experimental data file, as well as Angular units (by default 1) and Fraction of data taken for evaluation (by default 1.0). Then one has to select "Apply" button. In the graphic window the program will plot the experimental data and the best fit as well as the partial intensities of the model components.

The output files of the program mixture are the following: 3 files with extensions *.fit, *.pam, *.str, where the names of files coincide with the file name of experimental data as well as mixture.log file

Mixture.log file contains information about the file name of experimental data and obtained fitting parameters for your model for each component. After each run the program mixture adds information to this file, so you will have the whole history of running the program in this file.

Useful References:

1. D.I. Svergun, P.V.Konarev, V.V.Volkov, M.H.J. Koch, W.F.C. Sager, J. Smeeth and E.M. Blokhuis // A Small Angle X-ray Scattering Study of the Droplet-Cylinder Transition in Oil-Rich Sodium Bis(2-ethylhexyl) Sulfosuccinate Microemulsions. Journal of .Chemical Physics 2000, V.113, N. 4, p. 1651-1665
2. R.J.Baxter J.Chem.Phys. 49, (1968), 2270-2273.

For more detailed description, see MIXTURE manual.

BODIES

Program BODIES makes the approximation of the experimental scattering curve by the simple geometrical bodies. There are six possible types of bodies available for approximation:

1. ellipsoid (semiaxes a,b,c)
2. ellipsoid of revolution (semiaxes a,a,c)
3. cylinder (radius r, height h)
4. elliptic cylinder (radius semiaxes a,b, height h)
5. hollow cylinder (outer radius R,inner radius r,height h)
6. rectangular prism (sides a,b,c)

To do this approximation with PRIMUS one has to select BODIES menu option from the main menu. The popup dialog box will appear. In this dialog one has to specify the following parameters:

1. experimantal data file (by default the first active data file in the "Tools" dialog box will be selected)
2. the angular units of data. For each data file it is possible to set the scale for the X-axis (S-axis) where:
   1. - corresponds to the identity transformation (X(i)=X(i), for i=1,NsExp)
   2. - corresponds to a scaling from [Nanometer]^-1 to [Angstrom]^-1: (transformation X(i) = X(i)/10, for i=1,NsExp)
   3. - corresponds to a scaling from "S"-vector to "Q"-vector: (transformation X(i) = 2*π*X(i), for i=1,NsExp)
   4. - corresponds to a scaling from "S"-vector in [Nanometer]^-1 to "Q"-vector in [Angstroem]^-1: ( transformation X(i) = 2*π*X(i)/10, for i=1,NsExp)
3. the fraction of the data used for evaluation (by default 1.0 corresponds to the whole experimental curve)
4. the type of the geometrical body used for approximation, the number must be from 1 to 6 or equal to 0 (in case of all these types)

The best fits to the experimental data will be plotted. The parameters of the geometrical bodies are written in the text window. The output information are stored in the "expfilename"-bodies.dat file (in case of all bodies, type number = 0 ) or in "expfilename"-ellips.dat, -ell2ax.dat, -cylind.dat, -cylell.dat, -cylholl.dat, -parall.dat files respectively.

One can run BODIES as a separate application, in this case one can choose/change the starting values of fitting parameters.

PEAK

Program PEAK is designed for evaluating the positions of peaks for scattering profiles and calculating the structural characteristics of the systems. The program is running under Windows NT/9x/2000/XP.

The following structural parameters that can be calulated from the characteristics of the peaks:

1. Bragg spacing d = 2π / S_max
2. long-range order dimension L = λ / ( βs * cos (θ_Max) ) ,where λ - wavelength of X-rays, β_s - full width at a half-maximum intensity of the peak (in radians), θ_Max - scattering angle corresponding to Smax.
3. radius of interaction R_m = (π/2.5)² * λ / β_s
4. degree of disorder Δ/d = (1/π) * ( β_s * d / λ ) ^1/2

For more detailed description, see PEAK manual.

AXIS

The angular axis file can be created from the scattering patterns of the samples with defined Bragg spacing values. Tripalmitin, Turkey Tendon Collagen or Ag-behenate are usually taken for camera calibration. PRIMUS calls the special graphical program AXIS-DAT, where one has to load the experimental data in ASCII format. AXIS plots the graph of detector counts against the channel numbers of the detector. The scattering patterns contain several distinct sharp diffraction peaks. The fitting region for each peak can be selected with the mouse cursor and the positions of peaks in the diffraction pattern of collagen, tripalmitin or Ag-behenate will be defined automatically. The pop-up menu dialog of AXIS-DAT (called "MakeAxis") includes the defined positions of selected peaks as well as their corresponding diffraction order indexes. Then the linear interpolation of defined peak positions (calculated in nm-1) along the appropriate channel numbers of the detector allows one to create the angular axis file. The output angular file is written in ASCII format.