Cxi02416 calibration

Calibration of cspad using cxi02416, cctbx.xfel and DIALS

This page is not intended as a manual for processing XFEL data using cctbx.xfel and DIALS. Rather, this is a documentation of steps taken to calibrate the CSPAD using data collected at CXI in February 2016, on detector Ds2.

Program names are highlighted in bold. Generally, help can be obtained using -h or -c options to the program at the command line.

In this walkthrough, we will be calibrating the tile positions of the CSPAD detector at the CXI endstation at LCLS. We will be using a calibration dataset collected by CXI staff in February 2016, during calibration experiment cxi02614. The procedure is to index the images, refine the tile positions minimizing the difference between observed and calculated Bragg reflections, re-index the images, re-refine the tile positions, and repeat until convergence. At each step of the way, we will label our current metrology with a version number, starting at version 0:

Metrology version	Description
Version 0 (v0)	Initial metrology deployed by beamline operators. The tile positions are measured using an optical microscope, but as the quadrants can move independently, they are not correctly aligned in relation to each other or to the beam center.
Version 1(v1)	After collecting some data, powder rings can be seen after averaging the events in a run. Several tools are available for aligning the quadrants by eye or automatically using powder rings.
Version 2 (v2)	After indexing the images using v1, we will refine the tile positions to produce metrology v2.
Version 3 (v3)	After re-indexing the images using v1, we will re-refine the tile positions to produce metrology v3.
...	And so forth until convergence

We start with this known information provided by the beamline operators:

• Data is contained in runs 2-16
• Detector address: CxiDs2.0:Cspad.0. This string identifies the front CSPAD detector in the XTC streams.
• detz_offset (IE the distance from the sample position to the back of the detector rail): 568 mm.

Aligning quadrant positions (v1)

Alignment of quadrant positions using powder rings can be done manually using cctbx.xfel or LCLS's calibman tool [1]. ctbx.xfel also provides an automatic algorithm for quadrant alignment, provided powder rings of sufficient quality. For cxi02416, the beamline operators already calibrated quadrant positions to a point where indexing can proceed. Regardless, if needed, here is how to accomplish the same task using cctbx.xfel

Averaging diffraction data to create powder patterns

The cctbx.xfel program cxi.mpi_average is used to create averages:

 for i in `seq 2 16`; do bsub -n 12 -q psanaq -o avg_r$i.log \
   cxi.mpi_average -x cxi02416 -r $i -a CxiDs2.0:Cspad.0 -d 568 -o . -v; done

For each of the runs with data (2-16), this command submits an averaging job using 12 processors, providing information about the experiment such as detector address and detz_offset in the form of command line arguments.

Progress can be monitored with the command bjobs.

When the averages are complete, they will consist of files named cxi02416_avg-r0002.cbf, cxi02416_stddev-r0002.cbf, and cxi02416_max-r0002.cbf for each run, representing the average, standard deviation, and maximum of all the pixel data in each of the runs. Display the data using cctbx.image_viewer:

 cctbx.image_viewer *.cbf

Manual calibration using cctbx.xfel

Typically the best powder rings come from the maximum projection (example: cxi02416_max-r0013.cbf).

Initial indexing

The initial metrology deployed by the beamline operator is sufficient to get initial indexing results. Indexing in cctbx.xfel typically is done in a series of trials. By this point, I had done two trials of indexing (trials 0 and 1), working out some spotfinding parameters. We join this walkthrough at trial 2.

With this information, and this phil file, we can index the data:

 for i in `seq 2 16`; do cxi.mpi_submit input.experiment=cxi02416 \
   output.output_dir=/reg/d/psdm/cxi/cxi02416/ftc/brewster/dials \
   mp.nproc=36 mp.queue=psanaq output.split_logs=True \
   input.dispatcher=cctbx.xfel.xtc_process \
   input.target=cxi02416-lyso-t002.phil input.trial=2 \
   input.run_num=$i; done

This command submits jobs for runs 2 through 16, using the DIALS backend of cctbx.xfel. After indexing is completed, we got 4920 indexed images, as can be shown by this command:

 cd /reg/d/psdm/cxi/cxi02416/ftc/brewster/dials
 ls r0*/002/out/*.json | wc -l

Refine metrology (v2)

Let's call the metrology deployed by the beamline operator version 0 (v0). After quadrant alignment, the operators updated the metrology to version 1 (v1). The following command will do an iterative joint hierarchical refinement of the components of the CSPAD detector. The new tile positions we call version 2 (v2).

 bsub -q psanaq -o t002_1k.out cspad.cbf_metrology tag=t002_1k \
   cxi02416-refine.phil reflections=indexed ../r0*/002/out \
   n_subset=1000 split_dataset=True

The program first aggregates the requested number of images into a single dataset. Then, it refines the detector as a whole (including Z position and tilt). Using the new detector position, it refines the quadrants independently from each other, and then the 2x1 sensors, and then the individual panels. Finally, it converts the DIALS format metrology into the SLAC file format (0-end.data).

Here, I've asked it to pick 1000 images at random to refine using this phil file. split_dataset=True means the refinement is done twice independently, using odd numbered or even numbered images, each time using 1000 images. This will be useful later for evaluating the accuracy of the metrology. The output files will be named t002_1k*, set by the tag parameter. Finally, indexing produces two sets of reflection files, bright indexed reflections, and final integrated reflections (can include weak intensities). Here, I've chosen to refine only against the bright, indexed reflections by using reflections=indexed.

Visualize tile shifts

In order to get a sense of the magnitude of the shifts in panel position after refinement, use the program cxi.display_metrology. For example, the original detector geometry can be displayed thusly:

 cxi.display_metrology \
   /reg/d/psdm/cxi/cxi02416/calib/CsPad::CalibV1/CxiDs2.0:Cspad.0/geometry/0-end.data

Compare it to the refined geometry:

 cxi.display_metrology 0-end.data.t002_1k_1

You will see a small change in the origin (center arrow) and obvious changes in the quadrant positions. The relative positions of the sensors to each other will not change a large amount, though if you inspect the files themselves you will see changes.

Another tool that is useful for evaluating changes in metrology is dev.dials.plot_detector_shifts. This program will plot detector shifts in the X and Y directions (also known as the fast and slow directions, a convention referring to how data is read from the byte arrays stored on disk). It will also plot shifts along the Z axis, I.E., the detector's normal axis. Let's use it to compare the unrefined geometry to the geometry refined at level 2 (I.E. at the level of the 2x1 sensors):

 dev.dials.plot_detector_shifts t002_1k_1_combined_experiments.json \
   t002_1k_1_refined_experiments_level2.json \
   plot_type=spherical_polar tag=v1v2level2
 display v1v2level2*.png

Use the spacebar to cycle between the images. The pixels are mapped to the Ewald sphere and then displayed as a function of azimuthal and elevation angles along the Ewald sphere, which distorts the detector appearance but is independent of any detector layout. The colorbar scales will show the magnitude of panel shifts.

Try running the program using t002_1k_1_refined_experiments_level0.json to see how much the detector as a whole shifted, or t002_1k_1_refined_experiments_level1.json to see shifts in the quadrants.

Index using v2 metrology

In order to improve our metrology we will re-index using the new tile positions. We assume we don't have write access to the geometry file for this detector, namely /reg/d/psdm/cxi/cxi02416/calib/CsPad::CalibV1/CxiDs2.0:Cspad.0/geometry/0-end.data. To that end, we need a copy of the calibration directory for the experiment so we can modify it:

 cd <a subfolder in your home directory>
 mkdir -p cxi02416/calib
 cd cxi02416/calib
 cp -r /reg/d/psdm/cxi/cxi02416/calib/* .

Now, we can link in v2, backing up v1 first:

 cd CsPad::CalibV1/CxiDs2.0:Cspad.0/geometry
 mv 0-end.data 0-end.data.v1
 ln -fns <path to 0-end.data.t002_1k_1> 0-end.data

We optionally use softlinks here to avoid duplicating data. We can now reprocess the data as trial 3:

 for i in `seq 2 16`; do cxi.mpi_submit input.experiment=cxi02416 \
   output.output_dir=/reg/d/psdm/cxi/cxi02416/ftc/brewster/dials \
   mp.nproc=36 mp.queue=psanaq output.split_logs=True \
   input.dispatcher=cctbx.xfel.xtc_process \
   input.target=cxi02416/lyso-t003.phil input.trial=3 input.run_num=$i \
   input.cfg=cxi02416-calibdir.cfg; done

The input phil file is the same as before. However, to instruct psana to use the modified calibration directory, we add a psana config file named cxi02416-calibdir.cfg with these lines:

 [psana]
 calib-dir = <a subfolder in your home directory>/cxi02416/calib

If you have write permissions to your geometry folder, you don't need to use this config file or make a copy of your calibration directory. We recommend saving the original metrology like we did in the above example, by renaming it to 0-end.data.v1, so you can return to it as needed.

Indexing with the new metrology yielded 5484 indexed images.

Refine metrology (v3)

We now refine the metrology generated from the indexed images from trial 3 and call it metrology version 3 (v3). The command is otherwise the same, with an updated tag. We also increase the number images used to 2000.

 bsub -q psanaq -o t003_1k.out cspad.cbf_metrology tag=t003_1k \
   cxi02416-refine.phil reflections=indexed ../r0*/003/out \
   n_subset=2000 split_dataset=True

After refinement we can compare the new tile positions to those of v1.

 cxi.display_metrology 0-end.data.t002_1k_1 &
 cxi.display_metrology 0-end.data.t003_2k_1 &

Use cxi.display_metrology and dev.dials.plot_detector_shifts to evaluate how much the tile moved during this refinement. They moved a lot less between v2 and v3 then they did between v1 and v2.

Evaluate metrology

Iterative hierarchical joint refinement should proceed until convergence, meaning until rounds of indexing and refinement do not improve the model. cxi.display_metrology and dev.dials.plot_detector_shfits visually measure the magnitude of changes during refinement. An additional tool is available, cspad.detector_statistics, that can be used to evaluate the precision of refinement, and the state of the cspad after refinement.

 cspad.detector_statistics tag=t003_2k

Warning, this dumps a lot of output. The program examines the current directory for files from cspad.cbf_metrology. For each hierarchy level 0-3, the program creates two tables of statistics:

1) Detector precision. The two half datasets from each level of refinement are compared to each other, and agreement between the two independent refinement runs is reported.

2) Detector statistics. Using the two half datasets as independent measurements, statistics about the cspad are reported, such as normal vector tilts and XYZ offsets. Weighted means and standard deviations are reported as well, and can also be used to estimate the overall precision of refinement.

For this walkthrough, we will extract a few statistics only. Look for the third set of tables, delineated with

 ********************************************************************************
 Showing statistics for detector at level 2 (sensors, I.E. 2x1s)
 ********************************************************************************

In the second table, under Detector statistics, a few of the columns are reproduced here (click expand to show the table):

Panel group ID	Radial Dist (mm)	Fast Offset sigma (microns)	Slow offset sigma (microns)	N reflections
1	21.8	2.3	0.7	7585
9	23.4	2	1.9	7411
25	24.5	1.6	1.7	7211
17	26	0.3	1.1	7182
0	40.7	4.4	3.4	6429
8	41.1	0.3	1.5	6522
24	43.7	2.1	3.4	6733
16	44.3	3.1	2.5	6576
7	55.3	0.7	2.4	6048
31	57.5	0.7	0.4	5774
15	57.8	5	0.9	5763
23	59.7	2.6	1.9	5924
11	71.9	3.3	12.6	3750
3	73	20.7	4.5	3968
19	75.1	19.2	2.4	3614
6	76.3	1.3	8.3	3440
27	76.3	1.2	3.2	3813
2	77.6	10.7	5.2	3323
10	78	5.4	10.6	2964
30	78.4	11.3	6.4	2925
14	78.7	9.6	7.2	2863
22	80.4	0.8	0.3	3039
18	80.9	7.8	2.2	2970
26	81.2	4.5	12.5	3264
4	87.5	4.5	1.8	2193
12	89.6	3.4	2.7	2016
28	90.4	6.4	7.3	2011
20	91.9	34.4	31.1	1897
5	104.8	11.6	6	983
13	106.1	6.8	4.9	750
29	107.7	14	16.7	1028
21	108.5	6.2	4.5	874
All		4.7	3.9
Mean				4088.8

Here are the meaning of the columns:

• Panel G ID: here we are looking at the sensors, of which there are 32.
• Dist (mm): distance from the sensor center to the beam center. The table is sorted by this number.
• F Offset sigma (microns): weighted standard deviation of the two measurements of the sensor's fast coordinate.
• S Offset sigma (microns): weighted standard deviation of the two measurements of the sensor's slow coordinate.
• N refls: sum of the number of reflections recorded on the sensor between the two half dataset. Used as a weighting term.

The weighted mean of the fast and slow offset sigmas is 4.7 and 3.9 microns, respectively. This measure or the precision of this refinement, indicates it quite good compared to the pixel size of the detector (110 microns). However, there are still several panels with high fast or slow offset sigmas. That, plus the fact that the number of indexed images increased while using v3 metrology implies that refinement has not converged.

Further indexing and refinement (v4)

Reindexing the data using v3 and re-refining the data to create v4 metrology proceeds as described in the above steps. After generating v4, we evaluate it as described above and see this table:

PanelG ID	(mm)	F Offset Sigma (microns)	S Offset Sigma (microns)	N refls
1	21.8	1.6	1	6892
9	23.4	0	0.2	6878
25	24.5	0.5	1.1	6609
17	26	1.4	2.6	6637
0	40.7	4	2.1	6848
8	41.1	0.6	2.8	6624
24	43.7	0.3	0.6	6652
16	44.3	3.5	2.4	6655
7	55.3	0.7	4.1	6444
31	57.5	1.9	1.8	6538
15	57.8	2.5	3	6552
23	59.7	2.5	2.8	6443
11	71.9	1.2	13.2	6139
3	73	3.5	0.9	6070
19	75.1	1.8	1.4	6065
6	76.3	1.5	1.1	6118
27	76.3	0.8	2.9	6010
2	77.6	17.5	4.5	5917
10	78	2	1	5823
30	78.5	3.4	1.2	5885
14	78.7	10.4	0.5	5974
22	80.4	2.1	8.8	5867
18	80.9	3.6	6.5	5943
26	81.2	1.7	5.2	5891
4	87.5	17.1	19.6	5570
12	89.6	0.1	3.4	5514
28	90.4	4.4	3.7	5494
20	91.9	1.9	1	5417
5	104.7	8.4	0.9	5016
13	106.1	17.4	27.7	4957
29	107.7	10.8	14.6	4980
21	108.5	10.7	6.9	4855
All		4.1	4.4
Mean				6039.9

The fast and slow offset sigmas are lower generally, but not substantially. 5509 images were indexed, a small increase of 0.5% over v3 metrology. Further, the change in tile position is minimal <under construction>. The metrology has likely converged.

Deploy metrology

v4 metrology is now ready for use. Deploy it or use it directly for indexing as described in indexing using v2 metrology.