diff options
Diffstat (limited to 'doc')
| -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 | 99 | ||||
| -rw-r--r-- | doc/man/align_detector.1.md | 22 | ||||
| -rw-r--r-- | doc/man/indexamajig.1.md | 106 |
5 files changed, 112 insertions, 115 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..9e02b2f3 100644 --- a/doc/articles/tutorial.rst +++ b/doc/articles/tutorial.rst @@ -760,69 +760,44 @@ 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. 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. + +The command-line tool for detector geometry refinement is called +``align_detector``, and you can read more about how it works in its +`manual page <../man/align_detector.1.md>`_. diff --git a/doc/man/align_detector.1.md b/doc/man/align_detector.1.md index ec16f87b..953bafba 100644 --- a/doc/man/align_detector.1.md +++ b/doc/man/align_detector.1.md @@ -53,9 +53,17 @@ level. The default behaviour is to refine only the position components in the x-y plane, perpendicular to the beam. In favourable circumstances, you can add -option **--out-of-plane** to refine the panel tilts and shifts out of this -plane. However, be aware that this introduces additional cross-dependencies -and is less stable. +option **--out-of-plane** to refine the panel **translations** out of this +plane. However, be aware that this introduces additional cross-dependencies +and is less stable. Add option **--out-of-plane-tilts** to additionally +refine the panel **tilts** out of the x-y plane, which is even less stable. + +The overall detector z-position (camera length) is usually quite strongly +correlated with the crystal cell parameters, making it difficult to refine. +With high-resolution data, it can be possible, however. To refine the overall +camera length, add **--camera-length**. Without this option, the overall +camera length will not be altered, even with **--out-of-plane**. Instead, only +the z-positions of the panels relative to one another will be refined. **align_detector** relies on the program **pede** from the Millepede-II package. Usually, this will be installed as part of the CrystFEL installation @@ -80,8 +88,14 @@ OPTIONS : detector. **--out-of-plane** -: Additionally refine out-of-plane panel positions and tilts of the detector. +: Additionally refine out-of-plane panel translations, relative to one another +: (see **--camera-length**). +**--out-of-plane-tilts** +: Additionally refine out-of-plane panel tilts. + +**--camera-length** +: Additionally refine the overall camera length. AUTHOR ====== diff --git a/doc/man/indexamajig.1.md b/doc/man/indexamajig.1.md index 1955ef76..605782bd 100644 --- a/doc/man/indexamajig.1.md +++ b/doc/man/indexamajig.1.md @@ -77,7 +77,7 @@ They will also be rejected if the peak is closer than twice the inner integration radius from another peak. If you instead use **--peaks=peakfinder8**, indexamajig will use the -"peakfinder8" peak finding algorithm describerd in Barty et al. (2014). Pixels +"peakfinder8" peak finding algorithm described in Barty et al. (2014). Pixels above a radius-dependent intensity threshold are considered as candidate peaks (although the user sets an absolute minimum threshold for candidate peaks). Peaks are then only accepted if their signal to noise level over the local @@ -90,18 +90,18 @@ additional peak is ignored. If you instead use **--peaks=peakfinder9**, indexamajig will use the "peakfinder9" peak finding algorithm described in the master thesis "Real-time image analysis and data compression in high throughput X-ray diffraction -experiments" by Gevorkov. Other than peakFinder8, peakFinder9 uses local +experiments" by Gevorkov. Unlike peakfinder8, peakfinder9 uses local background estimation based on border pixels in a specified radius (**--local-bg-radius**). For being fast and precise, a hierarchy of -conditions is used. First condition is only useful for speed consideration, it +conditions is used. The first condition is only useful for speed consideration. It demands that a pixel that is the biggest pixel in a peak must be larger than every border pixel by a constant value (**--min-peak-over-neighbour**). -Second condition ensures, that the pixel passing the previous condition is the -highest pixel in the peak. It assumes, that peaks rise monotonically towards -the biggest pixel. Third condition ensures, that the biggest pixel in the peak +The second condition ensures that the pixel passing the previous condition is the +highest pixel in the peak. It assumes that peaks rise monotonically towards +the biggest pixel. The third condition ensures that the biggest pixel in the peak is significantly over the noise level (**--min-snr-biggest-pix**) by computing the local statistics from the border pixels in a specified radius. -Fourth condition sums up all pixels belonging to the peak +The fourth condition sums up all pixels belonging to the peak (**--min-snr-peak-pix**) and demands that the whole peak must be significantly over the noise level (**--min-snr**). Only if all conditions are passed, the peak is accepted. @@ -123,7 +123,7 @@ reports that the pattern has been successfully indexed. Choose from: : https://doi.org/10.1107/S0907444999009506. **asdf** -: This is a implementation of the dirax algorithm, with some very small changes +: This is an implementation of the dirax algorithm, with some very small changes : such as using a 1D Fourier transform for finding the lattice repeats. This : algorithm is implemented natively within CrystFEL meaning that no external : software is required. @@ -131,10 +131,11 @@ reports that the pattern has been successfully indexed. Choose from: **felix** : Invoke Felix, which will use your cell parameters to find multiple crystals in : each pattern. -: The Felix indexer has been developed by Soeren Schmidt <ssch@fysik.dtu.dk>. To -: use this option, 'Felix' must be in your shell's search path. This can be a +: To use this option, 'Felix' must be in your shell's search path. This can be a : link to the latest version of Felix. If you see the Felix version information -: when you run Felix on the command line, things are set up correctly. +: when you run Felix on the command line, things are set up correctly. See +: Beyerlein et al., J. Appl. Cryst. 50, p1075-1083, +: https://doi.org/10.1107/s1600576717007506. **xds** : Invoke XDS, and use its REFIDX procedure to attempt to index the pattern. @@ -261,9 +262,9 @@ methods, and you specify the method using **--integration**. Choose from: **prof2d** : Integrate the peaks using 2D profile fitting with a planar background, close to -: the method described by Rossmann (1979) J. Appl. Cryst. 12 p225. The default -: behaviour with prof2d is to center the peak first - use prof2d-nocen to skip -: this step. +: the method described by Rossmann (1979) J. Appl. Cryst. 12 p225, +: https://doi.org/10.1107/S0021889879012218. The default behaviour with prof2d +: is to center the peak first - use prof2d-nocen to skip this step. You can add one or more of the following to the above integration methods: @@ -359,6 +360,9 @@ BASIC OPTIONS : Set the timeout used for "get next" calls from ASAP::O, in ms. The default : is 500 ms. +**--asapo-acks* +: Use ASAP::O acknowledgements for more reliable message delivery. + **--data-format=format** : Specify the data format for data received over ZeroMQ or ASAP::O. Possible : values in this version are msgpack, hdf5 and seedee. @@ -553,11 +557,11 @@ INDEXING OPTIONS : CrystFEL format. **--tolerance=tol** -: Set the tolerances for unit cell comparison. tol takes the form a,b,c,ang. a, -: b and c are the tolerances, in percent, for the respective reciprocal space -: axes, and ang is the tolerance in degrees for the reciprocal space angles. If -: the unit cell is centered, the tolerances are applied to the corresponding -: primitive unit cell. The default is **--tolerance=5,5,5,1.5**. +: Set the tolerances for unit cell comparison. tol takes the form a,b,c,al,be,ga. +: a, b and c are the tolerances, in percent, for the respective reciprocal space +: axes, and al, be, ga are the tolerances in degrees for the reciprocal space angles. +: If the unit cell is centered, the tolerances are applied to the corresponding +: primitive unit cell. The default is **--tolerance=5,5,5,1.5,1.5,1.5,1.5**. **--no-check-cell** : Do not check the cell parameters against the reference unit cell (given with @@ -629,47 +633,50 @@ INDEXING OPTIONS : The rotation matrix trace tolerance in degrees. Default 3. **--felix-domega=n** -: Low-level parameter for the Felix indexing algorithm. +: Degree range of omega (moscaicity) to consider. Default 2. **--felix-fraction-max-visits=n** -: Low-level parameter for the Felix indexing algorithm. +: Cutoff for minimum fraction of the max visits. Default: 0.75. **--felix-max-internal-angle=n** -: Low-level parameter for the Felix indexing algorithm. +: Cutoff for maximum internal angle between observed spots and predicted spots. +: Default: 0.25. **--felix-max-uniqueness=n** -: Low-level parameter for the Felix indexing algorithm. +: Cutoff for maximum fraction of found spots which can belong to other crystallites. +: Default: 0.5. **--felix-min-completeness=n** -: Low-level parameter for the Felix indexing algorithm. +: Cutoff for minimum fraction of projected spots found in the pattern. +: Default: 0.001. **--felix-min-visits=n** -: Low-level parameter for the Felix indexing algorithm. +: Cutoff for minimum number of voxel visits. Default: 15. **--felix-num-voxels=n** -: Low-level parameter for the Felix indexing algorithm. +: Number of voxels for Rodrigues space search Default: 100. **--felix-sigma=n** -: Low-level parameter for the Felix indexing algorithm. +: The sigma of the 2theta, eta and omega angles. Default: 0.2. **--felix-tthrange-max=n** -: Low-level parameter for the Felix indexing algorithm. +: Maximum 2theta to consider for indexing (degrees). Default: 30. **--felix-tthrange-min=n** -: Low-level parameter for the Felix indexing algorithm. +: Minimum 2theta to consider for indexing (degrees). Default: 0. **--xgandalf-sampling-pitch=n** : Selects how dense the reciprocal space is sampled. [0-4]: extremelyLoose to -: extremelyDense. [5-7]: standardWithSeondaryMillerIndices to -: extremelyDenseWithSeondaryMillerIndices. Default is 6 -: (denseWithSeondaryMillerIndices). +: extremelyDense. [5-7]: standardWithSecondaryMillerIndices to +: extremelyDenseWithSecondaryMillerIndices. Default: 6 +: (denseWithSecondaryMillerIndices). **--xgandalf-grad-desc-iterations** : Selects how many gradient descent iterations are performed. [0-5]: veryFew to -: extremelyMany. Default is 4 (manyMany). +: extremelyMany. Default: 4 (manyMany). **--xgandalf-tolerance** -: relative tolerance of the lattice vectors. Default is 0.02. +: relative tolerance of the lattice vectors. Default: 0.02. **--xgandalf-no-deviation-from-provided-cell** : If a prior unit cell was provided, and this flag is set, the found unit cell @@ -678,14 +685,14 @@ INDEXING OPTIONS **--xgandalf-min-lattice-vector-length** **--xgandalf-min-lattice-vector-length** : Minimum and maximum possible lattice vector lengths (unit is A). Used for : fitting without prior lattice as starting point for gradient descent, so the -: final minimum lattice vector length can be smaller/highier as min/max. Note: +: final minimum lattice vector length can be smaller/bigger than min/max. Note: : This is valid for the uncentered cell, i.e. the P-cell! Default is 30A and 250A : respectively. **--xgandalf-max-peaks** : Maximum number of peaks used for indexing. For refinement all peaks are used. : Peaks are selected by increasing radius. Limits the maximum execution time for -: Patterns with a huge amount of peaks - either real ones or false positives. +: patterns with a huge amount of peaks - either real ones or false positives. : Default is 250. **--xgandalf-fast-execution** @@ -693,27 +700,28 @@ INDEXING OPTIONS **--pinkIndexer-considered-peaks-count** : Selects how many peaks are considered for indexing. [0-4] (veryFew to -: manyMany). Default is 4 (manyMany). +: manyMany). Default: 4 (manyMany). **--pinkIndexer-angle-resolution** : Selects how dense the orientation angles of the sample lattice are sampled. -: [0-4] (extremelyLoose to extremelyDense). Default is 2 (normal). +: [0-4] (extremelyLoose to extremelyDense). Default: 2 (normal). **--pinkIndexer-refinement-type** : Selects the refinement type. 0 = none, 1 = fixedLatticeParameters, 2 = : variableLatticeParameters, 3 = firstFixedThenVariableLatticeParameters, 4 = : firstFixedThenVariableLatticeParametersMultiSeed, 5 = -: firstFixedThenVariableLatticeParametersCenterAdjustmentMultiSeed. +: firstFixedThenVariableLatticeParametersCenterAdjustmentMultiSeed. Default: 1 +: (fixedLatticeParameters). **--pinkIndexer-tolerance** : Selects the tolerance of the pinkIndexer (relative tolerance of the lattice -: vectors). Default is 0.06. For bad geometrys or cell parameters use a high +: vectors). For bad geometries or cell parameters use a high : tolerance. For a well known geometry and cell use a small tolerance. Only : important for refinement and indexed/not indexed identificaton. Too small : tolerance will lead to refining to only a fraction of the peaks and possibly : discarding of correctly indexed images. Too high tolerance will lead to bad -: Fitting in presence of multiples or noise and can mark wrongly-indexed patterns -: as indexed. +: fitting in presence of multiples or noise and can mark wrongly-indexed patterns +: as indexed. Default: 0.06. **--pinkIndexer-reflection-radius** : Sets radius of the reflections in reciprocal space in 1/A. Default is 2%% of a* @@ -722,14 +730,14 @@ INDEXING OPTIONS **--pinkIndexer-max-resolution-for-indexing** : Sets the maximum resolution in 1/A used for indexing. Peaks at high resolution -: Don't add much information, but they add a lot of computation time. Default is +: don't add much information, but they add a lot of computation time. Default is : infinity. Does not influence the refinement. **--pinkIndexer-max-refinement-disbalance** : Indexing solutions are dismissed if the refinement refined very well to one : side of the detector and very badly to the other side. Allowed values range : from 0 (no disbalance) to 2 (extreme disbalance), default 0.4. Disbalance after -: Refinement usually appears for bad geometries or bad prior unit cell +: refinement usually appears for bad geometries or bad prior unit cell : parameters. **--asdf-fast** @@ -746,14 +754,14 @@ INTEGRATION OPTIONS : **--integration=rings-nocen**. **--fix-profile-radius=n**, **--fix-divergence=n** -: Fix the beam and crystal paramters to the given values. The profile radius is +: Fix the beam and crystal parameters to the given values. The profile radius is : given in m^-1 and the divergence in radians (full angle). The default is to : set the divergence to zero, and then to automatically determine the profile : radius. -: You do not have to use all three of these options together. For example, if +: You do not have to use both of these options together. For example, if : the automatic profile radius determination is not working well for your data : set, you could fix that alone and continue using the default values for the -: other parameters (which might be automatically determined in future versions of +: other parameter (which might be automatically determined in future versions of : CrystFEL, but are not currently). **--int-radius=inner,middle,outer** @@ -765,8 +773,8 @@ INTEGRATION OPTIONS **--int-diag=condition** : Show detailed information about reflection integration when condition is met. : The condition can be all, none, a set of Miller indices separated by commas, -: random, implausible or negative. random means to show information about a -: random 1% of the peaks. negative means to show peaks with intensities which +: random, implausible, negative or strong. random means to show information about +: a random 1% of the peaks. negative means to show peaks with intensities which : are negative by more than 3 sigma. implausible means to show peaks with : intensities which are negative by more than 5 sigma. strong means to show : peaks with intensities which are positive by more than 3 sigma The default is |
