AUTORG manual

autorg

Written by A.G. Kikhney.
Post all your questions about AUTORG to the ATSAS Forum.

Manual
Examples
- Command-line execution
- Running autorg on multiple files

Manual

The following sections shortly describe the method implemented in AUTORG, how to run AUTORG from the command-line on any of the supported platforms, the required input files and the produced output. This manual refers to version 3.0.

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

M. V. Petoukhov, P. V. Konarev, A. G. Kikhney and D. I. Svergun (2007) ATSAS 2.1 – towards automated and web-supported small-angle scattering data analysis J Appl Cryst. 40, s223-s228.

Introduction

AUTORG is a command-line program to estimate the radius of gyration (R_g) using the well known Guinier approximation

I(s) = I(0)exp(s²R_g²/-3).

The value of R_g is estimated from the best possible linear fit of ln[I(s)] versus s² (Guinier plot), which is valid for sufficiently small scattering vectors (in the range up to sR_g ≤ 1.0–1.3). The radius of gyration provides an estimate of the overall size of a particle (the root mean square distance to center-of-mass in a particle). Linearity of the Guinier plot is a sensitive indicator of the quality of the experimental data, and deviations from linearity usually point to strong interference effects, polydispersity of the sample or improper background subtraction. Based on that the program also estimates the quality of the input data. Please refer to the paper cited above for further details about the implemented algorithm.

Running autorg

Usage:

$> autorg [OPTIONS] <DATAFILE(S)>

AUTORG recognizes the following command-line OPTIONS. Mandatory arguments to long options are mandatory for short options too.

Short option	Long option	Description
	`--mininterval <NUMBER>`	Minimum acceptable Guinier interval length in points. Default is '3'.
	`--smaxrg <NUMBER>`	Maximum acceptable s_maxR_g value. Default is '1.3'.
	`--sminrg <NUMBER>`	Maximum acceptable s_minR_g value. Not limited by default.
	`--minrg <NUMBER>`	Minimum acceptable R_g value. Default is '1.0'.
	`--maxrg <NUMBER>`	Maximum acceptable R_g value. Not limited by default.
`-o`	`--output <FILE>`	Relative or absolute path to save result. If the output file name has ".csv" extension the output will be in comma separated values (CSV) format unless format is specified (see next option).
`-f`	`--format <FORMAT>`	Output format, one of: `csv`, `ssv`, `table`. '`csv`' will force to produce the output in Excel-compatible comma separated values format, a header will be written. '`ssv`' will force to produce the output in machine-readable space separated format without a header; the sequence of values is same as in CSV format apart from the file name – it will be written last, not first. '`table`' will force to produce the output as a human-readable table with round values. This is the default value if more than one input file is given.
`-v`	`--version`	Print version information and exit.
`-h`	`--help`	Print a summary of arguments and options and exit.

autorg input files

AUTORG accepts SAS experimental data files (*.dat) in ASCII format containing 3 columns: (1) momentum transfer, (2) experimental intensity and (3) experimental errors. If errors are not present, they are estimated as 4% of the intensity.

autorg output

AUTORG prints the result to standard output unless the output option was specified.

AUTORG output includes:

Field	Description
`File`	`DATAFILE` name.
`Rg`	Estimated radius of gyration. If the input data was in Å^-1 the unit of R_g is Å; if the input data was in nm^-1 the unit of R_g is nm.
`Rg StDev`	Standard deviation of the experimental data from the Guinier fit in the selected interval plus standard deviation of R_g values from all possible intervals from the R_g value from the selected interval. This way the accuracy of R_g is estimated by taking into account not only the error propagation in the selected fit but also by accounting for the deviation of R_g values calculated from other consistent intervals, accounting to some extent for systematic errors in the R_g determination.
`I(0)`	Extrapolated scattering intensity at zero angle I(0) (forward scattering).
`I(0) StDev`	Standard deviation of the I(0) value. Please note that this value is estimated only from the selected interval and therefore is underestimated.
`First point`	First point of the Guinier interval. Counting of data points starts from 1. Data points before the `first point` should not be used in further data processing.
`Last point`	Last point of the Guinier interval. In `table` format total number of points is given in brackets.
`Quality`	Estimated data quality. 1.0 – means ideal quality, 0.0 – unusable data. In `table` format it is given in percent (100% – ideal quality, 0% – unusable data). Please note that this estimation is based only on the Guinier interval (very low angles) and the number of negative intensities.
`Aggregated`	A number between -1.0 and 1.0 expressing the trend of the data before the chosen Guinier interval. Positive values indicate possible aggregation or background subtraction problems; negative values indicate repulsive interactions or background subtraction problems; values close to zero indicate good data quality.

Examples

Running autorg on a single file

Just pass the file name to the program. The result will look like this:

$> autorg bsa_006.dat
Rg   =   3.07 +/- 0.022 (1%)
I(0) =   88 +/- 0.15
Points   52 to 132 (81 total)
Quality: 86%

If the file name contains spaces please use quotes:

$ autorg "Copy of bsa_006.dat"

To get the result in a particular format use the format option. This way you get machine-readable space separated output:

$ autorg bsa_006.dat -f ssv
3.06972 0.0220475 88.0062 0.151798 52 132 0.862587 -0.0428083 bsa_006.dat

The values are in the following order: Rg, Rg stdev, I(0), I(0) stdev, first point, last point, quality, aggregated, file name. See the Output section for details.

Running autorg on multiple files

To run autorg on several files in one go pass several file names:

$ autorg bsa_006.dat rna_009.dat
  Rg  stdev       I(0)   Guinier points  Quality  File
  3.07   1%         88   52 - 132 ( 81)    86%    bsa_006.dat
  3.85  10%        139   37 -  94 ( 58)    87%    rna_009.dat

To run autorg on all *.dat files in folder use a mask:

$ autorg *.dat
  Rg  stdev       I(0)   Guinier points  Quality  File
  3.07   1%         88   52 - 132 ( 81)    86%    bsa_006.dat
  3.85  10%        139   37 -  94 ( 58)    87%    rna_009.dat
  6.69   5%        253    4 -  38 ( 35)    97%    rna_011.dat
  7.32   3%        373   11 -  39 ( 29)    90%    r2d2_013.dat
  8.02   2%        584    5 -  30 ( 26)    95%    r2d2_015.dat
  1.97   3%       13.1   40 - 221 (182)    96%    kgb-1_017.dat
  2.02   3%        8.9   40 - 215 (176)    86%    kgb-1_025.dat
  2.08  13%       4.75   53 - 208 (156)    61% A  kgb-1_028.dat
  4.15   3%       83.4   17 -  91 ( 75)    92%    c-3po_019.dat
  3.92   6%       67.9   36 -  97 ( 62)    83%    c-3po_021.dat
  3.68   2%       41.4   26 - 106 ( 81)    82%    c-3po_023.dat

To get the same information as a CSV file use:

$> autorg *.dat -o rg.csv

AUTORG manual

Table of Contents