XDSGUI: Difference between revisions

(8 intermediate revisions by 2 users not shown)

Line 3:

It graphically displays the ASCII and [http://www.bernstein-plus-sons.com/software/CBF cbf] files that XDS writes, and can run useful shell commands with a simple mouse click. The design goal of the program is to enable XDS data processing without the commandline, and to supply additional graphical information, in a simple, user-modifiable and user-extensible way.

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 also gives access to structure solution, through George Sheldrick's SHELXC, SHELXD and SHELXE programs via the [[XDSGUI#SHELX|SHELX]] tab, and to Isabel Uson's [https://ibmb.csic.es/en/department-of-structural-and-molecular-biology/crystallographic-methods/ 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 .

Line 24:

* 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.

* with SHIFT+(left-mouse-click) in the "Frame" tab one can set the direct beam impact position (useful if detector is not at 2theta=0).

* 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 .

Line 38:

=== 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. After XDS has indexed spots, they can be visualized with the *predictions* button.

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:

Line 97:

Line 99:

* The third item ("Optimizing data quality") offers commands that manipulate [[XDS.INP]] in several ways. Please note: the popup "XDS.INP has been changed externally" is emitted by the Qt system and cannot be switched off. It appears if one of the scripts changes XDS.INP while it is opened by XDSGUI (which is always the case) . Thus, one should simply press the "Reload" button. The user-definable command may be used e.g. for <pre>echo RELRAD=7 ! default is 5 >x; grep -v BEAM_DIVERGENCE XDS.INP >>x; cat x > XDS.INP; rm x</pre> This provides more pixels to the background estimation (for another INTEGRATE), and is useful for weakly exposed data sets which have mostly pixels with zero counts.

* The last item ("Further analyses") offers useful commands. "determine spacegroup with pointless" runs [[pointless]] against the XDS_ASCII.HKL file. The button "show spots in reciprocal space" runs [[spot2pdb]] to show you the reflections of SPOT.XDS in reciprocal space, with coot. You see the reflections that could be indexed in IDXREF in yellow, the not-indexed ones in pink, the rotation axis in blue and the origin as a blue cross. Ice rings and additional lattices can be easily identified - see [[spot2pdb]] for examples!

* The last item ("Further analyses") offers useful commands. "determine spacegroup with pointless" runs [[pointless]] against the XDS_ASCII.HKL file. The button "show spots in reciprocal space" runs [[spot2pdb]] to show you the reflections of SPOT.XDS in reciprocal space, with coot. You see the reflections that could be indexed in IDXREF in yellow, the not-indexed ones in pink, the rotation axis in blue and the origin as a blue cross. Ice rings and additional lattices can be easily identified - see [[spot2pdb]] for examples! Reason for possible failure: the spot2pdb program expects SPOT.XDS to have 7 columns, as IDXREF attaches 3 columns with indices to the 4 columns that COLSPOT wrote. So you cannot visualize SPOT.XDS from COLSPOT - it has to be written by IDXREF.

* Useful scripts for user tools are shared in [[XDSGUI User tools]]

Line 169:

Line 171:

# 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 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.

# Error pop-up "image conversion failed", and frames from HDF5-files (*master.h5) are not being displayed: the symptom is that the frames appear to be empty/blank. This is an error message not from XDS (the data processing program), but from XDSGUI (the graphics program). It 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 (or Preferences on Mac)"->insert "/usr/local/lib64/dectris-neggia.so" as "generic frame library", or try "/usr/local/lib64/durin-plugin.so" for DIAMOND data. Alternatively and even better, export the environment variable DURIN_PATH=/usr/local/lib64/durin-plugin.so or NEGGIA_PATH=/usr/local/lib64/dectris-neggia.so . 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. Please read [[Installation#other%20programs:%20XDS-viewer%2C%20XDSSTAT%2C%20XDSCC12%2C%20XDSGUI%2C%20XSCALE%20ISOCLUSTER%2C%20generate%20XDS.INP|https://wiki.uni-konstanz.de/xds/index.php/Installation#other_programs:_XDS-viewer,_XDSSTAT,_XDSCC12,_XDSGUI,_XSCALE_ISOCLUSTER,_generate_XDS.INP]]

# On Linux desktops with Wayland (e.g. KDE Plasma), xdsgui should be started with "QT_QPA_PLATFORM=xcb xdsgui" if xdsgui does not show the proper tabs content.

If you find a bug, please send email to Kay dot Diederichs at uni-konstanz dot de , with enough information/data to reproduce the bug ("it does not work" is not enough!).

Line 192:

Line 195:

Version 2023-12-29 now displays CBF files written at PETRA-III BLs.

Version 2024-11-04: Made tool categories and all button descriptions customizable. Prediction tool has note about customization. Add line-break to INTEGRATE graph for missing data regions. Works on Wayland. Bug fixes. (Juno Krahn)

Version 2025-05-15: Fix bug that SHELXC could not work with long paths (77 characters) to XDS_ASCII.HKL.

== See also ==

@@ Line 3: / Line 3: @@
 It graphically displays the ASCII and [http://www.bernstein-plus-sons.com/software/CBF cbf] files that XDS writes, and can run useful shell commands with a simple mouse click. The design goal of the program is to enable XDS data processing without the commandline, and to supply additional graphical information, in a simple, user-modifiable and user-extensible way.
-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 also gives access to structure solution, through George Sheldrick's SHELXC, SHELXD and SHELXE programs via the [[XDSGUI#SHELX|SHELX]] tab, and to Isabel Uson's [https://ibmb.csic.es/en/department-of-structural-and-molecular-biology/crystallographic-methods/ 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 .
@@ Line 24: / Line 24: @@
 * 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.
+* with SHIFT+(left-mouse-click) in the "Frame" tab one can set the direct beam impact position (useful if detector is not at 2theta=0).
 * 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 .
@@ Line 38: / Line 38: @@
 === 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. After XDS has indexed spots, they can be visualized with the *predictions* button.
+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:
@@ Line 97: / Line 99: @@
 * The third item ("Optimizing data quality") offers commands that manipulate [[XDS.INP]] in several ways. Please note: the popup "XDS.INP has been changed externally" is emitted by the Qt system and cannot be switched off. It appears if one of the scripts changes XDS.INP while it is opened by XDSGUI (which is always the case) . Thus, one should simply press the "Reload" button. The user-definable command may be used e.g. for <pre>echo RELRAD=7 ! default is 5 >x; grep -v BEAM_DIVERGENCE XDS.INP >>x; cat x > XDS.INP; rm x</pre> This provides more pixels to the background estimation (for another INTEGRATE), and is useful for weakly exposed data sets which have mostly pixels with zero counts.
-* The last item ("Further analyses") offers useful commands. "determine spacegroup with pointless" runs [[pointless]] against the XDS_ASCII.HKL file. The button "show spots in reciprocal space" runs [[spot2pdb]] to show you the reflections of SPOT.XDS in reciprocal space, with coot. You see the reflections that could be indexed in IDXREF in yellow, the not-indexed ones in pink, the rotation axis in blue and the origin as a blue cross. Ice rings and additional lattices can be easily identified - see [[spot2pdb]] for examples!
+* The last item ("Further analyses") offers useful commands. "determine spacegroup with pointless" runs [[pointless]] against the XDS_ASCII.HKL file. The button "show spots in reciprocal space" runs [[spot2pdb]] to show you the reflections of SPOT.XDS in reciprocal space, with coot. You see the reflections that could be indexed in IDXREF in yellow, the not-indexed ones in pink, the rotation axis in blue and the origin as a blue cross. Ice rings and additional lattices can be easily identified - see [[spot2pdb]] for examples! Reason for possible failure: the spot2pdb program expects SPOT.XDS to have 7 columns, as IDXREF attaches 3 columns with indices to the 4 columns that COLSPOT wrote. So you cannot visualize SPOT.XDS from COLSPOT - it has to be written by IDXREF.
 * Useful scripts for user tools are shared in [[XDSGUI User tools]]
@@ Line 169: / Line 171: @@
 # 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 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.
+# Error pop-up "image conversion failed", and frames from HDF5-files (*master.h5) are not being displayed: the symptom is that the frames appear to be empty/blank. This is an error message not from XDS (the data processing program), but from XDSGUI (the graphics program). It 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 (or Preferences on Mac)"->insert "/usr/local/lib64/dectris-neggia.so" as "generic frame library", or try "/usr/local/lib64/durin-plugin.so" for DIAMOND data. Alternatively and even better, export the environment variable DURIN_PATH=/usr/local/lib64/durin-plugin.so or NEGGIA_PATH=/usr/local/lib64/dectris-neggia.so . 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. Please read [[Installation#other%20programs:%20XDS-viewer%2C%20XDSSTAT%2C%20XDSCC12%2C%20XDSGUI%2C%20XSCALE%20ISOCLUSTER%2C%20generate%20XDS.INP|https://wiki.uni-konstanz.de/xds/index.php/Installation#other_programs:_XDS-viewer,_XDSSTAT,_XDSCC12,_XDSGUI,_XSCALE_ISOCLUSTER,_generate_XDS.INP]]
+# On Linux desktops with Wayland (e.g. KDE Plasma), xdsgui should be started with "QT_QPA_PLATFORM=xcb xdsgui" if xdsgui does not show the proper tabs content.
 If you find a bug, please send email to Kay dot Diederichs at uni-konstanz dot de , with enough information/data to reproduce the bug ("it does not work" is not enough!).
@@ Line 192: / Line 195: @@
 Version 2023-12-29 now displays CBF files written at PETRA-III BLs.
+Version 2024-11-04: Made tool categories and all button descriptions customizable. Prediction tool has note about customization. Add line-break to INTEGRATE graph for missing data regions. Works on Wayland. Bug fixes. (Juno Krahn)
+Version 2025-05-15: Fix bug that SHELXC could not work with long paths (77 characters) to XDS_ASCII.HKL.
 == See also ==