Automated protein-ligand structure determination with phenix.ligand_pipeline



phenix.ligand_pipeline is an automation system combining Xtriage, Phaser, eLBOW, phenix.refine, AutoBuild, and LigandFit, with optional interaction with Coot. In favorable cases, it can produce a near-finished structure of a protein-ligand complex starting from minimal inputs, and can significantly reduce the manual effort required for more difficult structures.

Input files

The typical input for the pipeline consists of processed experimental data, a starting model for molecular replacement, a sequence file equivalent to the starting model (with the same number of chains), and a source of ligand information. File types will be automatically detected if explicit parameter names are not used, for instance:

phenix.ligand_pipeline model.pdb data.mtz seq.fa lig.cif

The data may be in any format; if R-free flags are not found they will be generated automatically, but you may also supply the flags in a separate file (r_free_flags.file_name=flags.mtz). This is espeically recommended if you are working with multiple isomorphous structures. The sequence file is optional but highly recommended.

To specify the ligand geometry, several mutually exclusive options are available:

It is recommended that you use the most detailed and explicit information about the ligand chemistry and geometry that you have available: a pre-generated and manually validated CIF is ideal. You may also supply a PDB file (template_pdb=lig.pdb) containing the atom names to use. However, PDB files should not be the primary source of ligand geometry information! Additionally, if you have additional ligands in your input model, you can supply CIF files for refinement with the extra_cif keyword. You should also specify keep_hetatms=True to prevent Phaser from resetting the occupancies to zero.

Finally, if all files are in the same directory and their uses can be unambiguously determined, you may supply the path name as a single argument when launching the program:

phenix.ligand_pipeline /path/to/data [options]

Program workflow

Data preparation. The program begins by importing the experimental data and converting it to amplitudes with standard MTZ column labels (this simplifies later steps). R-free flags will be generated if not available, otherwise the user-supplied flags will be used (extended to higher resolution if necessary). Xtriage will be run to assess data quality and guess an appropriate number of search copies for MR (which, by default, will be the same as the number of ligands to look for).

Ligand generation. eLBOW will be run on the input ligand definition to generate suitable geometry restraints and a starting structure for LigandFit. The most important option is the choice of whether to run the semi-empirical AM1 quantum-mechanical optimization or not (optimize=True). This is not done by default because it is more time-consuming, but in some cases it may lead to improved geometry. For troublesome cases, we recommend generating the ligand restraints and structure manually prior to running the pipeline, then supplying the output CIF as input to the pipeline with the additional argument keep_input_restraints=True. In this case, eBLOW will only be used to generate a PDB file, and the input restraints will be used for refinement.

Model preparation. For each input model, a series of cleanup steps is run to remove specific details such as alternate conformations, hydrogen atoms, or waters. The model will also be processed with Sculptor to ensure that all residues match the target sequence. (This will not extend truncated sidechains, but this is available as a later step after ligand placement.)

Model placement. Two options are available, rigid-body refinement or molecular replacement:

Currently MR is run by default, but this will be changed in the future; if you are confident that the model can be correctly placed without MR, add mr=False or skip_mr=True or --skip_mr to jump straight to refinement. (This will automatically turn on rigid-body refinement in the subsequent step.) A more useful (but slightly slower) option is mr=Auto, which will attempt rigid-body refinement and then revert to running Phaser if the R-free is greater than 0.4 or no models with appropriate symmetry are found.

In automatic or MR mode, you may specify multiple models as input; the best model will be selected either by Phaser or the rigid-body refinement step. The space group will be updated based on the Phaser solution or selected model if necessary.

Initial refinement. The MR solution (or starting model, if MR was not performed) will be refined using a relatively conservative resolution-dependent strategy, by default rotamer fitting, real-space and reciprocal-space coordinate minimization, individual B-factor refinement, and TLS groups. Torsion NCS will be used if appropriate. Rigid-body refinement will be used if Phaser was not previously run. Water molecules will be added if the resolution is sufficient, but these will be removed prior to ligand fitting. Simulated annealing may be run if desired (anneal=True), but this will significantly increase the runtime. Because rapid convergence is more important at this point than ideal geometry, weight optimization will not be used by default. (Water picking is used because this improves the maps, but the solvent atoms will be removed prior to ligand fitting to avoid overlap.)

If the refined R-free is above 0.5, the program will immediately exit, since this indicates that the structure may be incorrect or at least in need of extensive manual rebuilding (or possibly additional search copies for MR). If R-free is above 0.3, the default behavior (build=Auto) is to rebuild the model in AutoBuild. Otherwise, the structure is considered suitable for ligand fitting.

Rebuilding. Rebuilding is optional but may be essential in some cases where large rearrangements are required. AutoBuild will be run with rebuild_in_place=Auto, which in most cases means that residues will not be added or removed. If run, AutoBuild is generally the most time-consuming stage in the pipeline, although it can take advantage of multiple processors.

An alternate protocol, run by default, is to simply delete those residues with poor fit to density, with the goal of moving them out of the way of the ligand binding site. Either the mainchain or sidechain atoms or both can be removed, but the default is to only prune sidechains. These may optionally be rebuilt after the ligand is placed.

As a final preparation step, waters are removed from the model and the difference map is recalculated.

Ligand placement. Currently only LigandFit is supported, although additional options will be available in the future. The target map will be the mFo-DFc map from phenix.refine. The parameters have been adjusted slightly for optimal performance at the expense of slightly longer runtime; you may specify quick=True or aggressive=True to override the defaults. Real-space refinement will be performed on ligands after placement to obtain an optimized fit and local geometry. Unlike most of the other steps, here the resolution will be truncated by default to 1.8Å (ligandfit.d_min=1.8), because higher-resolution data tend to lead to lower correlations even when the fit is excellent.

An essential feature of automatic ligand fitting is a cutoff model-to-map CC to prevent false positives (i.e. spurious placement). By default this is set to 0.7, which has been empirically determined to nearly always indicate a successful fit. Any ligands with a CC below this value will be omitted from the model. In some cases this may actually reject correct fits (see Troubleshooting section below), but we recommend that these solutions be viewed with suspicion. If no acceptable ligand fits are obtained, the pipeline will skip further refinement and exit early with an error message.

In many cases the one or more ligands will be placed, but fewer than the desired number; in these situations, a separate post-LigandFit routine will first attempt to use NCS operators to place additional copies of the ligand, pruning the model as necessary to avoid clashes. If there are still fewer copies than desired, the pipeline will continue with refinement but print a warning at the end of the run.

Final refinement and validation. If the ligand placement was at least partially successful, a final round of refinement will be performed on the combined model. In this run, waters will be added automatically if the resolution is at least 2.9Å, and the geometry weight will be optimized if the resolution is worse than 1.75Å (this is much slower but can run on multiple processors, and generally produces a superior model).

Interactive mode

For users desiring more control over the rebuilding process, or for difficult cases where more aggressive model modifications are required, the program can be run semi-interactively by adding the flag interactive=True (or alternately, --interactive). This will launch Coot after the first round of refinement, with model and maps loaded, allowing rebuilding to take place. The recommended procedure is to locate the putative ligand density in the mFo-DFc map, and adjust the protein structure as necessary to remove overlap with the ligand binding site (as well as any other modifications that will not be automatically fixed by refinement and/or AutoBuild). Once rebuilding is complete, click the button "Return to PHENIX" to save the edited model and resume the pipeline (the next step will be LigandFit, with a freshly calculated mFo-DFc map). At any point during rebuilding, you can obtain new maps for the edited model by clicking "Fetch new maps" on the toolbar, which will write out a temporary model and recalculate maps in the background, automatically loading these into Coot when finished.

Because the interactive mode overcomes many of the limitations present when significant rebuilding is required, it is the reocmmended method for running the pipeline, especially for new users.

Output files

All files will be written to a directory named pipeline_X, where X is an automatically incremented integer. Most of the important output files will be named after the ligand code, by default LIG:

The Coot script can be run like this:

coot --script pipeline_1/

This will open the final model and map coefficients, and if ligand fitting was successful, a window will be created containing buttons to zoom in on the ligand(s).

Inside the output directory, separate subdirectories will be created for each stage of the pipeline, e.g. phaser_0, refine_0, refine_1, LigandFit_run_1_. You do not normally need any of the files in these directories, but they may be useful for debugging purposes. In particular, if LigandFit failed to place one or more copies, the ligand PDB files will not be incorporated into the final model, but will still be available in the LigandFit output directory.

Next steps

Although the pipeline can produce nearly-complete models in favorable cases (typically at moderate-to-high resolution, approximately 2.2 to 1.8Å), the structures are unlikely to be truly complete. Several recommendations for finishing the refinement in Coot:

More generally, with any automation system, two rules apply: exercise appropriate skepticism and seek expert opinion if unsure of the results. (If a local expert is not available, email for advice.)



The pipeline may fail for a number of reasons, usually because LigandFit could not successfully place any copies of the ligand. If this happens, the program will skip the final refinement step and exit early with an error message. You can still run the Coot script to load the output of the previous refinement or AutoBuild, which may provide clues about the cause of failure. Several common problems are listed below. Note that these may also apply to cases where the pipeline runs to completion but was unable to place all copies of the ligand successfully (in which case a warning message will be printed).

Other notes about use

Speeding up execution: the bulk of the runtime is spent refining the model; the default protocol is very robust but not especially fast, and may be unnecessarily intensive for easy cases. You can switch to a faster protocol by specifying quick_refine=True, which will shorten both refinement steps from 6 to 3 cycles, and disable weight optimization.

Hydrogen atoms: these will be added prior to the final refinement step. Usually this will improve geometry somewhat (and also R-factors at high resolution); however, it has the side effect of making refinement significantly slower. Specfiy after_ligand.hydrogens=False to leave them off.

Rebuilding sidechains: sidechains truncated by a previous step (Sculptor or the pruning step), or missing in the input model, may optionally be restored after ligand placement by specifying extend_model=True.

Standalone tools: although most of the pipeline is built around pre-existing programs in Phenix, several new tools have been developed for this protocol and are also available as separate command-line programs:


Automating crystallographic structure solution and refinement of protein-ligand complexes. N. Echols, N.W. Moriarty, H.E. Klei, P.V. Afonine, G. Bunkóczi, J.J. Headd, A.J. McCoy, R.D. Oeffner, R.J. Read, T.C. Terwilliger, and P.D. Adams. Acta Crystallogr D Biol Crystallogr 70, 144-54 (2014).

Xtriage and Fest: automatic assessment of X-ray data and substructure structure factor estimation. P.H. Zwart, R.W. Grosse-Kunstleve, and P.D. Adams. CCP4 Newsletter Winter, Contribution 7 (2005).

Improvement of molecular-replacement models with Sculptor. G. Bunkóczi, and R.J. Read. Acta Crystallogr D Biol Crystallogr 67, 303-12 (2011).

Phaser crystallographic software. A.J. McCoy, R.W. Grosse-Kunstleve, P.D. Adams, M.D. Winn, L.C. Storoni, and R.J. Read. J Appl Crystallogr 40, 658-674 (2007).

electronic Ligand Builder and Optimization Workbench (eLBOW): a tool for ligand coordinate and restraint generation. N.W. Moriarty, R.W. Grosse-Kunstleve, and P.D. Adams. Acta Crystallogr D Biol Crystallogr 65, 1074-80 (2009).

Towards automated crystallographic structure refinement with phenix.refine. P.V. Afonine, R.W. Grosse-Kunstleve, N. Echols, J.J. Headd, N.W. Moriarty, M. Mustyakimov, T.C. Terwilliger, A. Urzhumtsev, P.H. Zwart, and P.D. Adams. Acta Crystallogr D Biol Crystallogr 68, 352-67 (2012).

Iterative model building, structure refinement and density modification with the PHENIX AutoBuild wizard. T.C. Terwilliger, R.W. Grosse-Kunstleve, P.V. Afonine, N.W. Moriarty, P.H. Zwart, L.-W. Hung, R.J. Read, and P.D. Adams. Acta Cryst. D64, 61-69 (2008).

Automated ligand fitting by core-fragment fitting and extension into density. T.C. Terwilliger, H. Klei, P.D. Adams, N.W. Moriarty, and J.D. Cohn. Acta Crystallogr D Biol Crystallogr 62, 915-22 (2006).

MolProbity: all-atom structure validation for macromolecular crystallography. V.B. Chen, W.B. Arendall, J.J. Headd, D.A. Keedy, R.M. Immormino, G.J. Kapral, L.W. Murray, J.S. Richardson, and D.C. Richardson. Acta Cryst. D66, 16-21 (2010).

List of all available keywords