phenix.map_box: extract box with model and map around selected atoms

Description

The program carves out a box with model and map around selected atoms. Resulting map is output in three files: map coefficients in MTZ, and maps in CCP4 and X-plor formatted files.

Contact author

For questions, bug reports, feature requests: Pavel Afonine (PAfonine@lbl.gov)

Usage examples

1. Using a map defined in MTZ file as Fourier map coefficients. Box is defined by selected atoms in residues from 1 to 10 in chain A

   phenix.map_box model.pdb map_coefficients.mtz selection="chain A and resseq 1:10"

2. Using a CCP4/mrc formatted map.

   phenix.map_box model.pdb map.ccp4 selection="resname LIG"

   Note that by default map_box chooses a rectangular box that is a little bigger than your model. If you want the map to be zeroed out away from your model you can use the keyword mask_atoms=True.

3. Extract unique part of a map. You can extract just the unique part of a map (unique based on map symmetry). This map is masked around high density. It will normally only have positive density and lower density parts of even the unique part are truncated. Note that if you want to sharpen the map, you must sharpen it before you extract the unique part. You should not sharpen a map file created with extract_unique because the extract_unique function creates a map that has been set to zero over much of the map and this interferes with auto-sharpen.

   phenix.map_box map.ccp4 extract_unique=True symmetry.ncs_spec resolution=3

4. Shift origin of a map. You can shift the origin of a map (redefine where in the unit_cell box the map goes). Normally you need to also specify the the map size should remain the same.

   You can specify the origin directly:

   phenix.map_box map.ccp4 keep_map_size=True prefix=map_origin_shifted

   output_origin_grid_units=3,5,7

   You can also specify the origin to be (0,0,0) with keep_origin=False:

   phenix.map_box map.ccp4 keep_map_size=True prefix=map_origin_shifted

   keep_origin=False

   You can also specify that the origin should match the origin of some other file. If you do this you have to use the keyword ccp4_map_file for the map to be shifted and output_origin_match_this_file for the one to match:

   phenix.map_box ccp4_map_file=map.ccp4 keep_map_size=True

   prefix=map_origin_shifted output_origin_match_this_file=map_with_origin_to_match.ccp4

5. Cut out a part of a map to match some other map. You can say:

   phenix.map_box ccp4_map_file=map.ccp4

   prefix=map_boxed bounds_match_this_file=map_with_bounds_to_match.ccp4

6. Invert the hand of a map:

   phenix.map_box ccp4_map_file=map.ccp4

   keep_map_size=True invert_hand = True

Notes

1. By default the output map will superimpose on the input map (keep_origin=True). The output map is normally smaller than the input map. For example, the input map might go from (0,0,0) to (100,100,100) and the output map might include only grid points from (50,50,50) to (100,100,100). The origin of the output map in this case will be (50,50,50). If the two maps are displayed, the region from (50,50,50) to (100,100,100) will be the same for the two maps. Not that anything outside of this range is meaningless for the output map.

2. The cell dimensions of the output map will be the dimensions of the part that is cut out. In the above example, if the starting unit cell was (200,200,200) then be output map will have a unit cell of (100,100,100).

3. Some maps may have a special tag called external_origin. In the map file it is called ORIGIN. This is different than the origin of the map, which specifies the grid point that corresponds to the first element in the map. The external_origin is a coordinate shift that may correspond to this grid point, but that does not have to fall right on a grid point.

   If a map (1) has an external_origin tag and (2) the external_origin falls on a grid point in the map, and (3) the map does not have an origin specified in the usual way, then the external_origin, converted to grid units, will be used as the origin of the map in Phenix.

   You can use phenix.show_map_info to display characteristics of your map. If you want to remove the external_origin tag from your map, you can run map_box with "keep_map_size=True" "keep_origin=False" and it will write out the same map but without the external_origin tag and without an origin shift. If you want to convert your external_origin tag to an origin shift, you can run map_box with "keep_map_size=True" and "keep_origin=True". Also, if you want to shift a model to match a map with an external_origin tag, you can use the tool phenix.shift_model_to_match_map (command-line only).

4. How map gridding is described in mrc/ccp4 format.

   Map specifications. A full map is defined for a full box or unit cell, however in many cases only a part of that map is present. The full map is on a grid of 'unit cell grid' which corresponds to one unit cell (box) with dimensions of 'unit cell parameters'.

   The map that is present is on part of the 'unit cell grid'. It starts at the grid point called the 'origin' and goes to one grid point in each direction before the grid point called 'last'. The map that is present has 'all' grid points in each direction. The map that is present has a 'map unit cell' and 'map grid' that correspond to the dimensions 'all'.

   Example: a full map with a unit cell grid of (10, 10, 10) goes from (0, 0, 0) to (9, 9, 9) and has dimensions of (10, 10, 10).

   Example: a partial map with a unit cell grid of (10,10,10) and an origin of (0, 0, 2) and a map grid or 'all' of (6, 6, 6), would go from (0, 0, 2) to (5, 5, 7).

5. Ignoring symmetry conflicts. If you cut out a part of a map, then the new map will have a box size that is different from the orginal one. If that box size does not match the box size for your PDB file or other map, then you may get an error message that says the symmetry of the maps or map and model is not the same. You can ignore this with the keyword ignore_symmetry_conflicts=True.

6. Running map_box with bounds that are outside the map. You can specify any lower and upper bounds for your output map, but if the bounds are outside the map you supply the values may not make any sense. By default the map you supply is wrapped so that the value for a point outside the map is taken from the grid point that would be in this place if another copy of the map were placed right next to your map. You can turn this off and instead supply zeroes outside the map with the keyword restrict_map_size=True.

List of all parameters

• job_title = None Job title in PHENIX GUI, not used on command line
• pdb_file = None Optional model file used to define region to be cut out
• map_coefficients_file = None Input map coefficients file (alternative to ccp4 map file)
• label = None Labels for map coefficients file
• ccp4_map_file = None Input map file (CCP4/mrc format).
• mask_file_name = None Input mask file (CCP4/mrc format).
• target_ncs_au_file = None File with model indicating which au to choose in extract_unique
• selection = all Atom selection to be applied to input PDB file
• selection_radius = 3.0 Atoms within selection_radius of a selected atom model will be kept as part of the selection.
• box_cushion = 3.0 If model is supplied, a box of density will be cut out around the input model (after selections are applied to the model). The size of the box of density will be box_cushion bigger than the model. Box cushion also applied if density_select is set. Box cushion is also used in extract_unique.
• mask_atoms = False Set map values to 0 outside molecular mask
• mask_atoms_atom_radius = 3. Radius for masking around atoms
• write_mask_file = False Write mask file. Requires setting mask_atoms
• set_outside_to_mean_inside = False Set value outside mask equal to mean inside
• resolution_factor = 1./4 Resolution factor for calculation of map coefficients
• map_scale_factor = None Scale factor to apply to map
• scale_max = 99999 Maximum value of amplitudes for output mtz file. If None, apply volume scaling
• resolution = None Resolution for calculation of output map coefficients. Default is based on the gridding of the map (and may be higher-resolution than you want).
• output_format = xplor *mtz *ccp4 Output format(s) for boxed map. Note that mtz format is only available if keep_origin = False or keep_map_size = True. (These are the cases where the map is cut down to size and placed at the origin or there is a full unit cell of data.)
• output_file_name_prefix = None Prefix for output file names. Default is name of the pdb file without the .pdb suffix.
• mask_select = False Select boundaries (min, max in x, y, z) based on auto-mask
• density_select = False Select boundaries based on where density is located.
• density_select_threshold = 0.05 Choose region where density is this fraction of maximum or greater
• get_half_height_width = True Use 4 times half-width at half-height as estimate of max size in density_select
• symmetry = None Optional symmetry (e.g., D7, I, C2) to be used if extract_unique is set. Alternative to symmetry_file. To find symmetry automatically specify symmetry = ALL.
• symmetry_file = None Symmetry file. Symmetry or symmetry_file required if extract_unique = True. May be a Phenix .ncs_spec file or BIOMTR records or a resolve ncs file.
• sequence_file = None Sequence file (any standard format). Can be unique part or all copies. Used in identification of unique part of map and in masking with mask_select
• molecular_mass = None Molecular mass of object in map in Da (i.e., 33000 for 33 Kd). Used in identification of unique part of map and in masking by mask_select.
• solvent_content = None Optional fraction of volume of map that is empty. Used in identification of unique part of map and in masking by mask_select
• extract_unique = False Extract unique part of map. Requires either symmetry_file or symmetry and either sequence file or molecular mass to be supplied. If chain type is not protein it should be set as well.
• increase_box_cushion_and_atom_radius_for_soft_mask = True Expand cushion and atom radii by soft_mask_radius
• soft_mask_extract_unique = True Create soft mask at edges of extract_unique box (feather map into edge of box). Uses resolution as mask_radius
• mask_expand_ratio = 1 Mask expansion relative to resolution for extract_unique
• regions_to_keep = None You can specify a limit to the number of regions to keep when generating the asymmetric unit of density.
• keep_low_density = True Get remainder (weak density) with extract_unique.
• chain_type = None *PROTEIN DNA RNA Chain type. Only used if extract_unique is set. Has minor effect in setting thresholds for identification of molecular region. Use None if there is a mixture.
• soft_mask = False Use Gaussian mask in mask_atoms and on outside surface of box
• invert_mask = False Make mask with 1 outside model (only applies to mask_around_atoms)
• soft_mask_radius = 3 Gaussian mask smoothing radius
• lower_bounds = None Lower bounds for cut out box. You can specify them directly. NOTE: lower and upper bounds refer to grid points after shifting the map to place the origin at (0, 0, 0). To refer to absolute values specify bounds_are_absolute = True.
• upper_bounds = None Upper bounds for cut out box. You can specify them directly. NOTE: lower and upper bounds refer to grid points after shifting the map to place the origin at (0, 0, 0). To refer to absolute values specify bounds_are_absolute = True.
• bounds_are_absolute = False Define lower and upper bounds as absolute. NOTE: lower and upper bounds refer to grid points after shifting the map to place the origin at (0, 0, 0). To refer to absolute values specify bounds_are_absolute = True.
• zero_outside_original_map = False If bounds for new map are outside original map, zero all points outside of original map
• keep_map_size = False Keep original map gridding (do not cut anything out). Use to apply soft_mask and/or mask_atoms keeping same map size.
• keep_origin = True Write out map, map_coefficients, and model with origin in original location. If False, shift the origin to (0, 0, 0). NOTE: to cut out a part of a map, shift the origin to (0, 0, 0), and make a new small map use keep_origin = False keep_input_unit_cell_and_grid = False
• keep_input_unit_cell_and_grid = True Keep the input unit_cell dimensions and unit_cell_grid. If False, use the dimensions and grid of the cut out box as the unit cell map_box dimensions and grid. NOTE: to cut out a part of a map, shift the origin to (0, 0, 0), and make a new small map set keep_origin = False and keep_input_unit_cell_and_grid = False
• output_unit_cell = None You can specify the unit cell for your map with 3 numbers. This should normally not be necessary. It can be used to fix a map that has the wrong unit cell.
• output_unit_cell_grid = None You can specify the grid (3 integers) corresponding to the output unit cell. This can be used to specify the full grid for the unit cell. if output_unit_cell is not specified, new unit cell parameters will be generated to maintain the grid spacing.
• output_origin_grid_units = None You can specify the origin of your output map. Normally you should use keep_origin = True or False to specify your origin but if you want to move it to a specific grid point you can do that. .short_caption = Output origin
• output_origin_match_this_file = None As output_origin_grid_units, but use origin from this file
• bounds_match_this_file = None Take the lower and upper bounds from this map file and apply them to the input map file.
• output_external_origin = None Write ORIGIN record to map file (this is an external origin used to specify relationship to external files such as model files. Three floating point numbers (A).
• restrict_map_size = False Do not go outside original map boundaries
• ignore_symmetry_conflicts = False Ignore unit cell from model if it conflicts with the map.
• wrapping = False If wrapping, map wraps around at map boundaries.
• check_wrapping = False Check that wrapping is consistent with map if it is set to True
• output_ccp4_map_mean = None Choose mean and SD of output CCP4 map
• output_ccp4_map_sd = None Choose mean and SD of output CCP4 map
• output_map_label = None Add this label to output map
• remove_output_map_labels = None Remove all output map labels
• invert_hand = False Just before writing out the map, swap the order of all sections in Z. This will change the hand of the map. Note that this removes any correspondence to models (these are not inverted). If you use this, be sure to apply it to all your starting maps. .short_caption = Invert hand of map
• guiGUI-specific parameter required for output directory
  • output_dir = None