→Libraries and software that the program depends on: small fixes
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 [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.
== How to use XDSGUI ==
After finally moving to the [[XDSGUI#XDS.INP|XDS.INP]] tab, other parameters can be adjusted by the user, and finally XDS may be run by clicking a button. The resulting output files from XDS will then be displayed in the next tabs.
After finishing this first round of processing, the [[XDSGUI#TOOLS|TOOLS]] tab may be used, which - among other things - offers those three options that I found most useful to optimize the data processing. After choosing (by mouse click) one of these three options, the user should go back to the [[XDSGUI#XDS.INP|XDS.INP]] tab, specify
JOBS=DEFPIX INTEGRATE CORRECT, and run XDS again. Ideally, each of the three options should be tried separately, and its effect should be compared with the previous processing to verify that it ''really'' improved the processed data. A significant increase in [[ISa]] (> 1%) indicates that the processing has improved; a slight decrease in ISa (<1%) often is accompanied by an increase of CC1/2 at high resolution, and thus should be tolerated.
Those options that improve ISa can then be used in combination.
* the simple editor operating in the XDS.INP, XDSCONV and XSCALE 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
(available since April 22, 2014).
* flexibility of operation: all commands in the 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.
== Tabs ==
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. Step-by-step:
* "Load" a raw frame or a CBF file (e.g. FRAME.cbf) to have it displayed. The pane can be "dragged" with the left mouse button; the mouse wheel zooms. 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 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 (say) "Untrusted Rectangle (2 clicks)"
=== [[IDXREF]] ===
detailed explanation of output: see [[IDXREF.LP]]
=== DEFPIX ===
The border between the left and right side of the window may be adjusted with the mouse.<br>
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 names of the buttons (e.g. "User defined command 1") can be changed by editing ~/.xds-gui .
* The first item of the left panel ("Show frame with predicted spots") generates the predicted pattern of reflections for a user-specified frame, overlaid on the frame, for display with [[XDS-viewer]]. The file FRAME.cbf (produced by INTEGRATE) 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 has the advantage that several frames with predictions may be inspected on the screen, at the same time. Please note: if the XDS directory resides in a FAT32 filesystem (which is often the case on a USB stick or disk), then "ln -s" should be replaced by "cp -p" since FAT32 does not support symlinks. Also note: for the script to work correctly, NAME_TEMPLATE_OF_DATA_FRAMES in XDS.INP has to specify an absolute, not a relative path.
* The second 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 commandline may be used e. g. for grep -v "JOB=" XDS. INP > x; echo "JOB= DEFPIX INTEGRATE CORRECT" > XDS.INP; cat x >> XDS. INP
* The third item ("
Saving and comparing good results") offers commands to save/restore the current data processing files to/from a " save" directory. Make sure to replace " xdiff" with "xxdiff" or "tkdiff", if one of the latter is available.
* The last item ("Further analyses") may be used for commands, e.g. running [[pointless]] against the XDS_ASCII.HKL file. The user-definable commandline may be used e.g. for
This tab allows to run [[XDSSTAT]] with a mouseclick. As soon as XDSSTAT.LP exists, the main plots derived from it are displayed.
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 .
=== XDSCONV ===
a simple XSCALE.INP is provided by default. It may be edited by the user, and saved. Upon clicking a button, [[xscale]] is run. XSCALE.LP may be displayed.
== Availability ==
The program is under development and probably has bugs. If it crashes, it should simply be restarted. A crash of the program ''does not interfere'' with the operation of [[XDS]]; likewise, closing the program window does not influence any XDS run started from XDSGUI.
=== Dependencies ===
XDSGUI depends on [[generate_XDS.INP]], [[XDS-viewer]], and of course [[XDS]] (both the xds and xds_par binaries!), and [[
XDSCONV]]. The XDSSTAT tab requires [[XDSSTAT]]. 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] may be used - please adjust the commandline below the button accordingly.
Technically, the word "dependency" means that these scripts/programs should be in your $PATH - an 'alias' is often not good enough because the TOOLS commands use bash as a shell, and that shell does not inherit the aliases from e.g. (t)csh.
=== Installation ===
The current version of the program can be downloaded, by academic users, for Linux [
ftp:// turn5.biologie.uni-konstanz.de/pub/xdsgui.rhel6.64 64bit] (compiled on RHEL6) , [ftp://turn5.biologie.uni-konstanz.de/pub/xdsgui.rhel6.32 32bit] (compiled on RHEL6), [ftp://turn5.biologie.uni-konstanz.de/pub/xdsgui.rhel5.64 64bit] (compiled on RHEL5, statically linked with Qt), [ftp://turn5.biologie.uni-konstanz.de/pub/xdsgui.rhel5.32 32bit] (compiled on RHEL5, statically linked with Qt), or [ ftp:// turn5.biologie.uni-konstanz.de/pub/xdsgui.dmg Mac] (works on OSX 10.6 and up). Industrial users of XDS: pls contact me directly.
In case of a '''Mac''', the DMG file may be installed in the usual way, by double-clicking it and dragging the icon into the Applications folder. '''It is advantageous to place a symbolic link, like'''
sudo ln -s /Applications/xdsgui.app/Contents/MacOS/xdsgui /usr/local/bin/xdsgui
'''and to start the GUI from a terminal window, by typing xdsgui'''. In a similar way, XDS-viewer should be put into the $PATH under the name xds-viewer, e.g. using
sudo ln -s /Applications/XDS-Viewer.app/Contents/MacOS/xds-viewer-bin /usr/local/bin/xds-viewer
Ubuntu 14.04''' has libmng2 instead of libmng. Therefore, on 32bit systems you should try sudo ln -s /usr/lib/i386-linux-gnu/libmng.so.2 /usr/lib/i386-linux-gnu/libmng.so.1 and on 64bit systems sudo ln -s /usr/lib/x86_64-linux-gnu/libmng.so.2 /usr/lib/x86_64-linux- gnu/libmng.so.1
if you get the error message
xdsgui: error while loading shared libraries:
libmng .so.1: cannot open shared object file: No such file or directory
== Known bugs, problems and workarounds ==
# ''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.'' <br> 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. 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.
# ''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
. 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 xdsgui in a console window.# both generate_XDS.INP and [[XDS]] do not seem to like 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 . version 0.45 of generate_XDS.INP makes a start towards a fix for this problem, but XDS also will have to be adjusted.
# ''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 re-downloading the script, and changing format to Plain - everything is working now.
If you find a bug, please send email to Kay dot Diederichs at uni-konstanz dot de ,
ideally with enough information/data to reproduce the bug.
== Limitations ==
* The program depends on [[generate_XDS.INP]] to interpret the header of the frames, so is currently limited to Dectris (Pilatus), ADSC (Quantum), Rigaku (several types)
and MAR (CCD and image plate) detectors. 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 oscillation range, wavelength, distance, and direct beam position (or rather: point of detector that is closest to the crystal). For fine-tuning of detector parameters, see the [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html detector-specific templates] . * The authors of [[generate_XDS.INP]] have made a "best effort" to provide a XDS.INP that results in the correct sign of the anomalous signal. In the case of one detector type (internally called Rigaku SMV) this requires reversal of one detector axis, and a negative DETECTOR_DISTANCE, as is found in some of the [http://xds.mpimf-heidelberg.mpg.de/html_doc/xds_prepare.html detector-specific templates]. '''For an unusual or unknown detector setup, the correct sign of the anomalous signal needs to be established and verified e.g. with a good dataset from a test crystal that has a anomalous signal.''' The authors do not take any responsibility for problems arising from incorrect sign of the anomalous signal, nor - obviously! - for any other mischief arising in or from data processing. * At some beamlines, the ROTATION_AXIS should be -1 0 0 ("backwards") instead of the usual 1 0 0 ("horizontal"), or even 0 1 0 ("vertical") like at one of the PETRA Hamburg BLs. We have no exhaustive list of these beamlines, and the frame headers do not have this information, so the default chosen by [[generate_XDS.INP]] may be wrong and need manual correction.
* The display of large frames in the FRAME tab may be slow over the network.
== News ==
update June 2, 2014: fix bugs
== See also ==