phenix_logo
Python-based Hierarchical ENvironment for Integrated Xtallography
Documentation Home
 

Correlation of two maps after accounting for origin shifts with get_cc_mtz_mtz

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

Author(s)

  • get_cc_mtz_mtz: Tom Terwilliger

Purpose

get_cc_mtz_mtz is a command line tool for adjusting the origin of a map so that the map superimposes on another map, and obtaining the correlation of the two maps. The maps are calculated from map coefficients supplied by the user in two mtz files.

Usage

How get_cc_mtz_mtz works:

get_cc_mtz_mtz calculates maps based on the supplied mtz files, then uses RESOLVE to find the origin shift compatible with space-group symmetry that maximizes the correlation of the two maps. This shift is applied to the second map and the correlation of the maps is calculated. Several parameters can be set by the user to define how the correlations are calculated. By default, maps are calculated using all the reflections present (to the specified high-resolution limit, if any) in each mtz file. If you specify

use_only_refl_present_in_mtz_1=True
Then the map calculated using your second mtz file will only include reflections that were present in your first mtz file. This removes the effects of missing reflections on the correlation. If you specify
scale=True
then get_cc_mtz_mtz scales the amplitudes from the second input mtz file to those in the first input mtz, including an overall B factor and a scale factor. This reduces effects of differences in overall B factors between the two mtz files on the correlation. If you specify
keep_f_mag=False
then get_cc_mtz_mtz uses amplitudes from the first input mtz file and phases and figure of merit from both to do the correlation. This has the effect of removing effects due to differences in amplitudes on the correlation, and focusing on differences in phases and figures of merit.

Output files from get_cc_mtz_mtz

offset.log: Log file for correlation calculation.

Examples

Standard run of get_cc_mtz_mtz:

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

phenix.get_cc_mtz_mtz map_coeffs_1.mtz  map_coeffs_2.mtz
If you want (or need) to specify the column names from your mtz file, you will need to tell get_cc_mtz_mtz what FP and PHIB (and optionally FOM) are, in this format:
phenix.get_cc_mtz_mtz map_coeffs_1.mtz  map_coeffs_2.mtz \
labin_1="FP=2FOFCWT PHIB=PH2FOFCWT"  labin_2="FP=2FOFCWT PHIB=PH2FOFCWT"

Possible Problems

Specific limitations and problems:

  • Versions of phenix.get_cc_mtz_mtz up to 1.3-final used a different set of defaults, with the values,
    scale=True 
    keep_f_mag=False 
    use_only_refl_present_in_mtz_1=True
    
    These defaults were changed after version 1.3-final in order to make the results independent of the order of the mtz files and to make the default be to get the correlation of maps without manipulation.
  • Literature

    Additional information

    List of all get_cc_mtz_mtz 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
    ------------------------------------------------------------------------------- 
    get_cc_mtz_mtz
       mtz_1= None MTZ file 1 with coefficients for a map
       mtz_2= None MTZ file 2 with coefficients for a map
       labin_1= "" Labin line for MTZ file 1 with map coefficients. This is
                optional if get_cc_mtz_mtz can guess the correct coefficients for
                FP PHI and FOM. Otherwise specify: LABIN FP=myFP PHIB=myPHI
                FOM=myFOM where myFP is your column label for FP
       labin_2= "" Labin line for MTZ file 2 with map coefficients. This is
                optional if get_cc_mtz_mtz can guess the correct coefficients for
                FP PHI and FOM. Otherwise specify: LABIN FP=myFP PHIB=myPHI
                FOM=myFOM where myFP is your column label for FP
       resolution= 0. high-resolution limit for map calculation
       low_resolution= 1000. low-resolution limit for map calculation
       offset_mtz= offset.mtz Output version of mtz file 2, offset to maximize
                   correlation with mtz file 1
       temp_dir= "temp_dir" Temporary work directory
       output_dir= "" Output directory where files are to be written
       gui_output_dir= None
       keep_f_mag= True If you set keep_f_mag=False then get_cc_mtz_mtz uses
                   amplitudes from the first input mtz file and phases and fom
                   from both to do the correlation. If you specify keep_f_mag=True
                   then the amplitudes from both files are included.
       scale= False If you set scale=True then get_cc_mtz_mtz scales the
              amplitudes from the second input mtz file to those in the first
              input mtz, including an overall B factor and a scale factor.
       use_only_refl_present_in_mtz_1= False You can specify that only reflections
                                       present in your first mtz file are used in
                                       the comparison. Note that this means that
                                       the order of the files will have an effect
                                       on the correlation coefficient
       any_offset= False You can search for a match with any offset even though
                   this is not allowed by space-group symmetry
       verbose= True Verbose output
       raise_sorry= False Raise sorry if problems
       debug= False Debugging output
       dry_run= False Just read in and check parameter names
       job_title= None Job title in PHENIX GUI, not used on command line