The phenix graphical interface
- Overview
- Running programs from the GUI
- Modules
- Reflection tools
- Model tools
- Phasing
- Molecular replacement
- Model building
- Refinement
- Maps
- Ligands
- Validation
- Utilities
- Other tools
- Projects
- Running PHENIX tutorials
- Preferences
- Coot integration
- PyMOL integration
- Reporting bugs
- Acknowledgments
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.
- Import CIF structure factors: convert a CIF file (used
by the PDB to store deposited experimental data) to an MTZ file. This will
automatically fetch data for a known ID from the PDB, or you may supply
your own files.
- French & Wilson data correction: procedure for estimating appropriate
values for weak and negative intensities. This is also run automatically
as part of several programs, including phenix.refine and the Phaser GUIs.
- Model-based phases: calculate phases and
structure factors in a variety of formats (including Hendrickson-Lattman
coefficients).
- 3D and 2D data viewers: these display data from
reflection files (usually
amplitudes or intensities) as they appear in reciprocal space, either in
a full 3D view or a pseudo-precession camera section.
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.
- NCS identification: determine appropriate NCS operators
and/or restraint groups based on a set of heavy-atom sites, macromolecule
chains, or electron density.
- Apply NCS: apply NCS operators to a PDB file to generate
the complete asymmetric unit.
Note that a simpler NCS GUI is also available as a plugin
to the phenix.refine GUI, and does 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.
- Hybrid substructure search: heavy-atom site identification
program. Used automatically as part of AutoSol.
- 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.) There are two interfaces, one for simple structures
with one or more copies of a single chain, and a more complex interface
for heterogeneous structures.
- 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.
- MR-Rosetta: automation pipeline for exceptionally
difficult structures, which uses the
Rosetta software for protein structure
prediction and design to rebuild poor MR solutions, along with Phaser and
AutoBuild. (Separate installation of Rosetta is required.)
- Sculptor: prepare a search model for molecular
replacement by trimming the structure, modifying B-factors, etc.
- Sculptor - Coot interface: a Coot plugin for running Sculptor interactively
and visualizing results.
- Ensembler: tool for creating superimposed ensembles
of related MR search models.
Model building
- 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.
- Phase and build: similar to AutoBuild, but
significantly faster (although less accurate).
- Find Helices and Strands: fast building of
secondary structure (as poly-ALA) into maps with RESOLVE and PULCHRA.
Especially good for low-resolution data.
- Fit Loops: simple GUI for building missing loops into
a map based on a sequence and start model.
- Morph model: improvement of poor molecular replacement
solutions by "morphing" into density and rebuilding.
Refinement
- 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.
- ReadySet: preparation of input files for refinement,
including generating restraints (CIF) files and adding hydrogens.
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)
- FFT map coefficients: convert an MTZ file containing
map coefficients to one or more CCP4 or XPLOR-format maps suitable for
viewing in PyMOL, etc. (Note that the main maps GUI and many other
programs can also output these files, and the GUI will generate them for
you as necessary for PyMOL.)
- AutoBuild - create omit map: similar to the main
AutoBuild GUI, but used for omit map generation rather than building.
- RESOLVE density modification: This is just a
simplified interface for running the AutoBuild wizard in
map-only mode.
- 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.
- Superpose maps: given two PDB files and
accompanying map coefficients
(in MTZ format), superposes the PDB files and reorients the maps to
follow them. Output is the reoriented PDB files and maps in CCP4 format.
- Cut out density: extracts a section of electron
density from input map coefficients, and outputs new map coefficients
(suitable for running molecular replacement in Phaser).
- Multi-crystal averaging: performs density
modification on different crystal forms of the same structure and averages
the maps around the models.
Ligands
- LigandFit: wizard for placing ligands in electron
density maps, accounting for necessary conformational changes.
- eLBOW: electronic Ligand Builder and Optimization
Workbench, a tool for generating restraints (and geometries) for any
molecule, using a variety of inputs including PDB file and SMILES string.
- 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).
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.
- Structure comparison: a tool for evaluating
assorted model features and validation criteria for multiple related
structures, and highlighting regions of difference. Automatically
superposes model and maps into a common frame of reference for viewing in
Coot or PyMOL.
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
- Calculate map correlations: interface to
phenix.get_cc_mtz_mtz.
- Calculate model-map correlations: interface to
phenix.get_cc_mtz_pdb.
- Generate Table 1: utility for extracting statistics from
PDB, reflection, and log files required for publication.
- Diffraction image viewer: a simple utility for inspecting images in a
variety of common detector formats (ADSC, MAR, R-AXIS, Pilatus, etc.).
Other tools
A number of simpler tasks involving file modification and visualization can
be accessed by clicking the button labeled "Other tools" on the toolbar.
Current options include:
- Fetch PDB data: Download structure data in PDB, FASTA, or CIF/MTZ
format. (Command line equivalent: phenix.fetch_pdb.)
- Convert PDB file(s) to FASTA: Extract sequences of polymer chains
in a model, with flexible options for handling gaps, insertions, etc.
(Command line equivalent: iotbx.pdb_as_fasta.)
- Multiple sequence alignment: uses the public-domain program MUSCLE
(Edgar 2005) to perform alignment of sequences in various formats
(including automatic extraction of sequences from PDB files).
(Command line equivalent: none, but MUSCLE can be run in PHENIX with
the command phenix.muscle.)
- Plot average B-factors in PDB file: Plots residue B-factors (for
all atoms, backbone, or sidechain) as a horizontal line graph.
(Command line equivalent: mmtbx.bfactor_plot.)
- Reindex reflections: Performs change-of-basis operations on reflection
files. (Command-line equivalent: phenix.reindex.)
- Modify PDB file: Shortcuts for performing some of the most common
tasks in phenix.pdbtools (also available as a full GUI).
- PDB remediation: Convert between versions 2 and 3 of the PDB format.
(Command-line equivalent: iotbx.pdb_remediator.)
- Import data and flags: Prepares data for use in refinement; this tool
is especially useful when bringing in new high-resolution reflections for
an already-refined structure.
- Plot PDB statistics: Generates scatter plots or histograms of
statistics output by phenix.model_vs_data for a large fraction of the PDB
(nearly all X-ray structures with experimental data available). The same
database is used to generate the plots in POLYGON.
- Inspect R-free flags: Plots distribution of R-free flags in a
reflections file; this is primarily used to determine whether the flags
have been created in thin resolution shells. (Command line equivalent:
wxtbx.inspect_r_free_flags.)
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.
Running PHENIX tutorials
A number of examples using published structures are included in the PHENIX
installation, and can be automatically loaded into the GUI as new projects.
To load tutorial data, click on "New project" in the main GUI; this window
also appears the first time the PHENIX GUI is started (before any projects
have been created). The button "Set up tutorial data" will open a new dialog
with a list of examples, grouped by the methods they are intended to
demonstrate.
For live demonstration, we normally use the P. aerophilum translation
initiation-factor 5a or p9-sad example for experimental phasing,
TEM-1 Beta-lactamase/beta-lactamase inhibitor complex (beta-blip) for
molecular replacement, S. aureofaciens ribonuclease Sa (rnase-s) for
refinement, and N-ethylmaleimide sensitive factor + ATP (nsf-d2-ligand)
for ligand fitting. All of these datasets run relatively quickly (5-30
minutes) in the intended programs. (These examples are also used extensively
in this documentation.)
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. More information is
in the separate PyMOL instructions.
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.
Acknowledgments
The PHENIX GUI is written in Python 2.7, using the wxPython toolkit for
most features, plus matplotlib for plotting.
Some of the icons used in the GUI came from the Crystal Icons project which is licensed under the LGPL. Many
additional icons (anything with a molecular representation) were generated
using PyMOL.
Several open-source programs have been included with PHENIX and
are used in various ways in the GUI; we are grateful to their authors for
permission to redistribute the code:
- **MUSCLE** written by Bob Edgar.
Edgar, R.C. (2004) MUSCLE: multiple sequence alignment with high accuracy
and high throughput.Nucleic Acids Res. 32(5):1792-1797.
- **ksDSSP** written by UCSF Computer Graphics Laboratory. Original method
(independently reimplemented): W. Kabsch and C. Sander, "Dictionary of
Protein Secondary Structure: Pattern Recognition of Hydrogen-Bonded and
Geometrical Features" Biopolymers 22:2577 (1983).
|
