Model-building into cryo-EM and low-resolution maps with map_to_model
Author(s)
- map_to_model: Tom Terwilliger
Purpose
The routine map_to_model will interpret a map (cryo-EM, low-resolution
X-ray) and try to build an atomic model, fully automatically.
Usage
How map_to_model works:
If you have a CCP4-style (mrc, etc) map or just mtz map coefficients
and a sequence file, you can use map_to_model to build a model into
your map. The tool map_to_model will identify what kind of chains to
build based on your sequence file. It will find where your molecule is
in the map and cut out and work with just that part of the density.
If your map has been averaged based on NCS symmetry and
you supply a file with that NCS information (.ncs_spec, biomtr.dat, etc),
map_to_model will find the asymmetric unit of NCS, build that, then
expand to the entire map. The map_to_model tool will cut the density
in your map into small pieces of connected density and
try to build model into each one. It will merge all the
pieces into a compact model, refine it, and superimpose
final model on the original map. The type of chain or chains to be
built are chosen based on your sequence file. If multiple chain types
are considered, the entire map is interpreted with each chain type, then
the best-fitting non-overlapping chains are chosen.
Output files from map_to_model
- map_to_model.pdb: A PDB file with the resulting model, superimposed on
- the original map
Shifting the map to the origin
Most crystallographic maps have the origin at the corner of the map (
grid point [0,0,0]), while most cryo-EM maps have the orgin in the
middle of the map. To make a consistent map, any maps with an origin not
at the corner are shifted to put the origin at grid point [0,0,0]. This map
is the shifted map that is used for further steps in model-building.
At the conclusion of model-building, the model is shifted back to
superimpose on the original map.
Finding the region containing the molecule
By default (density_select=True), the region of the map containing density
is cut out of the entire map. This is particularly useful if the original map
is very large and the molecule only takes up a small part of the map. This
portion of the map is then shifted to place the origin at grid point [0,0,0].
(At the conclusion of model-building, the final model is shifted back to
superimpose on the original map.) The region containing density is chosen
as a box containing all the points above a threshold, typically 5% of the
maximum in the map.
Finding the NCS asymmetric unit of the map
If you supply NCS matrices describing the NCS used to average the map (if any),
then map_to_model will try to define a region of the map that represents
the NCS asymmetric unit. Application of the NCS operators to the NCS
asymmetric unit will generate the entire map, and application to a model built
into the asymmetric unit will generate the entire model. Normally
identification of the NCS asymmetric unit and segmentation of the map (below)
are done as a single step, yielding an asymmetric unit and a set of
contiguous regions of density within that asymmetric unit. The asymmetric unit
of NCS will be written out as a map to the segmentation_dir directory,
superimposed on the shifted map (so that they can be viewed together in Coot).
Segmentation of the map
By default (segment=True) the map or NCS asymmetric unit of the map will
be segmented (cut into small pieces) into regions of connected density. This
is done by choosing a threshold of density and identifying contiguous regions
where all grid points are above this threshold. The threshold is chosen to
yield regions that have a size corresponding to about 50 residues. The
regions of density are written out to the segmentation_dir directory
and are superimposed on the shifted map (if you load the shifted map in
Coot and a region map in Coot, they should superimpose.)
Model-building
Models are built in several ways by map_to_model and then the best-fitting,
non-overlapping models are chosen. The main methods used for model-building
are:
Standard RESOLVE model-building for PROTEIN/RNA/DNA for the entire
asymmetric unit of NCS (or the entire molecule if no NCS).
Helices (RNA) or helices/strands (PROTEIN) for entire asymmetric unit
tracing chain (RNA/PROTEIN/DNA) for each segmented region, with various
values of map sharpening applied
RESOLVE model-building for each segmented region, with various values of
map sharpening applied
Intermediate models are refined with phenix.real_space_refine and are
written out relative to the shifted map with origin at [0,0,0].
You can view these intermediate models, the shifted map, and the
shifted map containing just the asymmetric unit of NCS, and any
region maps in Coot and they should all superimpose.
Once all intermediate models are built, all models of each chain type are
combined, taking the best-fitting model for each part of the map. Then all
chain types are combined, once again taking the best-fitting model for each
part of the map. The models are refined again.
Then (if present) NCS is applied to the model and the full model is refined.
Finally the best model, with NCS applied if present, is shifted to match
the original map and is written out.
Examples
Standard run of map_to_model:
Running map_to_model is easy. From the command-line you can type:
phenix.map\_to\_model my_map.map seq.fa ncs_file=find_ncs.ncs_spec
where my_map.map is a CCP4, mrc or other related map format, seq.fa is a
sequence file, and find_ncs.ncs_spec is an optional file specifying any
NCS operators used in averaging the map. This can be in the form of
BIOMTR records from a PDB file as well.
Possible Problems
Specific limitations and problems:
Literature
Additional information
List of all available keywords
- input_files
- map_coeffs_file = None File with map coefficients
- map_coeffs_labels = None Optional label specifying which columns of of map coefficients to use
- map_file = None File with CCP4-style map
- seq_file = None Sequence file
- pdb_in = None Input PDB file to use instead of tracing chains
- ncs_file = None Input NCS spec file for use with segment_and_split_map.
- seed_ca_in = None Input PDB file with possible CA positions to assist in tracing chains
- seed_ca_only = False Only use sites from seed_ca_in (do not find additional sites)
- model_pickle_file = None Pickle file with working models. You can read in this file and and start with the models in it.
- info_pickle_file = None Pickle file from segment_and_split_map. You can read in this file and and choose which map file to use.
- input_map_id_start = None first ID (number 1 to N) of the map to analyze from info_pickle file
- input_map_id_end = None last ID (number 1 to N) of the map to analyze from info_pickle file
- output_files
- pdb_out = map_to_model.pdb Output PDB file
- pdb_out_reverse = map_to_model_reverse.pdb Optional output reversed PDB file (traced opposite direction as pdb_out). Created if include_reverse is set.
- protein_mask_file = None Output ccp4-style map with mask for region of macromolecule
- region_model_suffix = None Suffix (before .pdb) for region models
- output_dir = None Place where final files will go
- segmentation_directory = segmented_maps Place where segmented maps will go if segment=True
- crystal_info
- resolution = None High-resolution limit. Data will be truncated at this resolution. If a map is supplied, it will be Fourier filtered at this resolution. Required if input is a map and only_original_map is not set.
- map_inside_box = True Place centers of all chains inside (0,1). This is required during normal operationi.
- space_group = None Space group (normally read from the data file)
- unit_cell = None Unit Cell (normally read from the data file)
- chain_type = PROTEIN DNA RNA Do not set. Use chain_types instead.
- chain_types = PROTEIN DNA RNA Chain type (PROTEIN/DNA/RNA). You can choose one or more. If not specified; it will be guessed from your sequence file. Multiple chain types are fine.
- sequence = None Sequence as text string. Normally supply a sequence file instead
- solvent_fraction = None Same as solvent_content
- solvent_content = None Solvent fraction of the cell. If this is density cut out from a bigger cell, you can specify the fraction of the volume of this cell that is taken up by the macromolecule. Normally set automatically. Values go from 0 to 1.
- solvent_content_iterations = 3 Iterations of solvent fraction estimation
- scattering_table = *n_gaussian wk1995 it1992 electron neutron Choice of scattering table for structure factor calculations. Standard for X-ray is n_gausian, for cryoEM is electron.
- origin_frac = None Saves origin shift
- strategy
- density_select = True Run map_box with density_select=True to cut out the region in the input map that contains density. Useful if the input map is much larger than the structure.
- segment = True Run segment_and_split_map to break up map into pieces for model-building (recommended for larger structures). You can also run segment_and_split_map separately and then run model-building (there are more parameters available for segment_and_split_map in that case).
- include_build_one_model = True If segment is True, also run build_one_model on the entire asymmetric unit of the map.
- include_helices_strands_only = True If segment is True, also run build_one_model on the entire asymmetric unit of the map with helices_stands (protein) or with build_rna_helices (RNA).
- max_nproc_for_build_one_model = 30 Use only up to this number of processors for a single run of build_one_model. Typically there is little time advantage to using more than about 30 processors and if you use too many the time could increase and quality decrease due to splitting up the model-building too much.
- include_reverse = False Create reversed model where all chains are traced in opposite direction to pdb_out
- reverse_only = False Only create reversed model where all chains are traced in opposite direction to pdb_out (requires input model).
- quick = False Run quickly (sets b_sharpen=0, thorough_resolve_model_building=False, ss_refine_ncycle=1
- superquick = False Run very quickly just to test routines
- pdb_in_only = None Only use pdb_in (do not build anything new)
- segmentation
- value_outside_mask = 0.0 Value to assign to density outside masks in segment_and_split_map
- min_relative_helical_cc_to_keep = 0.90 For helical symmetry, keep copies within this range of max at end
- sharpening
- include_original_map = False You can include the original map without Fourier filtering or in tracing chain with this keyword. To use only the original map use only_original_map=True
- only_original_map = False You can include just the original map without Fourier filtering. Applies if the starting point is a map (not map coefficients).
- b_sharpen = None B-factor for sharpening (positive is sharpen, negative is blur) Note: if resolution is specified map will be Fourier filtered to that resolution even if it is not sharpened.
- b_sharpen_low = -105 Lowest value of b_sharpen to use. Applies if b_sharpen_delta is set. Negative is blur, positive is sharpen.
- b_sharpen_high = 0 Ending value of b_sharpen. Applies if b_sharpen_delta is set Negative is blur, positive is sharpen.
- b_sharpen_delta = 15 Incremental value of b_sharpen. If set, b_sharpen will be applied with values from b_sharpen_low to b_sharpen_high in increments of b_sharpen_delta. Ignored if b_sharpen is set.
- resolve_model_building
- run_resolve_model_building = None Run resolve model-building algorithm on maps. If None, set to True for RNA/DNA and False for protein.
- thorough_resolve_model_building = True Use thorough resolve model-building
- run_helices_strands_only = None Run resolve helices-strands-only algorithms on maps. If None set to True for RNA and False for protein. This applies to segmented maps only if they exist. Compare with include_helices_strands_only which applies to the entire asymmetric unit
- trace_chain
- run_trace_chain = True Run trace-chain model-building algorithm on maps
- rho_cut_min = 2.0 Minimum density (rho/sigma) at coordinates of potential CA atoms in trace_chain, after normalization for solvent fraction. For constant actual local rms in a map, the sigma (overall rms) of the map is proportional to the sqrt(1-solvent_fraction). Therefore rho_cut_min is adjusted by sqrt(0.5)/sqrt(1-solvent_fraction) to place it on a constant scale relative to a map with standard local rms.
- rho_cut_min_low = 1. Starting value of rho_cut_min. Applies if rho_cut_min_delta is set (rho_cut_min is ignored in this case)
- rho_cut_min_high = 5 Ending value of rho_cut_min. Applies if rho_cut_min_delta is set
- rho_cut_min_delta = None Incremental value of rho_cut_min. If set, rho_cut_min will be ignored
- rat_pair_min = 0.5 Minimum ratio of density at midpoint between points to trace chain between them
- dist_ca_tol_max = 0.80 Maximum tolerance for CA-CA distances. Normally 0.8 A for thorough run and 1.3 A for quick
- dist_ca_tol_start = 0.10 Minimum tolerance for CA-CA distances.
- rad_sep_trace = 0.75 Dummy atom separation in trace_chain Usual 0.6 A for thorough run and 0.75 for quick Increased automatically if resolution is greater than 3 A Value of rad_mask_trace in resolve will be rad_sep_trace*2
- target_p_ratio = 3 Target ratio of nonamers to peaks in trace_chain
- max_triple_ratio = 10 Maximum ratio of triples to pairs in trace_chain
- max_pent_ratio = 10 Maximum ratio of pentamers to pairs in trace_chain
- atom_target_ratio = 0.45 Target ratio of CA to look for to expected atoms in structure Standard is 0.45, quick is 0.35
- build_both_directions = False Build chains both directions and choose after merging
- min_end_correl = 0.5 Minimum correlation of direction estimated from two ends to use end matching as criterion for keeping a chain
- add_side_chains = True Add in side chains at trace_chain step
- crossing
- combine_models = True Merge models from trace_chain to form single model
- standard_merge = None Merge by reading all chains and running resolve merging.
- use_cc_in_combine_extend = None You can choose to use the correlation of density rather than density at atomic positions to score models in the merge_second_model or merge_both_models step. This may be useful at lower resolution (> 3 A)
- merge_remainder = True Merge remainder in merge_by_segment_correlation
- merge_by_segment_correlation = True Merge using segment correlation if merge_with_combine_models is selected. Can be used along with merge_remainder=True/False and standard_merge=True/False
- merge_second_model = True In merging models, cut up second model to fill gaps in first Normally used internally.
- wang_radius = 5 Smoothing radius for solvent identification
- cc_min = 0.40 Minimum map-model correlation to keep a segment after refinement
- cc_min_rna = 0.25 Minimum map-model correlation (RNA/DNA building)
- contact_distance = 3.0 Minimum distance between N/P/C1' in different chains. Used to reject NCS-related chains.
- ncs_clash_threshold = 2. Threshold for considering two atoms too close after applying NCS
- refinement
- refine = True Refine fragments after each building cycle
- number_of_sa_models = 20 Number of refinement sa_models.
- number_of_trials = 20 Number of refinement trials.
- number_of_macro_cycles = 5 Number of refinement macro_cycles.
- number_of_build_cycles = 5 Number of refinement (SA) cycles.
- rebuilding
- rebuild = True Rebuild model. Only for protein.
- rebuild_cycles = 2 Number of rebuilding cycles. Set to zero to skip rebuilding.
- trace_loops = True Rebuild model by iterative loop tracing. Only for protein.
- trace_loops_target_time = 60 Target time for completing a single trace_loops job. You can decrease it to speed it up (and miss some rebuilding) or increase it and possibly get some more successful rebuilding.
- loop_lib = False Rebuild model using loop library. Only for protein.
- rebuild_length = 8 Length of segments to be rebuilt
- rebuild_length_worst = 6 Length of segments to be rebuilt in rebuilding worst sections
- offset_length = 3 Offset of segments to be rebuilt
- rebuild_length_loop_lib = 3 Length of segments to be rebuilt with loop library (max=3)
- offset_length_loop_lib = 1 Offset of segments to be rebuilt with loop library
- start_res = None Start residue for rebuilding. Normally use None.
- end_res = None Ending residue for rebuilding. Normally use None.
- worst_rebuild_percent = 10 If specified, this percentage of residues will be rebuilt. Otherwise, the entire model will be rebuilt
- target_insert = None Length of insert to put from start_res to end_res Normally leave blank. Can be used to force the addition or subtraction of residues.
- target_insert_offset = None If non-zero, try to rebuild with this number of extra residues in each rebuilt segment. Normally leave blank. Can be used to force the addition or subtraction of residues.
- iterative_ss_refine
- iterative_ss = True Run iterative assignment of secondary structure and refinement with secondary structure restraints
- ss_refine_ncycle = None Overall cycles of iterative secondary_structure identification and refinement. Default is 10
- refine_cycles = 5 Cycles of refinement within iterative secondary structure and refinement
- parallel_runs = 4 Number of parallel runs of iterative secondary structure assignment and refinement. Best model from each group is taken each cycle
- combine_annotations = False Combine existing secondary_structure annotations each cycle with new annotations
- replace_side_chains = True Replace side chains during iterative optimization
- regularize = True regularize secondary structure during iterative optimization
- mr_rosetta
- run_mr_rosetta = False Run mr_rosetta to rebuild model
- rosetta_models = 20 Number of rosetta models to build
- relax_models = 5 Number of relaxed rosetta models to build
- rosetta_fixed_seed = None Fixed seed for Rosetta. Only use for regression tests.
- control
- multiprocessing = *multiprocessing sge lsf pbs condor pbspro slurm Choices are multiprocessing (single machine) or queuing systems
- queue_run_command = None run command for queue jobs. For example qsub.
- nproc = 1 Number of processors to use
- build_only = False Only build model (then stop)
- build_and_refine_only = False Only build model and refine (then stop)
- resolve_size = None Size of resolve to use.
- random_seed = 77151 Random seed (allows duplicating calculations or getting different results each time.)
- verbose = False Verbose output
- comparison_model = None Comparison model