Auto-sharpening cryo-EM maps with auto_sharpen
Author(s)
- auto_sharpen: Tom Terwilliger
Purpose
The routine auto_sharpen will automatically identify optimal
sharpening/blurring/map adjustment for the input map and will write
out an optimized version of the map. Whether or not the origin is in
the middle of the input map, the output map will have the origin at one corner.
Usage
How auto_sharpen works:
Auto-sharpen adjusts the resolution dependence of the map
to maximize the clarity of the map. You can choose to use
map kurtosis or the adjusted surface area of the map (default) for this
purpose.
Kurtosis is a standard statistical measure that reflects the peakiness of
the map.
The adjusted surface area is a combination of the surface area of
contours in the map at a particular threshold
and of the number of distinct regions enclosed by the top 30% (default) of
those contours. The threshold is chosen by default to be one where the
volume enclosed by the contours is 20% of the non-solvent volume in the map.
The weighting between the surface area (to be maximized) and number of regions
enclosed (to be minimized) is chosen empirically (default region_weight=20).
Several resolution-dependent functions are tested, and the one
that gives the best kurtosis (or adjusted surface area) is chosen.
In each case the map is transformed to obtain Fourier coefficients. The
amplitudes of these coefficients are then adjusted, keeping the phases
constant. The available functions for modifying the amplitudes are:
No sharpening (map is left as is)
Sharpening b-factor applied over entire resolution range (b_sharpen
applied to achieve an effective isotropic overall b-value of b_iso).
Sharpening b-factor applied up to resolution specified with the
resolution=xxx keyword, then not applied beyond this resolution (with
transition specified by the keyword k_sharpen, b_iso_to_d_cut). If
blurring (sharpening with value less than zero) is applied,
the blurring is applied over the entire resolution range.
Resolution-dependent sharpening factor with three parameters.
First the resolution-dependence of the map is removed by normalizing the
amplitudes. Then a scale factor S is to the data, where
log10(S) is determined by coefficients b[0],b[1],b[2] and a resolution
d_cut (typically d_cut is the nominal resolution of the map).
The value of log10(S) varies smoothly from 0 at resolution=infinity, to b[0]
at d_cut/2, to b[1] at d_cut, and to b[1]+b[2] at the highest resolution
in the map. The value of b[1] is limited to being no larger than b[0] and the
value of b[1]+b[2] is limited to be no larger than b[1].
You can also choose to specify the sharpening/blurring parameters for your
map and they will simply be applied to the map. For example you can apply
a sharpening B-value (b_sharpen) to sharpen the map, or you can specify a
target overall B-value (b_iso) to obtain after sharpening.
Output files from auto_sharpen
sharpened_shifted_map.ccp4: Sharpened map, shifted to place the origin on grid point (0,0,0) and sharpened
sharpened_shifted_map.mtz: Sharpened map, shifted to place the origin on grid point (0,0,0) and sharpened. Map coefficients corresponding to the ccp4 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.
Examples
Standard run of auto_sharpen:
Running auto_sharpen is easy. From the command-line you can type:
phenix.auto_sharpen my_map.map resolution=2.6
where my_map.map is a CCP4, mrc or other related map format, and you
specify the nominal resolution of the map.
Possible Problems
Specific limitations and problems:
Literature
Additional information
List of all available keywords
- job_title = None Job title in PHENIX GUI, not used on command line
- input_files
- map_file = None File with CCP4-style map
- half_map_file = None Half map (two should be supplied) for FSC calculation. Must have grid identical to map_file
- map_coeffs_file = None Optional file with map coefficients
- map_coeffs_labels = None Optional label specifying which columns of of map coefficients to use
- pdb_file = None If a model is supplied, the map will be adjusted to maximize map-model correlation. This can be used to improve a map in regions where no model is yet built.
- ncs_file = None File with NCS information (typically point-group NCS with the center specified). Typically in PDB format. Can also be a .ncs_spec file from phenix. Created automatically if ncs_type is specified.
- seq_file = None Sequence file (unique chains only, 1-letter code, chains separated by blank line or greater-than sign.) Can have chains that are DNA/RNA/protein and all can be present in one file.
- input_weight_map_pickle_file = None Weight map pickle file
- output_files
- shifted_map_file = shifted_map.ccp4 Input map file shifted to new origin.
- sharpened_map_file = sharpened_map.ccp4 Sharpened input map file. In the same location as input map.
- shifted_sharpened_map_file = None Input map file shifted to place origin at 0,0,0 and sharpened.
- sharpened_map_coeffs_file = sharpened_map_coeffs.mtz Sharpened input map (shifted to new origin if original origin was not 0,0,0), written out as map coefficients
- output_weight_map_pickle_file = weight_map_pickle_file.pkl Output weight map pickle file
- output_directory = None Directory where output files are to be written applied.
- crystal_info
- use_sg_symmetry = False If you set use_sg_symmetry=True then the symmetry of the space group will be used. For example in P1 a point at one end of the unit cell is next to a point on the other end. Normally for cryo-EM data this should be set to False and for crystal data it should be set to True.
- resolution = None Optional nominal resolution of the map.
- solvent_content = None Optional solvent fraction of the cell.
- solvent_content_iterations = 3 Iterations of solvent fraction estimation. Used for ID of solvent content in boxed maps.
- map_modification
- b_iso = None Target B-value for map (sharpening will be applied to yield this value of b_iso)
- b_sharpen = None Sharpen with this b-value. Contrast with b_iso that yield a targeted value of b_iso
- resolution_dependent_b = None If set, apply resolution_dependent_b (b0 b1 b2). Log10(amplitudes) will start at 1, change to b0 at half of resolution specified, changing linearly, change to b1 at resolution specified, and change to b2 at high-resolution limit of map
- d_min_ratio = 0.833 Sharpening will be applied using d_min equal to d_min_ratio times resolution. Default is 0.833
- rmsd = None RMSD of model to true model (if supplied). Used to estimate expected fall-of with resolution of correct part of model-based map. If None, assumed to be resolution/3.
- fraction_complete = None Completness of model (if supplied). Used to estimate correct part of model-based map. If None, estimated from max(FSC).
- auto_sharpen = True Automatically determine sharpening using kurtosis maximization or adjusted surface area. Default is True
- auto_sharpen_methods = *no_sharpening *b_iso *b_iso_to_d_cut *resolution_dependent model_sharpening half_map_sharpening None Methods to use in sharpening. b_iso searches for b_iso to maximize sharpening target (kurtosis or adjusted_sa). b_iso_to_d_cut applies b_iso only up to resolution specified, with fall-over of k_sharpen. Resolution dependent adjusts 3 parameters to sharpen variably over resolution range. Default is b_iso, b_iso_to_d_cut and resolution_dependent.
- box_in_auto_sharpen = True Use a representative box of density for initial auto-sharpening instead of the entire map. Default is True.
- discard_if_worse = False Discard sharpening if worse
- local_sharpening = None Sharpen locally using overlapping regions
- select_sharpened_map = None Select a single sharpened map to use
- read_sharpened_maps = None Read in previously-calculated sharpened maps
- write_sharpened_maps = None Write out local sharpened maps
- smoothing_radius = None Sharpen locally using smoothing_radius. Default is 2/3 of mean distance between centers for sharpening
- local_aniso_in_local_sharpening = True Use local anisotropy in local sharpening
- box_center = None You can specify the center of the box (A units)
- box_size = 40 40 40 You can specify the size of the box (grid units)
- remove_aniso = True You can remove anisotropy (overall and locally) during sharpening
- max_box_fraction = None If box is greater than this fraction of entire map, use entire map. Default is 0.5.
- mask_atoms = True Mask atoms when using model sharpening
- mask_atoms_atom_radius = 3 Mask for mask_atoms will have mask_atoms_atom_radius
- value_outside_atoms = None Value of map outside atoms (set to mean to have mean value inside and outside mask be equal)
- k_sharpen = None Steepness of transition between sharpening (up to resolution ) and not sharpening (d < resolution). Note: for blurring, all data are blurred (regardless of resolution), while for sharpening, only data with d about resolution or lower are sharpened. This prevents making very high-resolution data too strong. Note 2: if k_sharpen is zero or None, then no transition is applied and all data is sharpened or blurred. Default is 10.
- maximum_low_b_adjusted_sa = 0. Require adjusted surface area to be this value or less when map is highly sharpened (at value of search_b_min).
- search_b_min = None Low bound for b_iso search. Default is -100.
- search_b_max = None High bound for b_iso search. Default is 300.
- search_b_n = None Number of b_iso values to search. Default is 21.
- residual_target = None Target for maximization steps in sharpening. Can be kurtosis or adjusted_sa (adjusted surface area). Default is adjusted_sa.
- sharpening_target = None Overall target for sharpening. Can be kurtosis or adjusted_sa (adjusted surface area). Used to decide which sharpening approach is used. Note that during optimization, residual_target is used (they can be the same.) Default is adjusted_sa.
- require_improvement = None Require improvement in score for sharpening to be applied. Default is True.
- region_weight = None Region weighting in adjusted surface area calculation. Score is surface area minus region_weight times number of regions. Default is 20. A smaller value will give more sharpening.
- sa_percent = None Percent of target regions used in calulation of adjusted surface area. Default is 30.
- fraction_occupied = None Fraction of molecular volume targeted to be inside contours. Used to set contour level. Default is 0.20
- n_bins = None Number of resolution bins for sharpening. Default is 20.
- max_regions_to_test = None Number of regions to test for surface area in adjusted_sa scoring of sharpening. Default is 30
- eps = None
- k_sol = 0.35 k_sol value for model map calculation
- b_sol = 50 b_sol value for model map calculation
- control
- verbose = False Verbose output
- resolve_size = None Size of resolve to use.
- guiGUI-specific parameter required for output directory