Overview

A composite omit map is an omit map covering the entire contents of the unit cell, generated by computing a number of omit maps covering specific regions, and combining the areas around the omitted regions. This allows a relatively bias-free map to be calculated for the structure without severely compromising phase quality. Because this is significantly slower than computing a simple omit map, it is not recommended if you are only interested in a specific ligand or problematic region of the structure. However, because the procedure is inherently parallel, it may be spread out over multiple processors or cluster nodes to limit the runtime.

The program phenix.composite_omit_map is used to generate these maps; internally, it is essentially no more than a wrapper for phenix.refine and the underlying map-calculation code. It may be run in three different modes:

• with simulated annealing, which aggressively removes residual bias in the partial models (but increases runtime).
• with minimization only, without annealing
• without refinement, which leaves the partial models alone, but performs an iterative procedure to quickly remove phase bias.

The final option is the default, since it is very fast but still effective. For best results we recommend running with simulated annealing, although this may be more problematic for especially poor and/or low-resolution structures.

Running the program

Execution of the program is very similar to running phenix.refine:

% phenix.composite_omit_map model.pdb data.mtz ligands.cif nproc=64

The requirements for input files and formats are the same. Because the program is intended to be as automatic as possible, only a limited subset of refinement parameters are exposed to the user. Refinement may be disabled by adding refine=False to the command line; annealing is switched on by adding anneal=True. Like phenix.refine, experimental phases (Hendrickson-Lattman coefficients) will be used automatically if present, and you may specify a twin law if necessary.

You may request any supported combination of maps using the same map type strings as elsewhere in Phenix, for instance 2mFo-DFc, anomalous, 3mFo-2DFc, and so on. The default map type is 2mFo-DFc, but the map_type keyword may specify one or more alternate maps. You may also change the choice of whether to fill in missing observations with F(calc) (off by default), or whether to exclude reflections flagged for calculating R-free (on by default). NCS averaging is also available as an option.

If simulated annealing is to be run, you may specify the dynamics type (annealing_type keyword, either "cartesian" or "torsion") and the starting temperature (annealing_temperature, which defaults to 5000K for Cartesian and 2500K for torsion; lower will run more quickly). The atoms left out of structure factor calculation will by default be restrained to their starting positions to prevent the other atoms from filling in the missing scattering. Note that the default behavior allows the bulk solvent mask to extend into the omitted region; this may be turned off by adding the argument exclude_bulk_solvent=True, but it is unclear what the best practice is.

The program will parallelize over multi-core systems or managed clusters (including Sun Grid Engine, PBS, and LSF queuing systems) if the nproc keyword is given. Use the technology keyword to specify the system type. The default behavior is to omit up to approximately 5% of the structure at a time (controlled by the fraction_omit keyword), but in practice because of the way the structure is divided there will be significantly more than 20 omit regions for the typical macromolecular structure. If you are unsure how many processes to use, specify nproc=Auto.

Output consists of a single MTZ file, named composite_omit_map.mtz by default; you may specify a preferred file name using the command line keyword output.file_name. This will contain amplitudes and phases for each map type. For 2mFo-DFc maps, the MTZ column labels will be interpretable using the auto-open function in Coot; all other map types require you to load them manually.

Singe-omit mode

The program can also be used to generate a simple omit map for a single region; the iterative de-bias procedure is not available in this mode, but you can perform refinement and/or simulated annealing. This is essentially equivalent to setting up a phenix.refine run manually, but with a simplified interface.

Other options

There are several other programs in Phenix with similar features:

• AutoBuild has an older implementation of this method. A more powerful approach is to generate an "iterative-build" omit map (Terwilliger et al. 2008), which rebuilds the structure instead of annealing.
• phenix.refine can be used to manually generate omit maps for a smaller selection of the model by specifying the omit_selection keyword. The single-omit mode of the composite omit map program is equivalent to this.
• phenix.maps can generate simple omit maps without refinement.

References

Model bias in macromolecular crystal structures. A. Hodel, S.H. Kim, and A.T. Brunger. Acta Cryst. A48, 851-858 (1992).

Iterative-build OMIT maps: map improvement by iterative model building and refinement without model bias. T.C. Terwilliger, R.W. Grosse-Kunstleve, P.V. Afonine, N.W. Moriarty, P.D. Adams, R.J. Read, P.H. Zwart, and L.-W. Hung. Acta Cryst. D64, 515-524 (2008).

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).

List of all available keywords

• input
  • sequence = None
  • scattering_table = wk1995 it1992 *n_gaussian neutron
  • wavelength = None
  • energy = None
  • use_experimental_phases = Auto
  • twin_law = None
  • xray_dataScope of X-ray data and free-R flags
    • file_name = None
    • labels = None
    • high_resolution = None
    • low_resolution = None
    • outliers_rejection = True Remove basic wilson outliers , extreme wilson outliers , and beamstop shadow outliers
    • french_wilson_scale = True
    • sigma_fobs_rejection_criterion = None
    • sigma_iobs_rejection_criterion = None
    • ignore_all_zeros = True
    • force_anomalous_flag_to_be_equal_to = None
    • convert_to_non_anomalous_if_ratio_pairs_lone_less_than_threshold = 0.5
    • french_wilson
      • max_bins = 60 Maximum number of resolution bins
      • min_bin_size = 40 Minimum number of reflections per bin
    • r_free_flags
      • file_name = None This is normally the same as the file containing Fobs and is usually selected automatically.
      • label = None
      • test_flag_value = None This value is usually selected automatically - do not change unless you really know what you're doing!
      • ignore_r_free_flags = False Use all reflections in refinement (work and test)
      • disable_suitability_test = False
      • ignore_pdb_hexdigest = False If True, disables safety check based on MD5 hexdigests stored in PDB files produced by previous runs.
      • generate = False Generate R-free flags (if not available in input files)
      • fraction = 0.1
      • max_free = 2000
      • lattice_symmetry_max_delta = 5
      • use_lattice_symmetry = True
      • use_dataman_shells = False Used to avoid biasing of the test set by certain types of non-crystallographic symmetry.
      • n_shells = 20
  • experimental_phases
    • file_name = None
    • labels = None
  • pdb
    • file_name = None Model file(s) name (PDB)
  • monomers
    • file_name = None Monomer file(s) name (CIF)
• output
  • file_name = composite_omit_map.mtz
  • debug = False Show additional debugging output, and save intermediate files.
  • directory = None Output directory for GUI jobs
  • job_title = None Job title in PHENIX GUI, not used on command line
• omit_map
  • map_type = None This should be a string representing standard map types, e.g. 2mFo-DFc. You may specify as many of these as you want (each as a separate argument).
  • omit_type = *simple refine anneal None Determines the method used to prepare the model used for phasing omit maps. The simple option de-biases the phases by treating F(model) directly in an iterative procedure. The refine and anneal options instead run phenix.refine on the partial model(s).
  • fraction_omit = 0.05 Fraction of atoms to omit at a time
  • resolution_factor = 0.25 Grid spacing for assembling partial maps.
  • fill_missing_f_obs = False Fill missing F(obs) with F(calc)
  • exclude_free_r_reflections = True Remove reflections flagged for R-free
  • map_types = None This should be a space-separated list of strings representing standard map types, e.g. 2mFo-DFc. Identical to the separate map_type parameter except that map types are combined into a single string.
  • boxing
    • selection = None Selection of atoms to omit in groups. If not specified, the procedure will use the entire structure. Not compatible with omit_type=simple.
    • single = False Generates a single omit map rather than instead of dividing into boxes and combining individual maps, equivalent to setting fraction_omit=1.0. The selection must be specified if this option is used.
    • ncs_average = False NCS average composite maps
    • box_cushion_radius = 2.5 Additional buffer around omitted region within which to set occupancies to zero.
    • exclude_bulk_solvent = False Prevent bulk solvent from extending into omitted regions.
    • optimize_binning = True Re-group omit regions to reduce the total number of regions while keeping the fraction omitted per region as similar as possible.
    • refinement
      • annealing_type = *cartesian torsion
      • annealing_temperature = Auto Defaults to 5000K for Cartesian, 2500K for torsion
      • ncs = Auto Use NCS restraints in refinement
      • harmonic_restraints = True Apply harmonic restraints to zero-occupancy atoms to prevent other atoms outside the omitted region from filling in the missing scattering.
      • harmonic_restraints_sigma = 0.1
      • vary_random_seed = False Vary the random seed between runs.
      • automatic_linking = False Automatically link covalent ligands (sugars, etc.).
    • ncs_averaging
      • resolution_factor = 0.25
      • use_molecule_mask = False
      • averaging_radius = 5.0
      • solvent_content = 0.5
      • exclude_hd = True
      • skip_difference_map = Auto
    • debuggingDebugging options, not for general use.
      • flatten_background = False
      • control_map = False
  • simple
    • n_debias_cycles = 2
    • neutral_volume_box_cushion_width = 1
    • full_resolution_map = True
• parallel
  • nproc = 1
  • technology = *multiprocessing sge lsf pbs condor slurm threading
  • qsub_command = None