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 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 CCP4 formatted map

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

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

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

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).
• 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 mask_atoms is False, 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.
• mask_atoms = False Set map values to 0 outside molecular mask
• mask_atoms_atom_radius = 3. Radius for masking around atoms
• value_outside_atoms = None Set to mean to make average value same inside and outside mask.
• 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.
• 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
• 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.
• 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.
• solvent_content = None Optional fraction of volume of map that is empty. Used in identification of unique part of map.
• 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.
• box_buffer = 5 Padding around unique region
• 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
• 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).
• 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).
• 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
• 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.
• 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_labels = None Add this label to output map
• guiGUI-specific parameter required for output directory
  • output_dir = None