The program OLIGOMER fits an experimental scattering curve from
a multicompoment mixture of proteins to find the volume fractions of
each component in the mixture.

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

The input data for oligomer is an experimental SAXS or SANS scattering
curve from a mixture of several dictinct components and a set of
form-factors for each component of this mixture.

The experimental scattering intensity I(s) from a mixture of
K different particles (components) is written as:

I(s) = ∑(w_{i}×I_{i}(s))

where w_{i} and I_{i}(s) are
the volume fraction and the scattering intensity from the i-th component,
respectively.

Given the intensities from the components (form-factors), OLIGOMER
finds the volume fractions by solving a system of linear equations using the
algorithm of nonnegative or unconstrained least-squares to minimize the
discrepancy between the experimental and calculated scattering curves.

X-ray or neutron form-factors of proteins with known structure or of dummy
atoms models can be computed using the programs CRYSOL and
CRYSON respectively, which both are part of the
ATSAS package.

OPTIONS known by OLIGOMER are described in next section.

Prior to running the application a file containing the Scattering
intensity from the form-factors must be prepared in the format:

1^{st} line: comment

from 2^{nd} line: scattering vector (s), iForm1, iForm2 ...

here, s = 4 * π * sin (θ)/λ, [1/angstrom]

Iform1, Iform2 etc are the scattering intensities of
the components. They should be normalized in such a way that
iForm(s=0) is equal (or proportional to) the square of
the molecular weight MW (or total scattering length).

OLIGOMER estimates molecular weights for calculation of volume
fractions and radii of gyration from experimental or model scattering
curves of components of the mixture. The latter values are used only
for determination of the average value of radius of giration for all
mixtures.

Therefore, one must enter the real values of molecular weight
for each component (for example, based on information about primary
sequence) in following cases:

scattering curves from components (i.e. sets of form-factors)
are standardized to I_{exp}(0) = 1

scattering curves from components calculated by CRYSOL
from dummy atom models built by programs DAMMIN
or GASBOR with beads not equal size

sets of form-factors are standardized to equally values of
I_{exp}(0)

If the iForm curves and not properly scaled, the fit not be affected
but the volume fractions will be incorrect.

If one just uses predicted CRYSOL curves from
different oligomers, no additional normalization of the form factors is required.

To quickly create form-factor file from pdb files and/or from scattering
data files (either from ASCII *.dat files where column 1 will be taken as S-axis, column 2
as intensities or from GNOM output files where desmeared curve - "Ireg" column will
be taken for intensity) one can use program FFMAKER
that automatically creates form-factor file (one can use interactive or batch mode to run the program.
There is no internal scaling in FFMAKER, the curves will correspond to CRYSOL output files (if calculated from PDB models) or
to the input scattering curves (as they are).

FFMAKER (versions from atsas 2.6 or later releases)
shall also calculate the contrasts for each of the components (in the case of input pdb files),
that will be later used by OLIGOMER (versions from atsas 2.6 or later releases)
in order to properly normalize the volume fractions of the components.
This additional adjustment of the volume fractions due to the constrasts
will have influence (up to 3-4% of correction for volume fractions) mainly for heterogenous systems
(e.g. mixtures of protein-DNA or protein-RNA molecules),
for homogenous systems (e.g. mixtures of proteins) there will be no difference
whether to take or not to take into account the contrast information (it means
the results from earlier or later versions of FFMAKER and
OLIGOMER will be the same for the latter case).

OLIGOMER and FFMAKER supports the absolute and relative paths to the input
file names (that can be important for Linux/OS users), by default the programs
are looking for the input files from the current working directory.

To process multiple data sets in the batch mode, simply pass multiple file names on the command line.
Most shells will automatically expand wildcard expressions such as *.dat into all matching file names.

NOTE: this option is available in OLIGOMER/FFMAKER only starting from atsas 2.6 or later releases

If the ratio between the fractions of the components is known, one can keep it during the OLIGOMER analysis
and find the best fit that still satisfies the desired fraction ratio. In general, the fit may become
worse compared to the result of the unconstrained analysis, however it will ensure the physically meaningful
values of the component volume fractions.

The ratios between the components should be provided in the input file for FFMAKER using
its option '/constrain' in the following format:

As an example, the above condition can be applied for an arbitrary three-component system, where the
volume fraction of the first component is forced to be equal to the volume fraction
of the second component (i.e. the following condition will be kept
1.0*V(1) - 1.0*V(2) + 0.0*V(3) = 0.0 ). Plese note that the number of coefficients in the ratio constrain file
should be the same as the number of form-factor curves.

In some cases, when the components are mixed with the certain molar ratio,
one can use the constraints for the number fraction of the components
(i.e. to keep a certain ratio between the number of molecules of different components).
For this one has to use the following format for the input constrain file:

Number Fraction Relation Coefficients: 0.0 1.0 -1.0

The above condition means that the number of molecules of component 2 is equal to
the number of molecules of component 3. In practice, such condition can correspond to the partially dissociated binary complex
which subunits were mixed with 1:1 molar ratio (here: the first component corresponds to AB complex,
the second component - molecule A, the third component - molecule B).

After running FFMAKER with the option '/constrain confileName',
the form-factor file with the following header lines will be produced:

The subsequent run of OLIGOMER with the above shown form-factor file
will find the best fit to the data from the linear combination of the components
with the volume (or number) fractions satisfying the input ratio constraints

the name of the output file, default is oligomer.log

-svd

singular value decomposition analysis of components for multiple
data curves, e.g. concentration serias, data measured at different
pH, time, temperature, pressure, salt concentration,
buffer composition, ligand addition, etc.

-compar

comparative analysis of the fits from all possible combinations of
the form-factor curves, this option is useful to separate the most
significant components that contribute to the fitted curve from the
components that only slightly influence the fit result.

-cst

adds constant as additional component. Default value is 10 times
greater than maximum I(0) value from the form-factor file.
This choice of constant will keep the volume fraction of the "constant"
component equal to 0 providing correction of the scattering curve
from parasitic constant background.
In batch mode one needs to provide only the option "-cst"
(without value for the constant).
The constant value can be changed only in interactive mode.

-pl

plots the fitted curves using sasplot

-br

brief output for .log file

Please note: if one runs OLIGOMER in batch mode for several data sets
that have different starting s-values and '/smin' option is not used, it will
automatically determine the maximum s-value among all starting s-values
and take it for fitting of all data sets.

If one explicitly uses '/smin' option,
all data sets will be taken starting from the specified 'smin' value.

If one runs OLIGOMER for the individual data set without specifying
'/smin' option, then the complete angular data range will be taken
for fitting.

OLIGOMER reads experimental data and form-factors
(both should be in ASCII format).
After starting OLIGOMER you may specify:

Prompt

Possible value(s)

Default value

Description

Program option

0 or 1

0

option 0 - permits to run OLIGOMER for multiple data sets using one
form-factor file, option 1 - permits to use multiple form-factor
files for fitting one data file.

Input data, form-factor file name

filename

ff.dat

Input file should contain intensity values from at least one component.
It can be prepared by FFMAKER program from *.pdb, *.dat and *.out (GNOM)
files or manually by composing the following columns:
1st column - s-axis, 2nd column - intensity from component 1,
3rd column - intensity from component 2 etc.

Use constant as additional component

Y or N

N

if 'Yes' - additional constant component will be added,
that permits to improve the fit at higher angles, if required

Calculated MW and Rg

X1,X2

var

default values are estimated from form-factor intensity curves

Experimental data file name

filename

lys.dat

The name of the file containing the experimental SAXS profile from
multicomponent system

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-4

1

Formula for the scattering vector in the data file and its units.

Range for evaluation of scattering

X1,X2

var

default values are estimated from the full-range of experimental
data file

Use of non-negativity condition

Y or N

Y

if 'Yes' - the volume fractions values will be required to be positive

Output fit file

filename

*.fit

by default: experimental file name + .fit extenstion.

Plot the result

Y or N

Y

if 'Yes' - the fit curve and exp. curve will be plotted

Process another data set

Y or N

Y

if 'Yes' - the fitting procedure can be repeated for another data set.

The fields can be interpreted as follows, top-left to bottom-right:

Field

Description

Chisquare

The quality of the fit (discrepancy value)

MW

The averaged molecular mass of the system

Rg

The averaged radius of gyration of the system

Volume fractions+-errors

The volume fractions of the components in the mixture and
errors of volume fractions.The sequence of the components is the same
as specified in the form-factor file

The form factor files consists of the individual form factor of the components.
If they are derived by the program CRYSOL the
second column of the calculated form factors has to be used.

OLIGOMER creates a output file named oligomer.log as default or as specified using the /out option.
If the file already exists, the results are appended to the file.

*** O L I G O M E R ***
================================================================================
01-Sep-2009 17:26:17
Option 0: a set of form-factors and several sets of experimental data
Form-factor file test.dat
Real oligomer weights 20849 58193
Oligomer radii of gyration 22.57 34.37
Experimental data file Merge00.dat Range of Scattering angle: 0.02 0.27
Using non-negativity condition
Output file Merge00.fit
ChiSquare <MW> <Rg> Volume fractions +- errors
--------------------------------------------------------------------------------
Merge00.da 2.17 52869 33.82 0.143+-0.004 0.857+-0.002
================================================================================

If the brief -br option is used only the last line with the results is plotted.

If -svd option (singular value decomposition analysis) is used,
the following files - _Ncomp_.log, _S_.dat, _U_.dat and _V_.dat are created, they contain
information about the singular values (_s_.dat), singular vectors
(_u_.dat and _v_.dat) and statistical estimation of the number of components (_Ncomp_.log)
obtained from singular value decomposition of the experimental
data series in the particular angular range defined by the -smin and -smax
options.

If -compar option is used,
OLIGOMER will calculate the fits and the volume fractions for all possible
combinations of the form-factor components. The output file oligomer.log
will contain this information in the form of the table where
the missing (non-present) components will be denoted as 'N/A'
(below you can see an example of oligomer.log with four components).
One can use these results to determine the most significant components present in the mixture.

OLIGOMER creates also *.fit file that contains 4 columns:
S-axis (1st column), experimental intensity Iexp(2nd column),
errors of intensity Ierr(3rd column), fit from OLIGOMER Ifit (4th column).
NOTE: The above format is valid for ATSAS 2.7 or later versions.

In the earlier versions (up to ATSAS 2.6) the output fit file contained
5 columns: S-axis (1st column), experimental intensity Iexp(2nd column),
fit from OLIGOMER Ifit (3rd column), errors of intensity Ierr(4th column),
the difference curve (Iexp-Ifit) (5th column).

For processing all experimental data files with the names beginning with "m"
and with "dat" extension using the formfactor file ff2.dat. The fitting will be
applied from smin=0.5 for the experimental curves. The fits will be plotted and
output oligomer.log file will have the brief format.