Content:


Introduction

Different beamlines might require specific settings whenever the image header doesn't contain a full description of the experimental setup. The main items often missing from image headers are

  • beam centre convention
  • sense of rotation for axes
  • descriptions of multi-axis setups

These might even change for a given beamline with time or when modifying the beamline setup.

Here we want to collect information about specific beamlines to help you getting started when processing datasets with autoPROC. However, it is still required to double-check those settings - eg. with the best dataset from a specific shift. Ideally, you would want to write a macro for a particular beamline so that one could run eg.

% process -M XYZ-123 ...

for all datasets collected at beamline 123 of synchrotron XYZ.

If you have information about beamlines not covered here (or with changed settings), please let us know at proc-develop@globalphasing.com. Even better: if beamline staff could provide us with some example dataset whenever a significant change in beamline configuration occurs (or place any example/calibration dataset on some publicly accessible site for us to pick up).

If no arguments are given in the table below, then autoPROC should work right out-of-the box (given the example datasets we had access to). If there are updates or different experiences - please let us know (proc-develop@globalphasing.com)!

Synchrotron Beamline Date (YYYYMMDD) Arguments to process Remark
ALBA XALOC - BL13 20121120 Pilatus 6M
ALS 4.2.2 20110929 ReversePhi="yes" NOIR-1 detector
20160211 to be determined RDI CMOS_8M detector
5.0.1 20031212 BeamCentreFrom=header:x,-y autoPROC_TwoThetaAxis="-1 0 0" ADSC Q4 (S/N 402)
5.0.2 20110424 BeamCentreFrom=header:x,-y
20130111 BeamCentreFrom=header:y,x
20170429 Pilatus3 6M, S/N 60-0131
8.2.1 20110908 BeamCentreFrom=header:x,-y autoPROC_TwoThetaAxis="-1 0 0" For older ADSC Q210 detector (S/N 445)
20140115 BeamCentreFrom=header:y,x For newer ADSC detector (S/N 905)
8.2.2 20121017 BeamCentreFrom=header:y,x
20071004 BeamCentreFrom=header:x,-y detector (S/N 905)
8.3.1 20121219 BeamCentreFrom=header:x,-y autoPROC_TwoThetaAxis="-1 0 0" (or: –M Als831) see Note 3 and here
12.3.1 20121205 BeamCentreFrom=header:x,-y autoPROC_TwoThetaAxis="-1 0 0" (or: –M Als1231) see Note 3
APS 14-BM-C 20081014 ReversePhi=yes ADSC QUANTUM 315, S/N 910
17-ID / IMCA-CAT 20100121 autoPROC_TwoThetaAxis="-1 0 0"
19-ID 20101210 ReversePhi=yes beam="1570 1491" ADSC QUANTUM 315R; see Note 1
20110609, 20130727, 20140602 ReversePhi=yes beam="1577 1496" ADSC QUANTUM 315R (S/N 458); see Note 1
20150209 ReversePhi=yes beam="1584 1497" ADSC QUANTUM 315R (S/N 458); see Note 1
20160317 ReversePhi=yes Dectris PILATUS3 6M, S/N 60-0132
19-BM 20081210 ReversePhi=yes beam="1579 1520" SBC-3 detector; see Note 1
20090406 beam="1052 1003" ADSC QUANTUM 210R, binned; see Note 1
21-ID-D 20130423 MarCCD, S/N 023
20160310 see here Eiger 9M
21-ID-F 20080725 beam="1521 1526" see Note 1
20130310 MarCCD, S/N 019
21-ID-G 20130209 MarCCD, S/N 025
23-ID-B 20081011
23-ID-D 20071025
24-ID 20081010 BeamCentreFrom=header:x,-y ADSC QUANTUM 315, S/N 911
Australian Synchrotron MX1 20130909, 20170401 BeamCentreFrom=header:y,x ReversePhi=yes ADSC QUANTUM 210, S/N 457
MX2 20171009 see here for details Eiger 16M, E-32-0106
20130909 BeamCentreFrom=header:y,x ReversePhi=yes ADSC QUANTUM 315 928, S/N; very old images have no date in image header
Bessy 14.1 20121120 MarCCD detector (MX-225)
201301 ? PILATUS 6M
14.2 20121120 MarCCD detector (MX-225)
201412 ? PILATUS 2M
14.3 201301 ? MarCCD detector (MX-225)
CLSI 08ID-1 20110920
Diamond Light Source I04 20171114 "–M DiamondI04" (to define SmarGon setup correctly)
I24 20170526 autoPROC_XdsKeyword_ROTATION_AXIS="0 -1 0"
Elettra XRD1 20150505 Pilatus 2M (24-0103)
ESRF BM-14 20070909 BeamCentreFrom=header:y,x MarCCD detector storing beam-centre in mm instead of standard pixels (automatically adjusted within autoPROC)
ID14-1 20070821 ADSC, S/N 444
ID14-4 20121206 BeamCentreFrom=header:y,x
ID29 M EsrfId29
MASSIF-3 (ID30A-3) 20160307 see here Eiger 4M
LNLS MX2 09/2016 - 11/2016 see Note 5 for Pilatus-2M specifics Dectris Pilatus 2M, S/N 24-0109
20170328 ReversePhi=yes autoPROC_Img2Xds_DamagedPixels="104,1624 473,144" see also Note 5 for Pilatus-2M specifics; Dectris Pilatus 2M, S/N 24-0109; thanks to A. Nascimento for test data
NSLS/BNL X25 20110319 Some older datasets have distance stored as mm when it should be m
X26C 20130422 BeamCentreFrom=header:y,x
Photon Factory BL-1A 20160309 see here Eiger 4M
BL-17A 20111209 BeamCentreFrom=header:y,x
SLS PX-I/X06SA Pilatus 6M
20160307 see here Eiger 16M
PX-II/X10SA
PX-III/X06DA M SlsPXIII Pilatus 2M with PRIGo goniometer
Soleil Proxima1 20110630 BeamCentreFrom=header:y,x ADSC S/N 927
20111027 M SoleilProxima1 Pilatus 6M detector
20170622 pixels in module gaps wrongly marked as "0" and not "-1" see Note 5 for Pilatus-6M specifics
Proxima2 20131004 BeamCentreFrom=header:y,x ADSC S/N 927
20160314 see here Eiger 9M
20170705
SPring-8 all MX beamlines 20160510 ReversePhi=yes (Thanks to Keitaro Yamashita)
SSRF BL17U-1 20151229 (Thanks to Qingjun Ma)
BL19U-1 20151229 ReversePhi=yes (Thanks to Qingjun Ma)
SSRL all see Note 2
BL7-1 see Note 4
 
 

As mentioned above: please let us know of beamlines not covered or any problems with data from a specific beamline at proc-develop@globalphasing.com!

Note 1

The image header unnecessarily contains wrong information about the beam centre. It is not just a question of coordinate system convention (which could be dealt with using the BeamCentreFrom=header:X,Y system), but the actual values are wrong. The beamline provides a so-called def.site file for HKL-3000 that contains the correct beam centre - but the image headers are left with incorrect values.

The fact that the image header content is not updated makes it more difficult to process datasets with other programs than HKL-3000, thus giving the wrong impression that data can only be processed successfully with a single program. Furthermore, the date recorded in those def.site files is wrong most of the time - probably because those files are edited by hand. So a file like http://www.sbc.anl.gov/hklint/19ID/19ID_Q315r_2011_01/def.site requires a bit of detective work:

        6/21/2012 11:38 AM         2390 def.site
  • so the file was last saved in that location on 21st June 2012 - although the file itself contains the misleading information
        {last_saved,date} {14:36:40 Oct 09, 2009}
  • (update July 2014) nothing has changed there: the file http://www.sbc.anl.gov/calibration/19ID/Hkl3000/19ID_Q315r_2014_02/def.site still shows the wrong date (as before 14:36:40 Oct 09, 2009) and the beam centre in the image headers is still completely wrong ...
  • (update December 2015) improvement: at least the date recorded in the site.def file seems now correct

If you have access to the def.site file, you can try and take the values given in there (usually in mm)

% grep "[xy]beam" def.site

together with the pixel size from running imginfo on an example image to get the beam centre (in pixels) for running autoPROC. For the above example this would give you a beam centre of (1496.09,1576.66) when the image header has (1541.016,1564.453) - which is wrong no matter what coordinate convention one uses.

Remember that the X- and Y-coordinates obtained from a def.site file often need to be swapped to go from HKL/Denzo convention to autoPROC/XDS convention.

Some resources for def.site files:

Unfortunately, often these files with correct information at the time of data collection are no longer available. In that case, the option BeamCentreFrom=getbeam:refined could be used as a last resort - or finding a dataset that did process correctly from the same session and use those values. Needless to say, manual inspection of the predictions is essential here.

Of course, the correct solution to this problem would be for the beamline control software to write correct beam centre values into the header in the first place! Especially since exactly that information seems to be available for writing those def.site files - and not writing it to the actual experimental results (images) seems rather odd. This would make it much easier to process data from these beamlines with more than just one software package.

Note 2

All data available to us for SSRL beamlines shows the same characteristics:

  • beam centre in header is mid-point of image
  • final direct beam centre from processing datasets confirms that this is correct

So no special keyword is required - nice! Some details (using datasets from the JCSG repository:

ssrl4-11_1
 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 10 Apr 2008 - 26 May 2011  
 <beamx,beamy> = 2047 2050   from 48 datasets

ssrl4-9_2
 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 17 Jan 2009 - 22 Apr 2011
 <beamx,beamy> = 2047 2047   from 78 datasets

ssrl4-12-2
 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 08 May 2009
 <beamx,beamy> = 2050 2049   from 6 datasets

ssrl1-9_2
 Beam centre in X            [pixel] = 1535.267
 Beam centre in Y            [pixel] = 1535.267
 <beamx,beamy> = 1534 1536   from 41 datasets

ssrl2-11_1
 Beam centre in X            [pixel] = 1535.267
 Beam centre in Y            [pixel] = 1535.267
 <beamx,beamy> = 1535 1536   from 16 datasets

 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 18 Jan 2007 - 10 Mar 2007
 <beamx,beamy> = 2048 2050   from 7 datasets

ssrl3-11_1
 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 07 Apr 2007 - 01 Feb 2008
 <beamx,beamy> = 2049 2051   from 16 datasets

ssrl2-9_2
 Beam centre in X            [pixel] = 2047.992
 Beam centre in Y            [pixel] = 2047.992
 29 Apr 2006 - 16 Mar 2007
 <beamx,beamy> = 2049 2048   from 7 datasets

ssrl1-11_1
 Beam centre in X            [pixel] = 1535.267
 Beam centre in Y            [pixel] = 1535.267
 <beamx,beamy> = 1536 1535   from 40 datasets

ssrl1-9_1
 Beam centre in X            [pixel] = 1535.267
 Beam centre in Y            [pixel] = 1535.267
 <beamx,beamy> = 1535 1538   from 10 datasets

Note 3

The beam centre in the image header is given including the 2-theta offset. In order to get the beam-centre at datum position, one needs to calculate backwards using a wrapper to our imginfo program: this is provided by using those macro definitions within autoPROC.

Thanks to James Holton for confirmation and providing further details regarding ALS beamlines.

Note 4

According to documentation the beamline should be equipped with a "Huber Kappa-geometry goniometer", but image headers for ADSC detector 902 only store Phi angle (missing Omega and Kappa values). Also: no date information is stored in the header.

Note 5

If the pixels within module gaps of Pilatus/Eiger detectors are not correctly marked (e.g. they have a value of "0" instead of a negative value), use the appropriate setting below:

  • Eiger16M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 4151 514 552 |0 4151 1065 1103 |0 4151 1616 1654 |0 4151 2167 2205 |0 4151 2718 2756 |0 4151 3269 3307 |0 4151 3820 3858 |1030 1041 0 4372 |2070 2081 0 4372 |3110 3121 0 4372" ...
  • Eiger1M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 1031 514 552" ...
  • Eiger4M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 2071 514 552 |0 2071 1065 1103 |0 2071 1616 1654 |1030 1041 0 2168" ...
  • Eiger9M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 3111 514 552 |0 3111 1065 1103 |0 3111 1616 1654 |0 3111 2167 2205 |0 3111 2718 2756 |1030 1041 0 3270 |2070 2081 0 3270" ...
  • Pilatus12M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 2464 195 213 |0 2464 407 425 |0 2464 619 637 |0 2464 831 849 |0 2464 1043 1061 |0 2464 1255 1273 |0 2464 1467 1485 |0 2464 1679 1697 |0 2464 1891 1909 |0 2464 2103 2121 |0 2464 2315 2333 |0 2464 2527 2545 |0 2464 2739 2757 |0 2464 2951 2969 |0 2464 3163 3181 |0 2464 3375 3393 |0 2464 3587 3605 |0 2464 3799 3817 |0 2464 4011 4029 |0 2464 4223 4241 |0 2464 4435 4453 |0 2464 4647 4665 |0 2464 4859 4877 |487 495 0 5072 |981 989 0 5072 |1475 1483 0 5072 |1969 1977 0 5072" ...
  • Pilatus1M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 982 195 213 |0 982 407 425 |0 982 619 637 |0 982 831 849 |487 495 0 1044" ...
  • Pilatus200K
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 488 195 213" ...
  • Pilatus2M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 1476 195 213 |0 1476 407 425 |0 1476 619 637 |0 1476 831 849 |0 1476 1043 1061 |0 1476 1255 1273 |0 1476 1467 1485 |487 495 0 1680 |981 989 0 1680" ...
  • Pilatus300K
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 488 195 213 |0 488 407 425" ...
  • Pilatus6M
      process autoPROC_XdsKeyword_UNTRUSTED_RECTANGLE="0 2464 195 213 |0 2464 407 425 |0 2464 619 637 |0 2464 831 849 |0 2464 1043 1061 |0 2464 1255 1273 |0 2464 1467 1485 |0 2464 1679 1697 |0 2464 1891 1909 |0 2464 2103 2121 |0 2464 2315 2333 |487 495 0 2528 |981 989 0 2528 |1475 1483 0 2528 |1969 1977 0 2528" ...

This should be automatised in autoPROC releases after 20171114.


Resources for XDS geometric correction files (Pilatus detector)

            78507e20a893b0cd280320a6d9a6467b  x_geo_corr.cbf
            d74423e8c78eef05985a8a1b98de5e6c  y_geo_corr.cbf

We don't guarantee that these are up-to-date or adequate for your particular dataset. Unfortunately, not all beamlines make these detector-specific calibration files easily accessible.