​Sastool Full Documentation

For solution scattering experiments, the scattering of the specimen (sample) in solution and the scattering of the solvent (buffer) are measured. During data analysis, the intensity of buffer scattering is subtracted from that of the sample to obtain the signal responsible by the difference between buffer and sample. At low sample concentrations or larger scattering angles the scattering of the buffer is often nearly as intense as that of the sample. Consequently even small fluctuations of beam intensity can have a big effect on the result if corrections are not applied. In addition, the errors of subtracted scattering patterns have to be determined from the actual intensities in the original data. Since scattering of the sample may change during an experiment due to radiation damage or movement of the beam, it is essential to make several successive measurements on the same sample. Those frames have to be analyzed for differences before they are added up. Our program SasTool integrates the 2-dimensional scattering patterns obtained from Rayonix and Pilatus detectors and reduces them to a 1-dimensional scattering profile. It performs all above mentioned tasks, and more.

Where To Get It
The SasTool can be download from here.  There are two versions of SasTool, one for the Windows operation system, and the other for the Linux operation system.  The following instructions are for the Windows version.  It is similar to run the Linux version.

How to Run It
The user needs a parameters file to run SasTool.exe. The parameters file is a text file that contains parameters regarding which image files to analyse and how to analyse. You can get a sample parameters file here. For demonstration purposes, in the following examples, assume the parameters file is called params.txt.

To run SasTool.exe, type "SasTool.exe params.txt" at a DOS prompt if both SasTool.exe and params.txt are in the current directory. Otherwise, you will have to either navigate to the directory they are in, or specify the directory in the command line.

What Does Each Parameter Mean
From the sample parameters file, the user can see that comments are inserted between the parameters. The comments start with the letter '#'. The user is encouraged to read the sample parameters file, especially the comments in the file to understand how the values of the parameters will affect data processing. The user is also encouraged to include comments in their parameters file for later or other users' use.

Each parameter starts with a dash and has one letter, and the letter is case sensitive. It is followed by a space and then by its values. Some parameters have default values so they need not be included in the parameters file if their default values are to be used. Here are the parameters, their meanings, and their acceptable values:

-a no points 80 461.67 100 55.53
Area of the image to be integrated. This is required. The first item takes values of yes or no. "yes" means to integrate the larger area that is defined by the rest of the parameter value, and "no" means to integrate the smaller area of the image defined by the parameter value. The second item tells SasTool how to define the integration area, and is assigned either "points" or "angle". If "points" is assigned, values of two points (in pixels) follow, as shown above. The area that is defined by two lines going through the beam center and one of the two points is the integration area. If "angle" is assigned, starting angle and angle range (in degrees) will be required. Angle starts from the horizontal line that passes through the beam center, and increases ccw, and angle range should be always positive and less than 180. For example: -a no angle 200 120. This parameter will be ignored if the -m parameter is set to "yes" (using a mask file to define integration pixels).

-c 343.46 250.59
Beam center coordinates in pixels. This is required.

-d no 17 493 30 480
Use different detector offsets for four individual quadrants. This is not required, and default is no. If "yes", two sets of numbers are required (each set has two numbers). The first set gives the boundaries of areas to be used for offsets calculation. The areas are where the column number is smaller than the small number and larger than the large number. The second set of the numbers gives the boundaries in column numbers for the area that should be included in data integration. Please note, if this parameter is set, the -o parameter will be ignored.

-e rectangular
Shape of the exposed detector area. This is not required, and default is circular. The image files generated by MarCCD 165 are circular, while those generated by MX225-HE are rectangular.

-f ../sample03_0_01.tif 20 ../buffer03_0_01.tif 100
Files for SasTool to process. This is required, of course, if one is to use SasTool to do some meaningful things. This parameter should always come after all other parameters are set. The sample files come first, then buffer files, if any. File names can be relative or absolution but cannot contain spaces.
The numbers following the sample image and buffer image file names are, respectively, number of images to be processed starting from the sample image or the buffer image file that was given. If no number is given or if the value is zero, SasTool will process all the sample or buffer image files that come after the sample or buffer file name in the parameter.
Please note, if the -n parameter is defined as "yes", any one file name from a directory will be enough to process the whole directory.

-i yes i1 1000
Use i1 or i2 for data normalization. This is not required. The default is not using i1 or i2, that is, no normalization. If "yes", then specify whether to use i1 or i2. The last number is the grand base for i1 or i2 so that multiple series of data can have the same normalization factor for better comparison. For best results, the grand base i1 or i2 should be equal to or slightly greater than the actual i1 or i2. If the base is too big, it may result in standard errors that are too big, producing incorrect results. If "yes", but the grand base is not given, SasTool will use the i1 or i2 of the first frame as the grand base.

-l sample.log
The log file name. This needs to be the first item, and is required. Most other parameters can be randomly placed.

-m no ./mask.tif
Use mask file for data integration. This is not required. Default is no. The mask file is generally obtained from FIT2D, and each pixel should have a value of either 1 (include the pixel in the integration) or 0 (exclude the pixel in the integration). If "yes", a file name is required to follow. The file name can be relative or absolute but cannot contain spaces. If this parameter is set to "yes", the -a parameter will be ignored.

-n yes 1 78
Use the buffer and sample naming convention. This is not required, and default is no. If "yes", two numbers may follow. The first number is the starting number, and the second ending number. SasTool will process data from the start number to the end number. If no start or end num is given, it starts from 1 to 999. If only one number is given, it is assumed to be the start num. This will allow data processing of a whole directory with one -f parameter.

-o 8.5
Detector offset for all the MarCCD images. This is not required. The default is 10.0.

-q yes 0 0.0 102 0.107 205 0.215 308 0.322
Conversion from pixel to q. This is not required. The default is no conversion. The first item tells SasTool whether conversion will be performed. If "yes", pairs of pixel-q values are required for linear least squares regression to convert pixels into q. Besides "yes" and "no" for conversion from pixel to q, there is a third choice: "wide" for wide angle conversion from pixel to q. If "wide", two values are required for converting from pixel to q (in nm^-1): first the beam energy (in eV) and then camera length (in mm). The "wide" option is currently only available in the command line version.

-r yes 2.0
Rejection of individual frames from the summation of the whole series. This is not required. The default is no rejection. The first item tells SasTool whether or not to reject frames. If "yes", a factor should follow. SasTool.exe will compare the average standard deviation of the buffer series and that of individual sample frames. If the ratio of the standard deviations of a sample frame and the buffer is larger than the factor, the sample frame will be rejected, i.e., not be included in the sum of the sample series. Individual buffer frame will be rejected if its standard deviation is larger than 1.3 of that of the first buffer frame.

-s no
Subtract buffer intensity from individual sample frame. This is not required. The default is no. If "yes", the average buffer intensity will be subtracted from the .dat file of each individual sample frame. If "yes", SasTool will display error and exit if there is no buffer files given in the -f parameter.

-t no
Re-use existing buffer .tot files for sample data processing. This is not required. The default is no. If "yes", the previously created buffer .tot files, if available, will be used for sample data analysis. This is intended to save processing time for multiple sample series using the same buffer series. But if any of the other parameters changed, this parameter should be set to "no" so a new .tot file will be generated for the buffer.

-u no
Process image files acquired from push-through experiments.  This is not required, and the default is no.  If "yes", sastool will process the image files assuming they were acquired through the push-through experiments and have the push-through naming convention.

-z yes 3.0
Perform dezinger operation to the images. This is not required, and default is no. If "yes", give the factor. If the difference between the intensity at the pixel and the average of all the pixels at the same distance is larger than the product of average and the factor, the pixel is considered to be a zinger and is excluded from the data integration. If no factor is given for "yes", default factor is 3.0. This could be useful for images that were acquired under "Normal" mode, and generally not useful for those acquired under "Dezingered" mode.

-E 10000
Specify the photon energy of the beam when the images were acquired. The number is the photon energy in eV. This parameter is not required. However, with this parameter, the -q yes parameter is essentially the same as -q wide.

-L yes
List number of pixels at different distances from the beam center. This parameter is not required, and the default is no. If "yes", SaxsTool will generate .dat files that contain three columns: first is the distance from the beam ceter with the unit of a pixel length, then the number of pixels at that distance, and finally the average value of all the pixels at that distance.

How to Process Multiple Series of Samples Using One Parameters File
There are two ways to do this. One is to use standard naming convention, i.e. use the -n parameter. The other way is to use multiple -f parameters. The second way also allows change of parameter values between series.

How to Interpret the Printouts in the Consol
SasTool prints out some messages on the screen while it runs. First, it prints out the parameters that are being set, files being processed, then the errors for each frame, and whether the frame was rejected from the inclusion in the summation of the series.

What is in the Log File
The log file is basically a recording of the printouts of the screen.

What is in .dat, .tot, and .sub Files
There are three columns in those files. The first column is either the distance in pixels from the beam center or the q value, depending on the assignment to the -q parameter. The second column is the intensity, and the third column is the error. The error is the smaller of the standard deviation and the square root of the intensity.