XDSGUI: Difference between revisions

1,891 bytes added ,  16 June 2013
no edit summary
No edit summary
No edit summary
Line 1: Line 1:
XDSgui is a GUI (graphical user interface) for academic users of 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.
== How to use the GUI ==
The program may be used to analyze graphically any existing directory with files earlier written by XDS, or may be used to create these files. It should be started in a terminal window which will show the output of the programs that are run (xds, pointless, xdsconv, ...).
The user is supposed to use the tabs on the top, from left to right.
Thus, one starts with the choice of the processing directory ("Projects" tab), goes to the "Frame" tab to display a raw dataframe, or a .cbf file written by XDS, or a .pck file written by XDSSTAT. Within the "Frame" tab, XDS.INP may be generated. Then, untrusted (shaded) areas may be marked with the mouse which will write the appropriate lines to XDS.INP, ORGX ORGY may be corrected if necessary, and the INCLUDE_RESOLUTION_RANGE, EXCLUDE_RESOLUTION_RANGE and TRUSTED_REGION adjusted as required. The latter operations are interactive in the sense that the user modifies the values in XDS.INP, and then checks the result in the Frame tab. In other words, the user moves back and forth between the Frame and the XDS.INP tab.
After finally moving to the XDS.INP tab, 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 TOOLS tab may be used to optimize the data processing, using those three operations that I found most useful in this respect. Ideally, each of these should be tried separately, and its effect should be compared with the previous processing to verify that it really improved the processed data - use [[ISa]] to decide whether the processing has improved!
Finally, the data may be analyzed with XDSSTAT and the resulting XDS_ASCII.HKL may be converted to e.g. MTZ, using the XDSCONV tab.
== Tabs ==


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


=== Projects ===


== Projects ==
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 .


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 .
=== 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 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 (and only values from XDS.INP, not the refined ones from XPARM.XDS) is used to calculate the resolution; this e.g. does not take care of detector swingout or otherwise skew geometry.


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 (and only values from XDS.INP, not the refined ones from XPARM.XDS) 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.
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.


== XDS.INP ==
=== XDS.INP ===
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). <br>
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). <br>
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.
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 ==
=== XYCORR ===
 
=== INIT ===
=== XYCORR, INIT, COLSPOT, IDXREF, DEFPIX ===
=== COLSPOT ===
=== IDXREF ===
=== DEFPIX ===


each tab shows its .LP file, respectively.
each tab shows its .LP file, respectively.
Line 34: Line 52:
The border between the left and right side of the window may be adjusted with the mouse.<br>
The border between the left and right side of the window may be adjusted with the mouse.<br>


== TOOLS ==
=== TOOLS ===


offers possibilities for running short scripts.  
offers possibilities for running short scripts.  
Line 46: Line 64:
The third item ("Saving and comparing good results") offers commands to save/restore the current data processing files to/from a "save" directory.
The third item ("Saving and comparing good results") offers commands to save/restore the current data processing files to/from a "save" directory.


The last item ("Further analyses") may be used for commands that e.g. run [[pointless]] against the XDS_ASCII.HKL file.
The last item ("Further analyses") may be used for commands that e.g. run [[pointless]] against the XDS_ASCII.HKL file. The user-definable commandline may be used e.g. for
phenix.xtriage XDS_ASCII.HKL


== XDSSTAT ==
=== XDSSTAT ===


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


== XDSCONV ==
=== XDSCONV ===


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.
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.
Line 76: Line 95:
and to start the GUI from a terminal window, by typing xds-gui .
and to start the GUI from a terminal window, by typing xds-gui .


== Known bugs / problems / workarounds ==
== 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 (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.
# ''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 (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.
# ''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 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.
# ''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 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.
2,684

edits