From XDSwiki
Revision as of 08:09, 7 June 2013 by Kay (talk | contribs)
Jump to navigationJump to search

XDSgui is a GUI (graphical user interface) for XDS that is supposed to help both novice and experienced users. It graphically displays the ASCII and 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.

The main window of XDSgui has the following sub-windows organized as tabs:


stores names of directories which contain files from XDS processing. If none of these is selected, the current directory is used. A new directory may be created. The list of project directories is saved to ~/.xds-gui .


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 for the raw data frame that is being displayed. The blue circles correspond to the areas of the detector that are within TRUSTED_REGION; the green circles correspond to INCLUDE_RESOLUTION_RANGE, and the red hatched regions correspond to EXCLUDE_RESOLUTION_RANGEs. The locations of the circles are not as accurate as those that XDS uses internally, because a simplified formula is used to calculate the resolution; this e.g. does not take care of detector swingout or otherwise skew geometry. 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 shown in the XDS.INP tab.


this shows the current XDS.INP file. Coloured items correspond to the circles of the FRAME tab. Changes can be made with the simple editor, and the new version can be saved. A run of xds_par can be started (and killed).
The XDS.INP tab is directly connected with the FRAME tab; changing a value in the XDS.INP tab results in immediate change in the FRAME tab. This means that e.g. an UNTRUSTED area that was positioned wrongly can be edited or simply removed in the XDS.INP tab.

Output from XDS


each tab shows its .LP file, respectively.


shows INTEGRATE.LP on the left side. During the INTEGRATE step, the temporary files are displayed. On the right side, plots of the tabular quantities given for each frame, or for each batch of data are shown. For the refined quantities, only the changes are plotted. THE SIGMAB (beam divergence E.S.D.) and SIGMAR (mosaicity) plots show these quantities estimated from each frame (blue), refined for each batch (green) and averaged over the whole dataset (red horizontal line).
The border between the left and right side of the window may be adjusted with the mouse.


shows CORRECT.LP on the left, and plots of tabular quantities on the right. The upper line in the I/sigma (unmerged data) plot gives [math]\displaystyle{ {I/Sigma(I)}^{asymptotic} }[/math] ([Diederichs, Acta Cryst. (2010). D66, 733-740 http://dx.doi.org/10.1107/S0907444910014836]). The three lines in the Chi^2 plot are the Chi^2 values obtained during scaling, for the ABSORP, MODPIX and DECAY corrections, respectively.
In the lower plots, the colored lines correspond to the nine resolution shells for which values are found in the tables.
The border between the left and right side of the window may be adjusted with the mouse.


offers possibilities for running short scripts. Several such scripts are pre-defined; the user may create her own scripts. If scripts are modified, they are saved to ~/.xds-gui .
The first item offers to run XDS-viewer for displaying the predicted pattern of reflections for a user-specified frame, together with the frame itself. The file FRAME.cbf is renamed to FRAME_$X.cbf (where X is the user-specified frame number) and remains in the temp subdirectory. It may of course be opened in the FRAME tab, but starting XDS-viewer automatically means that several frames with predictions may be inspected on the screen, at the same time.
The other pre-defined scripts run commands that either simplify to save/restore the current data processing files to/from a "save" directory, or to manipulate XDS.INP in several ways, or to run e.g. pointless on the generated XDS_ASCII.HKL file.

The popup "Warning: 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 XDS-gui (which is always the case) . Thus, one should simply press the "Ok" button.


This tab allows to run XDSSTAT at the press of a button. As soon as XDSSTAT.LP exists, it displays the main plots derived from it. Another button allows to run XDS-viewer to visualize the control images that XDSSTAT generates, namely anom.pck, scales.pck, rf.pck, misfits.pck, corr.pck, rlps.pck, peaks.pck and nobs.pck .


a simple XDSCONV.INP is provided by default. It may be edited by the user, and saved. Upon clicking a button, xdsconv is run and if necessary a MTZ file is produced. XDSCONV.LP may be displayed.


The program is under development and has bugs. If it crashes, it should simply be restarted. A crash of the program does not interfere with the operation of XDS.

The current version of the program can be downloaded from [1] (Linux 64bit), [2] (Linux 32bit), or [3] (Mac OSX 10.7).


The program depends on the availability of generate_XDS.INP, XDS-viewer, and of course xds_par, xds, xdsconv, and xscale. The XDSSTAT tab requires xdsstat. One of the items in the TOOLS tab requires xdiff, but if that program is not available, xxdiff or tkdiff may be used - please adjust the commandline below the button accordingly.


program updated May 22 14:40 CEST, May 28 19:55 CEST

Known bugs / problems / workarounds

  1. Question concerning TOOLS: "Show frame..." on Mac: it creates everything shown in the commandline but it seem to us that everything runs in the background. Therefore xds-viewer does not open anywhere as it is not seen. Also, it would be great if this image together with the predictions would be re-directed to the FRAME tab.
    Answer: On Linux, the xds-viewer window is brought to the foreground automatically, whereas on the Mac this does not seem to happen. However, an icon for xds-viewer appears in the dock (on the right) and I can double-click it to see the xds-viewer window. I have no idea how to bring xds-viewer to the foreground automatically, and I need input from people who know Macs and tell me how to do it (on the commandline!). The reason why we do not open automatically in the FRAME tab is that one can have several xds-viewer windows open at the same time, and compare the patterns. As a workaround, you can manually open the resulting temp/FRAME_$X.cbf in the FRAME tab.
  2. Another question concerning TOOLS: "Further analyses" on Mac: again pointless runs nicely but there is no output for the user.
    Answer: Could it be that you started xds-gui 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 xds-gui was started. We will try to find out how to open a window where the output is then shown. Thus, currently the workaround for this problem is to start xds-gui in a console window.