transformer

Transformer

1. Objectives

· To transform 3D peaks, as defined in the laboratory system, to G-vectors, as defined in the sample coordinate system. At the same time angles 2theta and eta are found. To do the transformation it is crucial that the geometry of the set-up is known to a high precision.
· To calibrate (determine) the parameters defining the set-up – e.g. detector distance and detector tilts - by an interactive fitting procedure.
· To enable filtering of the 3D peaks and G-vectors.

The transformer only works for far-field data, where the dimension of the illuminated part of the sample is smaller than the distance between hkl-rings on the detector (typically true when using detectors with large pixels, such as FRELON or image plates). The calibration procedure requires the unit cell to be known.

The G-vectors generated are in “crystallographic units” – no 2p in def. of reciprocal space.

Fable transformer is the graphical user interface (GUI) fortransformer.py. If one is not interested in the GUI version, transformer.py is also incorporated in the stand-alone program imageD11. See also ImageD11 for several advanced options, not included in the GUI version.

For a user guide see also the menu Help/help Contents

Note: screen shots below have been captured on windows xp OS.

2. Input & output files

2. 1 Input files

There are two input files :

• Filtered peaks file
• parameter files

2. 1. 1 Filtered peaks file

· one .flt file – a filtered file - comprising the information of the 3D peaks to be transformed. The .flt file is the output of the [peaksearch] GUI – see peaksearch for information on format.
· one parameter file, see below.

2. 1. 2 Parameter file

2. 1. 2. 1 Description
An example of a parameter file is shown below. All entries are required in the order as listed:

cella 5.8 # in Å
cellb 5.8 # in Å
cellc 5.8 # in Å
cell_alpha 90.0 # in deg
cell_beta 90.0 # in deg
cell_gamma 90.0 # in deg
cell_lattice_[P,A,B,C,I,F,R] F
chi 0.0 # in deg
distance 294662.658 # in mm
fit_tolerance 0.2
min_bin_prob 1.0E-5
no_bins 10000
o11 1
o12 0
o21 0
o22 -1
omegasign 1.0
t_x 129.322427382 # in mm
t_y 11.8135159025 # in mm
t_z 0 # in mm
tilt_x 0.00000 # in rad
tilt_y -0.013173 # in rad
tilt_z 0.002378 # in rad
wavelength 0.154 # in Å
wedge 0.0 # in deg
y-center 1016.32817 # in pixel units
y-size 48.0815 # in mm
z-center 984.924425 # in pixel units
z-size 46.77648 # in mm

The parameter file can be read into the GUI from the main toolbar or loaded from the Transformer GUI using the . Once edited it can be saved using

The parameter file comprises four types of information:

1. Set-up:
The coordinate systems used by Fable software and various conventions on signs and angles are laid out in the geometry [file:Geometry_version_1.0.7.pdf]. Conventions for flipping of the detector is laid out in this [file:Geometry_version_1.0.7.pdf] . Some entries are self-explanatory. Here is help for the others.

• distance: the distance between the rotation axis and the point where the central ray of the beam hits the plane of the screen.
• tilt_x, tilt_y, tilt_z: tilts of the detector. For conventions see the geometry document.

chi: rotation around x under the omega rotation table. Positive direction unknown
wedge: rotation around y under the omega rotation table. Positive direction ccw. At beamline ID11 this is used in connection with the Laue monochromator: the value should be -2q, where q is the Bragg angle of the monochromator.

• t_x, t_y, t_z: translations of the center-of-mass of sample. The signs follow the conventions in geometry document.

omegasign: positive for ccw

• o11,o12,o21,o22: matrix for flipping and rotating detector images. See separate document.

The recommended units are listed above. The units for cell bond lengths and wavelength can be different from Å but must be the same. The units for distance, t_x,t_y,t_z,y_size and z_size can be different from mm but must be the same. Note that you need many significant digits on some of the parameters.

2. Sample: The unit cell parameters are given in units of Ångstrøm and degrees. The Bravais lattice is indicated by the first letter of the space group symbol.

3. Fit-tolerance: The tolerance is a limit on the relative difference between the theoretical and computed 2q value for any given peak. Peaks with a difference above the tolerance will not be included in the fitting involved in calibration.

4. Parameters for histograms min_bin_prob and no_bins.

2. 2 Output file : G-vector file

Output is a *.gve file with G-vectors../../below#gve?. In addition one may save revised versions of the filtered file and the parameter file.

The *.gve file has a header with the parameters used for the transformation and a list of the hkl values used and their corresponding d-values. The follows as example a columnar list of G-vectors and their properties. Ex.:

   1. xr yr zr xc yc ds eta omega spot3d_id xl yl zl

-0.113322 -0.917841 0.069644 466.018235 1251.524905 0.927429 85.664602 0.415972 0 8000.000000 -1872.099620 141.927061
-0.153865 -0.870006 0.634103 175.114178 1231.950296 1.087507 53.952563 0.474699 1 8000.000000 -1793.801183 1305.543289
-0.140800 0.410273 -0.997258 1014.808715 573.382090 1.087507 202.261260 0.819253 2 8000.000000 840.471639 -2053.23486

• xr, yr, zr: the coordinates of the G-vector in crystallographi units – no use of 2p in the definition of reciprocal space.
• xc, yc: the detector coordinates for the center of the diffraction spot using slow/afst coordinates and after optional spatial distortion correction. These entries are identical to sc and fc in the output from Peaksearch (sorry for the confusion).
• ds: d-spacing in Å
• eta, omega: angular coordinates for the diffraction spot after optional spatial distortion correction
• xl,yl,zl: absolute coordinates of center of spot on the detector screen in the laboratory system after optional spatial distortion correction. Units of microns (not milimeters).

3. Visualization and filtering

Data from a filtered peaks file can be input from the top menu or from the GUI “transformation optics”. It will immediately be visualized as a Column file plot with sc and fc (detector coordinates) on the X and Y axis. Using the Plot options fields X and Y one can plot any other combination of 2 columns in the filtered peaks file.

One can zoom on the view by keeping Control bottom and left hand click on mouse down while dragging and setting a box with the mouse.
Using the plot editor one can define an area-of-interest (AOI) and either delete all data points inside the AOI or delete all point outside the AOI. By use of various choices of X/Y coordinates and boxes complicated filtering procedures can be performed interactively. The remaining peaks can be saved by . The format is identical to the output files from peaksearch.

Typically it is of interest to take the analysis one step further, namely to include filtering on angles tth (two-theta) and eta. with eta being the angle around a powder ring measured from the vertical. This requires loading a parameter file, where as a minimum the entries for the geometry parameters (see above) are correct. Then by pressing Compute tth eta.

the parameters tth,eta as well as xl,yl,zl are determined. These are added to the columns that can be plotted in the Column file plot. When saving the filtered peaks, these columns are added to the output file.

4. Generation of G-vectors

This operation follows that outlined above. In order to determine the G-vectors, one must know the unit cell parameters and the cell lattice, as specified in the parameters menu.
The procedure is as follows

1. Compute tth eta. Press
2. Plot unit cell peaks. Press . The theoretical values for tth will appear as small red lines in the (tth,eta) plot.
3. Compute G-vectors. Press .
4. Save transformed data . Set the filename and press

5. Calibration (fitting geometric parameters)

The calibration procedure is an interactive fitting procedure for determining the geometry parameters listed in the parameter menu with high precision. It is based on a simplex least square routine for minimizing the least squares sum over all spots of |2qmodel– 2qtheoryl|, where 2qmodel and 2qtheory are the experimentally determined (given geometry parameters) and the known theoretical values for the scattering angles.

Put simply the idea of the interactive procedure is after each iteration to test to what extent the diffraction spots form straight lines in a tth-eta plot. During the process one should exclude bad points and progressively include more and more spots in the fitting and improve the overall quality of it.

The fitting is based on the data shown in the plot window. To change the data included in the next iteration of the fit either change the zoom in the window and/or remove data. (Perhaps you will need to go to the plotting menu and clear plot before making this plot to get a sensible x/y range).The fitting procedure will keep the values ticked in the parameters window fixed.

An example of the plotting window is given above. The fit is already quite good as the valid spots all fall on nearly straight lines. Note the red bars which mark the theoretical tth positions.

The overall procedure is therefore:
1. Open parameter file and edit the parameters
2. Input data from filtered file
3. Iteratively
- Fix or free relevant parameters
- Zoom/unzoom window to include the parts of data to be fitted. Option: delete bad data points
- To register changes in settings and do the fitting press
- In case of a bad fit you can return to previous parameter setting by
4. Save the final resulting G-vectors in a G-vector file
5. Option: save the final iteration of parameters to parameter file, e.g. using , and the final set of 3D peaks used for fitting as a 3D peak file.

5. 1 Some guidelines for calibration procedure

• Make sure the sign of omega and detector flips are correct
• If a spatial distortion correction is needed, you must provide a FIT2D spline file – is probably known from local experts. Also, you MUST use the values for pixel size recorded in the spline file for things to work out properly.
• For first guess, estimate parameters as well as you can by traditional methods, e.g. know the distance within ~1%.
• Use a well known sample with a small unit cell for (at least first iteration on) calibration
• Use a 360 deg rotation in omega for the calibration
• Start by fitting only innermost rings (as there is less likelihood of overlap between hkl rings here) and gradually increase the 2q range included in the fit as the lines in the 2q-h plot become more and more straight
• Start by fitting only a few parameters and gradually include more and more parameters in the fit to avoid local minima
• Remove all noisy peaks – e.g. at wrong 2q’s - as the least-square routine is sensitive to outliers. However, avoid biasing the fit, when cutting away data.

6. Version

Sources code 1.0.5

Peaksearch is released with python programs which it depends and also their dependencies. These programs are available in python folder.
You don't have to install them, script file you launch for peaksearch set this path to python path.
Here are the two fable python program on which peaksearch GUI relies :
- ImageD11: version 1.2.1
- fabio : version 0.0.2

These fable python relies on numpy and PIL available in python folder.

7. TODO

- tth histogram action changes the plot to x-axis tth_hist_prob and y-axis to eta. It should be x-axis tth and y-axis tth_hist_prob or Maybe
a new plot should appear with the histogram instead of plotting on top of the other
- In the transform menu there is an item: open param file, but not a
save param file (this can only be done with a button, which I could not
find at first).
- user feed back : save gve buttons in the view shouldn't be a save as ....
- Parameter view is in front of options view in default perspective and it is hidden behind options transform in "small perspective"

8 fable 1.0.0