General

How should I cite PHENIX?

If you use PHENIX please cite:

PHENIX: a comprehensive Python-based system for macromolecular structure solution. P. D. Adams, P. V. Afonine, G. Bunkóczi, V. B. Chen, I. W. Davis, N. Echoo ls, J. J. Headd, L.-W. Hung, G. J. Kapral, R. W. Grosse-Kunstleve, A. J. McCoy, N. W. Moriarty, R. Oeffner, R. J. Read, D. C. Richardson, J. S. Richardson, T. C. Terwilliger and P. H. Zwart. Acta Cryst. D66, 213-221 (2010).

Individual programs may have additional citations.

How can I use multiple processors to run a job?

Only Autosol, Autobuild, Ligandfit, phaser.MRage, phenix.refine, the structure comparison GUI, and phenix.find_tls_groups support runtime configuration of parallel processing. In most cases this is done by adding the "nproc" keyword, for instance:

phenix.autobuild data.mtz model.pdb seq.dat nproc=5

Equivalent controls are usually displayed in the GUI. In addition to these options, it is also possible to compile phenix.refine and Phaser with the OpenMP library, which automatically parallelizes specific instructions such as the FFT. This requires using the source installer for Phenix, and adding the argument "--openmp" to the install command. Because of threading conflicts, OpenMP is not compatible with the Phenix GUI.

Where can I find sample data?

You can find sample data in the directories located in $PHENIX/examples. Additionally there is sample MR data in $PHENIX/phaser/tutorial.

In the Phenix GUI, tutorials may automatically be set up as projects. (You must run the specific programs manually, however.)

Can I easily run autosol, autobuild or ligandfit with some sample data?

You can run sample data with with a simple command. To run p9-sad sample data with autosol, you type:

phenix.run_example  p9-sad

This command copies the $PHENIX/examples/p9-sad directory to your working directory and executes the commands in the file run.sh

What sample data are available to run automatically?

You can see which sample data are set up to run automatically by typing:

phenix.run_example  --help

This command lists all the directories in $PHENIX/examples/ that have a command file run.sh ready to use. For example:

phenix.run_example  --help

PHENIX run_example script. Fri Jul  6 12:07:08 MDT 2007

Use: phenix.run_example example_name [--all] [--overwrite]
Data will be copied from PHENIX examples into subdirectories
of this working directory
If --all is set then all examples will be run (takes a long time!)
If --overwrite is set then the script will overwrite subdirectories

List of available examples:  1J4R-ligand a2u-globulin-mr gene-5-mad
p9-build p9-sad

Are any of the sample datasets annotated?

The PHENIX tutorials listed on the documentation index will walk you through sample datasets, telling you what to look for in the output files. For example, the Tutorial 1: Solving a structure using SAD data tutorial uses the p9-sad dataset as example. It tells you how to run this example data in autosol and how to interpret the results.

How is non-crystallographic symmetry handled in PHENIX?

The treatment of NCS depends on the specific program or task:

• In density modification (performed internally by RESOLVE, and used in Autosol, autobuild, phenix.multi_crystal_average, and related programs), NCS relationships (in the form of rotation/translation matrices) are used to average different parts of the map together, which usually improves phase quality. The NCS operators can be derived from heavy-atom positions, the map itself, or a partial model, but this is normally done automatically (although we recommend specifying the number of NCS-related copies if you know what it should be).
• In model-building (Autobuild), NCS is also used to copy pieces of the partial model to complete related chains.
• In refinement (both in phenix.refine itself, and in the Autosol/Autobuild pipelines), NCS-related chains will be restrained to have similar conformations. By default this will be done in torsion-angle space, which allows for local conformational changes if present, and also incorporates advanced sidechain-fitting features. The NCS groups will be determined automatically based on sequence comparison. Alternately, you may restrain the NCS groups to be globally similar, treating the relationships as rigid. This may work better in a few cases but is generally not recommended, especially since careful manual setup is usually required for optimal results.

Note that several programs may produce multiple forms of output specifying the NCS relationships. Files ending in .ncs_spec contain rotation and translation matrices for use in RESOLVE. Files ending in .phil contain atom selections for use in phenix.refine. In most cases, however, you can ignore these files, as the NCS relationships will be detected automatically.

How can I get Phenix to use a local PDB mirror instead of fetching entries remotely?

The Phenix GUI, phenix.cif_as_mtz, MRage, MR-Rosetta and several other programs use a common central function to download PDB files. You can substitute your own local PDB mirror by defining environment variables, for instance in bash/sh:

export PDB_MIRROR_PDB=/data/pdb_mirror/pdb
export PDB_MIRROR_STRUCTURE_FACTORS=/data/pdb_mirror/structure_factors

The structure factors are optional and may be left out to conserve disk space; most applications are only concerned with the model data. In both cases, these directories should contain a series of subdirectories with two-character names corresponding to the middle two characters of PDB IDs, each containing associated PDB files with specific names such as:

$PDB_MIRROR_PDB/hb/pdb1hbb.ent.gz
$PDB_MIRROR_STRUCTURE_FACTORS/hb/r1hbbsf.ent.gz

If the mirror is out of date and a specific entry cannot be found, the function will revert to downloading from the RCSB PDB site.

Graphical interface

When I start up the Phenix GUI for the first time, I get an error message "ImportError: libjpeg.so.62: cannot open shared object file: No such file or directory". How do I fix this?

This error usually occurs on recent versions of Ubuntu, which do not install an essential library by default. You can fix it by running this command:

sudo apt-get install libjpeg62

How do I find a specific parameter in the GUI?

Open the Settings menu, and select Search all parameters. This can be used to search for any keyword in the parameter name, label, or help text.

Working with reflection files

I have requested that the test set fraction be 0.05 (i.e. 5%), but Phenix only flags 1% of reflections. How do I make it use the number I specify?

By default there is a limit of 2000 on the number of reflections that will be picked for the test set; you don't really need more than this to ensure that R-free is statistically significant and that the maximum likelihood calculations work properly. However, if you want to use a full 5%, you can tell Phenix not to put any upper absolute limit. In the reflection file editor in the GUI, click "More options" in the R-free flags section of the editor, and delete the field labeled "Maximum number of reflections in test set".

number_of_parallel_models=1 n_cycle_rebuild_max=1

Maps

How do I obtain an anomalous difference map in Phenix?

If you have anomalous data (separate F+ and F- or I+ and I-) and use this as input, both phenix.maps and phenix.refine will automatically output the anomalous difference map in the map coefficients MTZ file. Note that depending on the application, you may need to manually open the MTZ file in Coot to get the anomalous map to appear.

How can I calculate a log-likelihood gradient SAD map using Phaser?

Several programs in Phenix interface with Phaser to calcluate an LLG map given a model with existing anomalous (and real) scatterers. This map is more sensitive towards weaker scatterers (such as phosphorous, sulfur, and chloride, or partially-occupied heavy atoms) because it subtracts the contribution of existing atoms. (In this sense it is similar to any other difference map, where the sigma level of the map around remaining unmodeled atoms becomes increasingly higher as more atoms are added to the model). The first two options are recommended; in both cases you will need to request an additional set of map coefficients where map_type=LLG. (This is available as a preset option in the GUI.)

• In phenix.maps, if you specify the wavelength parameter, the entire structure will have scattering factors adjusted to model the anomalous scattering expected at the given wavelength. This is relatively fast, but the disadvantage is that the theoretical f'' may be either too high or too low, leading to difference map peaks around existing atoms.
• In phenix.refine, if you enable anomalous group refinement and specify the groups to be refined (or manually enter fixed f'' values), the LLG map will reflect the refined values rather than theoretical calculations. You can also set group_anomalous.find_automatically=True to identify appropriate groups automatically (based on atomic number).
• If you use the Phaser-EP GUI, there is also an option to output the LLG map coefficients at the end. However, if you turn on anomalous substructure completion, the final LLG map will usually be relatively flat. (Alternately, if you do not use substructure completion, you will be limited to whatever anomalously scattering atoms are present in the input sites file.) Therefore, unless you actually want to perform experimental phasing, when starting from a partial (or mostly complete) model the above methods are more useful.

Finally, for automation purposes, there is a utility for calculating a single set of map coefficients:

mmtbx.compute_map_coefficients model.pdb data.mtz wavelength=0.9792 map_type=llg

This should produce identical output to phenix.maps, but has been streamlined to require minimal input.

Models

The validation GUI (or the PDB deposition annotator) is complaining about zero-occupancy atoms. Why does this happen, and how can I fix it?

The most common reason for atoms having zero occupancy is heteroatom groups (in this context, any atom labeled as HETATM in the PDB file) being reset to zero occupancy by Phaser. Although this can be avoided by modifying the Phaser settings, it is easy to fix using several different programs:

• In PDBTools, there is an option to reset all selected occupancies to a specified value (usually 1.0). If you do not want any non-unity occupancies it is safe to do this for the entire model, otherwise you will need to enter an atom selection to modify.
• For more manual control, the PDB file editor in the Phenix GUI allows you to change the properties of individual atoms (or residues, chains, etc.).
• In phenix.refine, there are options to modify the starting model in the middle panel of the configuration interface; these are essentially identical to the options in PDBTools. (On the command line, the parameter scope "modify_start_model" contains these options.)

Please note that any time you modify the atomic properties (or add or remove atoms), it is essential to refine the model again, as the previously calclulated R-factors and maps will be invalid.

Other

How can I obtain phases and Hendrickson-Lattman coefficients for my model and data?

There is a program specifically for this purpose; you can find in in the Phenix GUI under "Reflection tools".

What is the best way to generate an omit map in Phenix?

There are several options (with some overlap in functionality):

• To remove model bias, the fastest option is to generate a composite omit map for the entire structure. By default this uses a very fast procedure for iteratively de-biasing the phases, but other (slower) options are available too.
• For omitting just a subset of atoms, an older and very popular option is to run phenix.refine with simulated annealing, here specifying an atom selection to be omitted. This also includes an option to harmonically restrain atoms to prevent other parts of the model from drifting into the omitted region.
• The composite omit map tool also has an option to use phenix.refine to de-bias the structure, in addition to the fast method described above. The refinement is much slower, but may be parallelized across multiple CPU cores or a cluster.
• Finally, the most thorough procedure for bias removal is the iterative build omit map option in AutoBuild. This rebuilds the entire model, in addition to running refinement.
• If you just want a simple omit map for a subset of atoms and do not care about model bias, phenix.maps has an option to omit a subset of atoms. This is suitable for quick calculations, but not for generating figures for publication.