The phenix.refine graphical interface
- GUI overview
- Launching
- Configuration
- Automatic parameter updates
- Creating restraints
- Neutron crystallography
- Atom selection
- Running phenix.refine
- Acknowledgements
- References
GUI overview
The graphical interface for phenix.refine runs the unmodified command-line
version; default settings are unchanged. All parameters should be
configurable through the GUI, although some of these (such as NCS restraint
groups) are handled in a non-standard way. This document describes the
behavior of the GUI only; see the phenix.refine
documentation for details on specific parameters and methods.
At present the GUI has the following capabilities:
- automatic extraction of parameters from PDB and reflection files
- detection of unknown ligands, and generation of restraint files
- graphical mirroring and picking of any atom selection
- project-specific default settings and restraints
- NCS restraint group detection and editing tool
- real-time visualization of current model and maps during refinement
- model validation using programs from the Molprobity server
- graphical comparison of structure quality measures
- printable plots of final statistics
This software is still under development; to report any problems with
normal operation, please send email to bugs@phenix-online.org.
Launching
The GUI can be started by typing phenix.refine_gui, or by clicking the
phenix.refine button in program list of the main GUI window.
Any combination of PDB, CIF, reflection, and parameter (.param or .eff) files
may be specified on the command line. Most keyword parameters used in the
command-line version of phenix.refine should work as well.
The GUI uses a database of projects to track default settings and job
history for a structure or group of related structures.
The current project will be guessed based on the directory from which
PHENIX is launched; if not determined, a dialog window will be opened
prompting the user to enter a project ID and directory path. Although this
is not required for the GUI to function, we recommend using projects to
track preferences and data files specific to your structures. In some
cases, such as creating custom restraints files, this will be done for you
automatically.
Configuration
Because phenix.refine currently has nearly 500 distinct parameters, many
of which rarely need changing, and the window controls are mostly created
automatically, advanced settings are hidden by default. The "user level"
may be set within each window, or set globally in the Preferences. For
instance, the "Miscellaneous settings" dialog looks like this when the
user level is "Basic":
The same window on the "Advanced" setting:
The most important parameters (input and output files, strategy, additional
procedures such as solvent updating and simulated annealing) are shown
in the main window.
Some commonly-used settings are accessible via buttons on this screen; many
of these will open additional dialog windows in response to mouse clicks
or file selection. In many cases, you can open these windows on demand
by right-clicking on the appropriate control (for instance, right-clicking
the "Rigid body" strategy button will show the atom selection controls for
defining rigid groups). All other parameters can be found in the Settings
menu, which can also be displayed by right-clicking on any empty section
of the main window:
Automatic parameter updates
If your reflection and/or PDB files have the appropriate information on
crystal symmetry and data labels, parameters will be propagated to the
GUI. A detailed example is shown below for a reflection file containing
R-free flags and experimental phases:
These settings can be changed later by clicking any of the buttons below
the list of input files. Any valid space group symbol may be used (for
instance, '19', 'P212121', and 'P 21 21 21' are all equivalent). Data
labels are restricted to the suitable columns found in the reflection file.
Creating restraints
If the PDB file contains ligands or prosthetic groups that are not part of
the limited monomer library distributed with PHENIX, a warning message will
be displayed when the file is loaded. The necessary restraints must be
generated by phenix.elbow in order for refinement to proceed. To start
this process, click the ReadySet button in the toolbar or choose
"Prepare structure and restraints" from the Utilities menu. This will
launch a dialog for running phenix.ready_set, a simple utility for
preparing structures for phenix.refine.
Generating the restraints will take between 30 seconds and several minutes,
depending on computer speed and the size of the ligand. When ReadySet is
finished, another window will be displayed summarizing the results. If
a project directory is defined, these can be saved for future runs and
will be automatically loaded into the GUI when launched.|br|
If your input model does not contain hydrogen atoms and you would like to
use them in refinement, this can also be done via the ReadySet dialog, or
by clicking the box labeled "Automatically add hydrogens to model" in the
main window.
Neutron crystallography
phenix.refine can perform refinement using either X-ray data, neutron
diffraction data, or both. You can change the type of data contained in a
reflections file by right-clicking on the "Data type" field in the file list.
At present, phenix.refine always requires that you define an X-ray dataset;
this constraint will be removed in future versions. If you are performing
refinement against neutron data alone, you must treat the reflections as if
they were X-ray data. All of the data options remain the same, and will
be extracted automatically. You must change the scattering table to
"neutron" by clicking the "Other parameters. . ." button at the bottom of
the configuration window. If you are doing joint X-ray/neutron refinement,
you should leave the scattering table set to the default, and specify one
reflections file as neutron data (or both). Parameters for neutron data
are not chosen automatically; once you have specified a neutron reflections
file, click the "Neutron data. . ." button to select the column labels for
the data and test set.
If you need to add hydrogens and deuteriums to your model before running
phenix.refine, do not click the "Automatically add hydrogens" button in
the main window. Instead, click the ReadySet button in the toolbar or
select "Neutron crystallography" from the Utilities menu. This will allow
you to choose if and where to add deuterium or hydrogen atoms. If your
model already includes these atoms, you do not need to run ReadySet.
Atom selection
The atom-selection syntax used by PHENIX is described in the
phenix.refine manual. In the GUI, any valid
atom selection can be visualized if you have a suitable graphics card
and have already loaded a PDB file with valid symmetry information. The
graphics window can be opened by clicking the "View/pick" button next
to any atom selection field. Depending on the size of your structure, it
may take several seconds for PHENIX to determine the atomic connectivity.
The current selection, if any, will be highlighted:
The Select atoms button opens a window that allows you to type in
selections and immediately visualize the results, including the number of
atoms selected. On mice with at least two buttons, clicking on an atom
with the right button will open a menu for selecting residue ranges or
chains. However, we
recommend that you learn the selection syntax, as it is much more flexible
than mouse controls. Selections made in the graphics window will be sent
automatically to the appropriate control.
Once this window is open, it does not need to be closed; clicking a different
"View/pick" button will transfer control of the display. (On Linux, you
will first need to open the Actions menu and click Restore parent window
to transfer mouse and keyboard controls back to the configuration dialog.)
Running phenix.refine
Each time phenix.refine is run from the GUI, a new folder is created
(in the current output directory) named Refine_X, where X is an integer.
This directory will contain all temporary and output files created during
the course of the run. Existing folders will not be overwritten. All
output files will be displayed in the GUI in the results tab.|br|
Once you are done configuring refinement, switch to the Run tab in the
main window and start the process by clicking the "Run" button. The
log output will appear in the central window:
Statistics will be continually updated; any that appear to be outliers
(e.g. excessively high R-factors) will be highlighted in red. If an
error occurs during refinement, a message box will pop up and the process
will be halted. Once the refinement is complete, another tab will appear
containing the final statistics, buttons for opening the refined structure
in Coot and PyMOL, and a validation summary.
Acknowledgements
The electron-density isosurface code in the CCTBX was contributed by
Luc Bourhis.
Some of the icons used in the GUI came from the Crystal Icons project which is licensed under the LGPL.
References
- phenix.refine :
Afonine, P.V., Grosse-Kunstleve, R.W. & Adams, P.D. (2005). CCP4 Newsl.
42, contribution 8.
- Molprobity :
Davis IW, Leaver-Fay A, Chen VB, Block JN, Kapral GJ, Wang X, Murray LW,
Arendall WB 3rd, Snoeyink J, Richardson JS, Richardson DC.
MolProbity: all-atom contacts and structure validation for proteins
and nucleic acids.
Nucleic Acids Res. 2007 35:W375-83.
- POLYGON :
Urzhumtseva L, Afonine PV, Adams PD, Urzhumtsev A.
Crystallographic model quality at a glance.
Acta Cryst. 2009, D65:297-300.
|
