Phenix

PHENIX (Python-based Hierarchical ENvironment for Integrated Xtallography) is a software suite for the automated determination and refinement of macromolecular structures using X-ray crystallography and other methods. It integrates well with CCP4-formatted files for I/O, is highly automated, and very straightforward to use.

The suite (Phenix home page; documentation) has a GUI program (phenix) which can be used to run the programs, but they also work from the command line.

A short help, such as usage and options, is printed out by all PHENIX command line tools: just type phenix.TOOLNAME and hit Enter (or Return).

The documentation below focuses on the non-GUI commandline tools and may not be complete, nor up-to-date.

Crystallographic data

• phenix.xtriage - assessing data quality
• phenix.explore_metric_symmetry --unit_cell=145,44,67,90,110.5,90 --space_group=C2 --other_unit_cell=67,44,136,90,96,90 --other_space_group=p2 - investigate different settings
• phenix.reflection_statistics - compare datasets (in 1 or 2 files)
• phenix.xmanip - Structure factor file manipulations
• phenix.model_vs_data - not yet documented. Just use "phenix.model_vs_data model.pdb data.hkl" where data.hkl is a reflection file in most of known formats
• phenix.fmodel - calculate structure factors from model
• phenix.cif_as_mtz

Experimental phasing

• phenix.autosol - "wizard" using HYSS, SOLVE, Phaser, RESOLVE, xtriage and phenix.refine to solve a structure and generate experimental phases with the MAD, MIR, SIR, or SAD methods

Preparation for molecular replacement

• phenix.sculptor - automate selection and editing of molecular replacement (MR) models
• phenix.ensembler - multiple superposition tool to automate construction of ensembles for MR

Molecular replacement

• phenix.automr - "wizard" providing an interface to Phaser molecular replacement and feeding the results of molecular replacement directly into the AutoBuild Wizard for automated model rebuilding

Ligands

• http://www.phenix-online.org/documentation/reel.htm phenix.reel - restraints editor especially for ligands
• phenix.elbow - electronic Ligand Builder and Optimisation Workbench

Model building and completion

• phenix.autobuild - "wizard" for model rebuilding and completion. phenix.phase_and_build, phenix.build_one_model are fast ways to obtain results.
• phenix.ligandfit - "wizard" carrying out fitting of flexible ligands to electron density maps
• phenix.phase_and_build and phenix.build_one_model - fast autobuild
• phenix.find_helices - rapid helix fitting to a map
• phenix.fit_loops - fill short gaps using a loop library, and longer gaps (up to 15 residues) iteratively
• phenix.assign_sequence - Sequence assignment and linkage of neighboring segments with assign_sequence
• phenix.ligand_identification

Refinement with phenix.refine

Example for use of phenix.refine

basic usage

phenix.refine model.pdb data.mtz

Here "data.mtz" is your reflection data file. PHENIX automatically recognizes most of the known file formats, so it can be MTZ, CNS or ...

advanced usage

phenix.refine model.pdb data.mtz strategy=rigid_body+individual_sites+individual_adp \
   simulated_annealing=true optimize_wxc=true optimize_wxu=true main.number_of_macro_cycles=5 \
   ordered_solvent=True

This will do the following:

1. Rigid body refinement first cycle only (MZ protocol = VERY high convergence radius);
2. Refinement of individual xyz and b-factors every cycle with optimized weights (warning: optimize_wxc=true optimize_wxu=true makes the program use much more time!);
3. Simulated annealing at 2nd and one before the last cycles;
4. find (and remove if necessary) water molecules

Warning: the file model.pdb in this example should not have any ANISOU records! If it has any, these would be refined as individual anisotropic which is most likely not desired.

Ligands

If some ligand in model.pdb is unknown, phenix.refine will complain:

Sorry: Fatal problems interpreting PDB file:
 Number of atoms with unknown nonbonded energy type symbols: 18
 Please edit the PDB file to resolve the problems and/or supply a
 CIF file with matching restraint definitions, along with
 apply_cif_modification and apply_cif_link parameter definitions
 if necessary (see phenix.refine documentation).
 Also note that phenix.elbow is available to create restraint
 definitions for unknown ligands.

In that case, just running

phenix.elbow model.pdb --do-all --output=all_ligands

will produce all_ligands.cif, which may be fed to phenix.refine by

phenix.refine model.pdb data.mtz all_ligands.cif ...

If no PDB file for a ligand is available, its SMILES string should be input to phenix.elbow, and phenix.ready_set should run to generate the LINK records (e.g. for a non-natural amino acid that is part of the polypeptide chain), using phenix.elbow's CIF file.

Constraints and restraints in real and reciprocal space

Hydrogens

Use phenix.ready_set to add hydrogens to your PDB file, and (except at ultra-high resolution) the riding hydrogen model in phenix.refine (this is the default so you do not have to specify anything). phenix.ready_set internally uses phenix.elbow for ligands and phenix.reduce for the protein. phenix.pdbtools can also add hydrogens (FIXME: what are the differences?). Hydrogens should not be used in NCS and TLS groups - it might be a good idea to add and not (element H or element D) to all selection strings. See the phenix.refine documentation.

Occupancy

Adding "occupancy" to the "strategy" options will refine the occupancies of those parts of the model that have alternate conformations.

NCS

Automatic detection of NCS groups:

phenix.refine data.hkl model.pdb main.ncs=True

Manual specification of NCS groups:

phenix.refine data.hkl model.pdb ncs_groups.params main.ncs=True

where ncs_groups.params contains e.g.:

refinement.ncs.restraint_group {
  reference = chain A 
  selection = chain B 
  selection = chain C
}
refinement.ncs.restraint_group {
  reference = chain E
  selection = chain F
}

Secondary structure restraints

phenix.refine model.pdb data.mtz main.secondary_structure_restraints=true

You can find more information about secondary structure restraints in the PHENIX Newsletter (pages 12-17).

Low resolution refinement

Use an existing high resolution model (e.g. in a different spacegroup) for restraining the dihedrals:

  phenix.refine data.hkl model.pdb main.reference_model_restraints=True reference_model.file=reference.pdb

The behaviour can be modified with the keywords reference_model.limit (default 15 degrees) and reference_model.sigma (default probably 1 degrees - the current documentation says 1 Angstrom which is probably not right). See the full documentation.

TLS

• run your model through TLSMD server to identify TLS domains (it will produce PHENIX friendly TLS groups selections);

http://skuld.bmsc.washington.edu/~tlsmd/

• use these selections for TLS refinement in PHENIX: see http://www.phenix-online.org/documentation/refinement.htm

for example:

phenix.refine model.pdb data.hkl strategy=individual_sites+individual_adp+tls  tls_selections.def

with tls_selections.def something like:

refinement.refine {
 adp {
 tls = chain 'A'
 tls = chain 'B'
 }
}

Rigid body

example for file rigid_body.def defining 2 rigid bodies:

refinement.refine.sites {
 rigid_body = chain 'A' or chain 'B'
 rigid_body = chain 'L' or chain 'M'
}

Fix His/Asn/Gln sidechain orientations

Use

 phenix.refine data.hkl model.pdb main.nqh_flips=True

to automatically flip these sidechains to make them better fit the density and/or hydrogen bonding pattern.

Atom selection

e.g.

phenix.refine model.pdb data.mtz refine.sites.individual="not (chain A and resseq 123:156)"

Switching off specific interactions

To switch off the interaction between a specific atom and its environment, e.g. to obtain unbiased (by restraints) estimates of distances, see http://www.phenix-online.org/documentation/refinement.htm#anch80 - you just add restraints of the form:

refinement.geometry_restraints.edits {
 zn_selection = chain X and resname ZN and resid 200 and name ZN
 his117_selection = chain X and resname HIS and resid 117 and name NE2
 bond {
   action = *add
   atom_selection_1 = $zn_selection
   atom_selection_2 = $his117_selection
   distance_ideal = 2.1
   sigma = 0.02
# use slack=None if you _want_ to restrain, use large slack if not
   slack = 1
 }
}

Maps

• phenix.maps - a command line tool to compute various maps. Seems to have no specific documentation. Can do B-factor sharpening for improving low-resolution maps.
• phenix.real_space_correlation - compute correlation between two maps; can work with ensembles of structures. Seems to have no specific documentation.
• phenix.get_cc_mtz_mtz -
• phenix.fobs_minus_fobs_map - calculate difference density. Seems to have no specific documentation.
• phenix.multi_crystal_average -
• phenix.grow_density - local density improvement, as originally described in Acta Cryst. (1997). D53, 540-543 (in development). Seems to have no specific documentation.

NCS usage

• phenix.find_ncs - identification of NCS operators from protein coordinates (chains), heavy atom coordinates, or a density map
• phenix.superpose_maps - transforms maps following a molecular superposition. Seems to have no specific documentation.
• phenix.apply_ncs - applying NCS to a molecule to generate all NCS copiea

Model analysis and manipulation

• phenix.pbdtools - PDB model manipulations and statistics; e.g. phenix.pbdtools your_model.pdb --show-adp-statistics will show you complete statistics about B-factors; phenix.pbdtools your_model.pdb --show-geometry-statistics will show you complete statistics about stereochemistry, phenix.pbdtools your_model.pdb set_b_iso=25.3 selection="chain A and resname ALA and name CA" - this will set all B=25 for all CA atoms in all ALA residues of chain A.
• phenix.reduce - tool for adding hydrogens to a PDB model
• phenix.superpose_pdbs - Superposition of models

Validation

• phenix.polygon - starts the GUI and runs calculations resulting in a POLYGON drawing of important characteristics of your PDB file in relation to the data
• phenix.validate_model and phenix.validate are also GUI-only
• phenix.ramalyze, phenix.rotalyze, and phenix.cbetadev
• phenix.clashscore

See also

Phenix home page

Phenix mailing list

PHENIX Newsletter

http://phenix-online.org/presentations/neutron_japan_2009/phenix_japan_part1.pdf

http://cci.lbl.gov/~afonine/for_ak/validation.pdf

• 42 pages of general introduction to structure refinement: [1]
• 45 pages of phenix.refine overview (including extended details about its use from the command line): [2]
• 42 pages of "Some Facts About Maps": [3]
• 50 pages of "Crystallographic Structure Validation": [4]
• 31 pages of introduction to PHENIX: [5]

server producing custom RNA/DNA base pairing restraints

References

• electronic Ligand Builder and Optimization Workbench (eLBOW): a tool for ligand coordinate and restraint generation. Nigel W. Moriarty, Ralf W. Grosse-Kunstleve and Paul D. Adams, ActaCryst. (2009). D65, 1074-1080
• phenix.model_vs_data: a high-level tool for the calculation of crystallographic model and data statistics. Afonine PV, Grosse-Kunstleve RW, Chen VB, Headd JJ, Moriarty NW, Richardson JS, Richardson DC, Urzhumtsev A, Zwart PH, Adams PD. (2010) J Appl Crystallogr. 43, 669-676. [6]