Preparatory steps

This tutorial covers averaging dark and light runs, and creating mask images.

Setup your scratch area

Create a scratch folder and populate it with some directories that will be used during this tutorial. Usually you will work within the ftc directory of your experiment, for example:

/reg/d/psdm/cxi/cxi49812/ftc

In that directory, add a directory for your username, changing expname to your experiment name and <username> to your SLAC account name:

$ cd /reg/d/psdm/cxi/<expname>/ftc
$ mkdir <username>
$ cd <username>
$ mkdir darks
$ mkdir averages
$ mkdir results

You may use a directory in your home folder for saving results but this is not advised as it will fill quickly.

Finally, create a directory in your myrelease folder to hold config files and phil files needed during processing:

$ cd ~/myrelease
$ mkdir <expname>

Create a dark average

The CSPAD detector at LCLS is sensitive to temperature distortions and, unlike images collected at a synchrotron source, its output is not automatically dark-subtracted. Because of this it is necessary to periodically record a dark run with the shutters closed during an LCLS experiment. The dark run should contain on the order of at least 1000 images. Before an experimental run can be processed, this dark run must be averaged so that subsequent experimental data can have the dark subtracted from each image. Furthermore, events during collection can necessitate a new dark, such as ice in the beam over-saturating creating dead pixels or a change in temperature.

To create the average, you will need this config file: dark.cfg. Save it to your myrelease/<expname> folder.

The configuration file is broken into two sections, the psana section and the modules section.

psana section

The psana section specifies which modules to run. In this case we are running the built in module CSPadPixCoords.CSPadNDArrProducer. This module is fully documented in SLAC's module catalog. If we were running multiple modules, we could chain them together here, and each module would be executed in sequence using the parameters specified in the corresponding module section.

Module section

The module section specifies parameters specific to the CSPadPixCoords.CSPadNDArrProducer. The user should only ever need to change the source, which dictates which detector is going to be averaged. This string can be obtained from the beamline operator.

Running and testing the command

To average a dark run, the user can use cxi.mpi_average. Run it with no parameters to get a full help listing with examples. To test it on 10 events before using the queuing system, run it as follows:

cxi.mpi_average -c expname/dark.cfg -x expname -r runnumber -a addres -d detzoffset -n 10 -p

The options are described as follows:

• -c: path to the dark config file
• -x: your experiment name
• -r: the dark run number
• -a: the address string for the detector. Will be something like CxiDs1.0:Cspad.0
• -d: The detz offset. This is the offset (in mm) from the sample interaction region to the back the CSPAD detector rail at CXI. Typically it's on the order of between 560 and 580 mm. The beamline operator will provide you with a value. At XPP you must specify the detector distance directly as their CSPAD is on a robot arm.
• -p: write the output as image pickle files. Currently the standard file format for cctbx.xfel.

When complete, three new .pickle files will be present in your directory. The dark average will be named expname_avg-rrunnum.pickle. A similar stddev and max file will be found as well. Use the -o option to put these averages somewhere else, such as a location available for all users to access for your experiment, e.g. /reg/d/psdm/instrumentname/expname/res/darks

Now, to submit the averaging job to the processing queue using many processor and all the events, use bsub:

bsub -a mympi -n 100 -q psanacsq -o dark_average.log cxi.mpi_average -c expname/dark.cfg -x expname -r runnumber -a address -d detzoffset -p

The job will be scheduled in the queue called psanacsq, which is one of several available queues, using 100 cores. Note that the job must be submitted from the ~/myrelease directory.

Type bjobs to see if the job is running. When it is, follow the output thusly:

$ tail -f dark_average.log

When the average has been completed, the output can be inspected using the cctbx image viewer:

$ cctbx.image_viewer <path to pickle files>

Averaging an experimental light run

Once the dark average is completed, experimental, lighted, runs can be averaged to see the extent of diffraction and potential pathologies in the run. Copy the average.cfg file from the tutorials directory to your pyana directory:

$ cd ~/myrelease
$ cp /reg/g/cctbx/tutorials/preprocessing/average.cfg .

The configuration file will look like this:

[pyana]
modules = my_ana_pkg.mod_average
num-cpu = 8

[my_ana_pkg.mod_average]
calib_dir      = /reg/g/cctbx/sources/cctbx_project/xfel/metrology/CSPad/run4/CxiDs1.0_Cspad.0
dark_path      = /reg/g/cctbx/tutorials/scratch/<username>/r0002/000/out/<name of dark average>.pickle
dark_stddev    = /reg/g/cctbx/tutorials/scratch/<username>/r0002/000/out/<name of dark stddev>.pickle
avg_dirname    = /reg/g/cctbx/tutorials/scratch/<username>/averages
stddev_dirname = /reg/g/cctbx/tutorials/scratch/<username>/averages
max_dirname    = /reg/g/cctbx/tutorials/scratch/<username>/averages
detz_offset    = 581
address         = CxiDs1-0|Cspad-0
avg_basename    = Ds1-r0003-avg
stddev_basename = Ds1-r0003-stddev
max_basename    = Ds1-r0003-max

The only difference is the addition of two parameters:

dark_path

path to the average dark image created before

dark_stddev

path to the standard deviation dark image created before

The job is ran as before using cxi.lsf, again remembering to change all instances of <username> to your own SLAC user name. Here you must also change <name of dark average> and <name of dark stddev> to the names of the average and standard deviation images created in the previous step. The result of the run will be three new images that can be viewed with cctbx.image_viewer in the same manner as the darks were.

Information contained in the light average

Firstly, the light and dark images can be used to mask of any bad pixels. Inactive and non-bonded pixels, as well as hypersensitive pixels and any beam stop (if used) should be masked out. The light images (maximum in particular) also serve as a virtual, dark-subtracted, powder pattern that can used to inspect the data for diffraction. The light maximum should also flag up obvious errors in metrology, because rings will be non-continuous if the quadrants are misaligned. Intensity values from the corners of the light average or maximum are also useful to estimate background when taking first guesses at thresholds for hit-finding and integration.

Creating a mask image

cctbx.xfel uses three images to create a mask. Those images, and the purposes of them are listed below:

• Average image from a dark run: pixels ≤ 0 are considered dead, pixels > 2000 are too sensitive
• Standard deviation from a dark run: pixels ≤ 0 are considered dead, pixels ≥ 10 are too uncertain
• Maximum projection from a lighted run (i.e. an experimental run): pixels < 300 are considered non-bonded or in a shadow. [N.B.–this assumes a lot–300 may be appropriate for XPP data collected at atmosphere; not CXI data in vacuo–NKS.] The presence of diffracting data is not needed, but also will not interfere.

To create the mask, execute these commands:

$ cd /reg/g/cctbx/tutorials/scratch/<username>/
$ mkdir masks
$ cd masks
$ cxi.make_mask -m 10 <name of dark average>.pickle <name of dark standard deviation>.pickle \
    <name of light maximum projection>.pickle

A new image is created where each pixel has one of two values: -2 (masked out pixels), and 0 (good pixels). Note, the maximum projection minimum pixel value is overridden here to a value that is more sensible for the tutorial's lysozyme data. You will likely need to adjust this parameter based on your data (see below for details and for further overrides).

Use the resultant mask image during processing with cctbx.xfel by adding this flag to your pyana config file:

mask_path = <path to mask file>

In addition, a polygon and a circle can be specified using the --poly_mask and --circle_mask parameters:

$ cxi.make_mask --poly_mask=17,854,76,967,760,982,762,879 --circle_mask=855,939,103 Cspad-avg.pickle Cspad-stddev.pickle Cspad-max.pickle

This example creates a mask image with a polygon [with vertices (17,854), (76,967), (760,982), and (762,879)] masked out, and a circle with center (855,939) and radius 103 masked out. Only one polygon and circle can be specified at the moment.

The mask can be examined with cctbx.image_viewer.

Applying the mask

Once the mask is created, it needs to be referenced by your configuration file:

mask_path = <absolute path to mask file>

Further, the indexing software needs to know what value to use as the masked-out value. Add the following to your phil files for indexing:

integration.mask_pixel_value=-2

Where -2 is the default mask value, but it can be whatever you specify using the -x option cxi.make_mask (see below).

Options

Some additional options are available for specifying the details of the masking operation:

-a, --avg_max (default 2000)

specifies the maximum value in ADU a pixel in the average image can have before it's masked out. The minimum is always zero.

-s, --stddev_max (default 10)

specifies the maximum value in ADU a pixel in the standard deviation image can have before it's masked out. The minimum is always zero.

-m, --maxproj_min (default 300)

specifies the minimum value in ADU a pixel in the maximum projection image can have before it's masked out. Of the three parameters for controlling cutoffs in cxi.make_mask, the -m option is unique from the -a and -s options in that it will likely vary the according to your sample's background. Carefully examine the corners of your lighted maximum projection and choose a value lower than the ADU values displayed. Also note that there is no cutoff on the high end of the maximum projection image specified in the mask, as that is defined as the saturation value for the detector.

-x, --mask_pix_val (default -2)

specifies the value to use when masking out a pixel. In other words, bad pixels in images in the XTC stream will be replaced with this value.

-o, --output (default mask_.pickle)

specifies the output file path, should be *.pickle, can include directory.