Previous: format of ".rmat" files for unit cell orientation and transformation matrices
Next: When to recalibrate what?

Calibrating a KappaCCD detector

This is a complete procedure, used in the factory in Delft, to calibrate a detector starting from scratch. This may also be used to partly re-calibrate a detector in the field.

The program autocal performs the steps 1 (if allowed) and 4 through the end of this procedure (it will skip the visualisation bits, so it will slightly more sensitive to abberations than going through all steps manually). Just start "autocal" from an empty directory in your own area (i.e. NOT in the calibration directory itself) with ample disk space available (a normal KappaCCD calibration will take about 650MB). But: please read the manual first.

In most places, the example commands in this manual use detector 9986 as detector number. Please use your own detector number in its place.

If you do not have it yet, create global calibration directories for your detector. It might be necessary to do this as "root":
```
mkdir /usr/local/calibration/9986
mkdir /usr/local/hklint/9986
    
```
```
chmod 755 /usr/local/calibration/9986
chown ccd /usr/local/calibration/9986
chmod 755 /usr/local/hklint/9986
chown ccd /usr/local/hklint/9986
    
```
If the calibration directory is not owned by ccd, calibration files will have to be moved there by "root" in later stages.
If your detector is a 135mm detector (protein applications), the detector number should be suffixed with "BU" if you are using it in unbinned mode, and with "BB" if you are using it in binned mode.
Create an empty directory e.g. called "calib", or if you have more than one detector, create a directory with the detector number in the name.
```
cd /diska
mkdir 9986
cd 9986
    
```
If you have more than one system in your lab, select the right KappaCCD Server using the CCD_HOSTNAME environment variable.
```
setenv CCD_HOSTNAME 192.168.17.53
    
```
or, on "bourne" shell systems:
```
    CCD_HOSTNAME=192.168.17.53
    export CCD_HOSTNAME
    
```
If you have only one system, just make sure that the ccdhostname configuration parameter is correctly set.
At this moment, you can choose to run the fully automatic calibration procedure "autocal", or continue using the manual procedure outlined here.
In the calibration directory make a directory called "distortion", and go in there.
```
mkdir distortion
cd distortion
    
```
Get the so-called grid file. You should either have a "grid<detid>.kcd" file somewhere, or a file named "flm-4-1.spe".
```
cp /mnt/zip/flm-4-1.spe .
    
```
If you have "flm-4-1.spe", and are using detector in "binned" mode (all 65mm detectors are used in binned mode), turn it into a binned kcd image using the "imagebin" program. Call the result "grid<detid>.kcd" (put your own detector ID on the right spot). If you are running an unbinned detector, you can use the ".spe" image unchanged.
```
imagebin flm-4-1.spe write=grid9986.kcd
    
```
run
```
ndisp nofilters grid9986.kcd
    
```
In the "Options" menu, select "3-97% scaling".
See whether the image looks OK. If the grid is severely rotated, please keep this in mind when going through the next steps.
run the "makedistor" procedure for Nonius software.
```
makedistor grid9986.kcd
    
```
For a 65mm detector, this should locate more than 6000 peaks (likely between 6400 and 6500). If it finds less peaks, the contrast might be too small or there might be another difficulty with the image. It might be a good idea to ask Nonius for help. If it finds almost no peaks, and you did see that the image was rotated, try to specify the approximate rotation angle you saw earlier as a command line option:
```
makedistor grid9986.kcd rotation=-15
    
```
If the number of the detector is not apparent from the name of the grid file, the program will prompt you for the detector id.
Study the output of the "makedistor" program. RMS error should not be higher than 0.1 for a 65mm detector or 0.2 for a 95mm detector. If it comes out higher, contact Nonius for a double-check.
copy the "distorpol.vic" file to /usr/local/calibration/<detid>
```
cp distorpol.vic /usr/local/calibration/9986
    
```
If desired, run the "makedistor" procedure for Denzo.
```
makedistor denzo grid9986.kcd
    
```
If you needed to specify a rotation on the command line before, do it again here.
Copy the resulting "ndef.cal" file to the calibration directory. Make sure not to overwrite the "def.cal" file as it was delivered with the system!
```
cp ndef.cal /usr/local/calibration/9986/ndef.cal
cp ndef.cal /usr/local/hklint/9986/def.cal
    
```
Mount an AMBI crystal. Make sure it is very well centered.
Test the microscope image transfer:
```
microscopetest
    
```
When you are satisfied, press the "Quit" button (you may need to press it for a second or so before it reacts).
Perform the dx calibration in a new directory "dx".
```
cd ..
mkdir dx
cd dx
caldx make
    
```
and follow the instructions.
Go up, and make a new directory "theta". Go in there.
```
cd ..
mkdir theta
cd theta
    
```
Copy the "detalign.vic" file from the "dx" directory.
```
cp ../dx/detalign.vic detalign.vic
    
```
If no "detalign.vic" file exists in the "dx" directory, that is OK too.
Run the program "caltheta".
```
caltheta make
    
```
Calibrate the "theta zero" of the machine following the instructions.
Go up, and make a new directory "kappa". Go in there.
```
cd ..
mkdir kappa
cd kappa
    
```
Copy the "detalign.vic" file from the "dx" directory.
```
cp ../dx/detalign.vic detalign.vic
    
```
If no "detalign.vic" file exists in the "dx" directory, that is OK too.
Run the program "calkappa".
```
calkappa make
    
```
Calibrate the "kappa zero" of the machine following the instructions.
Go up, and make a new directory "alignment". Go in there.
```
cd ..
mkdir alignment
cd alignment
    
```
Run
```
 
makedetalign make 
    
```
This collects 180 images in about 45 minutes. After collecting the images, it does a peak-search on all images and tries to find all quadruplets of identical reflections. Please ignore any warnings about "no suitable short exposure dark image" and "no suitable frozen dark image"; the dark current calibration will be done later.
The program should find between 500 and 1000 quadruplets. If it does not get enough quadruplets, load one of the collected images into ndisp
```
ndisp s01f001.kcd
    
```
Activate the "Primary Beam" (under "Tools"), and check whether the beam stop you can see is in the proper location. If it is not, position your mouse cursor where you think the primary beam sits. Then look in the status window for the "mmx" and "mmy" values. Now edit the file "detalign.vic" and add the "mmx" value to "DETZEROY" and the "mmy" value to "DETZEROZ". Exit ndisp and restart it to see whether the beam stop is now in the proper place. Finally, restart the analysis:
```
makedetalign
    
```

Copy the file "detalign.vic" to /usr/local/calibration/<detid>

cp detalign.vic /usr/local/calibration/9986/detalign.vic

If desired, make a "def.site" file for the HKL software. Copy it to the calibration directory.
```
makedefsite
cp def.site /usr/local/hklint/9986/def.site
    
```
Go up, and make a new directory "ambi". Go in there.
```
cd ..
mkdir ambi
cd ambi
    
```
Run the program "makeambi" to collect 2*90 standard images plus some dark images for later reference. This should take about 3 hours.
```
makeambi
    
```
If you have "dirax" installed, some "phi/chi" data will need to be collected now. Go up, and make a new directory "cell". Go in there.
```
cd ..
mkdir cell
cd cell
    
```
Use a "phi/chi" experiment, and the "dirax" program to find a unit cell. Save it as "i.rmat".
```
phichi make
cp phichi.rmat i.rmat
    
```
Note: the autocal procedure will do this step only if the "dirax" program is installed. It will otherwise use the "denzo" program to obtain the unit cell using "denzoindex" from the "alignment" data.
If you are using an AMBI crystal with Cu radiation (e.g. on a protein diffraction system), please specify the additional option "frameangle=15" to make sure sufficient reflections are found for indexing.
Go up, and make a new directory "spoton". Go in there.
```
cd ..
mkdir spoton
cd spoton
    
```
Copy the ambi unit cell information to the current directory.
```
cp ../cell/i.rmat .
    
```
Make sure your theta can move from -20 to +30 degrees in theta at least (better -30 to +50), and then run:
```
spoton make
    
```
This will make 2 times 40 images (at dx=30 and dx=120mm).
The procedure will try to measure a single high-intensity reflection at different positions on the detector to make a last intensity calibration. To be able to do this at low dx, a considerable freedom in theta swing is required. Especially at negative theta, this range is normally restricted.
If no suitable reflection can be found, this can be due to this theta restriction. The best thing to do would be to move the low theta limit in the server (under goniometer setup) from the default value of -10 to somewhere around -35 degrees, open the radiation safety enclosure, test the negative theta range manually to make sure there are no other obstructions, and provide for another way to ensure radiation safety. If all of that has been done, the machine can be put in open beam mode, and the "spoton" program will probably continue without problems.
Go up, and make a new directory "respons". Go in there.
```
cd ..
mkdir respons
cd respons
    
```
Get the fluorescent sample ready. Mount it on a goniometer head. [don't worry about the exact position yet, the "makesensi" program will give you exact instructions on how it should be mounted.] Make sure the detector can move theta to 51 degrees (not only by changing the theta limit, but also by carefully moving there with dx=150 to check whether nothing is in the way).
Run the makesensi program, and follow the instructions exactly. do not run this with the machine in open-beam mode. The measurement will take about 6 hours (very dependent on the beam intensity). If you want old-style transmission images as well, specify the optional "transmission" keyword.
```
makesensi make 
    
```
or if you need a new denzo calibration to be performed by HKL Inc:
```
makesensi make transmission
    
```
Please note that the "transmission" measurement require access to theta=-22.5 degrees; that position is not always reachable.
Run
```
ndisp nofilters responsMO.kcd
    
```
Check whether this looks reasonable. Unreliable/unusable pixels will have an intensity 0, other pixels should have values higher than 8000: low in the center and higher at the edges. It is easiest to see in "linear" scaling, with "3-97% median scaling" selected under options.

Copy the responsMO.kcd file to /usr/local/calibration/<detid>

cp responsMO.kcd /usr/local/calibration/9986/responsMO.kcd

Go up, and make a new directory "dark". Go in there.
```
cd ..
mkdir dark
cd dark
    
```
Make a symbolic link to the file "ffdark.kcd" from the "respons" directory to the current directory.
```
ln -s ../respons/ffdark.kcd .
    
```
Run the dark current calibration. This will use the existing ffdark image, and create some quick short exposure dark images. If desired, "caldark" can be instructed to perform the standard zinger measurement using the "makezing" option.
```
caldark makeshort makezing
    
```
Copy the "*_frozen" and "badpixel.*" files to /usr/local/calibration/<detid>
```
cp *_frozen badpixel.* /usr/local/calibration/9986/
    
```
Go to the "spoton" directory, and run "spoton-integrate",
```
cd ../spoton
spoton-integrate 
    
```
After the "near" set, the program will display some statistics on the results. The "incidence coefficient" should be about 0.3-0.5 for Mo radiation or between -0.3 and -0.5 for Cu. This should explain more than 90% of the variance. And the residual uncertainty should be 0.025 or less.

Copy the file "XX-incidence.coefficient" to the calibration directory,

cp MO-incidence.coefficient /usr/local/calibration/9986/MO-incidence.coefficient

If desired, you can now make a "sensitivity file" for denzo.
Go to the "respons" directory, and run the "respons2sensi" program:
```
cd ../respons
respons2sensi responsMO.kcd write=sensi9986.kcd
    
```
Copy the resulting sensi9986.kcd file to the calibration directory.
```
cp sensi9986.kcd /usr/local/hklint/9986/sensi9986.kcd
    
```

Go to the "ambi" directory, and integrate the standard data set. Check whether everything goes to plan.

cd ../ambi
cp ../cell/i.rmat i.rmat
nprocess nogui i.rmat together=30 *_0??.kcd *t0??.kcd
makescalein nogui prefix=scale_all *.x
makescalein nogui prefix=scale_zero *_0??.x
tail -25 scale_zero.log

Previous: format of ".rmat" files for unit cell orientation and transformation matrices
Next: When to recalibrate what?