Author(s)

• cut_out_density: Tom Terwilliger

Purpose

This routine cuts density out of a map and writes an MTZ file in space group P1 with map coefficients for the cutout density. The density map is calculated from map coefficients supplied as an input MTZ file. The region to be cut out is specified through the center of the region and dimensions in X Y and Z of a box to be cut out (cutout_center=X,Y,Z and cutout_dimensions=a,b,c). Alternatively the region can be specified with a PDB file and optional atom selections, with all points within a specified radius of an atom included, or the region can be specified with a center and the radius of a sphere to include. The density in the region cut out can optionally be offset to have a mean density of zero. The region outside the cut out region always will have a density of zero. The cut out region can be optionally padded with flat density an additional distance beyond the box that is cut out (padding=xx). The resolution of the cutout map can also be specified (the input map will be truncated at the high-resolution limit specified, and the output map will extend to the high-resolution limit.)

Usage

The main uses of phenix.cut_out_density are:

• Cutting out a small part of a map and molecule to work on independently of the rest of the structure. This can be useful if you have a very large structure, as working with a small piece may be much quicker. Note that you can only carry out real-space methods on the extracted map and model.
• Cutting density out of a map to use in molecular replacement. In this case it is easiest to use the keyword "for_phaser=True" to make a file suitable for use in Phaser.

Please note: you should not use phenix.cut_out_density to select regions near your model for display purposes. You can create a highly misleading map by displaying only density that is within a small radius of atoms in your model.

How cut_out_density works:

cut_out_density assumes that you are supplying map coefficients and calculates a map. Then it creates a new unit cell in space group P1 with orthogonal axes and dimensions big enough for your cut out region and padding of zero density around it. The density in your map at the center you specify is then centered at the origin in the new map. Then new map coefficients are created and written out.

You can optionally specify the region to be cut out as a box, a sphere, or a region defined by all points within a specified distance of atoms in a PDB file.

You can specify the center of the region to be cut out with its coordinates, or as the centroid of a PDB file that is input.

If you specify an input PDB file, you can use a selection string to select any part of that model (i.e., one domain or one chain) as the region to be cut out or as the center of the cut out region.

If you specify an input PDB file, then the selected atoms from that file will be offset to match the new map and written out.

As a convenience, you can re-transform a PDB file back to the original position in your original model as well.

Output files from cut_out_density

cutout.mtz: An MTZ file with your cut out density in space group P1.

cutout.pdb: A PDB file with your input molecule translated to match the offset used in creating cutout.mtz

Examples

Standard run of cut_out_density:

Running cut_out_density is easy. From the command-line you can type:

phenix.cut_out_density model.pdb map_coeffs.mtz

Preparing density for molecular replacement in Phaser:

The for_phaser=True keyword sets most of the defaults appropriately. You have to provide a PDB file with atoms defining the centers of spheres around which the density should be cut out. Set the cutout_model_radius parameter to define the size of the spheres. If you have a reasonably detailed atomic model, a value of 3. may be appropriate, but you may have a PDB file specifying one big sphere as in this command:

phenix.cut_out_density for_phaser=True cutout_model_radius=15 sphere.pdb map_coeffs.mtz

List of all available keywords

• cut_out_density
  • input_files
    • pdb_in = None Input PDB file marking region to cut out
    • mtz_in = None Input MTZ file with map coefficients
    • map_coeff_labels = None If map coefficients cannot be identified automatically from your MTZ file, you can specify the label or labels for them. (Please separate labels with blank space, MTZ columns grouped together separated by commas with no blanks.) You can specify: map_coeff_labels (e.g., FWT,PHIFWT) amplitudes and phases (e.g., FP,SIGFP PHIB) or amplitudes, phases, weights (e.g., FP,SIGFP PHIB FOM)
    • pdb_to_restore_position = None You can supply a PDB file that has previously been offset by this routine and it will restore it to its original position. You should specify everything else just as you did originally, then just add these two keywords and their values: pdb_to_restore_position=my_offset_pdb_file_with_edits.pdb and pdb_restored_in_position=my_restored_pdb.pdb Nothing will be run except your pdb_to_restore_position will be offset by the right amount and rewritten to pdb_restored_in_position
    • pdb_to_trim = None You can supply a PDB file to trim down to the region that is cut out of density. (Note only applicable for box and sphere values of cutout_type)
  • output_files
    • mtz_out = cutout.mtz Output MTZ file in sg p1 with cutout of density
    • pdb_out = cutout.pdb Output PDB file offset to match mtz_out If atom_selection is specified, only selected atoms are written to cutout.pdb
    • pdb_restored_in_position = None Name of output PDB file restored to its original position. You can supply a PDB file that has previously been offset by this routine and it will restore it to its original position. You should specify everything else just as you did originally, then just add these two keywords and their values: pdb_to_restore_position=my_offset_pdb_file_with_edits.pdb and pdb_restored_in_position=my_restored_pdb.pdb Nothing will be run except your pdb_to_restore_position will
    • pdb_trimmed = None Name of output PDB file trimmed to match cutout region.
    • log = cutout.log Output log file
    • params_out = cutout_params.eff Parameters file to rerun cutout
    • cutout_map_file_name = None File name for map file if cutout_as_map=True
    • cutout_mask_file_name = None File name for mask file if cutout_as_map=True
    • job_title = None Job title in PHENIX GUI, not used on command line
  • directories
    • temp_dir = "temp_dir" Optional temporary work directory
    • output_dir = "" Output directory where files are to be written
    • gui_output_dir = None
  • cutout_region
    • high_resolution = None Resolution of output map coeffs (default is high_resolution_scale times resolution of input map coeffs.) Purpose is to miminize truncation errors.
    • high_resolution_scale = 0.95 Resolution of output map coeffs will be high_resolution_scale* resolution of input map coeffs if high_resolution is None
    • cutout_center = None Center of region to be cut out. If cutout_center=None and pdb_in is specified, the center will be the molecular center of the molecule in pdb_in (after applying any atom selections specified with atom_selection.) If None and no pdb_in is specified, the center will be (0,0,0).
    • cutout_fix_position = False If True, then do not translate the density to the origin. Instead leave it in original position.
    • cutout_dimensions = None Dimensions (A) of region to be cut out. If None and pdb_in is specified, the region will be the the molecular dimensions of the molecule in pdb_in (after applying any atom selections specified with atom_selection), plus a distance cutout_model_radius. If box_scale is not defined, the unit cell for the cutout density will have dimensions specified by cutout_dimensions, increased by the distance padding=xxx on each side. If cutout_dimensions=10,10,10 and padding=5, then the unit cell will be (20,20,20). Otherwise if box_scale is defined, the unit cell will be box_scale times cutout_dimensions.
    • box_scale = None If defined, make the dimensions of the final cell box_scale times cutout_dimensions.
    • padding = 5 Padding of flat density to add around cutout density. The unit cell for the cutout density will have dimensions specified by cutout_dimensions, increased by the distance padding=xxx on each side. If cutout_dimensions is None, then the unit cell will be the molecular dimensions of the molecule in pdb_in, increased by padding on each side. If cutout_dimensions=10,10,10 and padding=5, then the unit cell will be approximately (20,20,20). Note that the unit cell dimensions may differ from this slightly as each must fall on an exact grid multiple of 12 and the cutout region will determine the grid.
    • cutout_type = *box sphere model If box and cutout_dimensions are specified, actual density will be replaced with flat density added outside the box defined with cutout_dimensions. If box and pdb_in are specified then the cut out region will be a box defined by the model plus a distance cutout_model_radius. If sphere is specified, then flat density will replace actual density outside of a sphere with radius cutout_sphere_radius. Cutout_dimensions will be the dimensions of the sphere. If model and pdb_in are specified then the cut out region will be the region defined by the model plus a distance cutout_model_radius. Flat density will replace actual density outside of region within cutout_model_radius of an atom in pdb_in.
    • cutout_sphere_radius = 10. If cutout_type is sphere, then flat density will replace actual density outside of a sphere with radius cutout_sphere_radius.
    • soft_mask = False If True and cutout_type is model, then create soft mask around density (Gaussian smoothing between density inside and outside mask). This will also increase the size of the box, sphere or region by about 2 times the buffer_radius, or by default 2 times the resolution of the map. Requires high_resolution to be set.
    • buffer_radius = None Buffer radius for mask smoothing. Default is resolution
    • map_scale = 1. You can scale the output map if you want to.
    • cutout_model_radius = 5. If cutout_type is model, then flat density will replace actual density outside of region within cutout_model_radius of an atom in pdb_in (after application of any selections specified with atom_selection.
    • cutout_subtract_mean = False If True, then mean density in cutout region will be calculated and subtracted from all the density in that region, yielding a mean of 0. This is recommended if the density is to be used in molecular replacement.
    • include_hetatm = True If True, then include HETATM atoms in input PDB file in defining density to be included (e.g., if cutout_type is model)
    • atom_selection = None Any selection specified with atom_selection is applied to input model before using the model.
    • cutout_as_map = False Return cut out region as map (alternative is map coeffs).
  • control
    • verbose = False Verbose output
    • raise_sorry = False Raise sorry if problems
    • debug = False Debugging output
    • dry_run = False Just read in and check parameter names
    • for_phaser = False Set defaults for phaser: cutout_fix_position=True, cutout_type=model, box_scale=3.0 (if not set explicitly), high_resolution is set to allow molecular transform to be interpolated to resolution of original map
    • resolve_command_list = None You can supply any resolve command here NOTE: for command-line usage you need to enclose the whole set of commands in double quotes (") and each individual command in single quotes (') like this: resolve_command_list="'no_build' 'b_overall 23' "