Newsletter contents... UP


The CCP4 Graphical User Interface

Liz Potterton

Chemistry Department, University of York, York Y01 4DD

lizp@yorvic.york.ac.uk

Introduction

I have been working for CCP4 since the beginning of 1997 on a new graphical user interface which should simplify running CCP4 programs and provide tools for reviewing and analysing results. There have been previous attempts at developing a user interface but none have prooved popular mostly because users found them too complicated. So we are very aware of the need to keep it simple this time. A Working Group II meeting last year produced guidelines for what was required:

  • based on free, distributable software
  • easy to port and maintain
  • possible for someone other than the original developer to modify and extend
  • user not 'locked in' to using the interface
  • simple interfaces, everything in one place and not too many windows
  • does not need to be comprehensive, consider the needs of a novice user first
  • Most of the work so far has been on an interface to run the programs - tools for reviewing and analysing results will come later.

    Why Tcl/Tk?

    A major issue in designing the user interface was choosing a language to work in. The ubiquity and familiarity of web browsers made some combination of HTML/Java/Javascript attractive but there seems to be two drawbacks with this system:

  • The client side of the system can not straightforwardly access disk so it can not read files or even list files which a file browser would need to do. We want the user interface to access files, particularly MTZ files to extract the names of column labels and information such as space group and resolution range.
  • It is difficult to get 'intelligently dynamic'web pages (unintelligently dynamic pages are another matter!) - that is pages which are customised in response to user input. Given the complexity of input to many CCP4 programs it is desirable to customise the interface after the user has made a key decision so they only see relevant parts of the interface with reasonable preset defaults.
  • These problems may not be unsurmountable but Tcl/Tk seemed a far more attractive option as it provides all the tools we need and is straightforward to use. Tcl is a scripting language and Tk is a graphics toolbox which includes tools for 2D graph drawing which will be useful in future. The package is free and runs on many systems including UNIX, LINUX,VMS, Windows and Macs. Another advantage is that the RasMol program developed by Roger Sayle, now at Glaxo, has a Tk interface which will make it possible to set up communication between RasMol and any Tk programs.

    Running CCP4 Programs - Task Windows

    A task window is one window which provides the interface to, usually, one CCP4 program. Where appropriate more then one program may be accessed from one task window, for example the FFT interface to generate maps can also run the Extend program to extend a map and also jiffy programs to convert the map format.

    Everything to run one task is in one window; this could quickly lead to information overload for the user but not all of the window is always visible. The window is divided vertically into folders and within each folder are related parameters. The folders containing the less popular parameters are by default closed so the contents are not visible. The user can toggle folders open and closed.

    The task window for FFT is shown below.

    Here the two folders at the bottom of the display Exclude Reflections and Unusual Options are closed but could be opened by picking the toggle button on the right hand side of the folder title line. At the top of the window are the Protocol and File folders- these are not toggleable folders -they are always open. The Protocol folder contains parameters which control what is available and default values set in the rest of the interface. For example opting to draw a vector difference map rather than the current choice of difference map will change the MTZ input label fields in the File folder.

    In the File folder the user can select a file - a file browser is brought up by clicking the filing cabinet icon. When the user has selects an input MTZ file it is read and useful information such as resolution range an space group are extracted and entered as the defaults in the appropriate fields. The names and types of the labelled columns are also extracted and used to set up a pop-up menu for selection of input columns.

    One of the buttons at the bottom of the dialog box is an option to Save&Restore which will either save the current set parameters to file or restore previously saved parameters.

    After this quick tour of the window layout you should be able to find your way around the interface. There is always the Help button which links to HTML web pages and there is context dependent help wich will bring up help on the relevant parameter if you press the < F1> key when the cursor is over an input field. Also when the cursor is over an input field the message line at the top of the window will display one line of information about the parameter.

    The Main Window

    The individual task windows are accessed from a main window which looks like this:

    The contast colour field on the left (currently saying Refinement) is a pop-up menu to access the various modules of the interface, each module corresponds to a stage in the structure solution process. Beneath the module name is a list of the tasks in that module, click on one of these to open the appropriate task window. The large scrolling frame on the right is used to list such things as log files or, in this case, the header information from an MTZ file generated using mtzdmp.

    The Comments button on the bottom left will enable you to enter a message in a text editor and then mail it off, automatically, to the program developer. I am trying to encourage user feedback!

    The Job Database

    The interface includes some simple database functionality to keep track of the structure solution process. You should set up a different database for each structure project you are working on and the interface will allow easy switching between different project databases.

    The database automatically keeps a record of every task run by saving the def file which contains the parameters used to run each task including the names of input and output files. Data files are not saved automatically but the interface will provide a simple mechanism to archive and restore data files and will keep a record of their context in the overall process.

    The interface to the database is shown below. On the left of the window is a list of the jobs which are currently running or have completed with some information on their date/time of running and status. Other information such as output data file names could also be listed to help identify the job. On the right is a list of database options. The user can select a job from the list on the left and then pick a function on the right.

    The functionality associated with the database includes:

  • Reviewing log files and displaying graphical data in a form similar to the current xloggraph program.
  • Deleting temporary filescreated while running the job.
  • Archiving data files. This is saving a compressed version of the file in a 'safe' directory with a record of which job created the file.
  • Rerunning a task - with the option to change some input parameters.
  • A notebook which the user can edit to enter comments associated with each job.
  • Interteraction with Data Harvesting tools which will simplify Data Deposition.
  • Future Plans

    The first release of the interface will be part of the main CCP4 release in middle of 1998. This release should include interfaces to most commonly used CCP4 programs and the Job Database system. Intended for the future are:

    2D Graph Plots which initially will be used to produce xloggraph style presentation of program out but which should be flexible enough for users to define their own data input and graph style. Tcl/Tk has tools for producing postscript files.

    Interface to RasMol 3D molecular visualisation program to improove presentation of results and possibly also to simplify atom selection.

    Plotting 2D Map Sections (and atom/vector positions) with some interactive tools this is particular useful for solving Pattersons.

    MTZ File Editor and Data Analysis

    Further suggestions are welcome.

    Running the GUI on Different Platforms

    The GUI is expected to run, as is, on any UNIX or LINUX platform. The GUI is written in Tcl/Tk which is interpreted at run time rather than compiled so the GUI does not need to be built but it will be necessary to have Tcl7.6 and Tk4.2 (or later versions) installed. This software is available free from several web sites and the GNU-style installation should be straightforward.There is a Tcl/Tk utility called ET which could enable us to bundle the Tcl/Tk executables and the GUI code to appear as one executable so it may be possible for CCP4 to provide an 'executable' for some popular platforms.

    A prototype of the GUI has run on a Vax VMS system with no major problems. There are two recognised issues with porting to VMS:

  • the current VMS version of Tcl/Tk is not up to date and does not support a couple of useful (but not absolutely essential) functions
  • some GUI functionality, particularly operations such as moving and deleting files, are implemented by calls to system routines and so are machine dependent
  • Tcl/Tk runs on Macs and various Windows systems so, in principle, the GUI could be ported to these systems.

    Just for Programmers...

    ..this is a brief overview of how the GUI is programmed.

    The GUI program has two distinct layers - the core and the task interfaces. The core code includes:

  • general utilities such as file browser, database, the main window
  • CCP4 specific utilities for example reading MTZ file headers
  • a library of functions for creating task interfaces
  • a library of functions for use in run scripts
  • The basic core utilities are not CCP4 specific and could be used to interface to any program. The task interface side of the interface is intended to be simple and accessible to allow anyone to create or modify an interface to a program. For each task interface there are three files to define a task window and then run the program(s). The files are:

    The Definition File

    This contains a list of the names of all the parameters used in the interface , their data type and initial default values. The files used to Save&Restore the interface status are in the same format.

    The Tcl File

    This file describes the appearence of the task window. It is written in the Tcl scripting language but uses very few basic Tcl commands as it is based on the CCP4 interface library and should be comprehensible to someone with minimal knowlede of Tcl.

    The Script File

    The script file runs the program and is similar to the usual CCP4 com files. It has the advantage that, since it is written in Tcl, one file can run on all platforms (at least all the ones which support the interface!). Since these scripts do have to cope with all possible options they are not always very readable but the majority of users should have no need to look at these files. Rather than saving and/or editting a script file a user should save a definition file using the Save&Restore option.

    An Example

    Here is an example of what appears in each of the above files to handle the space group which appear in FFT task window shown above.

    In the fft.def file:

    SPACE_GROUP     _space_group             "P1"

    The first column contains the parameter name, the second is the data type and the third is the initial default value. The data types are defined in a separate types.def file. The data types can be simple generic types such as _logical or _positivereal or more complex such as _space_group which can only take values which correspond to space group names or numbers read from a dictionary file. If the user enters an invalid space group name they will be warned.

    In the fft.tcl file:

      CreateLine line \
          message "Space group (default as in MTZ file) (FFTSPACEGROUP)" \
          help "fftsgp" \
          label "Generate map in space group" \
          widget SPACE_GROUP

    The backslash at the end of the Tcl line is a line continuation character so this is one command line laid out to be more readable. This calls the CCP4 interface routine CreateLine which returns a line id line. There can be any number of subsequent arguments which are interpreted as a list of pairs of parameter types and parameters.

    The message and help parameters define the context sensitive information which is available to the user if the cursor is in the space group input field. The message parameter is a line of text which will appear in the message line at the top of the window. The help parameter is a key to find the appropriate help text if the user picks the help function key <F1>.

    The label and widget parameters define the text which appears in the interface and the parameter that the input field is tied to. The CreateLine function uses the information about the data type of the parameter SPACE_GROUP to determine what type of widget to draw.

    Further arguments can be added to the CreateLine input to build up a more complex input line. The FFT interfacein the picture above has the scale amplitudes input fields on the same line as the spacce group input.

    The fft.run file is created when the program is run. It is based on a template file called fft.script but has the additional information of parameters taken from the task window. At the top of this file are definitions of the values for all the parameters taken from the interface. For example:

    set SPACE_GROUP P3121

    Within the run script another temporary script file is created which is the command file read by the program. The appropriate coomand line is written to this temporary file:

    WriteTmpFile "FFTSPACEGROUP $SPACE_GROUP"

    The run script will run the CCP4 program(s) and when they have finished send a message to the GUI database to inform it that the job is completed.


    Newsletter contents... UP