cctbx.xfel GUI/Trials tab

The Trials tab is where processing is set up. A trial is a numbered set of spot finding, indexing and integration parameters; each trial owns one or more run blocks that say which runs it applies to and how their images should be read. Making a trial active is what causes jobs to be submitted.

Back to cctbx.xfel GUI.

Layout

Each trial is a box labelled with its number and the start of its comment, laid out left to right (scroll horizontally when there are many). Inside each box:

• A list of the trial's run blocks, one button each, labelled [block id] runs first - last. An open block shows ... in place of the last run. Click a button to edit the block.
• New Block: create a run block for this trial (pre-filled from the trial's last block).
• Select Blocks: tick which of the run blocks from all trials belong to this trial. This is how a block created in one trial is reused by another. A block that no longer belongs to any trial becomes inactive.
• The magnifying-glass button shows the trial's parameters. Everything is read-only except the comment.
• Active Trial: while ticked, the job sentinel submits an indexing job for every run in every one of this trial's blocks. Untick to stop submitting new jobs; jobs already running are not affected.

Below the trials: Show Only Active Trials hides inactive trials, and New Trial opens the trial dialog.

Creating a trial

New Trial opens the New Trial Settings dialog. A new trial inherits the parameters and comment of the most recent trial, so you normally change a few values and press OK. Trials are created inactive; tick Active Trial when you are ready to process.

Control	Meaning
Trial number	Allocated automatically (one more than the highest existing trial).
Import PHIL	Load parameters from a PHIL file. The file is validated against the processing program; unknown parameters are reported and the import is rejected.
Edit PHIL	Open the full parameter set as text (only the values that differ from the program's defaults are shown). Anything the simplified controls do not cover is set here, for example masks, refinement options or integration settings. Changes are validated when you press OK in the editor and the simplified controls update to match.
Comment	Free text, shown in the trial box and in job listings. Say what you changed.

Overall parameters

• Find spots, Index, Integrate: which stages to run. Untick Index and Integrate for a quick hit-finding pass, or to tune spot finding on the Run Stats tab before indexing.
• Min spots: the minimum number of strong spots an image needs before indexing is attempted (the hit finder threshold). Images below it are logged as non-hits and skipped.

Spotfinding parameters

These map onto the DIALS spot finder:

• Min spot size / Max spot size: pixel count limits for a spot. The minimum removes single-pixel noise; the maximum removes ice rings and bad regions.
• Sigma background / Sigma strong: the dispersion algorithm's thresholds, in units of the local background standard deviation. Lower sigma strong finds weaker spots.
• Global threshold: absolute pixel value below which nothing counts as signal.
• Gain: detector gain in ADU per photon. Leave blank to use the value reported by the image format. When integration is on, the same gain is also used to scale the integrated intensity variances.
• Kernel size: size of the local background window in pixels (two numbers).
• Threshold algorithm: dispersion (standard), dispersion_extended (more sensitive at low resolution) or radial_profile (radial background subtraction).

Indexing parameters

• Unit cell and Space group: the known symmetry, if any. Giving both makes indexing much more reliable; the pair is checked for compatibility.
• d_min indexing: high-resolution cut-off used during indexing refinement.
• Max lattices: more than 1 enables multi-lattice indexing of the same image.
• Reflection subsampling: index on a random subset of the strong spots, which can help with very dense patterns.

Other options

• Copy runblocks from: give the new trial the same run blocks as an existing trial, so that a parameter change can be tried on exactly the same runs.
• Percent events processed: process only this percentage of the images in each run (a throttle for a quick look at a large run).
• Number of bins and High res. limit: used for logging resolution statistics to the database.

Run blocks

A run block groups a contiguous range of runs with the detector settings needed to read them. New Block and clicking an existing block open the Run Block Settings dialog.

Run range

• Start run: the first run in the block.
• Auto add runs: the block has no end; every new run the run sentinel finds is added to it. Use this while collecting data.
• Specify end run / End run: a closed range.

In standalone mode the start and end are database ids (order of discovery) rather than run numbers, since run names there need not be numeric.

Run block settings

Setting	Meaning
Extra XTC format parameters (LCLS)	PHIL text passed to the XTC image format, for example a locator override. Import PHIL loads it from a file.
Detector Address (LCLS)	The detector's address in the XTC stream, such as CxiDs2.0:Cspad.0 or MfxEndstation.0:Rayonix.0. Use the detnames tool at LCLS to list them.
Beam X, Y, DetZ (LCLS)	Beam centre in pixels and detector distance in mm. Required for Rayonix detectors even when a reference geometry is given (the reference geometry then takes precedence).
binning (LCLS)	Rayonix binning (2, 3, 4, ...).
energy / Energy override	Fixed photon energy in eV applied to every image, overriding the per-shot values. Leave blank to use the measured energies.
wavelength_offset (LCLS)	Offset added to each image's wavelength, in Å, from the Energy tab calibration.
spectrum_eV_per_pixel / spectrum_eV_offset (LCLS)	FEE spectrometer calibration, from the Energy tab.
two_theta_low / two_theta_high	Two scattering angles in degrees. The ratio of the radial average at the high angle to that at the low angle is used by the Run Stats tab to count solvent hits (the defaults are a kapton ring and the water ring).
Untrusted Pixel Mask	A DIALS mask file (.mask) of pixels to ignore.
Reference geometry	An experiment file (.expt) whose detector geometry replaces the one from the image headers, typically from a geometry refinement.
Comment	Free text.
Edit PHIL	Any other processing parameter that should apply only to this block (the reference geometry is stored this way, as input.reference_geometry). Block parameters are combined with the trial's parameters when a job is submitted.

Editing an existing block

Results on disk are stored by trial and block id, so a block's settings must not change under results already produced. When you press OK on an existing block:

• if only the end run, the open/closed state or the comment changed, the block is updated in place (the job sentinel is paused briefly while the runs are re-synced);
• if anything else changed, the old block is made inactive and a new block with a new id is created and attached to the trial. Jobs for the new block are submitted afresh; the old results stay where they were.

What happens next

With a trial active, run blocks attached and Auto-submit jobs on, the job sentinel submits one job per run in each block, each writing to r<run>/<trial>_rg<block>/ in the output folder. Watch them in the Jobs tab and the results in the Run Stats tab. Multiple trials can be active at once, for example to compare two parameter sets on the same runs.