LAUESCALE - WAVELENGTH NORMALISATION

INTRODUCTION

The program LAUESCALE is used to calclulate a normalisation curve for a set of Laue data by scaling a set of Laue reflection data against a standard set of monochromatic data as a function of wavelength. Once calculated, the curve may be used to normalise further sets of Laue data. The program now has an option to calculate a two dimensional absorption correction surface and to iterate the wavelength normalisation and absorption correction steps. Special options are also available to handle wavelength/sign separated reference data e.g. for use in conjunction with wavelength dependent structure factor calculations. The program was written by J.W. Campbell, Daresbury Laboratory.

List of sections:

Data Control Cards
Input and Output Files
Running the Program
Notes
Printer Output
Error Messages
Program Function
References
Examples

DATA CONTROL CARDS

Data Card 1

TITLE

Title (up to 70 characters) for the output file(s). If a file to be written for input to ROTAVATA/AGROVATA then this title will also be used as the batch title.

Data Card 2

CODE [ GE INTYP ISPAT ]

CODE is either the code NORMALISE if a set of Laue data is to be normalised against a reference set of standard (e.g. monochromatic data) or SCALE or RSCALE if a set of Laue data is to be scaled using a previously calculated normalisation curve. The RSCALE option requires an input reference reflection file so that the scaled data may be compared to this set. The SCALE option only requires the Laue data file.

Normally the input Laue data file to LAUESCALE is a file created by the program AFSCALE. However, there is an alternative option to use the data from the 'A' film only directly from a '.ge1' file. To use this option, three extra parameters are given:

The code 'GE' to indicate that a .ge1 file is to be read.

INTYP is the integration type:

= 1, box integration,

= 2, profile fitted (the default)

ISPAT indicates the required handling of spatially overlapped spots:

= 0, Do not include spatially overlapped data

= 1, Include spatially overlapped data

Data Card 3

NSPGRP AMINL AMAXL RES1 RES2 TH1 TH2 BFAC NRANGE

NSPGRP is the space group number. The symmetry positions for this space group are read from the CCP4 symmetry operators file and the corresponding point group symmetry matrices are read from the CCP4 point groups file.

AMINL, AMAXL are cutoff limits in lambda (in Angstroms) to be applied to the Laue data on input. If zero values are given, then values of AMINL and AMAXL will be the taken as the minimum and maximum lambda values in the input Laue data.

RES1, RES2 are cutoff resolution limits (in Angstroms), either order, to be applied to the Laue data on input.

TH1, TH2 are cutoff limits in theta (in degrees), either order, to be applied to the Laue data on input.

BFAC is a differential temperature factor between the Laue and standard data to be applied to the Laue data on input.

NRANGE is the number of separate ranges of Lambda (1 to 3) to be used in the curve fitting process.

Data Card 4

BMINL BMAXL BINS NFIT IFEX [IORD Q(0) ... Q(IORD)]

BMINL, BMAXL are the minimum and maximum Lambda values (in Angstroms) for the range. If only one range was requested, then zero values may be given and the values will be set to AMINL and AMAXL (see data card 3).

BINS may either given as the width of the Lambda bins to be used in the curve fitting (a value in Angstroms less than 1.0) or as the number of bins (a value greater than 1). The total number of bins for all the ranges must not exceed 100.

NFIT is the order of the polynomial to be fitted (0 to 10) for the range. (ignored for SCALE/RSCALE options)

IFEX is a flag indicating whether or not extra end of range points are to be added to the wavelength bin scale factors before curve fitting. See LAUENORM documentation for details.

= 0, Do not add extra end points (the default).

= 1, Add an extra end point at the low wavelength end of the range.

= 2, Add an extra end point at the high wavelength end of the range.

= 3, Add extra end points at both ends of the wavelength range.

IORD Q0 ...Q(IORD). These values are only required if the input code on data card 2 was 'SCALE' or 'RSCALE'. They are the order of the polynomial followed by the polynomial coefficents (IORD+1 values) of the normalisation curve to be applied. If necessary the polynomial coefficients may continued on additional cards.

Data Card 5

IFILE1 IFILE2 SCAL2 IWTS AWTS IWTL AWTL IWMEAN SCALIN SIGREJ NDIAG1 NDIAG2

IFILE1 is a flag = 1, Output a first reflection data file containing the merged and scaled Laue data. If the option NORMALISE was requested then the the FP and sigma(FP) values from the standard file will also be written to the output file.

=-1, Output a first reflection data file containing the merged and scaled Laue data in SHELX format.

=-2, Output a first reflection data file containing scaled but unmerged Laue data, including wavelength values, in SHELX format.

<-1000, Output a first reflection data file containing scaled but unmerged Laue data including a batch number (= -IFILE1 -1000) and wavelength values. I and sig(I) values (divided by 100.0) are output rather than F and sig(F) values (SHELX)

= 0, Do not output any of these files

IFILE2 is a flag < 0, Output a second file with scaled Laue data with anomalous differences and with reflections measured at different wavelengths kept separate.

> 0, Output a second file with the scaled Laue data in a form suitable for input to ROTAVATA and AGROVATA. The value of IFILE2 will be used as the batch number.

= 0, Do not output a second file.

SCAL2 is the value by which output intensities are to be divided for a ROTAVATA/AGROVATA compatible second output file. The default value is 20000. If IFILE2 <= 0 then the value of SCAL2 is ignored.

IWTS is a flag:

= 0, use weights = 1/sigma(Is)**2 when calculating the mean standard intensities for the lambda bins. (Is = standard intensity)

= 1, use unit weights when calculating the mean standard intensities for the lambda bins. (This is probably the safest option to start with)

> 1, use weights = 1.0 + AWTS*Is/1000 when calculating the mean standard intensities for the lambda bins.

AWTS is a weighting factor used only if IWTS > 1 (see above)

IWTL is a flag = 0, use weights = 1/sigma(Il)**2 when calculating the mean Laue intensities for the lambda bins. (Il = Laue intensity)

= 1, use unit weights when calculating the mean Laue intensities for the lambda bins. (This is probably the safest option to start with)

> 1, use weights = 1.0 + AWTS*Il when calculating the mean Laue intensities for the lambda bins.

AWTL is a weighting factor used only if IWTL > 1 (see above)

IWMEAN is a flag:

= 0, use weights = 1/sig(Il)**2 when calculating the mean intensity values when merging the scaled Laue data for a reflection. This is the recommended value. (Il = Laue intensity)

=1, use unit weights when calculating the mean intensity values when merging the scaled Laue data for a reflection.

SCALIN in a scale factor by which the input intensities and their sigma values are to be multiplied when they are read in. This may be used to scale down the values if there are sigma values greater than 32767 in the Laue input data. The default value is 1.0.

SIGREJ. If a value greater than 0.0 is given, the reflections with I < SIGREJ * ISIG will be rejected. The default value is 0.0 such that this rejection criterion is not applied.

NDIAG1, NDIAG2 are the number of diagnostic relections to be printed when the Laue data are being collected for scaling and when the Laue data have been scaled for output respectively. Normally values of zero are given.

Note: The values of IWTL, AWTL, IWTS, AWTS and NDIAG1 are ignored for the SCALE or RSCALE options.

Data Card 6

NITER IUPDB IABS NQORD NRORD ISQMIN ILMIN LASTIT DIAGR DLAM ICTYP

NITER is the number of iterations of the Normalisation (/absorption correction) procedur required.

IUPDB is 1 if the temperature factor difference calculated at the end of the normalisation procedure is to be applied on the next iteration. If 0 then the initlai value given for BFAC on card 3 is used througout.

IABS > 0 if a two dimensional absorption surface is to be calculated and 0 if no absorption correction is required. The actual value indicates the type.

=1, The two parameters 'Q' and 'R' used in the absorption surface calculation are the angles whose tangents are xf/ctof and yf/ctof where xf, yf are the film coordinates and ctof is the crystal to film distance.

=2, The two parameters 'Q' and 'R' used in the absorption surface calculation are the film xf and yf coordinates in mm.

QQORD is the order of polynomial to be fitted in the 'Q' dimension (max of 10). Only required if IABS>0.

QRORD is the order of polynomial to be fitted in the 'R' dimension (max of 10). Only required if IABS>0.

ISMIN. A standard intensity will be omitted from the calculation of the absorption surface if the (unscaled) intensity is less than ISMIN. (Only required if IABS>0).

ILMIN. A Laue intensity will be omitted from the calculation of the absorption surface if the (unscaled) intensity is less than ILMIN. (Only required if IABS>0).

LASTIT. When absorption corrections are being carried out each iteration has a normalisation step followed by an absorption surface calculation step. If LASTIT is set to 1 then the absorption surface calculation will be omitted in the final iteration (recommended) so that the final calculation is that of a normalisation curve. Otherwise set LASTIT to 0. (Only required if IABS>0).

DIAGR. Diagnostic ratio. Display rogue intensity pairs for which IS/IL>DIAGR or IL/IS>DIAGR is found when calculatng the absorption surface. (Default value = 10.0). (Only required if IABS>0).

DLAM. If a value greater than 0.0 is given, then wavelength dependent reference data are used instead of the usual fully merged data. Laue and reference reflections are only considered to match if their wavelengths are within DLAM Angstroms as well as having the same indices. The option was introduced to allow the use of reference data from wavelength dependent structure factor calculations.

ICTYP. Normally 0. If a value of 1 is given then 'sign separated' reference data are used instead of the usual fully merged data. Laue and reference reflections are only considered to match if they have the same sign as well as having the same indices. The option was introduced to allow the use of reference data from non-centrosymmetric (and usually wavelength dependent) structure factor calculations.

Data Card 7

LABIN item1=name1 item2=name2 ...

These are the MTZ assignments for the input MTZ reflection data file for the items H K L FP SIGFP where FP and SIGFP are the reference F and sigma(F) values. If DLAM>0, then there is an extra assignment for a wavelength column LAM and if ICTYP>0 there is an extra assignment for the sign column SIGN.

INPUT AND OUTPUT FILES

The input files are:

  1. The control data file

  2. The input Laue data file. This is a card image file with one reflection per record giving the items H K L LAMBDA THETA I SIGI. See program documentation for further details. The data are unmerged and need be in no particular order.

    Alternatively, if the code 'GE' is specified on Data Card 2, then the input file is a '.ge1' format file.

  3. The input reflection file containing the standard reflection data to be used in the normalisation in standard MTZ format. This data file must be sorted on h, k and l and must contain the unique set of indices for the point group as produced by the standard data processing programs.

    If one of the special options is used to have wavelength and/or sign separated reference data, the additional wavelength and/or sign columns must be present in the reference data file. The sign values are +1 and -1 for non-centrosymmetric reflections and 0 for centrosymmetric reflections. The sort order is h k l [sign] [lam].

The output files are:
  1. An optional first output reflection data file which may be one of the following:

    1. A standard MTZ format file containing the merged and scaled Laue data. If the option NORMALISE or RSCALE is selected, the output data items are H K L FS SIGFS FL SIGFL. If the option SCALE is selected, the output data items are H K L FL SIGFL. (FS and SIGFS are the F and sig(F) values for the standard data and FL and SIGFL are the F and sig(F) values for the Laue data. If a special option for wavelength/sign separated data is used then there will be additional columns LAM (wavelength) and/or SIGN (sign) written.

    2. A card image file containing the fully merged normalised reflection data (without anomalous) in SHELX format. (H K L F SIGF in format 3I4,2F8.2). If a special option for wavelength/sign separated data is used then there will be additional columns for wavelength (F8.4) and/or sign (I8) written.

    3. A card image file containing the unmerged normalised reflection data (with lambda values) in SHELX format. (H L K F SIGF LAMBDA in format 3I4,2F8.2,F8.4)

    4. A card image file containing the unmerged normalised reflection data (with lambda values and a batch number) in SHELX format. (H L K I SIGI BATCH LAMBDA in format 3I4,2F8.2,I4,F8.4)

  2. An optional second output reflection data file in MTZ format.

    This may be either of the following:

    1. A file containing scaled and partially merged Laue data. The symmetry related (I+) and (I-) pairs for the reflection are merged provided that they were measured at wavelengths within 0.1 A of each other. The output data items are H K L LAMBDA THETA FP SIGFP DANO SIGDANO. LAMBDA is the wavelength in Angstroms, THETA is the theta angle in radians and FP etc. are the F value, the sig(F) value, the anomalous difference and sig(anomalous difference) for the scaled Laue reflection data. It should be noted that this output MTZ file will be of the multirecord type as there may be more than one record present for a given reflection. This output is intended for further special processing associated with the Laue technique.

    2. A file suitable for input to ROTAVATA and AGROVATA containing the columns H K L S M/ISYM BATCH I and SIGI. (See documentation of ROTAVATA for further details)

RUNNING THE PROGRAM

Use the command 'laue lauescale'

Parameters:

DATA

The control data file.

LAUEHKL

The input Laue data file. (type = .afout or .ge1)

HKLIN

The input MTZ standard reflection data file if required.

HKLOUT

The output reflection data file containing the scaled and merged reflection data.

HKLOUT2 (optional)

The optional second output reflection data file if required.

SHELX (optional)

The optional output SHELX file if required.

DIAGNOSTICS FILE NAME (optional)

The optional diagnostics file if required.

NOTES

Note 1. Internal scaling factor

During the scaling process the standard intensities from the input MTZ file are divided by a preset factor of 1000 so that, in general, they should then be of comparable magnitude to the input Laue intensities.

PRINTER OUTPUT

Key: Il = Laue intensity, Is = Standard intensity

The printer output consists of the following sections.

  1. Control data and reflection data details

    The printer output starts with details derived from the control data cards and from the input MTZ reflection data file if present. Header details for the output MTZ file(s) are then given. These are followed by counts of the number of Laue reflections read and accepted and the lambda (wavelength) limits found in the Laue data file.

  2. Curve fitting results (Option NORMALISE only)

    For each range of lambda selected, a table is given of the curve fitting Polynomial coefficients for polynomial orders from 0 to 11 (or up to the maximum number of points for the range minus one). the r.m.s. deviations for each order is given so that the user may judge whether the curve fitting order, selected via the control data, is appropriate.

  3. Normalisation analysis (Option NORMALISE only)

    For each lambda bin, the following items are given:

    A graphical output is also given to indicate the results of the curve fitting. The above table is split into sections if more than one lambda range for curve fitting was specified via the control data.

    Values of lambda for which extrapolated values rather than curve fitted values will be used for the scaling are then indicated.

  4. Analysis of the scaled Laue data

    For each lambda bin, the following items are given:

  5. Rscale calculation and B-Factor analysis

    This section is output, except on the last iteration, if either an absorption correction is being calcualted or if the BFAC temperature factor is to be updated.

    The scaling R-factor between the merged Laue data and the standard data is calculated as

    RSCALE = Sum( Il-Is )/Sum(Il+Is)

    where the sums are over all matching reflections.

    An analysis of the data in 10 equal bins of sin(theta)**2/lambda**2 is the given with the following items:

    From these data, a difference temperature factor between the normalised data and the standard data is then calculated and output.

  6. Absorption correction analysis and results

    This section is only present if an absorption correction is being carried out.

    The section starts with a list of any 'rogue' reflections with Il/Is or Is/Il ratios larger than the ratio DIAGR specified in the control data. The table gives the following information for each such reflection:

    Details of the number of reflections to be used in the absorption correction calculation and the numbers excluded because of low standard or Laue intensity values (<ISMIN, <ILMIN).

    A table of average observed Is/Il values on a 16 by 16 grid of the 'Q' and 'R' parameters used in the absorption correction calculation.

    The polynomial coefficients for the absorption correction surface fitted to the Is/Il data as a function of 'Q' and 'R'.

    A table of the surface fitted values of Is/Il on the same 16 by 16 grid of the 'Q' and 'R' parameters.

    The analyses of the scaled laue data, Rscale calculation and B-Factor analysis are then repeated.

  7. The sections from the curve fitting onwards are repeated for each requested iteration.

  8. Final analyses.

    The analysis of the scaled Laue data is repeated.

R-factor analyses

Three Laue data merging R-factors, RFACT1 to RFACT3, are then given. These are calculated as R = Sum( Il-Imean )/Sum(Imean) with sums over the individual Laue reflections where Imean is calculated as follows for the different R-factors:

RFACT1 Imean = The mean intensity for all measurements (I+) and (I-) for the reflection (and all symmetry equivalents)

RFACT2 Imean = The mean intensity for all measurements of the same sign (I+ or I-) for the reflection.

RFACT3 Imean = The mean intensity for all measurements of the same sign (I+ or I-) for the reflection and with lambda values within 0.1 Angstroms.

Note: If a special option for wavelength/sign separated reference data is used then each reflection with a different wavelength and/or sign (depending on the options selected) is effectively treated as a different reflection e.g. if sign separated data are used then RFACT1 will be the same as RFACT2. If the wavelength dependence is used then there may end up being very few (or even zero) reflections included in these internal R-factor calculations.

If the option NORMALISE or RSCALE was specified, the a scaling R-factor between the merged Laue data and the standard data is calculated as

RSCALE = Sum( Il-Is )/Sum(Il+Is)

where the sums are over all matching reflections.

Again, if the option NORMALISE was requested, three tables are then printed giving analyses of the scaling in ten equal bins of theta, sin**2theta/lambda**2 and intensity respectively.

ERROR MESSAGES

  1. General syntax error in the control data 
    **SYNTAX ERROR IN FIELD n **
text
  2. Errors in the control data

    **NORMALISE OR SCALE OR RSCALE MUST BE SPECIFIED**

    **INVALID CODE**: code

    **INVALID LAMBDA LIMITS**

    **ORDER FOR CURVE FITTING MUST BE 1-10**

    **MAXIMUM ORDER ALLOWED IS 10 FOR POLYNOMIAL ABSORPTION SURFACE**

    **NO. OF COEFFICIENTS MUST BE 1-11**

    **CMAX MUST BE GREATER THAN CMIN**

    **NUMBER OF LAMBDA RANGES MUST BE 1 to n**

    **LAMBDA RANGE LIMITS MUST BE IN INCREASING POSITIVE VALUES OF LAMBDA**: blmin1 blmax1 blmin2 blmax2 blmin3 blmax3

    **INVALID VALUE OF IFEX FOR RANGE n **

    **ABSORPTION TYPE n NOT AVAILABLE**

  3. Errors in calculating bins requirements

    **BINS PARAMETER MUST BE GREATER THAN 0, BINS = x FOR RANGE y **

    **MINIMUM OF TWO BINS ALLOWED IN EACH RANGE**

    **MAXIMUM OF 100 BINS ALLOWED**

  4. Errors in reading Laue data

    **NUMBER OF REFLECTIONS MAY NOT EXCEED n**

    **INDICES OUT OF RANGE -127 TO 127, HKL= h k l **

    **SIGMA OUT OF RANGE 0-32767 FOR REFLECTION HKL= h k l SIGMA = isig **

    **NO LAUE REFLECTIONS ACCEPTED**

  5. Errors in collecting data for curve fitting

    **NUMBER OF BINS CONTAINING DATA IS LESS THAN TWO FOR RANGE n **

  6. Errors in curve fitting

    **LESS THAN TWO POINTS DETERMINED FOR CURVE FITTING**

    **INVALID PARAMETERS FOR EXTRAPOLATION x1 x2 x3 x4 **

  7. Errors in absorption surface fitting

    **FEWER OBSERVATIONS THAN PARAMETERS FOR SURFACE FITTING**

    **UNABLE TO FIT ABSORPTION SURFACE**

    **SINGULAR MATRIX FOR ELEMENT n **

  8. Error in reading standard data when preparing output file

  9. Other MTZ file handling errors

    Other error messages may be produced by the MTZ file handling routines.

PROGRAM FUNCTION

The program LAUESCALE is used to scale a set of unmerged intensity data measured by the Laue method to a set of conventionally measured reflection data (ref. 1). The scaling is carried out as a function of the wavelength lambda. It is done by dividing the data into lambda bins and calculating the ratio of the mean Laue intensity to the mean standard intensity for these bins. The points of this ratio as a function of wavelength are fitted by calculated curves using polynomial curve fitting routines. To allow for discontinuities in the function of scale factor against lambda, the scaling may be divided into up to 8 lambda ranges. The data are analysed in a number of ways during the scaling process (see section 7 above for details).

The resulting scaling curve may also be used to scale further sets of Laue data.

The program may also be used to calculate an absorption correction surface. In this case the standard data will normally be a set of Fcalc values. A two dimensional surface is fitted to the observed Is/Il (Standard/Laue intensity) ratios as a function of two parameters such as the film xf and yf coordinates or two angular parameters. A bivariate polynomial is used to fit the surface. When using the program to calculate an absorption correction, the wavelength normalisation and absorption surface correction steps are iterated.

The program may also be used to calculate a difference temperature factor between the standard and Laue intensity data and to update the temperature factor on successive iterations if required. The temperature factor difference is calculated by fitting a straight line to log(Il/Is) as a function of sin(theta)**2/lambda**2.

Options have also been incorporated so that wavelength dependent calculated structure factor data may be used as reference data. In this case reflections with the same indices but with different wavelengths and/or signs are treated effectively as separate reflections.

REFERENCES

  1. "The Recording and Analysis of Synchrotron X-radiation Laue Diffraction Photographs" J.R. Helliwell, J. Habash, D.W.I. Cruickshank, M.M. Harding, T.J. Greenhough, J.W. Campbell, I.D. Clifton, M. Elder, P.A. Machin, M.Z. Papiz and S. Zurek, J.Appl.Cryst. (1989) 22 483-497

EXAMPLES

Example of the control data for calculating a normalisation curve in three lambda ranges for a set of Pea Lectin data. 

PEA LECTIN LAUE DATA
NORMALISE
19  0.00 0.00  0.0 0.0  0.0 0.0  0.0  3
0.45 0.48 2 1 0
0.49 0.90 5 3 0
0.93 1.60 16 5 0
1 10 20000    1  0.0   1  0.0  0  1.0 1.5    0   0
1 0 0 4 4 500 500 1 10.0
LABIN FP=F SIGFP=SIGF

Example for a zinc insulin film with normalisation and absorption corrections. 

Zinc insulin film
NORMALISE
146 0.45 1.6 0.0 0.0 0.0 0.0  0.0  2
.495 .905 6 4 3
.93 1.6 6 4 3
1 0 0 1 0 1 0 0 1.0 2.0 0 0
3 0 1 4 4  5000 1000 1 2.5 0.0 0
LABIN FP=FO SIGFP=SDFO


John W. Campbell
CCLRC Daresbury Laboratory
Last update 21 Aug 1996