The phenix graphical interface
- Overview
- Running programs from the GUI
- Modules
- Reflection tools
- Model tools
- Phasing
- Molecular replacement
- Building and refinement
- Ligands
- Maps
- Validation
- Utilities
- Projects
- Preferences
- Coot integration
- PyMOL integration
- Reporting bugs
Overview
The Phenix GUI is primarily a frontend to the command-line programs, with
several extra graphical utilities for validation, map generation, and file
manipulations. The original GUI is still available but deprecated, and all
functionality has been more or less superseded. This page covers the main
interface and common behavior; individual program GUIs are covered separately.
The main GUI is started simply by typing the command phenix; by default,
it will also open automatically when you launch any of the individual
program GUIs. You should not run more than one instance of the GUI at a
time, to avoid conflicts with internal database files.
Running programs from the GUI
When starting a job, Phenix writes out a configuration file and calls the
command-line version of the program. By default, this is started directly in
the main process, i.e. "locally", which allows communication between the
program and the GUI in memory rather than via temporary files. The drawback
to this is that if the GUI is closed or crashes, the job will be ended too.
An alternate "detached" mode is available, which starts the job as an entirely
separate process. This limits the speed at which the GUI can be updated,
but allows quitting the GUI without stopping the job.
A third mode is to run jobs on a queueing system; while this could be done
entirely on a multi-core workstation, it will usually be spread across a
cluster of similar computers. Currently only Sun Grid Engine is supported.
To enable queued jobs, open the Preferences, switch to the "Processes"
tab, and check the box to enable queueing. The queue submission option will
now appear when starting a job. For this to work, the SGE binaries ('qsub',
'qstat', and 'qdel') must be in the current environment $PATH, Phenix
must be installed in the same location on all nodes, and the filesystem on
which the job is being run must be mounted on all nodes. The GUI will display
a "waiting" status until the job is actually started. The main interface
has a window for viewing the current queue status (Utilities->Show queue
status).
Modules
Individual programs are grouped by category. Except where noted, most of
these correspond to command-line programs, and the documentation for the
command-line version should be the primary reference for understanding
program behavior and inputs. Additional GUI documentation is available
for some programs.
Reflection tools
- Xtriage: reflection data analysis and quality
assessment; used to detect twinning and other pathologies.
- Reflection file editor: utility for
merging reflection files and creating or extending R-free flags. (GUI only)
- Calculate F(model): utility for generating structure
factors (as real or complex numbers) from a model alone.
Model tools
- PDB Tools: various model manipulations such as
modifying atom records, geometry minimization, and generating "fake"
structure factors.
- Combine PDB files: simple utility for merging models split over several
PDB files (such as massive complexes like the ribosome). Chain IDs will
be modified if necessary (using up to two characters).
- Superpose PDB files: structure alignment program.
- ReadySet: preparation of input files for refinement,
including generating restraints (CIF) files and adding hydrogens.
- NCS restraint editor: determine appropriate
restraint groups based on an existing PDB file.
Note that the ReadySet and NCS GUIs are also available as plugins to the
phenix.refine GUI, and do not necessarily need to be run separately.
Phasing
- AutoSol: automated experimental phasing for all
experiment types (SAD, MAD, MIR, etc.); also performs simple model-building
after phasing. Combines HySS, Phaser, SOLVE, RESOLVE, and phenix.refine.
- Phaser-EP: Another Phaser interface, for SAD and MR-SAD
phasing. We recommend trying AutoSol first, but this GUI exposes
additional parameters.
Molecular replacement
- AutoMR: automated molecular replacement using Phaser;
feeds directly into AutoBuild. (This is also the starting point for
running MR-SAD.)
- Phaser-MR: Interface for molecular replacement using
standalone Phaser, with all parameters available as well
as different modes of operation. We recommend starting with AutoMR
first, but this GUI is useful for tough cases.
- Sculptor: prepare a search model for molecular
replacement by trimming the structure, modifying B-factors, etc.
- Ensembler: tool for creating superimposed ensembles
of related MR search models.
Building and refinement
- Find Helices and Strands: fast building of
secondary structure (as poly-ALA) into maps with RESOLVE and PULCHRA.
Especially good for low-resolution data.
- AutoBuild: automated model-building and refinement with
RESOLVE and phenix.refine. This GUI only encapsulates the building
functions; a separate GUI is available for omit-map calculations.
- phenix.refine: automated refinement, supporting both
X-ray and neutron data. In addition to the features available in the
command-line program, the GUI version includes graphical atom selection,
simplified setup of restraints, automatic addition of hydrogens, and
post-refinement validation.
- Fit Loops: simple GUI for building missing loops into
a map based on a sequence and start model.
Ligands
- LigandFit: wizard for placing ligands in electron
density maps, accounting for necessary conformational changes.
- REEL: "Restraints Editor Especially Ligands", a graphical
editor for CIF files, also serves as a frontend to eLBOW. Currently runs
as a separate program. (GUI only)
- Ligand search: program for identifying
unknown blobs of electron density and placing appropriate ligand(s).
Currently uses the old GUI.
Maps
- Create map coefficients: simple GUI for generating
likelihood-weighted maps, including 2mFo-DFc, mFo-DFc, anomalous, and
others, including averaged "kick" maps. Currently works only on untwinned
data. (GUI only)
- AutoBuild - create omit map: similar to the main
AutoBuild GUI, but used for omit map generation rather than building.
- Isomorphous difference map: simple utility for creating a map from two
sets of amplitudes. Corresponds to the command-line program
phenix.fobs_minus_fobs_map.
Validation
Although these programs exist only in the GUI, some of the individual
analyses are available as command-line tools (phenix.ramalyze,
phenix.rotalyze, phenix.cbetadev, and phenix.clashscore). Because
all three programs are subsets of the same functionality, their
documentation is lumped together.
- Comprehensive validation: reports R-work and R-free,
statistics for
geometry restraints, Ramachandran plot, sidechain rotamers, C-beta
deviation, all-atom contacts, and real-space correlation with electron
density. Outlier lists are linked to graphics programs such as Coot,
and clicking a residue or atom will zoom in on that site in the graphics
window. Coot will also display clashes detected by PROBE.
- POLYGON: graphical comparison of user-selected
model statistics with similar structures in the PDB.
- PDB Statistics Overview: This very simple application uses the same
database as POLYGON, but presents it in a different format. Useful when
you simply want to view a histogram of a statistic for a filtered subset
of the PDB.
We recommend including reflections in validation, since the model geometry
ideally needs to be analyzed along with experimental data. However, the
validation GUI will also run with just a PDB file. The phenix.refine GUI
will also display a complete validation report at the end of refinement.
Utilities
Projects
Like the CCP4 GUI (ccp4i), Phenix manages data and job history by grouping
into projects. You will be prompted to create a project the first time you
start the GUI. On subsequent launches Phenix will attempt to guess the
project based on the current directory. There are several constraints on
project management:
- Project IDs should be no more than 24 characters and contain only
alphanumeric characters (including underscore).
- Project directories may not be nested, i.e. you may not create a project
for a directory that is part of an existing project, or that has a
subdirectory that is owned by another project.
When a project is created Phenix will create a folder "phenix" in the project
directory; this is used to store job history, temporary files, and other
internal data. Users should not need to modify this folder unless deleting
the project. All functions related to project management are available
from the main GUI only, either in the toolbar or the File menu.
The current version of the
GUI has limited functionality for configuring projects. Several options
are available for setting the behavior of phenix.refine, such as
default parameter files. The GUI will give you the opportunity to create
these files automatically, but this feature is optional. The other primary
function of the projects is storing job history; although this feature is
still in development, it will save basic statistics and configuration files,
and can restore the parameters and results of any successful previous run.
You may switch between projects while a GUI program is running; however, each
program window stays associated with the project it was opened with.
Preferences
Some of the behavior of the GUI can be customized via the Preferences dialog,
which is available from the File menu (Linux) or Phenix menu (Mac) and on the
toolbar of most programs.
Because some of the larger programs may have up to 500 distinct parameters,
many of which rarely need changing, advanced settings are hidden by default.
You may control this in individual dialogs using the "User level" menu at
the bottom of the window, or change the global level in the "PHENIX interface"
pane (shown above), in the "User level" option. For example, in
phenix.refine, a typical configuration dialog will look like this when the
user level is "Basic":
When set to "Advanced", many more options will appear:
Other Preferences settings determine what external programs are used for
various file types, interactions with molecular graphics programs (Coot,
PyMOL, and the simple built-in graphics), and options for some of the
specific modules in Phenix.
Coot integration
Coot is an open-source (GPL) model-building
program written by Paul Emsley. Although we do not distribute it with
Phenix, it is available as source and binaries for Linux (from the developer's
page), and third-party Mac binaries are available (provided by Bill Scott).
Documentation on how to use it with Phenix is here. Phenix
will try to locate Coot on your system automatically, but if it is not found,
you may specify the command to use under Preferences->Graphics->Full path to
Coot.
PyMOL integration
PyMOL is an open-source molecular viewer written by
Warren DeLano. We distribute an older precompiled version (0.99) with Phenix;
however, we recommend installing the latest version and add the command
under Preferences->Graphics->Full path to PyMOL.
Reporting bugs
Bugs in the code may result in a pop-up window containing a detailed error
message. Clicking "OK" will send an email to the Phenix developers with
this information. We strongly encourage users to submit these reports, as
they are one of the primary mechanisms by which we identify coding errors.
The report will include the error message, information about the host
system, and user name/email; no other personally identifying information or
data is sent.
|
