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.

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. For this experiment, the tile positions were measured using an optical microscope, then quadrants were adjusted by eye using powder rings.
Version 1 (v1)	After indexing the images using v0, we will refine the tile positions to produce metrology v1.
Version 2 (v2)	After re-indexing the images using v1, we will re-refine the tile positions to produce metrology v2.
...	And so forth until convergence

Initial indexing

The initial metrology deployed by the beamline operator is sufficient to get initial indexing results. Important parameters given by the beamline operators:

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

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 (v1)

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

 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=v0v1level2
 display v0v1level2*.png

Use the space bar 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 v1 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 v1, backing up v0 first:

 cd CsPad::CalibV1/CxiDs2.0:Cspad.0/geometry
 mv 0-end.data 0-end.data.v0
 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.v0, so you can return to it as needed.

Indexing with the new metrology yielded 5484 indexed images.

Refine metrology (v2)

We now refine the metrology generated from the indexed images from trial 3 and call it metrology version 2 (v2). 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 &

This time, the two metrologies are mostly unchanged, though again if you inspect the files themselves you will see changes.

Evaluate metrology

We have a program in development to evaluate the statistics of refinement. When it goes live, this section will be updated.

Deploy metrology

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