cctbx.xfel GUI/Runs tab
The Runs tab lists every run the GUI knows about and the sample tags attached to each. It is where tags are created, applied and kept up to date as runs arrive. Tags are the handles that the Run Stats, Unit Cell and Datasets tabs use to select runs, so keeping them accurate pays off later.
Back to cctbx.xfel GUI.
Where runs come from
Runs appear in the list when the run sentinel finds them, so press Watch for new runs on the toolbar to populate the tab. At LCLS it queries the run database for the experiment named in Settings; in standalone mode it scans the monitored folder (see Standalone options). New runs are checked for every 10 seconds, and the list refreshes itself; there is no refresh button.
When the sentinel finds new runs it also:
- applies the persistent tags (below) to each new run, and
- adds the new runs to every open ("Auto add runs") run block, so processing starts without any further clicks if a trial is active and Auto-submit jobs is on.
The run list
Each row shows the run number and a wide button listing the run's tags.
- Tag button: click it to open a checklist of all tags and tick the ones that apply to this run. Changes are saved immediately.
- Drag and drop: press on a row and drag it onto another row to copy all of the source run's tags onto the target run (the target's existing tags are kept). The target row is highlighted while you hover over it. A plain click on the tag button still opens the checklist.
- Average: submits an image averaging job for the run (see below).
Buttons
| Button | What it does |
|---|---|
| Change Tags on Multiple Runs | Opens a dialog with a checklist of all runs. Tick the runs, then Add tags or Remove tags to choose tags to add to, or remove from, every ticked run. The Sort tags by radio sorts the tag checklist by database id (creation order) or by name. |
| Manage Persistent Tags | Choose tags that the run sentinel applies automatically to every new run it discovers. Use it when starting a new sample: tick the sample's tag here, and every run collected from now on carries it. The choice lasts for this GUI session only. |
| Manage Tags | Create, rename, comment and delete tags. Add Tag inserts a new row with a placeholder name; click the name or comment cell to edit it. Remove Tags deletes the selected rows and Clear All deletes every tag (after a confirmation; this cannot be undone). Tag names must be unique. Nothing is written to the database until you press OK. |
Image averaging
Average submits a dxtbx.image_average job for the run, using the same queuing settings as processing jobs. It writes three CBF images to averages/ inside the output folder: the mean (avg.cbf), the per-pixel maximum (max.cbf) and the standard deviation (std.cbf). These are useful for checking beam centre and detector distance, finding bad pixels, and making masks.
The dialog asks how many images to skip at the start of the run and whether to use all images or a specified number. The job needs a run block for the detector settings (address, distance, binning): it uses the run's own run block if it is in one, otherwise the run block whose run range is closest. If no run block exists yet, create one in the Trials tab first.
The button label changes to Running once the job is submitted. The job appears in the Jobs tab like any other.
Tips
- Decide on a tagging scheme before the beamtime (sample, buffer, laser on/off, detector distance) and create the tags in Manage Tags at the start.
- Change the persistent tags every time the sample changes. Runs that arrive with the wrong tags can be fixed afterwards with Change Tags on Multiple Runs.
- A dataset needs at least one tag to select runs by, so even an experiment with a single sample needs one tag applied to its runs.