phenix_logo
Python-based Hierarchical ENvironment for Integrated Xtallography
Documentation Home
 

Structure factor file manipulations with Xmanip

Author(s)
Purpose
Usage
Command line interface
Parameters and definitions
Examples
Possible Problems
Literature
Additional information
List of all xmanip keywords

Author(s)

  • Xmanip: Peter Zwart
  • Phil command interpreter: Ralf W. Grosse-Kunstleve

Purpose

Manipulation of reflection data and models

Usage

Command line interface

xmanip can be invoked via the command line interface with instructions given in a specific definition file:

  phenix.xmanip params.def
The full set of definitions can be obtained by typing:
  phenix.xmanip
which results in::
  xmanip {
    input {
      unit_cell = None
      space_group = None
      xray_data {
        file_name = None
        labels = None
        label_appendix = None
        name = None
        write_out = None
      }
      model {
        file_name = None
      }
    }
    parameters {
      action = reindex manipulate_pdb *manipulate_miller
      reindex {
        standard_laws = niggli *reference_setting invert user_supplied
        user_supplied_law = "h,k,l"
      }
      manipulate_miller {
        task = get_dano get_diso lsq_scale sfcalc *custom None
        output_label_root = "FMODEL"
        get_dano {
          input_data = None
        }
        get_diso {
          native = None
          derivative = None
          use_intensities = True
          use_weights = True
          scale_weight = True
        }
        lsq_scale {
          input_data_1 = None
          input_data_2 = None
          use_intensities = True
          use_weights = True
          scale_weight = True
        }
        sfcalc {
          fobs = None
          output = *2mFo-DFc mFo-DFc complex_fcalc abs_fcalc intensities
          use_bulk_and_scale = *as_estimated user_upplied
          bulk_and_scale_parameters {
            d_min = 2
            overall {
              b_cart {
                b_11 = 0
                b_22 = 0
                b_33 = 0
                b_12 = 0
                b_13 = 0
                b_23 = 0
              }
              k_overall = 0.1
            }
            solvent {
              k_sol = 0.3
              b_sol = 56
            }
          }
        }
        custom{
          code = print >> out, "hello world"
        }
      }

      manipulate_pdb{
        task = apply_operator *set_b
        apply_operator{
          operator = "x,y,z"
          invert=False
          concatenate_model=False
          chain_id_increment=1
        }
        set_b{
          b_iso = 30
        }
      }
    }
    output {
      logfile = "xmanip.log"
      hklout = "xmanip.mtz"
      xyzout = "xmanip.pdb"
    }
  }
Detailed explanation of the scopes follow below.

Parameters and definitions

The xmanip.input scope defines which files and which data xmanip reads in::

    input {
      unit_cell = None        # unit cell. Specify when not in reflection or pdb files
      space_group = None      # space group. Specify when not in reflection or pdb files
      xray_data {
        file_name = None      # File from which data will be read
        labels = None         # Labels to read in.
        label_appendix = None # Label appendix: when writing out the new mtz file, this appendix will be added to the current label.
        name = None           # A data set name. Useful for manipulation
        write_out = None      # Determines if this data set will be written to the final mtz file
      }
      model {
        file_name = None      # An input pdb file
      }
    }
One can define as many sub-scopes of xray_data as desired (see examples). The specific tasks of xmanip are controlled by the xmanip.parameters.action key. Possible options are:
  • reindex
  • manipulate_pdb
  • manipulate_miller
Reindexing: reindexing of a data set (and a model) is controlled by the xmanip.parameters.reindex scope. Standard laws are available:
  • niggli: Brings unit cell to the niggli setting.
  • reference_setting: Brings space group to the reference setting
  • invert: Inverts a data set
  • user_supplied: A user supplied reindexing law is used, specified by reindex.user_supplied_law
manipulate_pdb: A pdb file can be modified by either applying a symmetry operator to the coordinates (select the apply_operator task from the manipulate_pdb.task list. The operator needs to be specified by apply_operator.operator. Setting apply_operator.invert to true will invert the supplied operator. One can choose to put out the newly generated chain with the original chain (set concatenate_model = True). The new chain ID can be controlled with the chain_id_increment parameter. manipulate miller: Reflection data can be manipulate in various ways:
  • get_dano: Get anomalous differences from the data set with name specified by manipulate_miller.get_dano.input_data.
  • get_diso: Get isomorphous differences (derivative-native) from the data sets specified by the names manipulate_miller.get_diso.native and manipulate_miller.get_diso.derivative. Least squares scaling of the derivative to the native can be done on intensities (use_intensities=True), with or without using sigmas (use_weights) and by scaling the weights if desired (recommended).
  • lsq_scale : As above, no isomorphous difference are computed, only input_data_2 is scaled and returned.
  • sfcalc: Structure factor calculation. Requires a pdb file to be read in. Possible output coefficients are
  • 2mFo-DFc (Fobs required. specify sfcalc.fobs).
  • mFo-DFc (Fobs required. specify sfcalc.fobs).
  • complex_fcalc (FC,PHIC)
  • abs_fcalc (FC)
  • intensities (FC^2)
bulk solvent and scaling parameters will be either estimated from observed data if supplied, or set by the user (using keywords in the bulk_and_scale_parameters scope)
  • custom: If custom is selected, all data names for the xray data will become variable names accessible via the custom interface. The ``custom`` interface allows one to write a small piece of python code that directly works with the python objects them self. Basic knowledge of the cctbx and python are needed to bring this to a fruitful ending. Please contact the authors for detailed help if required. An example is given in the example section.

Examples

Reindexing a data set and model ::

  xmanip {
    input {
      xray_data {
        file_name = mydata.mtz
        labels = FOBS,SIGFOBS
        write_out = True
      }
      xray_data {
        file_name = mydata.mtz
        labels = R_FREE_FLAG
        write_out = True
      }
      model {
        file_name = mymodel.pdb
      }
    }
    parameters {
      action = reindex
      reindex {
        standard_laws = *niggli
        user_supplied_law = "h,k,l"
      }
    }
    output {
      logfile = "xmanip.log"
      hklout = "reindex.mtz"
      xyzout = "reindex.pdb"
    }
  }

Applying a symmetry operator to a pdb file ::

  xmanip {
    input {
      model {
        file_name = mymodel.pdb
      }
    }
    parameters {
      action = manipulate_pdb
      manipulate_pdb {
        task = apply_operator
        apply_operator{
          operator = "x+1/3,y-2/3,z+1/8"
        }
      }
    }
    output {
      logfile = "xmanip.log"
      xyzout = "shifted.pdb"
    }
  }

Printing out some useful information for an mtz file ::

  xmanip {
    input {
      xray_data {
        file_name = mydata.mtz
        labels = FOBS,SIGFOBS
        name = fobs
      }
    }
    parameters {
      action = custom
      custom{
        code = """
  print >> out, "Printing d_spacings, epsilons and intensities"
  #change amplitude to intensities
  fobs = fobs.f_as_f_sq()
  #get epsilons
  epsilons = fobs.epsilons().data().as_double()
  #get d spacings
  d_hkl = fobs.d_spacings().data()
  #print the lot to a file
  output_file = open("jiffy_result.txt", 'w')
  for ii, eps, dd in zip( fobs.data(), epsilons, d_hkl):
    print >> output_file, ii, eps, dd
  print >> out, "Done"
               """
      }
    }
  }

Possible Problems

None

Literature

None

Additional information

List of all xmanip 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
------------------------------------------------------------------------------- 
xmanip
   input
      unit_cell= None Unit cell parameters
      space_group= None space group
      xray_data Scope defining xray data. Multiple scopes are allowed
         file_name= None file name
         labels= None A unique label or unique substring of a label
         label_appendix= None Label appendix for output mtz file
         name= None An identifier of this particular miller array
         write_out= None Determines if this data is written to the output file
      model A model associated with the miller arrays. Only one model can be
            defined.
         file_name= None A model file
   parameters
      action= *reindex manipulate_pdb manipulate_miller Defines which action
              will be carried out.
      reindex Reindexing parameters. Acts on coordinates and miller arrays.
         standard_laws= niggli *reference_setting primitive_setting invert
                        user_supplied Choices of reindexing operators. Will be
                        applied on structure and miller arrays.
         user_supplied_law= 'h,k,l' User supplied operator.
      manipulate_miller Acts on a single miller array or a set of miller
                        arrays.
         task= *get_dano get_diso lsq_scale sfcalc custom None Possible tasks
         output_label_root= None Output label root
         get_dano Get ||F+| - |F-|| from input data.
            input_data= None
         get_diso Get |Fder|-|Fnat|
            native= None Name of native data
            derivative= None Name of derivative data
            use_intensities= True Scale on intensities
            use_weights= True Use experimental sigmas as weights in scaling
            scale_weight= True Whether or not to scale the sigmas during
                          scaling
         lsq_scale
            input_data_1= None Reference data
            input_data_2= None Data to be scaled
            use_intensities= True Scale on intensities
            use_weights= True Use experimental sigmas as weights in scaling
            scale_weight= True Whether or not to scale the sigmas during
                          scaling
         sfcalc
            fobs= None Data name of observed data
            output= 2mFo-DFc mFo-DFc *complex_fcalc abs_fcalc intensities 
                   Output coefficients
            use_bulk_and_scale= *as_estimated user_upplied estimate or use
                                parameters given by user
            bulk_and_scale_parameters Parameters used in the structure factor
                                      calculation. Ignored if experimental
                                      data is given
               d_min= 2.0 resolution of the data to be calculated.
               overall Bulk solvent and scaling parameters
                  k_overall= 0.1 Overall scalar
                  b_cart Anisotropic B values
                     b_11= 0
                     b_22= 0
                     b_33= 0
                     b_12= 0
                     b_13= 0
                     b_23= 0
               solvent Solvent parameters
                  k_sol= 0.3 Solvent scale
                  b_sol= 56.0 Solvent B
         custom A custom script that uses miller_array data names as variables.
            code= None A piece of python code
            show_instructions= True Some instructions
      manipulate_pdb Manipulate elements of a pdb file
         task= set_b apply_operator *None How to manipulate a pdb file
         set_b
            b_iso= 30 new B value for all atoms
         apply_operator
            standard_operators= *user_supplied_operator
                                user_supplied_cartesian_rotation_matrix 
                               Possible operators
            user_supplied_operator= "x,y,z" Actualy operator in x,y,z notation
            invert= False Invert operator given above before applying on
                    coordinates
            concatenate_model= False Determines if new chain is concatenated
                               to old model
            chain_id_increment= 1 Cain id increment
            user_supplied_cartesian_rotation_matrix Rotation,translation
                                                    matrix in cartesian frame
               r= None Rotational part of operator
               t= None Translational part of operator
   output Output files
      logfile= xmanip.log Logfile
      hklout= xmanip.mtz Ouptut miller indices and data
      xyzout= xmanip.pdb output PDB file