phenix_logo
Python-based Hierarchical ENvironment for Integrated Xtallography
Documentation Home
 

Cutting density out of a map with cut_out_density

Author(s)
Purpose
Usage
How cut_out_density works:
Output files from cut_out_density
Examples
Standard run of cut_out_density:
Possible Problems
Specific limitations and problems:
Literature
Additional information
List of all cut_out_density keywords

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

Possible Problems

Specific limitations and problems:

Literature

Additional information

List of all cut_out_density keywords

------------------------------------------------------------------------------- 
Legend: black bold - scope names
        black - parameter names
        red - parameter values
        blue - parameter help
        blue bold - scope help
        Parameter values:
          * means selected parameter (where multiple choices are available)
          False is No
          True is Yes
          None means not provided, not predefined, or left up to the program
          "%3d" is a Python style formatting descriptor
------------------------------------------------------------------------------- 
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
   directories
      temp_dir= "temp_dir" Optional temporary work directory
      output_dir= "" Output directory where files are to be written
   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.
      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
      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' "