Options and Arguments of the SAXS Programs *

Version: 2005-10-12 *

Introduction *

Examples *

Some Useful Commands *

Reference Systems *

Raster Orientation *

List of Options *

General Options Available in All SAXS Programs *

General Options for Output and Input Files *

Error Propagation Options *

SAXS Program Specific Options *

Other Routines *

Programs *

Macros *

Error Propagation *

Mathematical Concept *

Explicit Error Propagation Formulas *

Index *

Parameters can be passed in three ways to the saxs programs:

a) by prompts

b) by arguments

c) by options

The multiplication of the first three images of the input file "x.edf" with the factor 5.5 is used to demonstrate these possibilities. The output is written to "y.edf"

The program prompts for some important parameters, but not for all.

• > saxs_mac

The same parameters can be passed as arguments in the same order as the program would prompt for them. "=" stands for an empty argument. The option -p is used to switch off the prompt mode. With +p the program will prompt and will show the arguments as defaults in parenthesis []. This can be used for checks.

• saxs_mac -p x.edf y.edf = 3 = -1 = = 5.5 = = =

Usually, the default of all arguments can be set with options. While arguments must be passed in a specific order options can be passed in any order before the first argument. Options are preceeded by "-" or "+" and can be repeated. The last occurence sets the value.

• saxs_mac -p -i1nam x.edf -onam y.edf -i1lst 3 -odum -1 -i1fac 5.5

• Subtraction of two images:

• saxs_sub image1.edf image2.edf output.edf

• Divide image1.edf by image2.edf

• saxs_div.edf image2.edf output.edf

• Add image1.edf and image2.edf

• saxs_add image1.edf image2.edf output.edf

• Multiply image1.edf with image2.edf

• saxs_mul image1.edf image2.edf output.edf

More complex operations between images are possible, e.g. subtraction of series of background images from series of images. In these cases special options must be used.

In the following examples all header values of the input images are passed to the output images (+pass). The user will not be prompted (-p) and existing output files will be overwritten (-omod n). The command will be automatically applied to a series of input files.

In the first example the intensity of the input image is normalized to the header value Intensity1 (-scal) and then divided by by a flat-field image (+flat -i3nam flat.msk). The intensity of each pixel is divided by its spherical angle (calculated from the header values Center_1, Center_2, Psize_1, Psize_2 and SampleDistance). The output image is binned by 4 in each direction (-obin 4 4) and finally multiplied by 1.8/2.75 (-ofac 1.8/2.75).

This operation is done for all input files stp3_0002.edf to stp3_0039.edf (-i1nam stp3_%%%.edf,2,39). The results are written to the files stp3_0002.nrm to stp3_0039.nrm (-onam stp3_%%%.nrm).

• saxs_normn -p -ofac 1.8/2.75 -omod n +pass +flat -i3nam flat.msk -scal \
  -i1nam .. stp3_%%%.edf,2,39 -onam stp3_%%%.nrm -obin 4 4

If the values of center, pixel size and sample distance are not correct in the input images they can be set with the options -i1cen <Center_1[pc]> <Center_2[pc]> -i1pix <Psize_1[m]> <Psize_2[m]> -i1wvl <WaveLength[m]> (pc = pixel coordinate). Attention, the length unit is always meter.

The following command performs an azimuthal regrouping of the input image. Axis 1 of the output image corresponds to the radius, axis 2 to the azimuthal angle. The default creates 360 sections of 1 degree that are written to a row of the output image. The center and pixel sizes must be correctly defined in the header, otherwise the options shown above (-i1cen and -i1pix) must be used to update them.

This operation is done for all input files stp3_0002.nrm to stp3_0039.nrm (-i1nam stp3_%%%.nrm,2,39). The results are written to the files stp3_0002.ang to stp3_0039.ang (-onam stp3_%%%.ang). In this case the input and output files are passed as arguments in the same way the program would prompt for them.

• saxs_angle -omod n -p +pass -rsys normal \
  stp3_%%%.nrm,2,39 stp3_%%%.ang

The following command averages over all rows of the input image, in this case the azimuthally regrouped scattering pattern where each line corresponds to a sector. Like in the previous cases the operation is applied to all images between stp3_0002.ang stp3_0039.ang and the file names are passed as arguments. Each output image contains only a single row, the azimuthal average.

• saxs_row +pass -omod n -p stp3_%%%.ang,2,39 stp3_%%%.row

The last command converts the azimuthal average to a text file with two columns (+swap) that are separated by a tabulator (ASCII TAB character). The first column contains the scattering vector q in 1/nm, the second column the intensities. The default for scattering vectors is s=2sin(Theta)/WaveLength (in 1/nm). The option -scf "2*pi" multiplies the scattering vector by 2pi: 2*pi*s = q (in 1/nm). The scattering vectors are calculated using the scattering angle and trigonometric functions (+waxs) and not an approximation for small angles. The table is preceded by a summary of header values, e.g. the data history. Column labels (-headl "lab1 lab2 ...") are written above the columns. The first column label is "#q*nm", the second column label is "I([WaveLength]m)", where [WaveLength] will be replaced by the header value of WaveLength. The hash (#) is only added to allow a plot with gnuplot.

• saxs_ascii -scf "2*pi" -p +waxs +swap -hedl "#q*nm I([WaveLength]m)"\
  stp3_%%%.row,2,39

The output file looks like

#{

#Image = 1

#Size = 756

...

#History-4 = saxs_row +pass -omod n -p stp3_%%%.ang,2,39 stp3_%%%.row

#

#

#

#}

#q*nm I(1.75114e-10m)

0.0136098 -10

0.0408293 -10

0.0680488 -10

0.0952682 -10

0.122488 -10

0.149707 6.08817

0.176926 7.82687

...

Currently, seven different reference systems are defined: array, image, center, region, real, normal, saxs. They are used to define the geometrical relation between two images. A reference system is chosen with the option -rsys <refsys> (see chapter Option Values);

1. Raster Orientations for N=2 (two-dimensional image). Raster orientation number 1 is used as reference. It is defined as the orientation where the geometrical origin of the image is at the lower left corner, where index 1 corresponds to the horizontal coordinate (x_1) and where index 2 corresponds to the vertical coordinate (x_2). All other orientations are derived from orientation 1 by swapping and exchanging the coordinates. In raster orientation 5 index 1 corresponds to the vertical and index 2 to the horizontal coordinate.

The orientation of the image describes the relation between data indices and directions in real space. In orientation 1 index 1 corresponds to the horizontal axis and index 2 to the vertical axis. Internally, all images are converted to orientation 1. The conversion includes a reorientation of the image and a swapping of some header values, e.g. for dimension, pixel size and offset. The orientation of the input and output image can be chosen with the options -i1ori O and oori O, where O is the orientation number shown in the upper right corner of Fig. 1.

Each option in the following list is followed by a parenthesis that shows the number of parameters and the parameter type:

The saxs programs are called in the following way:

Options are preceeded by '-' or '+'. Options are read from left to right

and are processed before the arguments are read. Options can be repeated.

The last option sets the value.

Each option can be followed by parameters. The number of parameters

and the type of the parameter are shown in brackets. The following parameter

types are used:

• +: boolean value , e.g. +option and -option (no parameter)
• d: integer value, e.g. -ofst 3
• f: float value, e.g. -ofac 1/0.0003
• M: file opening mode ( n+fp, n+ip, n, o+fp, o+ip, o, a+fp, a+ip, a)

• n, n+fp : new (create new file and empty any old file, allow to overwrite existing images if header size and image size fit into the existing block structure)
• n+ip : new + image protection (create new file, do not allow to overwrite existing images)
• o, o+fp : old (use old file, error if it does not exist, allow to overwrite existing images if header size and image size fit into the existing block structure)
• o+ip : old + image protection (use old file, do not allow to overwrite existing images)
• a, a+fp : any (if the file does not exists create a new file, otherwise open it as an old file, allow to overwrite existing images if header size and image size fit into the existing block structure)
• a+ip : any + image protection (like any but do not allow to overwrite existing images)

• P: projection type value

• R: reference system value

• array: ARRAY coordinate p = pixel coordinate
• image: IMAGE coordinate i = ARRAY coordinate + offset
• center CENTER coordinate i = IMAGE coordinate - center
• region REGION coordinate i = IMAGE coordinate * bin size
• real: REAL coordinate r = IMAGE coordinate * pixel size
• normal NORMAL coordinate i = CENTER coordinate * pixel size
• saxs: SAXS coordinate s = (NORMAL coordinate) / (sample distance) * WaveLength0/wavelength (WaveLength0=1e-9 m)

• s: string value, e.g. -otit "flatfield image"

Integer and float values can be expressed by C-type expressions. Values are converted to SI-units, e.g. keV is converted to Joule. Additional functions and constants are defined. To get a full list of all defined constants and units type "calc debug=2 a" on the command line. Units can be appended with an underscore to a number, e.g. 1_nm for 1e-9_m. The multiplication with a unit is only the multiplication with a conversion constant to a base unit, e.g. nm=1e-9, m=1.

Physical and mathematical constants are taken from:

[86] Lawrence Berkeley Laboratory
University of California
Berkeley, California 94720
X-Ray data booklet, second printing, with corrections, April 1986

Constants that are not contained in this edition are taken from
[91] Kuchling, Taschenbuch der Physik, Verlag Harri Deutsch 1991
There are currently some inconsistencies in some definitions, e.g. amu, ga and p.

Float Functions

Long integer functions

An option can be followed one or more parameters. All options are described in the following way:

<option name> [<number_of_parameters>, <parameter type>]

• test [ 0, +]

• h [ 0, +]

• p [ 0, +]

• add [ 1, d]

• shft [ 2, f]

• rsys [ 1, R]

• usys [ 1, R]

• gblk [ 1, +]

• bibo [ 1, d]

• mlw [ 1, d]

• mhs [ 1, d]

The following options can be used for output and for input files. An option for the output file starts with o, an option for the <n>-th input file starts with i<n>, e.g. -odum -1 -i1dum -1 -i2dum -1 etc. The number of input and output files can be viewed with the extended help option +h (block should be read as file):

The file contains 1 output file (-onam <output file name>) and 2 input files (-i1nam <name of input file 1>, -i2nam <name of input file 2>).

Some conversion programs do not have standard input and output files, e.g. gas2saxs. In this case the number of image files ("blocks") is 0.

Image numbers offer the possibility to store a sequence of (small) images in a single file. All images are numbered and can be stored in different memories. Image numbers and memory numbers are integer values. Positive memory values stand for image data, negative memory values for error data. Memory zero must not be used. The default input memory number is 1, the default output memory number is the input memory number.

How image numbers can be chosen is described in the section Loop Control. Memory numbers can be chosen with the options -i<n>mem and -omem.

• omem (i<n>mem) [ 1, d]

• omod (i<n>mod) [ 1, M]

• onam (i<n>nam) [ 1, s]

The file "/dev/null" is used as dummy. Used as input, a saxs_xxx programs runs as if it would read from a file. All parameters can be defined explicitly by options, e.g. saxs_mac -i1dim 512 512 -i1con 5 /dev/null output.edf will create an image with 512 512 pixels and write it to output.edf. Each pixel has the value 5. Output to "/dev/null" suppresses the output to a real file.

All saxs_xxx programs read images sequentially from several input sequences (i1, i2, ...) and write the resulting images sequentially to a single output sequence (o). Per default the output images are described in the same way as the images of the first input sequence, e.g. title, pixel size etc. are copied from the input images of the first sequence. Only a single output image sequence is created: (Output[i01], Output[i02], ...). The output image is a function of the input images: Output[i0] = Function(image1[i1], image2[i2], image3[i3], ..., imageN[iN]). Per default, the start number (ofst), the increment (oinc) and the last number (olst) of the output image sequence are the same as start number (i1fst), increment (i1inc) and last number (i1lst) of the first input sequence. Thus, normally the output image number is equal to the number of the image in the FIRST input file.

If the increment of the output image is 0, maxloop0 is set to infinity and it is only written once at the end of the other loops.

If the increment of an input sequence J is zero the loop is stopped after the first loop (maxloopJ is set to 1).

The loop is stopped when the first incrementation loop has finished. Also negative increments are possible.

Missing images are skipped. All start images must exist.

• ofst (i<n>fst) [ 1, d]

• olst (i<n>lst) [ 1, d]

• oinc (i<n>inc) [ 1, d]

All saxs programs >= V4.0 allow incrementation of file numbers. The command

• saxs_mac input%%%.edf,1,10,1 output%%%.edf

processes the files input001.edf, input002.edf, input003.edf, ... input010.edf and writes the results to the files output001.edf, output002.edf, output003.edf, ... output010.edf.

Numbers in a file name are marked with place holders (percent signs %%%%%). The range of file numbers must be indicated by parameters after the file name, e.g.

input%%%.edf,<first>,<last>,<increment>

The parameters are separated by commas. Numerical expressions are possible, e.g.

input%%%.edf,1,1+20,2

Omitted parameters are replaced by default values. If possible, they are copied from a preceding input parameter, e.g.

saxs_mac input%%%.edf,1,20,1 output%%%.edf,,,2

The output file numbers will start with 1 (copied), will be incremented by 2 and will stop after 20 (copied):

output001.edf, ouput003.edf, ... output019.edf

Multiple files with a single data section (images) can be written into a single file with multiple data sections by writing the output file name without placeholders for numbers, e.g.

• saxs_mac input%%%.edf,1,20 output.edf

will write input001.edf .. input020.edf to output.edf (image 1 to image 20). If the input data files contain itself several images, only the first image in an input file or the one specified with -i1fst is written into the output file.

In the same way a single file can be split into multiple files by giving placeholders in the output filename, e.g.

• saxs_mac input.edf output%%%.edf

will write all images of input.edf to numbered output files that contain only single images (default: image number 1).

Successive output images can be added before they are written. The option -add <n> will add n successive images (n>=1), e.g.

• saxs_mac -add 3 input%%%.edf,1,20 output%%%.edf

will add input001.edf to input003.edf and write the result to output001.edf,

will add input004.edf to input006.edf and write the result to output004.edf,

...

will add input016.edf .. input018.edf and write the result to output016.edf

Attention, the sum of input019.edf and input020.edf will be written to output020.edf. It will be the sum of only two images. Not all saxs-programs do really add the images, some may only output the last image. A test is necessary before using this option.

After reading and before writing the pixel values of all images can be modified. The transformations are done in the following order after reading the input data and before writing to the output file. If the option is omitted nothing is done.

Attention, each step can create new dummy pixels, e.g. -odum 10 -ofac 0 -ocon 10 would replace all output pixels with the value 10 which is the dummy value.

• omin (i<n>min) [ 1, f]

• omax (i<n>max) [ 1, f]

• ocon (i<n>con) [ 1, f]

• ofac (i<n>fac) [ 1, f]

• obin (i<n>bin) [ 2, d]

• oori (i<n>ori) [ 1, d]

• ogna (i<n>gna) [ 2, d]

• oave (i<n>ave) [ 0, +]

• +iNave: averaging of rebinned and resized pixels (default)
• -iNave: addition of rebinned and resized pixels

• odim (i<n>dim) [ 2, d]

• odum (i<n>dum) [ 1, f]

• oddum (i<n>ddum) [ 1, f]

• otit (i<n>tit) [ 1, s]

• otim (i<n>tim)

The reference system for calculation is globally chosen with rsys. The reference systems are described in a separate document.

• ooff (i<n>off) [ 2, F]

• ocen (i<n>cen) [ 2, F]

• opix (i<n>pix) [ 2, F]

• odis (i<n>dis) [ 1, F]

• owvl (i<n>wvl) [ 1, F]

• orot(i<n>rot) [ 3, F]

• opro (i<n>pro) [ 3, P]

Replacement of Parameter Values with Header Values (2003-05-25)

The parameters of some options can contain keys between square brackets. The keys and the square brackets are replaced by the header values of the keys. If a key cannot be replaced the parameter string is not changed and will probably cause an error when the parameter is a number. Only input header values can be used. The keys are searched in the corresponding input file. If a program has several input files the input file number (block number) can be explicitly written after the key separated by a comma. For example, to divide all values of input file 2 by the header value of Psize_1 in input file 2 one can write: -i2fac "1/[PSize_1]". Header values after output file options, e.g. -ofac "1/[PSize_1]", are replaced by header values of input file 1. A comma separated number after a key specifies the input file number in which the key should be searched, e.g. -i2fac "1/[PSize_1,1]" will search PSize_1 in input file 1.

Parameters that allow replacement by header values are marked in the help list (+h) by D and F. Usually all string parameters (s) allow replacement of header values. Exceptions are filenames. The following list shows parameters in which header values are replaced:

-shft, -i1/-omin, -i1/-omax, -i1/-ocon, -i1/-ofac, -i1/-obin,

-i1/-ogna, -i1/-otit, -i1/-otime, -i1/-odim, -i1/-odum, -i1/-oddum,

-i1/-ooff, -i1/-obis, -i1/-opix, --i1/-ocen, i1/-odis, -i1/-owvl, -i1/-orot

• var [ 0, +]

• oval expression(_oval), i<N>val expression(_i<N>val)
• oerr expression(_oval,_oerr), i<N>err expression(_i<N>val,_i<N>err)

If one of these options is used error propagation is switched on. The option +val is not needed.

The variances are propagated using the laws of Error Propagation. Cross correlations between pixels are ignored.

The variance array contains the variance of each pixel of the image array. The variance array has the same dimensions and orientation as the image array. The pixel [i,j] of the variance array contains the variance of pixel [i,j] of the image array. The variance header contains only keywords that describe an array. (Dim_1, Dim_2, DataType, ByteOrder, DataRasterConfiguration). The variance array does not use any additional keyword. If there are any, theyare ignored. The variance values are calculated after the calculation of the image values. Negative values in the variance array describe undefined variance values. The default value of a variance array is 0 (=exact).

Input and output variance arrays are only created if the first input image

If the option +var is set (default: not set) default variance arrays with variance zero are created for all input arrays. If the option -var is given no variance arrays are read/created and no error propagation calculation is done.

The variance array are stored in a second edf data block with the data block ID

EDF_DataBlockID = <image>.Image.Error[.<mem>].

The suffix .<mem> is omitted for memory=1.

For convenience, the data block of the variance array is written after the data block of the image and the header of the variance array of memory 1 contains additionally the keyword Image.Error = <image>, where <image> is the image number of the EDF_DataBlockID. The image header contains in this case the keyword Image = <image>.

To define initial variances for the input array sphere.edf the following option must be given:

• saxs_mac -i1err _i1val sphere.edf sphere.err

It assumes that each pixel of sphere.edf contains the number of detected photons and that the errors follow Poisson statistics (var=s²=N). The option -i1err _i1val sets the variance to the pixel value (_i1val) of sphere.edf, _i1val is a variable. The following variables are defined:

_i1val: input pixel value

_i1err: input variance value

_oval: output pixel value

_oerr: output variance value

All variables start with an underscore.

Additional errors, e.g. var=1.5, can be added with.

• saxs_mac -i1err _i1val+1.5 sphere.edf sphere.err

To avoid negative variance values, the following command can be given:

• saxs_mac -i1err "max(0,_i1val)+1.5" sphere.edf sphere.err

Number of image blocks : 2

Maximum number <n> of input blocks: 1

V4.02 2002-04-06

binary2saxs [options] <fnam> <onam> <i1dim1> <i1dim2> <fskp> <ftyp> <fend> <fdvo> <fras> <odum>

• fskp [ 1, d]

• fnam [ 1, s]

• ftyp [ 1, s]

• "FloatValue" (old "float")
• "DoubleValue"
• "SignedByte"
• "SignedShort" (old "short integer")
• "SignedInteger" (old "integer")
• "SignedLong" (old "long integer")
• "UnsignedShort" (old "unsigned short integer")
• "UnsignedInteger" (old "unsigned integer")
• "UnsignedLong" ("unsigned long integer")
• "UnsignedByte" (old "byte")

• fend [ 0, +]

• fhbf [ 0, +]

• fras [ 1, D]

• fdvo [ 1, D]

Number of image blocks : 0

ccd2saxs [options] <i/p file> <dummy> <first> <last> <inc> <o/p file> <o/p first> <i/p hm>

• ext [ 1, s]

Number of image blocks : 0

gas2saxs [options] <i/p file> <dummy> <first> <last> <inc> <o/p file> <o/p first> <i/p hm>

• ext [ 1, s]

Number of image blocks : 0

gel2saxs [options] <i/p file> <dummy> <o/p file>

Addition of two image sequences

saxs_add [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

Average columns between col1 and col2 in image sequence 2 and add the results to each column of image sequence 1

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_addcol [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• col1 [ 1, f]

• col2 [ 1, f]

Average rows between row1 and row2 in image sequence 2 and add the result to each row of image sequence 1

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_addrow [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• row1 [ 1, f]

• row2 [ 1, f]

Affine transformation of an image sequence

Tranformation matrix T

with coordinates W (input image), W' (output image)

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_aff [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2>
<t00> <t01> <t10> <t11> <t20> <t21>

• t00 [ 1, f]

• t10 [ 1, f]

• t20 [ 1, f]

• t01 [ 1, f]

• t11 [ 1, f]

• t21 [ 1, f]

Transformation of an edf-file into ASCII format

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_ascii [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2>
<header> <swap> <head_1> <head_2>
Purpose: Transformation into ASCII format
Options: +-head +-swap +-hd1 +-hd2 -hdmk <marker> -ext <extension> +-noi +-waxs

• hist [ 1, +]

• noi [ 1, +]

• waxs [ 1, +]

• scf [ 1, f]

• pref [ 1, s]

• ext [ 1, s]

• head [ 0, +]

• swap [ 0, +]

• hd1 [ 0, +]

• hd2 [ 0, +]

• abs [ 0, +]

• spc [ 1, s]

Averaging of two image sequences

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_ave [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

Transformation of an image from cartesian coordinates to polar coordinates with pixel interpolation and azimuthal averaging.

1. Description of the azimuthal averaging procedure. The division of a section in several subsections is shown.

The integration is done on rings with thickness dr around the center. The default thickness is the minimum of the x_1 and x_2 pixel sizes in the chosen reference system. In the default reference system (Image) the default thickness is 1. In the following explanation it is assumed that the pixels are quadratic. The default values ensure that each pixel of the source image contributes to the result. Therefore, the radial default value (dr) should not be changed. The azimuthal default (da) can be changed.

Each ring is divided in subsections so that the azimuthal length of each subsection is less than the thickness dr. The integration uses the trapezoidal rule. Integration points are calculated for the center of each subsection by interpolation of the four neighbouring pixels. The weight of each pixel is proportional to the common cross section of a pixel with a squared pixel with size 1x1 around the interpolated point. (dashed pixel in Fig. 2).

x_1 of the output file corresponds to the radius

x_2 of the output file corresponds to the angle

The angle coordinate (x_2) uses always the real reference system (Offset, PixSiz). Center, WaveLength and SampleDistance are not used for coordinate 2 of the output image.

4.10 2004-12-03

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_angle [options]

<i1nam> <onam> <i1fst> <i1lst> <i1inc> <odum>

<i1cen1> <i1cen2> <r0> <dr> <dim1> <a0> <da> <dim2>

• r0 [ 1, f]

• dr [ 1, f]

• a0 [ 1, f]

• da [ 1, f]

• s2 [ 0, +]

The options asym and csym are used together with the option s2. They allow proper azimuthal averaging of intensities when the scattering pattern shows fiber symmetry and the fiber axis is lying in the detector plane. The angle of the fiber axis with the w_1 axis is defined by the option asym.

• asym [ 1, f]

• csym [ 0, +]

Transformation of an edf image sequence into bsl format (daresbury otoko)

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_bsl [options]
<i1nam> <output header name> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2>

• hnam [ 1, s]

• bsl [ 0, +]

Averaging of a point mirrored sequence with itself.

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_cave [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <center1> <center2>

• cen1 [ 1, f]

• cen2 [ 1, f]

Sets all values above maxclip to maxvalue and all values that are smaller than minclip to minvalue. Works like -min and -max on the read data (after transformation and binning), but the excluded pixels are set to minimum and maximum (not to dummy).

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_clip [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <micl> <macl>

• macl [ 1, f]

• micl [ 1, f]

Projection of a vertical band in a sequence of images to a single column. The output column is swapped to a line. The swapped column is written to a line of the output image.

see also saxs_row

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_col [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <col1> <col2>

V4.50 (2002-06-02)

• col1 [ 1, f]

• col2 [ 1, f]

• row1 [ 1, f]

• row2 [ 1, f]

• +/-vint [ 0, +]

aliased to --> saxs_mac

Subtraction of a point mirrored sequence from itself.

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_csub [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <center1> <center2>

• cen1 [ 1, f]

• cen2 [ 1, f]

Division of two image sequences. To calculate the inverse of each image in an image sequence with the name x.edf type: saxs_div -i1fac 0 -i1con 1 -i1nam x.edf -i2nam x.edf

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_div [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

Average columns between col1 and col2 in image sequence 2 and divide each column of image sequence 1 by the results

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_divcol [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• col1 [ 1, f]

• col2 [ 1, f]

Average rows between row1 and row2 in image sequence 2 and divide each row of image sequence 1 by the result

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_divrow [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• row1 [ 1, f]

• row2 [ 1, f]

Sets pixels in an ellipse around a dummy also to dummy. Similar to the general option +ogna <gnc> <gnr>.

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_gnaw [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <gnc> <gnr>

• gnc [ 1, d]

• gnr [ 1, d]

Logarithm (base 10) of the image. To calculate the logarithm to another base multiply the output with -ofac "log(<base>)/log(10)"

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_log [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2>

Mulitplication with a factor and addition of a constant to each image in a sequence. This routine performs a simple read and write of an image sequence. All general options are available and can be used to modify the values, e.g. to multiply with a factor and to add a constant: +ofac <fac> +ocon <con>. To convert an edf-file or bsl file to a standard edf-file with 512 byte block size and float binaries type saxs_mac old.edf new.edf or saxs_mac A01000.BSL new.edf.

Number of image blocks : 2

Maximum number <n> of input blocks: 1

saxs_mac [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <ofac> <ocon> <shft1> <shft2>

Multiplication of two image sequences.

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_mul [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

Average columns between col1 and col2 in image sequence 2 and multiply each column of image sequence 1 with the results

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_mulcol [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• col1 [ 1, f]

• col2 [ 1, f]

Average rows between row1 and row2 in image sequence 2 and multiply each row of image sequence 1 with the result

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_mulrow [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• row1 [ 1, f]

• row2 [ 1, f]

Normalization of an image sequence to absolute intensities (+ccd for ccd, -ccd for delay line detector, default: -ccd)

Number of image blocks : 4

Maximum number <n> of input blocks: 3

2004-10-31

saxs_normn [options]
<i/p file> <scaler file> [<flatfield file>] <o/p file>
<first image> <last image> <inc>
<first scaler header> <inc scaler header>
[<flatfield image>]
<o/p dummy> <o/p dim1> <o/p dim2>
<transmission>
<scaler I0 mon.> <scaler exposure time> <scaler anode counts>
<2nd scaler I0 mon.> <2nd scaler exposure time> <2nd scaler anode counts>

The program saxs_normn normalizes a two dimensional scattering pattern measured with a plane two-dimensional detector to absolute intensities in units of scattered photons per steradian and per incident photon. In other words, it is the scattering cross section ds/dW per sample cross section A. To correct for absorption the normalized pattern is divided by the sample transmission T. The last step is optional. The transmission corrected scattering cross section per sample cross section can be calculated in the following way:

1. 

I₀ is the number of incident photons during the exposure, i_s is the number of detected photons in a single pixel with the area p₁•p₂, r_d is the distance between sample and pixel and L the length of the detector normal to the sample (keyword SampleDistance). The division by the spherial angle dW is done by the last two factors in formula (1). The factor r_d/L corrects the projection of the pixel area to the scattering sphere under large angles. To calculate the scattering cross section per scattering volume dS/dW of a non-absorbing sample the result must be divided by the effective sample thickness d_eff.

2. 

The division by the transmission T is effectively an absorption correction for a flat sample with thickness d_eff. In small angle X-ray scattering the transmission and the effective sample thickness are practically independent of the scattering angle. This is usually not the case in wide angle X-ray scattering. In this case the X-ray attenuation length and the sample shape influence the scattering pattern and formula (2) is no longer valid. In this case saxs_normn can still be used to calculate the number of scattered photons per steradian per incident photon, a property that can be measured without any knowledge about the scattering sample.

To take into account a non-homogeneous response over the detector area input pattern can be divided by a flat-field pattern F. A flat-field pattern is the detector response to a homogeneous illumination.

If extinction is small the transmission T can be approximated by I1/I0, where I0 is the number of photons in the incident primary beam during the exposure and I1 is number of photons in the transmitted primary beam.

1. Scattering geometry used in saxs_normn. I₀ (Intensity0) is the number of photons in the incident beam with cross section A, I₁ (Intensity1) is the number of photons in the transmitted beam. The number of scattered photons is i_s. L (SampleDistance) is the smallest distance between sample and detector. C (Center_1, Center_2) is the corresponding point on the detector. The pixel size is p₁*p₂ (PSize_1, PSize_2). The distance between sample and detecting pixel is r_d. A*d is the scattering volume, where d is the thickness of the sample. The incident beam does not need to be perpendicular to the detector surface.

The program saxs_normn divides each pixel by the intensity I₀ of the incident beam (option -monv <Intensity0>) and by the sample transmission. As default the transmission is equal to Intensity1/Intensity0, where Intensity1 is the number of transmitted photons (option -trmv <Intensity1>). Intensity0 and Intensity1 are read from the file header. The default corresponds effectively to a normalizion to Intensity1 because the Intensity0 cancels out. Alternatively, a fixed transmission value can be entered (option -trm <tranmission>). In this case, I₁ is equal to T*I₀. In this case, the header value Intensity1 is ignored. The pixel intensity i_s is divided by the spherical angle DW under which it observes the scattering.

To take into account the different sensitivities of the pixels the scattering pattern can be divided by a flat-field image F. In this case the option +flat must be set (default -flat) and the name of the flat-field image must be given after the option -i3nam <flat-field>.

The calculation of the transmission corrected scattering cross section per sample cross section is done in the following way:

1. 
2. 

i_s is the number of scattered photons at pixel coordinate (i_1, i_2), I(i_1, i_2) is the detector pixel intensity, F(i_1, i_2) is the flat-field value (+flat -i3nam <flat-field file> and f a normalization factor, that can be entered by the option -i1fac <f>)

3. 

T is the sample transmission, it can be modified with the option -trm <T>, Intensity0 can be modified with the option -monv <Intensity0> and Intensity1 can be modified with the option -trmv <Intensity1>

4. 

DW is the spherical angle under which the detector pixel sees the scattering volume, PSize_1 and PSize_2 are the pixel sizes (option -i1pix <PSize_1> < PSize_2>), SampleDistance is the distance between detector and sample (option -i1dis <SampleDistance>). r_d is the distance between the detector pixel and the scattering volume.

5. 

(i_1,i_2) is the pixel coordinate, Offset_1 and Offset_2 are the coordinate offsets and (Center_1, Center_2) is the pixel coordinate of the point of normal incidence on the detector.

Call

The basic call to normalize a 2d CCD scattering pattern is:

a) without flat field

• saxs_normn -p +ccd -i1nam <in> -onam <out>

b) with flat field

• saxs_normn -p +ccd +flat -i3nam <flat-field> -i1nam <in> -onam <out>

The input file header must contain the following keywords. It they are missing the values must be given with the option shown in the second column:

The parameter ExposureTime value is only required to display the detector summary. It is not used to calculate the output pattern. If not known, it can be set to 1. The displayed detector summary may be wrong.

If the input file does not contain the values Intensity0, Intensity1 and ExposureTime, they can be read from a second input file that contains the header values, e.g. the raw data file.

• saxs_normn -p +ccd -i1nam <in> -i2nam <header-file>-onam <out>

If the normalization is applied to data from a delay line detector the intensities can also be corrected for the dead time of the time to digital converter (TDC). In this case, the sum of the anode counts must be measured and given in the header after the keyword Anode (-anov <Anode>). The pixel intensities I(i_1,i_2) of the detector are scaled by the factor Anode/Sum(I(i_1,i_2)). In case of no losses the ratio should be 1. This correction does only work when the whole detector pattern is used, when the rejection is independent of the position on the detector and as long as the anode count rate is proportional to the global scattering intensity. Only global count rate losses are corrected.

The basic program call is:

• saxs_normn -p -ccd -i1nam <in> -onam <out>

It is possible to read the intensity information (Intensity0, Intensity1, Anode, ExposureTime) from a multi channel scaler (MCS). Normally, the program saxs_normn tries to find the multi channel scaler keywords HSI0, HSI1 and HSTime (and HSAnode in case of a delay line detector). If they are not found saxs_normn looks automatically for the keywords Intensity0, Intensity1, ExposureTime and Anode. The MCS counts of scaler nn is written after the keyword HS32Cnn, the zero value after the keyword HS32Znn, the calibration factor after the keyword HS32Fnn and its name after the keyword HS32Nnn. The scaler values are calculated in the following way:

1. value(nn,time) = (HS32Cnn-HS32Znn*time)*HS32Fnn

and specifically:

2. ExposureTime = value(HSTime,0)
3. Intensity0 = value(HSI0, ExposureTime)
4. Intensity1 = value(HSI1, ExposureTime)
5. Anode = value(HSAnode,ExposureTime)

To force saxs_normn not to read from scalers, the option -scal must be given.

• trm [ 1, f]

• dpth [ 1, f]

• monc [ 1, f]

• monz [ 1, f]

• monf [ 1, f]

• monv [ 1, f]

• timc [ 1, f]

• timf [ 1, f]

• timv [ 1, f]

• anoc [ 1, f]

• anof [ 1, f]

• anoz [ 1, f]

• anov [ 1, f]

• trmc [ 1, f]

• trmz [ 1, f]

• trmf [ 1, f]

• trmv [ 1, f]

• mo2c [ 1, f]

• mo2f [ 1, f]

• ti2c [ 1, f]

• ti2f [ 1, f]

• an2c [ 1, f]

• an2f [ 1, f]

• tr2c [ 1, f]

• tr2f [ 1, f]

• sum [ 1, f]

• bcf [ 1, f]

• rdis [ 1, f]

• mons [ 1, d]

• tims [ 1, d]

• anos [ 1, d]

• trms [ 1, d]

• mo2s [ 1, d]

• ti2s [ 1, d]

• an2s [ 1, d]

• tr2s [ 1, d]

• slen [ 1, d]

• flat [ 0, +]

• tron [ 0, +]

• +tron: use user supplied tranmission value (option: -trm <transmission>)
• -tron: calculate transmission with scaler values (I1/I0)
• default: -tron

• scal [ 0, +]

• +scal: use scaler values to calculate I0, I1, exposure time and anode counts.
• -scal: read I0, I1, exposure time and anode counts from keywords in the file
• default +scal, automatically set to -scal if scaler information not found

Replacement of the first image by the second image (where it is defined). The second image is patched into the first image.

Number of image blocks : 3
Maximum number <n> of input blocks: 2

saxs_patch [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2>

• ex [ 0, +]

• +ex: do not copy dummy values from image 2 to image 1
• -ex: copy all pixels from image 2 to image 1
• default: -ex

• dumo [ 0, +]

• +dumo: only the dummy values of image 1 are patched with the values of image 2
• -dumo: replace all values of image 1
• default: -dumo

Division/multiplication by the polarization factor. All angles are in radian or must be followed by a unit, e.g 30_deg, 10_mrad.

The polarization factor P is splitted into an unpolarized P(1) and a polarized P(2) part:

1. P = P(1) + P(2)
2. P(1) = (1-Pol) * ( 1 + kout3*kout3 )/2
3. P(2) = Pol * (
   (1-kout1*kout1) * 0.5 * (1+cos(2*PChi)*cos(2*PPsi))
   + (1-kout2*kout2) * 0.5 * (1-cos(2*PChi)*cos(2*PPsi))
   - kout1*kout2 * cos(2*PChi)*sin(2*PPsi) )

The scattered beam kout is either calculated from an Ewald-sphere projection (ProjectionType = Waxs) or from a detector image (ProjectionType = Saxs). The calculation of kout is done with the same routines that are used in saxs_waxs. The rotation parameters etc are identical. Rotations are only used for detector images (ProjectionType = Saxs). The options -i1pro Saxs or -i1pro Waxs set the projection type manually.

The polarization state is described by the degree of polarization Pol and the Poincaré sphere: PChi (ellipticity ) and PPsi (polarization direction).

Number of image blocks : 2
Maximum number <n> of input blocks: 1

V4.52 2004-10-14

Usage: saxs_pol [-mul]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <odum> <odim1> <odim2>
<pol[1.0]> <pchi[0.0]> <ppsi[0.0]>

• pol [ 1, F] <Pol>
  degree of polarization (0<=Pol<=1)
• pchi [ 1, F] <PChi>
  ellipticity (radian, -pi/4<=PChi<=+pi/4)

• PChi=-pi/4 left hand (cw) circular polarization
• PChi<0 left hand polarization
• PChi==0 linear polarization
• PChi>0 right hand polarization
• PChi=pi/4 right hand (ccw) circular polarization

• ppsi [ 1, F] <PPsi>
  rotation of the polarization ellipse/axis (radian, 0<=PPsi<pi).
  The angle PPsi is measured ccw around axis x_3 starting at axis x_1
• i1pro [ 1, P] <pro> (general option, automatically set by image header)
  Apply the calculation to a Saxs image (i1pro Saxs) or to a Waxs projection (i1pro Waxs).
• i1rot [ 1, F] <i1rot1> <i1rot2> <i1rot3> (general option, define detector rotation angles)
  <i1rot1>, <i1rot2>, <i1rot3>: detector rotation angles (radian).
• mul [ 1, +]
  Multiply input image with polarization factor instead of dividing it

Calculate the n-th power of each image value

Number of image blocks : 2
Maximum number <n> of input blocks: 1

saxs_power [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <power>

• pow [ 1, f]

Refraction correction of 2d-sub-surface scattering patterns. The calculation is valid for grazing incidence small angle scattering (GISAXS) and higher angle scattering. The incoming beam is refracted at the surface, scattered below the surface inside the sample and again refracted at the surface before it hits the detector. This routine transforms the observed (external) scattering pattern into the internal scattering pattern that would be observed inside the sample below the surface. The calculation is done using Snell's law. The surface normal N^ is defined by the angles chi and eta in the following way:

1. N^ = ( cos(chi),
   cos(eta)*sin(chi),
   sin(eta)*sin(chi) )

The primary beam is pointing against axis3 = axis1 X axis2. The surface normal N^ is initially pointing along axis1. It is first rotated ccw around axis3 (with chi). Then N^ is rotated around axis1 (with eta).

V4.05 2004-10-14

saxs_refract [options] <i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <delta[0.0_deg]> <the[0.0_deg]> <chi[90.0_deg]>

• del [ 1, F]

• chi [ 1, F]

• eta [ 1, F]

Rotation of an image sequence by alfa in radian

with coordinates W (input image), W' (output image)

see also: saxs_aff

Number of image blocks : 2

Maximum number <n> of input blocks: 1

V4.04 2004-10-14

saxs_rot [options] <i1nam> <onam> <i1fst> <i1lst> <i1inc> <odum> <odim1> <odim2> <alfa>

• -alfa [ 1, f]

Projection of a horizontal band in a sequence of images to a single row. The row is written to a line of the output image.

see also: saxs_col

Number of image blocks : 2
Maximum number <n> of input blocks: 1

V4.50 (2002-06-02)

saxs_row [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <row1> <row2>

• col1 [ 1, f]

• col2 [ 1, f]

• row1 [ 1, f]

• row2 [ 1, f]

• +/-vint [ 0, +]

Read the value of a keyword from the headers of each picture and write it to a text file.

Number of image blocks : 2
Maximum number <n> of input blocks: 1

saxs_scal [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <keyword>

• key [ 1, s]

• pref [ 1, s]

• ext [ 1, s]

• fnam [ 1, s]

Calculates statistics of the input image and write the result into a text file.

Number of image blocks : 2
Maximum number <n> of input blocks: 1

saxs_stat [options]
<i1nam> <i2nam> <o/p prefix> <i1fst> <i1lst> <i1inc>
<selection>

• sel [ 1, s]

• inum Image number
• dim1 Dimension 1
• dim2 inferior limit 1
• sup1 superior limit 1
• inf2 inferior limit 2
• sup2 superior limit 2
• ntot Number of data points
• nval Number of valid data points
• ndum Number of dummies
• max Maximum Value
• min Minimum Value
• amin Minimum absolute value
• dum Dummy value
• sum Sum of data values
• ssum Sum of squared data values
• mean Mean value = sum / nval
• smean Mean squared value = ssum / nval
• rms Root mean square value = sqrt( smean )
• devi Standard deviation value = smean - mean*mean
• gc1 Center of gravity 1

• pref [ 1, s]

• ext [ 1, s]

• fnam [ 1, s]

• show [ 0, +]

Subtraction of two image sequences

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_sub [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

Average columns between col1 and col2 in image sequence 2 and subtract the results from each column of image sequence 1

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_subcol [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• col1 [ 1, f]

• col2 [ 1, f]

Average rows between row1 and row2 in image sequence 2 and subtract the result from each row of image sequence 1

Number of image blocks : 3

Maximum number <n> of input blocks: 2

saxs_subrow [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc> <i2fst>
<odum> <odim1> <odim2> <i1con> <i1fac> <i2con> <i2fac>
<ocon> <ofac>

• row1 [ 1, f]

• row2 [ 1, f]

Transformation of an edf image sequence to 1byte/2byte/4byte tiff files. If more than 1 image is read from the input file the output files are numbered. The input file is first converted to an intermediate output file and then converted to a tiff file. The output dummy is never scaled. The title is written as comment into the tiff file. The outptu byte order is given by the machine byte order.

Hint: To convert a 16 bit unsigned integer edf-raw data file to a tiff files with 16 bps the options "-auto -bps 16" should be set. If the file contains dummy values the output dummy value should be set to a positive value inside the mapping range. If it lies outside the output range it is forced to the closest number inside the output range.

Number of image blocks : 2
Maximum number <n> of input blocks: 1

saxs_tiff [options]

<i1nam> <tiff file name -tnam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <8|16|32-bps> <1-8-rori>
<auto> [<min> <max>]

• bps [ 1, d]

• rori [ 1, d]

• auto [ 1, +]

• min [ 1, f]

• max [ 1, f]

saxs_tiff saxs_tiff 3.0 1999-11-12, Peter Boesecke

Input sequence 1 [input.edf] : flat.new230696

Output tiff file [flat.tif] :

First image of input sequence 1 [1] :

Last image of input sequence 1 [1] :

Increment of input sequence 1 [1] :

Output dummy [-1.000000e+00] :

Output dimension 1 [512] :

Output dimension 2 [512] :

Bits per sample (8, 16, 32) [16] :

Orientation of output image (1-8) [3] :

Range output image with minimum and maximum? [FALSE] :

Minimum value [0.000000e+00] :

Maximum value [6.553500e+04] :

input file : flat.new230696

output prefix : flat.tif

first image : 1

last image : 1

increment : 1

output dummy : -1.000000

output dimension 1 : 512

output dimension 2 : 512

bits per sample : 16

autorange : 0

minimum value : 0.000000

maximum value : 65535.000000

Reading image: flat.new230696, Image : 1 done

Calculating ihb[0, 1] = Function(ihb[ 1, 1] )

Input file : flat.new230696

Input image number : 1

Output tiff file : flat.tif

End of /home/boesecke/programs/saxs/bin/saxs_tiff

Projection of the Ewald sphere measured with a flat area detector (projection type Saxs) to a plane perpendicular to the incident beam (projection type Waxs) and vice versa. The detector can be inclined. Additionally, xy-displacement files can be written that can be used by the spatial distortion program spd. The projection will be called WAXS-transformation (see Fig. 4).

The length of the radial coordinate in the projected pattern corresponds to the length of the scattering vector s. The azimuthal angle corresponds to the azimuth of s. The projection is strictly valid for isotropic scattering patterns. In all other cases it is only a useful projection.

The scattering vectors are calculated using saxs-coordinates (default: -rsys saxs ). The keywords PSize_N, Center_N, SampleDistance and WaveLength are required. The detector rotation can be defined with the option -i1rot <i1rot1> <i1rot2> <i1rot3>.

1. Illustration of the WAXS projection. Pixel distances di on a Saxs projection are proportional to distances dx on the detector: dx = di * PSize. Pixel distances di on a Waxs projection are proportional to distances ds in reciprocal space (WaveLength0=1e-9 for convenience, sp=2*sin(Theta)*(WaveLength0/WaveLength): dsp = di * (PSize/SampleDistance) * (WaveLength0/WaveLength)

V4.12 2004-10-14

saxs_waxs [options] <i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <i1rot1> <i1rot2> <i1rot3>

• i1rot [ 1, F] <i1rot1> <i1rot2> <i1rot3> (general option, define detector rotation angles)
  <i1rot1>, <i1rot2>, <i1rot3>: detector rotation angles (radian).
• i1pro [ 1, P] (general option, automatically read from header)
  projection type of the input image (default: saxs)
  The input projection type is read from the header of the input image. Its default is saxs. This option allows to change the input value.
• opro [ 1, P] (general option, preset to waxs)
  required projection type of the output image (default: waxs)
  The output projection type is set to waxs if it is not changed by the option opro. An input image that is already in the projection type waxs will not be transformed again. To transform this image back to a detector pattern the projection type of the output image must be set to saxs: -opro saxs.
• xy [ 1, +]
  write/do not write xy-displacement files (default: -xy)
  Xy-displacement files can be used as input for the spatial distortion correction program spd, e.g. spd xfile=xfile.edf yfile=yfile.edf.

• xyna [ 1, s]
  base name of xy-displacement files (default: file). The xy-displacement files are called x<xyna>.edf and y<xyna>.edf, e.g. xfile.edf and yfile.edf.

saxs_waxs [options] <i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <i1rot1> <i1rot2> <i1rot3>

Conversion of rapid bsl files to edf files (frames, scalers, timing). The program uses the standard edfio routines to read rapid files.

It copies rapid data to edf data files including scaler data:

The general option -add <number of frames> allows summation over multiple frames. The scaler data are also summed. The timing data is also modified, the deltatime of the first added frame is used, the new exposure time is the sum of the exposure times of all added frames. rapid2saxs can also be used to average a sequence of edf-detector file and its header data (HS32Cnn, Intensity0 and Intensity1), e.g. a ccd file+ .

Example:

BSL data consist of a header file and a number of memory files. Each memory file contains three-dimensional binary data (rows, colums, frames).

The file name definition is very strict. Header and memory files must comply with the following naming convention (C: ASCII character, M, N: number between 0 and 9).

• Header file: CNN000.CCC
• Memory file: CNNMMM.CCC

A rapid data set can consist of up to 4 files:

• A01000.323 (header file, readable ASCII data)
• A01001.323 (memory 1: binary image data, contains all frames in a single file)
• A01002.323 (memory 2: binary scaler data, optional)
• A01004.323 (memory 3: binary timing data, optional)

The header file defines the link between a file and a memory number. In the above example the header file looks like this:

The two first lines (maximum 80 characters) contain a description (free format).

The third and forth lines contain the format (rows, columns, frames) and the filename of memory 1, here A01001.323. The file contains 256 frames of 512 x 512 pixels. Each number consists of exactly 8 characters.

Each following successive line pair defines in the same way an additional memory. The last number is 1 except for the last memory definition.

The scaler memory (memory 2) contains 1 frame, 256 rows, each containing a single scalar value.

The timing memory (memory 3) contains 1 frame, 256 rows, each containing 4 scalars (dead time, live time, accumulated dead time, accumulated live time)

As a consequence of this the file numbers MMM of the memory files do not need to be consecutive. In the above example memory 3 is using the file A01004.323.

To rename a bsl data set it is necessary to update the file names in the header file.

V4.53 (2003-04-15)

rapid2saxs [options] <i1nam> <onam> <odum> <i2mem> <i3mem> <bibo>

-i1nam <rapid header file> : frame data

-i1mem <memory of frame data, default 1>

-i1fst <first frame, default 1>

-i1inc <increment, default 1>

-i1lst <number of frames>

-i2nam <scaler data file, default i1nam> : scaler data

-i2mem <memory of scaler data, default 2> (-i2nam /dev/null" to ignore scaler memory)

-i2fst <first frame, default 1>

-i2inc <increment, default 0>

-i3nam <timing data file, default i1nam> : timing data (-i3nam /dev/null" to ignore timing memory)

-i3mem <memory of timing data, default 3>

-i3fst <first frame, default 1>

-i3inc <increment, default 0>

Other options:

-bibo <bsl input byte order, default high byte first>: 1 or 2

-add <number of images to add>

Generates the scattering cross section of diluted spheres

2002-04-21 V4.04

sphere2saxs [options] <onam> <odum> <odim 1> <odim 2> <opix 1> <opix 2>
<odis> <owvl> <rad> <dre> <vfr> <d><norm> <monv> <trm> <timv>

• dre [ 1, F]

• rad [ 1, s]

• mono disperse : radius [m], e.g. sphere2saxs -rad 1e-7 ...
• Schultz distribution : "Schultz, radius [m], Z" with Z>-1, e.g. sphere2saxs -rad "Schultz,1e-7,1"
• from File : "File,name,skipl,skipc,swap,colx,coly", e.g. sphere2saxs -rad "File,xy.txt" (defaults : name["xy.txt"], skipl[0], skipc[0], swap[1], colx[1], coly[2])

• vfr [ 1, F]

• d [ 1, F]

Conversion of spec mca data to edf files (mca-frames, scalers). Only tested for spec files with one mca frame per scan

V4.51 (2003-05-25)

mca2saxs [options]
<i1nam> <onam> <i1fst> <i1lst> <i1inc>
<odum> <odim1> <odim2> <ofac> <ocon> <shft1> <shft2>

The scan number is chosen with i1fst.

• skip [ 1, D]

A single column is extracted from a set of numbered ascii-input files and are rearranged to rows of a single ascii-output file. The columns must be separated by tabs ´\t´. The columns are numbered with 1, 2, 3 etc. from the start and -1, -2, -3 etc. from the end. The parameters must be entered in the described order. For omitted parameters default values are used.

col2array [-h] [-b <mode[0]>] <output> <input> <first[1]> <last[1]> <inc[1]>

<col[1]> <skip_lines[0]> <skip_chars[0]> <separator['\t']>

• output : output filename, e.g. output.txt
• input : input filename with optional #-character specifying the position of
• the number, e.g. input_###.txt. Leading positions are filled with
• zeros.
• first : number of the first file (default: 1)
• last : number of the last file (default: first)
• inc : increment (default: 1)
• col : column number (default: 1)
• skip_lines : number of lines to skip at the top (default: 0)
• skip_chars : number of characters to skip (default: 0).

• -b <mode>: 0->text (default), 6->Signed32; 9->FloatIEEE32
• -h : show this help

The command

• col2array output.txt input_###.txt 105 095 -3 -1 2 0

will read the last column of the files input_105.txt, input_102.txt, input_099.txt and input_096.txt and write it to output.txt. It will skip 2 lines and 0 characters at the start of each file.

Macros can only be used if the path to the saxs programs is defined in the shell initialization script (e.g. ".cshrc"). The initialization script must not change the directory.

A single image of an edf file is converted into 8 bps tiff format and displayed with xv. The output image is automatically scaled between 0 and 255. Dummy values are set to 255. The macro may be aliased to xdisp.

saxs_disp <input> [<num>]

• input: input file name
• num: image number (optional) (default: first image)
• mem: memory number (optional) (default: memory 1)

The error propagation is based on the following assumptions:

• The errors of different data points are not correlated.
• The error of each data point is described by its variance.
• The variances are propagated using the laws of error propagation. Cross correlations are ignored.

The variance values are stored in a separate variance array. Usually, the file size is doubled when error propagation is switched on.

The probability density f of a vector with n statistical variables x_i can be written as

1. 
2. 

This can be written as the expectation value of an n-dimensional vector x:

3. 

The variance is the expectation value E of the squares of the differences between x and its mean value E[x]:

4. 
5. 
6. 
7. 

The matrix V[x] is called covariance matrix. It contains the variances V_ii and the covariances V_ij (i≠j).

Principle of Error Propagation

The input variables are described with x and the output variables with y.

The variance array of the output array V[y] is calculated from the variance array of the input arrays V[x] using the derivative matrix B. The input array x has n variables (pixels), the output array y has m variables (pixels).

The error propagation is calculated by transforming the input covariance matrix V[x] to the output covariance matrix V[y] according to the rule of error propagation given in eq. (24):

8. 

The matrix B contains the derivatives of each output variable (output pixel) y_i with respect to each input variable x_j (input pixel):

9. 

A straightforward application of this rule would result in an explosion of array sizes and calculation time. For practical purposes it must be simplified.

Error Propagation During 2d-data Reduction

Uncorrelated Input Data

In the case of uncorrelated input variables x the non-diagonal elements of the covariance matrix V[x] (eq. (21)) disappear and the diagonal elements V[y]_ii of the output covariance matrix V[y] can be calculated with :

10. 

The non-diagonal elements of the output covariance matrix are

11. 

If the B matrix is not diagonal the output variables are correlated.

Pixel by Pixel Calculations

Identical number of input and output variables

If the number n and m of the input and output variables are equal the derivative matrix B can be diagonal. In this case the component V[y]_ij of the output covariance matrix can be calculated directly from the component V[x]_ij of the input covariance matrix:

12. 

In this case the elements of the covariance matrix do not mix. The output variance array can be calculated independently for each variable, even if the input variables are correlated. This case corresponds to a pixel to pixel manipulation of a two dimensional data array, e.g. during scaling or normalization.

Smaller number of output variables than input variables

When L identically dimensioned input arrays with variables x¹, x², ... _x^L are combined pixel by pixel to an output array with the same number of variables the derivative matrix B can be splitted into L diagonal subarrays of the form:

13. 

The matrix B can be written as.

14. 

The covariance matrix V can be written in the same way, if any correlation between variables of different arrays can be excluded.

15. 

 

16. 

The component ij of the output covariance matrix is given by

17. 

The summation is running over all input arrays l

Pixel by pixel combination of L identical input data arrays with uncorrelated variables

In the case that all input data variables are uncorrelated also the output variables are uncorrelated. The variance of each output data point can be calculated with eq. (33). In this case it is only necessary to store additionally to each output data value its variance, which is the diagonal value of the covariance matrix.

18. 

where V[y]_ii = V[y_i] = s²_yi is the variance of data point i of the output array and V[x^l]_ii = V[x^l_i] = s²_xli the variance of the i-th data point of the l-th input data array.

Correlations between data points are not taken into account. This assumption is strictly valid if the calculations are done pixel by pixel. It is also valid if images are binned. It is generally not strictly valid if pixels are artificially divided into sub-pixels. This happens if an image is mapped to an image with different binning size. It leads to spatial smearing of the image.

This operation writes the pixel intensities of region[i,j] of input array In1 into pixel Out[i,j] of the output array. A pixel has the area 1. The value of a partial pixel is calculated by multiplying the value of the full pixel with the partial pixel area.

A region is a rectangular area of an array. The sum of a region is the sum of all partial pixel values inside the region, the weight is the sum of all partial pixel areas inside the region. Dummy pixels are not take into account.

Sum(In1,region[i,j]): sum of all non-dummy partial pixel values in region[i,j] of array In1

Weight(In1, region[i,j]): sum of all non-dummy partial pixel areas in region[i,j] of array In1

Out[i,j] = Sum(In1, region [i,j])

VOut[i,j] = Sum(VIn1, region [i,j])

Out[i,j] = Sum(In1, region [i,j])/Weight(In1, region [i,j])

VOut[i,j] = Sum(VIn1, region [i,j])/Weight(In1, region [i,j])^2

Out[i,j] = In1[i,j] * factor1 + constant1

VOut[i,j] = VIn1[i,j] * factor1^2

Out[i,j] = In1[i,j] + In2[i,j]

VOut[i,j] = VIn1[i,j] + VIn2[i,j]

Out[i,j] = In1[i,j] * In2[i,j]

VOut[i,j] = VIn1[i,j] * In2[i,j] ^2 + In1[i,j] ^2 * VIn2[i,j]

Out[i,j] = In1[i,j] / In2[i,j]

VOut[i,j] = (VIn1[i,j] + Out[i,j]^2 * VIn2[i,j]) / In2[i,j]^2