MERGEHKLF5

Introduction
Download and Installation
How does it work
Input and Output files
Help
How to use
Final Notes

Introduction

mergehklf5 is program to merge so-called hklf5 files.

If performing a TWIN refinement with an hklf5 file using shelxl merging must be surpressed with MERG 0 ( Herbst-Irmer & Sheldrick,(1998) Acta Cryst. B54, 443-449). Therefore it is advisable to merge the hklf5 file before entering shelxl
mergehklf5 is made for this purpose and takes into account the point group symmetry and the hklf5 batch numbers. Several weighting schemes for merging intensities and sigmas may be selected.

Features:

merge shelx hkl files
various weighting schemes
determination and application of instability constant (error model)
proper treatment of batch numbers (for twinning)
outlier rejection
add inversion twin reflections

Remarks:

If you intend to perform an absorption correction on your data, you should do this before using mergehklf5.
Depending on the geometry of the diffraction experiment, it may happen that, for a given h,k,l, there are overlapping and non-overlapping reflections available. From our experience it is advisable to use, in the case of eval14, only the non-overlapping equivalents. In the case of eval15, it is advisable to use only the overlapping equivalents.

Download and Installation

Obtaining MERGEHKLF5

The program (version 26-sep-2018) is distributed as source code in the form of a tar file for Unix/Linux platforms.

Installing mergehklf5

Copy the file mergehklf5src.tar into an empty directory, for example /usr/local/src/mergehklf5
Untar the file with the command tar -xvf mergehklf5.tar
Edit the Makefile and (un)comment the lines for your operating system.
Compile the source code by typing make all
Create with your editor a file /usr/local/bin/mergehklf5 (or somewhere else in your searchpath). This file should contain two lines:
```
#!/bin/sh
exec /usr/local/src/mergehklf5/mergehklf5 "$@"
```
Make this file executable: chmod ugo+x /usr/local/bin/mergehklf5
You should now be able to use mergehklf5

How does it work

Equivalent reflections will be merged.

pointgroup

You have to specify the pointgroup. The program can handle the following pointgroups:

  -1
   2      m    2/m
 222    mm2    2mm   m2m    mmm
   4     -4    4/m
 422    4mm   -42m  -4m2  4/mmm
   3     -3
 312    321    31m   3m1   -31m    -3m1
   6     -6    6/m
 622    6mm   -6m2  -62m  6/mmm
  R3    R-3
 R32    R3m   R-3m
  23     m3
 432   -43m    m3m

Reflections are considered equivalent if the indices of the main AND the indices of the overlapping lattice follow the pointgroup symmetry AND if the batchnumbers are equal.

Intensity merging

To calculate the average intensity I_mean of every group of equivalent reflections, you must select one of three weighting schemes
(WeightInt):

         ∑w_iI_i
 I_mean = ——————
          ∑w_i

Unit Weights
```
 w_i = 1
```
Statistical weights
```
 w_i = 1/σ_i²
```

Shelx weights (taken from the SHELXL-97 source code)

 if I_i/σ_i > 3
 w_i = I_i/σ_i²
 otherwise
 w_i = 3/σ_i

Sigma merging

For calculating the final sigma, you must select a sigma weighting scheme, a formula for the Internal Sigma, a formula for the External Sigma and a formula for the Final Sigma.

weighting schemes for the calculation of the merged sigma (WeightSig)
1. Unit Weights
```
w_i = 1
```
2. Statistical weights
```
w_i = 1/σ_i²
```
3. Shelx weights (taken from the SHELXL-97 source code)
```
w_i = 1/σ_i²
```

Formulae to calculate the internal sigma σ_int (FormulaSigInt)

standard (D. Schwarzenbach et al., (1989) Acta Cryst. A45, 63-75)

         ∑w_i(I_i-I_mean)²
 σ_int= √ ——————————————
          (n-1)∑w_i

shelx (taken from the SHELXL-97 source code)

       ∑|(I_i-I_mean)|
 σ_int= —————————————
         n√(n-1)

crystals (taken from the CRYSTALS manual)

         ∑w_i(I_i-I_mean)²
 σ_int= √ —————————————
             ∑w_i

sortav (Blessing, (1997) J.Appl.Cryst.,30, 421-426)

         n∑w_i(I_i-I_mean)²
 σ_int= √ ——————————————
          (n-1)∑w_i

Formulae to calculate the external sigma σ_ext (FormulaSigExt)
1. shelx (taken from the SHELXL-97 source code)
```
         ∑w_iσ_i²
 σ_ext= √ ——————
          n∑w_i
```
2. crystals (taken from the CRYSTALS manual), sortav (Blessing, (1997) J.Appl.Cryst.,30, 421-426)
```
         ∑w_iσ_i²
 σ_ext= √ ——————
          ∑w_i
```
Formulae to calculate the final sigma σ_mean (ResultSig)
1. σ_mean = σ_int
2. σ_mean = σ_ext
3. σ_mean = the maximum of σ_int and σ_ext
4. σ_mean = the minimum of σ_int and σ_ext

Input and Output files

Both the input file and output file are ascii files in shelx format:

 h k l Intensity σ batchnr
 (3i4,2f8.2,i4)

see shelx manual
Optional direction cosines in the input file are not transfered to the output file.

Help

By typing help at the Mergehklf5> command prompt, a webbrowser will be launched to display this page.

How to use mergehklf5

Start the program with mergehklf5
You have to answer a few questions first:
- Enter Point Group
  Enter one of the above-mentioned pointgroups
- WeightInt [3]
  specify weightscheme for Intensity merging
- WeightSig [3]
  specify weightscheme for Sigma merging
- FormulaSigInt [2]
  specify formula for Internal Sigma.
- FormulaSigExt [2]
  specify formula for External Sigma.
- ResultSig [3]
  define final sigma
- Ignore Batch numbers[no]
  If set to yes, all batch numbers are set to 1 while reading the input data. Use yes only to merge a hklf4 file. Never use yes on a hklf5 file.
- Omit single reflections if overlaps are available [yes]
  (Only asked if Ignore Batch numbers is no)
- Omit reflections with intra-overlap [yes]
  A reflection is intra-overlapping if:
  - The main reflection overlaps with another reflection in the main lattice
  - Two or more interfering reflections are from the same (interfering) lattice
- Enter *.hkl* filename[]
  specify input hkl file
Now you have the possibility to enter commands. Possible commands are:
- ?
  A summary of available commands
- addfriedel
  Treat the dataset as an inversion twin. Every reflection (h,k,l) will overlap with (-h,-k,-l).
  In the output file the inverted reflections will be added with an appropriate new batch number.
- automsa
  Determine and apply an optimal msa in order to obtain a flat χ² distribution. Use msa to set the instability constant manually.
- dumpd n
  Print all information on one reflection
- dumpm n
  Print all information on a set of equivalent reflections
- exit
  End of program
- formulasigext n
  Specify the formula for the external sigma. The default is 2.
- formulasigint n
  Specify the formula for the internal sigma. The default is 2.
- help [command]
  Start webbrowser with help on mergehklf5. The following browsers are tried: (GETENV BROWSER),iceweasel, firefox, mozilla, netscape.
  You may add the optional command; if possible, the browser will jump to the appropriate section.
- hkl h k l
  Print a set of equivalent reflections
- invert
  Enter a list of batch numbers. Reflection indices for members of this list will be inverted. See noinvert.
- listintra
  Print all intra-overlapping reflections. A reflection is intra-overlapping if:
  - The main reflection overlaps with another reflection in the main lattice
  - Two or more interfering reflections are from the same (interfering) lattice
- listreject
  Print all sets of equivalent reflections where at least one is rejected. Use reject to reject reflections.
- msa f
  Set the instability constant to f. See Stout&Jensen, X-ray structure determination (1989), page 186.
```
 σ = √( (σ_orig)² + ( f*intensity)² )
```
  The goal is to obtain a flat χ² distribution. Use automsa to determine an optimal value.
- merge
  Do merge the reflections.
- noaddfriedel
  Do not treat the dataset as an inversion twin. See addfriedel.
- noinvert
  Enter a list of batch numbers. Reflection indices for members of this list will not be inverted. See invert.
- nomerge
  Do not merge the reflections. This can be useful in combination with omitsingle to remove single reflections if overlapping equivalents exist.
- omitsingle on/off
  if on: omit single reflections if overlaps are available.
  This can be useful in combination with merge to remove single reflections if overlapping equivalents exist.
- pg s
  Set pointgroup to s. See above for a list of pointgroups.
- reject f
  Reject reflections with |Δ_i|/σ_i > f. (Δ_i = I_i-I_mean). Use a negative value to unreject.
  - For every set of equivalent reflections, the average intensity I_mean is calculated (using WeightInt).
  - Then for every reflection within this set calculate |Δ_i|/σ_i.
  - If the largest Δ/σ is greater than f, that specific reflection is rejected.
  - The same set of equivalents is then re-evaluated.
  Use listreject to get a list of rejected reflections.
- resultsig n
  What final sigma to use. The default is 3.
- rsym
  Calculate Rsym
- status
  Print program status
- weightint n
  Specify weightscheme for Intensity merging. The default is 3.
- weightsig n
  Specify weight scheme for sigma merging. The default is 3.
- write s
  Write merged reflections to file s
You should at last use the write command to create the file with the merged reflections
You may specify the answers to the initial questions and succeeding commands on the commandline. Use a · (dot) to accept the proposed default.
Examples:
```
mergehklf5 p212121 . . . . . .  .   .   shelx.hklf5 write merged.hkl exit
mergehklf5 p212121 3 3 2 2 3 no yes yes shelx.hklf5 write merged.hkl exit
```

Final Notes

Disclaimer: you use mergehklf5 freely, but at your own responsibility completely.

Please do report failures, give comments and ask questions, preferable via e-mail. We will help you as much as possible.
Email: m.lutz@uu.nl or a.m.m.schreurs@uu.nl.
Postal address: Laboratory for Crystal and Structural Chemistry, Bijvoet Center for Biomolecular Research, Padualaan 8, NL-3584 CH Utrecht, The Netherlands.