27
edits
(→Frame: mention HKL indices display) |
|||
(22 intermediate revisions by 2 users not shown) | |||
Line 4: | Line 4: | ||
XDSGUI gives access to George Sheldrick's SHELXC, SHELXD and SHELXE programs, via the [[XDSGUI#SHELX|SHELX]] tab, and to Isabel Uson's ARCIMBOLDO programs, via the [[XDSGUI#ARCIMBOLDO|ARCIMBOLDO]] tab. | XDSGUI gives access to George Sheldrick's SHELXC, SHELXD and SHELXE programs, via the [[XDSGUI#SHELX|SHELX]] tab, and to Isabel Uson's ARCIMBOLDO programs, via the [[XDSGUI#ARCIMBOLDO|ARCIMBOLDO]] tab. | ||
The XDSGUI paper (Brehm, Triviño, Krahn, Usón and Diederichs (2023) XDSGUI: a graphical user interface for XDS, SHELX and ARCIMBOLDO. J. Appl. Cryst. 56) is open access at https://doi.org/10.1107/S1600576723007057 . | |||
== How to use XDSGUI == | == How to use XDSGUI == | ||
Line 21: | Line 23: | ||
=== Technical aspects of XDSGUI usage === | === Technical aspects of XDSGUI usage === | ||
* the simple editor operating in the tabs understands ctrl-X (cut), ctrl-c (copy), ctrl-v (paste), ctrl-z (undo) and ctrl-Z (redo) | * the simple editor operating in the tabs understands ctrl-X (cut), ctrl-c (copy), ctrl-v (paste), ctrl-z (undo) and ctrl-Z (redo); ctrl-+ (control-plus) and ctrl-- (control-minus) enlarge or decrease the font size of characters. | ||
* with SHIFT+(left-mouse-click) in the "Frame" tab one can set the direct beam impact position. | |||
* flexibility of operation: all commands in the [[XDSGUI#TOOLS|TOOLS]] tab may be modified by the user, simply by modifying the (bash) code in the text field below the button. The user-changed command is automagically and permanently stored in ~/.xds-gui . The user may also change what is written on a button, by editing ~/.xds-gui. It should be obvious what to change. | * flexibility of operation: all commands in the [[XDSGUI#TOOLS|TOOLS]] tab may be modified by the user, simply by modifying the (bash) code in the text field below the button. The user-changed command is automagically and permanently stored in ~/.xds-gui . The user may also change what is written on a button, by editing ~/.xds-gui. It should be obvious what to change. | ||
* Menu / Settings is used for specifying: In "Paths" the "generic library" (e.g. /usr/local/lib64/dectris-neggia.so) for reading HDF5 files and for binaries (xds_par, xscale_par, shelxc/d/e, ...), in "Appearance" (font size and default plot height), and in "User Buttons" the names for user defined tool buttons. The Settings menu can be opened on the Mac by clicking upper-left on "xdsgui", then "Preferences ...", or pressing the "Command" (⌘) key and the "," key. Changed settings are automatically stored in ~/.xdsgui . | * Menu / Settings is used for specifying: In "Paths" the "generic library" (e.g. /usr/local/lib64/dectris-neggia.so) for reading HDF5 files and for binaries (xds_par, xscale_par, shelxc/d/e, ...), in "Appearance" (font size and default plot height), and in "User Buttons" the names for user defined tool buttons. The Settings menu can be opened on the Mac by clicking upper-left on "xdsgui", then "Preferences ...", or pressing the "Command" (⌘) key and the "," key. Changed settings are automatically stored in ~/.xdsgui . | ||
Line 36: | Line 38: | ||
=== Frame === | === Frame === | ||
to display existing 2-dimensional data frames, or to start XDS data processing by displaying a raw data frame. In the latter case, the "generate XDS.INP" button runs the [[generate_XDS.INP]] script to create a first XDS.INP from the header of the raw data frame that is being displayed. (Note: this button needs to be used only once per dataset; all later changes to XDS.INP are done by different means - manually or scripted) The blue circle(s) delineate(s) the area(s) of the detector within TRUSTED_REGION; the green circles correspond to INCLUDE_RESOLUTION_RANGE, and the red [[XDSGUI#Technical aspects of XDSGUI usage|hatched]] regions correspond to EXCLUDE_RESOLUTION_RANGEs. The locations of the circles are not as accurate as those that XDS uses internally, because only values from XDS.INP, not the refined ones from XPARM.XDS) are used to calculate the resolution | to display existing 2-dimensional data frames, or to start XDS data processing by displaying a raw data frame. In the latter case, the "generate XDS.INP" button runs the [[generate_XDS.INP]] script to create a first XDS.INP from the header of the raw data frame that is being displayed. (Note: this button needs to be used only once per dataset; all later changes to XDS.INP are done by different means - manually or scripted) The blue circle(s) delineate(s) the area(s) of the detector within TRUSTED_REGION; the green circles correspond to INCLUDE_RESOLUTION_RANGE, and the red [[XDSGUI#Technical aspects of XDSGUI usage|hatched]] regions correspond to EXCLUDE_RESOLUTION_RANGEs. The locations of the circles are not as accurate as those that XDS uses internally, because only values from XDS.INP, not the refined ones from XPARM.XDS) are used to calculate the resolution. After XDS has indexed spots, they can be visualized with the *predictions* button. Prediction display can be toggled off and on to refresh predictions from an updated XPARM.XDS, and with refined BEAM_DIVERGENCE from INTEGRATE. | ||
When predictions are displayed, the corresponding HKL indices will be displayed in the pixel value panel. HKL indices depend on the current spacegroup, which is also displayed, and will be P1 if SPACE_GROUP_NUMBER is not defined in XDS.INP. | |||
Untrusted areas can be specified by the user, using two (UNTRUSTED_ELLIPSE; UNTRUSTED_RECTANGLE) or four (UNTRUSTED_QUADRILATERAL) right mouse clicks. The resulting areas are shown with red outline, and the keyword/parameter pairs are placed in the XDS.INP tab. Step-by-step: | Untrusted areas can be specified by the user, using two (UNTRUSTED_ELLIPSE; UNTRUSTED_RECTANGLE) or four (UNTRUSTED_QUADRILATERAL) right mouse clicks. The resulting areas are shown with red outline, and the keyword/parameter pairs are placed in the XDS.INP tab. Step-by-step: | ||
* "Load" a data file (e.g. FRAME.cbf) | * "Load" a data file (e.g. FRAME.cbf) to have it displayed. The pane can be "dragged" with the left mouse button; the mouse wheel zooms. For HDF5 data, the *master.h5 file must be loaded; this will automatically show its first frame (note that for this to work, the path to the correct [[XDSGUI#Technical aspects of XDSGUI usage|"generic library"]] must be specified in Menu/Settings). The frame number can be chosen with the selection box on the right, or the up-down arrows. The parameters in the XDS.INP tab are taken for resolution calculations (i.e. the frame header is not being interpreted in any way). | ||
* if XDS.INP does not yet exist, click "generate XDS.INP" (this ''will'' read the header). Check the XDS.INP tab afterwards but then go back to the Frame tab. Note that the current [[generate_XDS.INP]] works well for Pilatus, ADSC, Mar, [[Eiger]] and some Rigaku detectors; for other kinds of detectors the values marked XXX in XDS.INP have to be filled in manually. | * if XDS.INP does not yet exist, click "generate XDS.INP" (this ''will'' read the header). Check the XDS.INP tab afterwards but then go back to the Frame tab. Note that the current [[generate_XDS.INP]] works well for Pilatus, ADSC, Mar, [[Eiger]] and some Rigaku detectors; for other kinds of detectors the values marked XXX in XDS.INP have to be filled in manually. | ||
* left-click on "Untrusted areas" -> a pulldown menu appears | * left-click on "Untrusted areas" -> a pulldown menu appears | ||
Line 67: | Line 71: | ||
=== [[IDXREF]] === | === [[IDXREF]] === | ||
detailed explanation of output: see [[IDXREF.LP]]. | detailed explanation of output: see [[IDXREF.LP]]. | ||
The right side of the tab shows the indexed (black) and not-indexed (red) reflections of [ | The right side of the tab shows the indexed (black) and not-indexed (red) reflections of [https://xds.mr.mpg.de/html_doc/xds_files.html#SPOT.XDS SPOT.XDS]. | ||
=== DEFPIX === | === DEFPIX === | ||
Line 129: | Line 133: | ||
=== Dependencies === | === Dependencies === | ||
XDSGUI depends on [[generate_XDS.INP]], [[XDS-viewer]], and of course [[XDS]] (both the xds and xds_par binaries!), [[XDSCONV]], and [[2cbf]]. The ''statistics'' tab requires [[XDSSTAT]] and [[XDSCC12]]. For visualization of the raw data frames in the ''Frame'' tab, [[Eiger]] data processing requires either the [https://www.dectris.com/features/features-eiger-x/h5toxds/ <code>H5ToXds</code>] binary or the [https://www.globalphasing.com/autoproc/wiki/index.cgi?DataProcessingHdf5 <code>hdf2mini-cbf</code>] binary ( | XDSGUI depends on [[generate_XDS.INP]], [[XDS-viewer]], and of course [[XDS]] (both the xds and xds_par binaries!), [[XDSCONV]], and [[2cbf]]. The ''statistics'' tab requires [[XDSSTAT]] and [[XDSCC12]]. For visualization of the raw data frames in the ''Frame'' tab, [[Eiger]] data processing requires a "generic library" (see above) specified in Menu/Settings. As a deprecated fallback, either the [https://www.dectris.com/features/features-eiger-x/h5toxds/ <code>H5ToXds</code>] binary or the [https://www.globalphasing.com/autoproc/wiki/index.cgi?DataProcessingHdf5 <code>hdf2mini-cbf</code>] binary (from GlobalPhasing's autoPROC) could be used. Only the latter works for the .h5 files produced at Diamond Light Source; if hdf2mini-cbf should be used, it needs to be symlinked under the name H5ToXds (because XDSGUI has the name H5ToXds hardwired). ([https://github.com/biochem-fan/eiger2cbf <code>eiger2cbf</code>] does not seem to work with Eiger2 .h5 files.) | ||
One of the items in the ''tools'' tab calls a graphical file comparison program; if the default (xdiff) is not available, [http://furius.ca/xxdiff xxdiff] or [http://sourceforge.net/projects/tkdiff tkdiff] or [http://kdiff3.sourceforge.net/ kdiff3] or [http://meldmerge.org/ meld] may be used - please adjust the command line (below the button) accordingly. | One of the items in the ''tools'' tab calls a graphical file comparison program; if the default (xdiff) is not available, [http://furius.ca/xxdiff xxdiff] or [http://sourceforge.net/projects/tkdiff tkdiff] or [http://kdiff3.sourceforge.net/ kdiff3] or [http://meldmerge.org/ meld] may be used - please adjust the command line (below the button) accordingly. | ||
Line 141: | Line 145: | ||
=== Installation === | === Installation === | ||
The program can be downloaded, by academic users, as binary for Linux [https://{{SERVERNAME}}/pub/linux_bin/xdsgui 64bit] (compiled on RHEL7) and for Mac ([https://{{SERVERNAME}}/pub/mac_bin/xdsgui_mac_intel.dmg Intel] and [https://{{SERVERNAME}}/pub/mac_bin/xdsgui_mac_silicon.dmg Apple Silicon], respectively) | The program can be downloaded, by academic users, as binary for Linux [https://{{SERVERNAME}}/pub/linux_bin/xdsgui 64bit] (compiled on RHEL7) and for Mac ([https://{{SERVERNAME}}/pub/mac_bin/xdsgui_mac_intel.dmg Intel]. compiled on Catalina, and [https://{{SERVERNAME}}/pub/mac_bin/xdsgui_mac_silicon.dmg Apple Silicon], compiled on Big Sur, respectively). | ||
Industrial users: pls contact me directly. | Industrial users: pls contact me directly. | ||
Line 158: | Line 160: | ||
Procedures for identifying and installing missing libraries are given in the [[Installation]] article. | Procedures for identifying and installing missing libraries are given in the [[Installation]] article. | ||
On the '''Mac''' | On the '''Mac''', one needs to install the (free) Xcode command line tools (with <code>xcode-select –install</code>). | ||
If on '''Linux''' you get an error message like | If on '''Linux''' you get an error message like | ||
xdsgui: error while loading shared libraries: libQtGui.so. | xdsgui: error while loading shared libraries: libQtGui.so.5: cannot open shared object file: No such file or directory | ||
or similar for libQtCore.so. | or similar for libQtCore.so.5 or libQtOpenGL.so.5 , you should install the Qt5 libraries. | ||
== Known bugs, problems and workarounds == | == Known bugs, problems and workarounds == | ||
Line 168: | Line 170: | ||
# ''Another question concerning TOOLS: "Further analyses" on Mac: again pointless runs nicely but there is no output for the user.'' <br> Answer: Could it be that you started xdsgui by double-clicking its icon in the Finder? In that case, there is no output visible, because there is no console. Unfortunately, for all the Tools, the output is in the console window where xdsgui was started. Thus, you should really start xdsgui in a console window. | # ''Another question concerning TOOLS: "Further analyses" on Mac: again pointless runs nicely but there is no output for the user.'' <br> Answer: Could it be that you started xdsgui by double-clicking its icon in the Finder? In that case, there is no output visible, because there is no console. Unfortunately, for all the Tools, the output is in the console window where xdsgui was started. Thus, you should really start xdsgui in a console window. | ||
# both generate_XDS.INP and [[XDS]] do not tolerate spaces ("blanks") in file/directory names. While frame names rarely have a space in them, directories might, e.g. if an external disk has the label "John's USB disk" then this would be mounted on Linux as /media/John's USB disk/ and that would result in a error message from generate_XDS.INP and/or XDS. The '''workaround''' is to use a symlink on a different hard disk. | # both generate_XDS.INP and [[XDS]] do not tolerate spaces ("blanks") in file/directory names. While frame names rarely have a space in them, directories might, e.g. if an external disk has the label "John's USB disk" then this would be mounted on Linux as /media/John's USB disk/ and that would result in a error message from generate_XDS.INP and/or XDS. The '''workaround''' is to use a symlink on a different hard disk. | ||
# ''Problem description: On the Mac, after loading frames, by clicking “generate XDS.INP”, the program gives some strange symbol “Ô in XDS.INP. And the more you click “save” button, the more “Ô appeared. This looks like <br>SPACE_GROUP_NUMBER=0 à ! 0 if unknown <br>UNIT_CELL_CONSTANTS= 70 80 90 90 90 90 à .''<br> The problem is due to the “Rich text” format in TextEdit when saving "generate_XDS.INP". It is solved by | # ''Problem description: On the Mac, after loading frames, by clicking “generate XDS.INP”, the program gives some strange symbol “Ô in XDS.INP. And the more you click “save” button, the more “Ô appeared. This looks like <br>SPACE_GROUP_NUMBER=0 à ! 0 if unknown <br>UNIT_CELL_CONSTANTS= 70 80 90 90 90 90 à .''<br> The problem is due to the “Rich text” format in TextEdit when saving "generate_XDS.INP". It is solved by changing format to Plain in TextEdit, and re-downloading the script. | ||
# Frames from HDF5-files (*master.h5) are not being displayed: the symptom is that the frames appear to be empty/blank. This means you have not specified the correct "generic library" - see [[XDSGUI#Technical aspects of XDSGUI usage|Technical aspects of XDSGUI usage]]. The fix is: go to (upper left) "Menu"->"Settings"->insert the string "/usr/local/lib64/dectris-neggia.so" as "generic library", or try "/usr/local/lib64/durin-plugin.so" for DIAMOND data. Ask the system administrator for the exact path! If none of these works, leave "generic library" empty and install <code>H5ToXds</code> or <code>hdf2mini-cbf</code> as explained above. | # Frames from HDF5-files (*master.h5) are not being displayed: the symptom is that the frames appear to be empty/blank. This means you have not specified the correct "generic library" - see [[XDSGUI#Technical aspects of XDSGUI usage|Technical aspects of XDSGUI usage]]. The fix is: go to (upper left) "Menu"->"Settings"->insert the string "/usr/local/lib64/dectris-neggia.so" as "generic library", or try "/usr/local/lib64/durin-plugin.so" for DIAMOND data. Ask the system administrator for the exact path! If none of these works, leave "generic library" empty and install <code>H5ToXds</code> or <code>hdf2mini-cbf</code> as explained above. | ||
Line 178: | Line 179: | ||
* The program depends on [[generate_XDS.INP]] to interpret the header of the frames, so is currently limited to Dectris (Pilatus, Eiger), ADSC (Quantum), Rigaku (several types), MAR (CCD and image plate) detectors, and the Bruker PHOTON II. Other detectors need some values to be manually filled into XDS.INP - the relevant places are marked with XXX. These are detector properties (type, pixel size and number, min and max counts in a pixel), and experimental parameters like ROTATION_AXIS, OSCILLATION_RANGE, X-RAY_WAVELENGTH, DETECTOR_DISTANCE, and XORG, YORG. For fine-tuning of detector parameters, see the [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html detector-specific templates]. | * The program depends on [[generate_XDS.INP]] to interpret the header of the frames, so is currently limited to Dectris (Pilatus, Eiger), ADSC (Quantum), Rigaku (several types), MAR (CCD and image plate) detectors, and the Bruker PHOTON II. Other detectors need some values to be manually filled into XDS.INP - the relevant places are marked with XXX. These are detector properties (type, pixel size and number, min and max counts in a pixel), and experimental parameters like ROTATION_AXIS, OSCILLATION_RANGE, X-RAY_WAVELENGTH, DETECTOR_DISTANCE, and XORG, YORG. For fine-tuning of detector parameters, see the [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html detector-specific templates]. | ||
* The display of large frames in the FRAME tab may be slow over the network. | * The display of large frames in the FRAME tab may be slow over the network. | ||
* The green | * The green INCLUDE_RESOLUTION_RANGE and red semi-transparent EXCLUDE_RESOLUTION_RANGE circles in the Frame tab as well as all resolution values in the Frame and IDXREF tabs are calculated from values in XDS.INP (rather than from the refined values in XPARM.XDS, which XDS uses). For the (segmented) Pilatus 12M, the calculations in XDSGUI do not give the correct results - this is fixed in versions from Sep-2023 onwards. | ||
* The path (e.g. /usr/local/lib64/dectris-neggia.so) to the <code>dectris-neggia</code> library (available from Dectris) or the <code>durin-plugin</code> library (download from Diamond Light Source, DLS) should be entered into the "generic frame library" entry, in Menu->Settings, to enable visualization of raw data from Eiger detectors, but this mechanism may not work properly. Therefore, <code>H5ToXds</code> or (better because maintained by GlobalPhasing)<code>hdf2mini-cbf</code> may be installed as explained above. | * The path (e.g. /usr/local/lib64/dectris-neggia.so) to the <code>dectris-neggia</code> library (available from Dectris) or the <code>durin-plugin</code> library (download from Diamond Light Source, DLS) should be entered into the "generic frame library" entry, in Menu->Settings, to enable visualization of raw data from Eiger detectors, but this mechanism may not work properly. Therefore, <code>H5ToXds</code> or (better because maintained by GlobalPhasing)<code>hdf2mini-cbf</code> may be installed as explained above. | ||
== News == | == News == | ||
(changes before 2023 were deleted on Oct 4, 2023) | |||
update | update May 5, 2023: lots of bugfixes and enhancements mainly by Juno Krahn. Should evaluate the environment variable NEGGIA_PATH and DURIN_PATH, as does generate_XDS.INP from v1.14 onwards. Binaries for Linux, Intel Mac and Silicon Mac. | ||
update | update Sep 2023: segmented detectors (Juno Krahn) | ||
The XDSGUI paper Brehm, Triviño, Krahn, Usón and Diederichs (2023) XDSGUI: a graphical user interface for XDS, SHELX and ARCIMBOLDO. J. Appl. Cryst. 56, is open access at https://doi.org/10.1107/S1600576723007057 | |||
update | Version 2023-11-21 fixes a bug (predictions were only available if XDS.INP was older than XPARM.XDS). To update XPARM.XDS, run JOB=IDXREF or "cp GXPARM.XDS XPARM.XDS" in the Tools tab. Please note that hkl values in predictions are based on the spacegroup in XPARM.XDS, not on the spacegroup in XDS.INP . | ||
Version 2023-12-29 now displays CBF files written at PETRA-III BLs. | |||
== See also == | == See also == | ||
Line 223: | Line 200: | ||
[[Installation]] | [[Installation]] | ||
Qt environment variables (scaling etc): [https://doc.qt.io/qt-6/highdpi.html] |
edits