diff options
author | Thomas White <taw@physics.org> | 2024-06-06 16:59:37 +0200 |
---|---|---|
committer | Thomas White <taw@physics.org> | 2024-06-06 17:01:00 +0200 |
commit | e26937bd935a1e20e7a5bf6f7a7499052df4f9af (patch) | |
tree | ea91e2c39e693b9c2d5d825ca0d14d812a3e0af4 | |
parent | c5a643628ac10db775237968946e1759b83743fb (diff) |
tutorial.rst: Update geometry refinement step
This was out of date, referring to the old detector-shift which doesn't
work any more.
Fixes: https://gitlab.desy.de/thomas.white/crystfel/-/issues/97
-rw-r--r-- | doc/articles/tutorial-images/detector-shift-2.png | bin | 48161 -> 0 bytes | |||
-rw-r--r-- | doc/articles/tutorial-images/detector-shift.png | bin | 70526 -> 0 bytes | |||
-rw-r--r-- | doc/articles/tutorial.rst | 95 |
3 files changed, 33 insertions, 62 deletions
diff --git a/doc/articles/tutorial-images/detector-shift-2.png b/doc/articles/tutorial-images/detector-shift-2.png Binary files differdeleted file mode 100644 index 3c17148f..00000000 --- a/doc/articles/tutorial-images/detector-shift-2.png +++ /dev/null diff --git a/doc/articles/tutorial-images/detector-shift.png b/doc/articles/tutorial-images/detector-shift.png Binary files differdeleted file mode 100644 index 1bd50738..00000000 --- a/doc/articles/tutorial-images/detector-shift.png +++ /dev/null diff --git a/doc/articles/tutorial.rst b/doc/articles/tutorial.rst index 15c23ae0..662332ae 100644 --- a/doc/articles/tutorial.rst +++ b/doc/articles/tutorial.rst @@ -760,69 +760,40 @@ parameteters for just one frame, before launching the big processing job! Advanced: Check and optimise the detector geometry -------------------------------------------------- -This step is marked as *Advanced* because it needs some work outside the -CrystFEL GUI, but it's a very good idea to do this check. - Even if the geometry file is supposedly correct for the experiment, it's best -to check that, for example, the beam position hasn't drifted. Fortunately, -CrystFEL has already done most of the work for you. After indexing each -pattern, CrystFEL runs a short optimisation procedure, adjusting the unit cell -parameters, orientation and beam centre position to get the best possible -agreement between the observed and predicted peak locations at the same time as -making sure that the observed peaks correspond to Bragg positions as closely as -possible. The required beam shift (equivalently considered as a shift of the -detector) is recorded in the stream for each pattern (see the *Advanced* part -of section 8):: - - $ grep "predict_refine/det_shift" index-all-cell-1/crystfel.stream | head -n 5 - predict_refine/det_shift x = 0.020 y = 0.010 mm - predict_refine/det_shift x = -0.028 y = -0.017 mm - predict_refine/det_shift x = 0.028 y = 0.048 mm - predict_refine/det_shift x = 0.022 y = -0.014 mm - predict_refine/det_shift x = -0.016 y = -0.002 mm - $ - -A program provided with CrystFEL called detector-shift will plot these values. -Simply run it on the stream:: - - $ detector-shift index-all-cell-1/crystfel.stream - Mean shifts: dx = 0.0062 mm, dy = -0.0097 mm - -You can also run ``detector-shift`` conveniently from within the CrystFEL GUI: -Simply choose **Check detector shift** from the **Tools** menu. This will run -``detector-shift`` on whichever indexing result is currently selected (see the -start of section 7). - -A window should open, which shows the detector shifts as a scatter plot: - -.. image:: tutorial-images/detector-shift.png - -The cyan point marks the origin (0,0), and the pink point marks the mean of all -the offsets. The pixel size of the `Jungfrau detector -<https://www.psi.ch/en/lxn/jungfrau>`_, which was used for this experiment, is -75 µm, so almost all of the offsets are less than 1 pixel, and the average -offset is very much less than 1 pixel. Therefore, no further refinement is -required. - -Just for reference, here is how the graph might look if the offset were larger: - -.. image:: tutorial-images/detector-shift-2.png - -Notice that the cluster of points is significantly displaced from the origin. -This offset has already been taken into account by CrystFEL when calculating -the position of Bragg peaks, but the results will be better overall if the -geometry is correct from the start of the process. In this case, it would be a -good idea to update the geometry file. The detector-shift program can fix the -geometry file for you:: - - $ detector-shift index-all-cell-1/crystfel.stream jf-swissfel-16M.geom - Mean shifts: dx = -0.14 mm, dy = -0.25 mm - Applying corrections to jf-swissfel-16M.geom, output filename jf-swissfel-16M-predrefine.geom - default res 9097.525473 - -The updated geometry file is called ``jf-swissfel-16M-predrefine.geom``, as the -script tells you. If you process this dataset again, use this new geometry -file. +to check that, for example, the beam position hasn't drifted. CrystFEL +includes a tool for refining the detector geometry, called ``align_detector``. +This tool looks for small alterations to the geometry which improve the average +fit between observed and calculated peak locations, for all patterns, while +taking into account that changing the detector position will also change the +orientation reported by the indexing procedure. The topic of detector geometry +refinement is deep and complex, but only a basic application is needed here. + +Click **Refine detector geometry** in the bar at the left of the CrystFEL GUI. +You will be presented with a dialogue box to choose the filename for the new, +refined geometry file. Choose any suitable new filename, then look at the +bottom of the window. There is a drop-down menu where you should select the +name of the indexing job from earlier in this step (using prior unit cell +parameters). The geometry refinement calculations will be based on the results +of that indexing job. Leave **Heirarchy level** at zero and **Include +out-of-plane positions and tilts** unselected, to keep the refinement simple. +This will only refine the overall beam center position on the detector. Higher +refinement levels will do a more fine-grained refinement where the subunits +comprising the detector are refined individually, but this usually needs more +data than have been included in this tutorial. + +Once you click **Save**, the updated geometry file should appear after a moment +of calculation. The corrections applied to the detector position are reported +in the terminal::: + + Millepede succeeded. + + Group all: + x-translation +0.019464 mm + y-translation +0.001548 mm + +If you process this dataset again, use this new geometry file and you should +find that the indexing results are slightly better. |