2,684
edits
(→Libraries and software that the program depends on: remove hint to libpng12.so) |
m (→Installation: clarify) |
||
(30 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
XDSGUI is a GUI (graphical user interface) for XDS that is supposed to help both novice and experienced users. | 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. | 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. | ||
Line 20: | Line 21: | ||
=== Technical aspects of XDSGUI usage === | === Technical aspects of XDSGUI usage === | ||
* the simple editor operating in the | * 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. | * ctrl-+ (control-plus) and ctrl-- (control-minus) enlarge or decrease the font size of characters. | ||
* flexibility of operation: all commands in the | * 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. It should be obvious what to change. | ||
* Menu / Settings is used for setting "Paths" for binaries (xds_par, xscale_par, shelxc/d/e, ... | * Menu / Settings is used for setting the name of a "generic library" (e.g. /usr/local/lib64/dectris-neggia.so) for reading HDF5 files, "Paths" for binaries (xds_par, xscale_par, shelxc/d/e, ...), and "Appearance" (font size and default plot height). The Settings menu can be opened on the Mac by going to "Preferences", or pressing the "Command" (⌘) key and the "," key. | ||
== Tabs == | == Tabs == | ||
Line 91: | Line 92: | ||
* The second 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. If [http://www.globalphasing.com/autoproc autoPROC] is installed, I suggest to use the "User defined command 2" for <code>mkdir staraniso; cd staraniso; aP_scale -hkl ../XDS_ASCII.HKL; echo anisotropy-corrected files are in staraniso subdirectory</code>. | * The second 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. If [http://www.globalphasing.com/autoproc autoPROC] is installed, I suggest to use the "User defined command 2" for <code>mkdir staraniso; cd staraniso; aP_scale -hkl ../XDS_ASCII.HKL; echo anisotropy-corrected files are in staraniso subdirectory</code>. | ||
* 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 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") | * 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! | ||
=== statistics === | === statistics === | ||
Line 128: | Line 127: | ||
=== 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]]. [[Eiger]] data processing requires | 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 (needs autoPROC license). 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. | |||
The XDSCONV functionality requires a working CCP4 installation for conversion to MTZ files. Likewise, XDSSTAT (in the ''statistics'' tab) needs CCP4. | |||
Technically, the word "dependency" means that these scripts/programs should be in your $PATH - an 'alias' is often not good enough because the commands in the ''tools'' tab use <code>bash</code> as a shell, and that shell does not inherit the aliases from e.g. (t)csh. | |||
If you use the <code>get_folder.sh</code> script as explained in [[Installation]], most of these dependencies are checked, and binaries are downloaded. | |||
=== Installation === | === Installation === | ||
The | The program can be downloaded, by academic users, as Qt5 binary for Linux [https://{{SERVERNAME}}/pub/linux_bin/xdsgui 64bit] (compiled on RHEL6) and as Qt4 binary for [https://{{SERVERNAME}}/pub/mac_bin/xdsgui_qt4.dmg Mac] (works on OSX 10.6 and up). | ||
A Qt4 version for [https://{{SERVERNAME}}/pub/linux_bin/xdsgui.qt4 old Linux distributions], and a Qt5 version (attention: needs Qt5 installation!) for [https://{{SERVERNAME}}/pub/mac_bin/xdsgui_qt5.dmg latest MacOS] is also available. | |||
Industrial users: pls contact me directly. | Industrial users: pls contact me directly. | ||
The easiest way to install XDSGUI, and all XDSGUI-related programs is documented in [[Installation]]. | The easiest way to install XDSGUI, and all XDSGUI-related programs is documented in [[Installation]]. | ||
If you want to install manually, in case of Linux, after downloading the binary file, its name should be changed to "xdsgui" and then be made executable ("chmod a+x xdsgui"). The binary may then be copied into e.g. the directory /usr/local/bin by the administrator, or to the $HOME/bin directory by the user. Any other directory should be suitable as long as it is in your $PATH. In case of MacOS, 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 | 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 | '''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/ | sudo ln -s /Applications/XDS-Viewer.app/Contents/MacOS/XDS-Viewer /usr/local/bin/xds-viewer | ||
==== Libraries and software that the program depends on ==== | ==== Libraries and software that the program depends on ==== | ||
Procedures for identifying and installing missing libraries are given in the [[Installation]] article. | |||
On the '''Mac''' (e.g. Yosemite) one needs the (free) [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 Xcode] command line tools installed. | |||
If on '''Linux''' you get an error message like | |||
''' | xdsgui: error while loading shared libraries: libQtGui.so.4: cannot open shared object file: No such file or directory | ||
xdsgui: error while loading shared libraries: | or similar for libQtCore.so.4 or libQtOpenGL.so.4 , you should install the Qt5 version which is now the default on Linux. | ||
== Known bugs, problems and workarounds == | == Known bugs, problems and workarounds == | ||
# ''Question: the program prints'' <code> Object::connect: No such signal XdsconvTab::signalSetTabEnabled(QWidget*,bool) Object::connect: (sender name: 'xdsconv') Object::connect: (receiver name: 'tabWidget')</code> ''What's wrong?'' Answer: nothing is wrong. Just ignore this; it's a debugging output. | |||
# ''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. | # ''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. 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. | ||
Line 185: | Line 169: | ||
# ''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. | # ''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. | ||
# on a Mac, you may find a stream of the following error messages in the console window: <code>Jan 31 14:35:17 xdsgui[20939] <Error>: Error: this application, or a library it uses, has passed an invalid numeric value (NaN, or not-a-number) to CoreGraphics API and this value is being ignored. Please fix this problem. Jan 31 14:35:17 xdsgui[20939] <Error>: If you want to see the backtrace, please set CG_NUMERICS_SHOW_BACKTRACE environmental variable.</code> This sounds terrible, but is actually harmless. Since it is a message from Qt (which XDSGUI uses for graphics), ''it does not compromise the XDS data processing in any way''. If it bothers you, just suppress the printout of these messages, by <code>xdsgui 2>&1 | egrep -v 'CoreGraphics|CG_NUMERICS'</code> | # on a Mac, you may find a stream of the following error messages in the console window: <code>Jan 31 14:35:17 xdsgui[20939] <Error>: Error: this application, or a library it uses, has passed an invalid numeric value (NaN, or not-a-number) to CoreGraphics API and this value is being ignored. Please fix this problem. Jan 31 14:35:17 xdsgui[20939] <Error>: If you want to see the backtrace, please set CG_NUMERICS_SHOW_BACKTRACE environmental variable.</code> This sounds terrible, but is actually harmless. Since it is a message from Qt (which XDSGUI uses for graphics), ''it does not compromise the XDS data processing in any way''. If it bothers you, just suppress the printout of these messages, by <code>xdsgui 2>&1 | egrep -v 'CoreGraphics|CG_NUMERICS'</code> | ||
# there is a bug in | # there is a bug in XDSGUI that prevents it from displaying .h5 files. The symptom is that the frames appear to be blank. The workaround is: go to (upper left) "Menu"->"Settings"->remove the string "/usr/local/lib64/dectris-neggia.so" from "generic library", and install <code>H5ToXds</code> or <code>hdf2mini-cbf</code> as explained above. | ||
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. | 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!). | ||
== Limitations == | == Limitations == | ||
Line 196: | Line 178: | ||
* 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 INCLUDE_RESOLUTION 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 (curved) Pilatus 12M, the calculations in XDSGUI do not give the correct results. | * The green INCLUDE_RESOLUTION 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 (curved) Pilatus 12M, the calculations in XDSGUI do not give the correct results. | ||
* 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 currently does not work properly. Therefore, <code>H5ToXds</code> or <code>hdf2mini-cbf</code> should be installed as explained above. | |||
== News == | == News == | ||
Line 229: | Line 212: | ||
update April 17, 2019: Arcimboldo programs are available through the ARCIMBOLDO tab. | update April 17, 2019: Arcimboldo programs are available through the ARCIMBOLDO tab. | ||
update October 22, 2020: Qt4 (xdsgui) and experimental Qt5 (xdsgui_qt5) versions with improved TOOLS, and bugfixes. | |||
== See also == | == See also == | ||
Video [https://www.youtube.com/watch?v=yN2gk_PtWeY Running XDS (and xdsgui) on Windows 10 build 14361] by Gustavo Machado Alvares de Lima | |||
[[Installation]] | [[Installation]] |