Aaron: Created page with "{{DISPLAYTITLE: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..."

2026-10-09T21:00:18Z

Created page with "{{DISPLAYTITLE: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..."

New page

{{DISPLAYTITLE: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 [[cctbx.xfel GUI/Run Stats tab|Run Stats]], [[cctbx.xfel GUI/Unit Cell tab|Unit Cell]] and [[cctbx.xfel GUI/Datasets tab|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 [[cctbx.xfel GUI/Settings#Standalone options|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 ==
{| class="wikitable"
! 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 <code>dxtbx.image_average</code> job for the run, using the same queuing settings as processing jobs. It writes three CBF images to <code>averages/</code> inside the output folder: the mean (<code>avg.cbf</code>), the per-pixel maximum (<code>max.cbf</code>) and the standard deviation (<code>std.cbf</code>). 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 [[cctbx.xfel GUI/Trials tab|Trials tab]] first.

The button label changes to ''Running'' once the job is submitted. The job appears in the [[cctbx.xfel GUI/Jobs tab|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.

Cctbx.xfel GUI/Runs tab - Revision history