File: refine.txt
Last modified: 8-oct-2010

REFINE

  • NCS
  • CRYST_NCS
  • FLAT_B25
  • KICK_B_5
  • GEN_SOLVENT

    Controls interactive positional, B-value, and occupancy refinement of "WORK_SEGM" atoms. By clicking the right mouse button Tk GUI is used to invoke the configuration menus.

    KICK_XYZ

    KICK_XYZ displaces all "WORK_SEGM" atoms up to the current "KICK_VAL" shift.

    REF_ALL

  • NCS
  • CRYST_NCS

    
     create_refine_all.pl
     -h|--help)      prints this message with available options and current status
     -c|--cool)      sets number of cooling cycles [0]
    -v|--overall)   B-FACTOR REFINEMENT overall  [-1 off;>0 on] = [-1]
     -z|--xyz)       POSITIONAL REFINEMENT [ [ON/OFF] [ON]
     -b|--bfactor)   B-FACTOR REFINEMENT [ON/OFF] = [ON]
     -y|--occupancy) OCCUPANCY REFINEMENT [ON/OFF] = [OFF]
        --step)      steps of refinement [30]
     -1|--sigma)     sigma target for bond deviations  [0.005 - 0.1]
                     current = [0.02]
     -p|--p_kick)    sets starting and final maximal xyz kick [0.0 - 0.33]
                     current = [0 - 0]
     -m|--map)       MAP for DENSITY refinement [1]
     -u|--cutoff)    distance cutoff for nonbonded interactions [4.5]
    

    
     -2|--b_sigma)   sigma target for standard deviations of bonded B-values [1. - 10.]
                       current = [2]
     -k|--b_kick)    sets starting and final maximal B-kick [0 - 30] current = [0 - 0]
    -p|--bond)      B-value bond inter-group constrain force [-1.0 off;> 0.0 on] = [1.4]
    -g|--group)     B-value intra-group constrain force [-1.0 hard;> 0.0 soft] = [-1]
     -^|--border)    borders of min-max B-values [1 - 200]
    

    
     -n|--ncs)       NCS - Non-Cryst-Symmetry NCS energy flag [ON/OFF]
                     current = [OFF]
     -y|--cryst_ncs) Refine in variety of crystal forms [1/2/BOTH]: current = [OFF]
     -4|--gncs)      NCS Non-Cryst-Similarity geometry force = [5]
     -3|--fncs)      NCS Non-Cryst-Similarity B_value force  = [0.4]
     -t|--target)    TARGET FUNCTION for refinement [MAP/REAL_SPACE/LSQ/CROSS_COR/FREE_KICK/REFMAC/PHENIX]
                     current = [FREE_KICK]
     -f|--free)      r-free flag [ON/OFF] current [OFF]
     -l|--ml_kick)   kick ratio for ML function  [0.0 - 3.0] [0.5]
     -j|--tickle)    tickle for minimizer - negative is off [0.0 - 1.0] [-1]
     -a|--adjust)    adjust energy scale steps on the fly - negative is off [10]
     -7|--ml_aver)   averaging over last n AB coefifients for ML function  [1]
     -w|--way)       way of reciprocal space refinement [ACCURATE/FAST] [FAST]
     -r|--precision) precsion of x derivatives [3]
     -q|--grid)      map grid spacings per resolution [4]
     -j|--badd)      B factor add value /-999 leaves default [-9999]
     -x|--backup)    backup after each cycle [ON/OFF]: current = [OFF]
     -o|--output)    set file name of the created macro [refine_all.cmds]
        --doit)      create the macro
    

    Alternatively you can configure it via the command line interface by running the MAIN_CONF:create_refine_all.pl script by yourself.

    After the "refine_all.cmds" has been configured click "REF_ALL" to run it.

    The "MAP/DIFF/LSQ/ML/ML_EST/ML_APR" are target functions "-t|--target" that can be used in refinement. The "ML_EST" requires also an estimate of missing number of atoms "-a|--atoms". Pavel Afinine said that 25% error in estimate is still good enough.

    Maps used in refinement are defined by "-m|--map", "-x|--xmap", "-q|--qmap", whereas the strength of the target terms is controlled via the ratio between traget and chemistry terms. Geometry violations printed out during each step of refinemeny will tell you if your RATIO is too low or too high. (See also ANA_BOND and ANA_ANGL in MAIN_MENU:analysis.html).

    Before refinement it makes sense to "KICK_ALL" the atomic coordinates to jump out of the current state (heat the atoms to several 1000 K) and then let the minimizer cool down the molecule in the "fast cooling" procedure. Multiple kicks "-k|--kick" can be applied in a number of cooling cycles "-c|--cool", each cycle with the maximal along the line of the two specified kick values.

    Refinement output writes the "step" number, "stepsize", total energy "summ", average "gradient" and values for each particular energy term turned on. "Density" is the map constraint term, whereas "r-value" is only listed, its value changes only when structure factors are recalculated.

    Note that refinement using NCS across several crystal forms is possible too.

    
     step:     15      stepsize: 0.63802867E-13
     summ:    -6507.4916 grad:       24.2193 bond:      169.3255 angl:      663.3933
     dihe:     1206.1670 impr:      135.8787 vdw :     -236.2183 elec:    -4877.6440
     dens:    -3568.3938 rval:       37.0655
    

    Applying NCS constraints

    Non-Crystallographic-Symilarity Constraints can be applied between equivalent molecular parts of in principle unlimited number of equivalent regions within a single crystal as well as among several crystal forms.

    NCS

    When approaching the end of structure determination you are advised to edit the file "define_key_out.com" in order to remove the non-super imposable residues from the NCS constrains forces.

    
     key out sele .not all end
    < define_key_out.com
    

    The "define_key_out.com" macro would look something like this:

    
     key out sele ( seq  x1 x4 y16 : y27 ) \
             end
    

    The lines below show how it is possible to impose stronger NCS constraints on main chain atoms (FORCE 20.) and slightly weaker on the side chain atoms (FORCE 5.) An example MAIN_DOC:nmol/refine.cmds file is in the MAIN_DOC:nmol/ directory.

    
     define init constrain ncs
     define constraint ncs \
        sele ( segm name MOLA .a .not out ) .a atom name CA N C O H end
     define constraint ncs
        sele ( segm name MOLB .a .not out ) .a atom name CA N C O H end
     define constraint ncs force 20.
     define constraint ncs b-force 0.04
    

    
     define constraint ncs next
     define constraint ncs \
                 sele segm name MOLC .a .not atom name CA N C O H end
     define constraint ncs \
                 sele segm name MOLD .a .not atom name CA N C O H end
     define constraint ncs force 5.
     define constraint ncs b-force 0.01
    

    It does make sense to verify the success of the NCS groups creation. Since equivalent atoms are the consecutive ones in the both selections the NCS keys should contain at least the same number of atoms:

    
     show key
    

    
    SHOW> KEY:   9 int_ncs__1 SELECTED  254 OF TOTAL 6176
    SHOW> KEY:  10 int_ncs__2 SELECTED  254 OF TOTAL 6176
    

    The next more sever test (good for debugging) is to create PAIR lists and see, whether the equivalent atoms match by their atomic, residue and sequence names or not.

    
     make pair init select int_ncs__1 end select int_ncs__2 end
     write pair
    

    If you want to be sure the default initial guess will work well calculate the superposition parameters before the minimizer starts to work:

    
     define constraint ncs auto_guess
    

    
    RMS_FIT> PARAMETERS X-ROT: 191.373 Y-ROT": 111.292 X-ROT"":  35.276
    XYZ-TRAN:  88.258   6.726  15.660 RMS-FIT   .452"XYZ-TRAN:  88.258   6.726  15.660 RMS-FIT   .4520
    

    The "RMS-FIT" value should look reasonable. Values above 3. are very likely to mean that the selections are not properly defined and maybe that the procedure did not converge properly.

    Instead of leaving all 6 degrees of freedom (3 rotation axis and translation component) one can also fix some of the parameters (with flag exual 0), by providing initial guess and fixing the rotational axis (in thes case the 2-fold). Use of the matrix defined by polar angles is certainly the choice here:

    
     rms coor all eigen \
      sele segm name MOLB end sele segm name MOLA end
    

    
     show rms
    

    
     defin constr ncs polar \
           set_gues 2 RESULT_0 RESULT_1 180.0 RESULT_3 RESULT_4 RESULT_5 \
           flags 1 1 0 1 1 1
    

    The energy term is turn on with the NCS ON command

    
     energy ncs on
    

    CRYST_NCS

    When refining a molecular model in two or more crystal forms means that each model should interact with its own diffraction data and own unit cell. Converted to MAIN language it means, that each molecule should interact with its own crystal form difference Fourier map during a refinement procedure and that all energy interactions between the molecular models, besides the NCS term, should be excluded.

    The setup is done through the MAIN_CONF:create_main_config.pl , where segment IDs bind structrue to tehir crystal forms, which require cell constants file, space groups and diffraction data specified via theMAIN_CONF:create_read.pl.

    From a user perspective, apart from the above mentioned additional specifications, the case is not much different from the case with several molecules in one crystal form.

    OF course the cros "crystal" term should be on.

    FLAT_B25

    Flattens B-values of all "WORK_SEGM" atoms to 25.

    KICK_B_5

    Kicks B-values of all "WORK_SEGM" atoms with the maximum kick of 5.

    Overall B-value refinement

    Overall B-value refinement is based on Wilson plot statistics comparing Fobs and Fcalc in separate shells.

    
    > mini b-val overall sele segm name SEGMENTS end step 3
    

    Individual B-value refinement

    For B-value optimizations GROUPS have to be DEFINED. The group definitions are located at the top of a MAIN_CMDS:refine_b.cmds macro.

    The smallest group is an atom and the largest are all atoms. Between these two extremes any number of groups composed from any combination of atoms is valid. Currently GROUPS can be defined through SINGLE, ATOM, RESIDUE and SEGMENT command words. The GROUP SINGLE command defines single atoms group - each selected atom is a separate group. The GROUP ATOM defines all selected atoms as a group. The GROUP RESIDUE command DEFINES each selected residue as a group and the GROUP SEGMENT does the same on the segment level.

    
    > define init group
    > define group atom select all end
    > define group single select all end
    

    The MINIMAL and MAXIMAL atomic B-value specify in which limits can B-factors of individual atoms be optimized. Once defined, they serve as a contraints to return the "escaped" B-values into the defined limits.

    Oppose to the measured data, which try to scatter atomic B-values, several restraining terms try to make neighboring atomic B-values similar to each other. The ANGLE, BOND, GROUP force constants pull together B-values of groups that are linked by covalent BONDS or ANGLES. The smallest group (by default) is an individual atom. A GROUP restraint is hard when the GROUP force is set to a negative value. Otherwise atoms are pulled towards the arithmetic middle of each group. Negative BOND and ANGLE force constants turns these restrains off.

    
    > ener minimal = 5.0 \
    > maximal = 80. \
    > b-val bond = 1.444 \
    > b-val angle = 1.0 \
    > b-val group = -1.0
    

    Similarly as in position refinement, in B-valu refinement, the BOND RMS deviations serve as the aim to derive the scaling constant.

    
    > mini b-val 2.0
    

    is the default.

    Besides, non-crystallographic-similarity, NCS, constraints can be applied. These constraints refer to the same groups which are used in positional refinement. See MAIN_DOC:nmol/refine.cmds. The NCS B-FORCE constant pulls the B-values of similar atoms towards their arithmetic middle.

    
    > define constr ncs b-force 0.1
    

    Before start of minimization B-values of selected atoms can be kicked in order to shift refinement from the current (local minimum) position.

    
    > set temp kick = 4. sele segm name SEGMENTS .and. weight 0.1 1.1 end
    

    B-value for refinement with an ENERGY command and then start MINIMIZATION. Command below submits 10 cycles of B-VALUE refinement. Energies will be WRITTEN each iteration step.

    
    > mini b-val indiv  sele segm name SEGMENTS end step 10 writ 1
    

    An equilibrated assignment of B-VALUE scales is essential for a succesfull refinement. Values as BOND 1.0 for example result in an equal B-value for all atoms. After refining a structure check the B-VALUES sigmas with a SHOW TEMPERATURE command, and if necessary increase or release the force of constraining terms.

    See also to the MAIN_DOC:1mol/1mol.html example.

    Subroutine arguments:

    For more see MAIN_DOC:refine/refine.html.

    GEN_SOLVENT

    
     create_gen_solv.pl
      -h|--help)      prints this message with available options and current status
      -b|--b_value)   B-value cut for previous rounds in WAT [70.0]
      -p|--peak)      peak threshold in diff density map (fo-fc) [2.3]
      -d|--density)   density map (2fo-fc) cutoff [1.1]
      -c|--close)     the closest density pick existing atom distance [2.3]
      -e|--empty)     the distance to the closest empty occupancy atom [4.5]
      -f|--far)       the farthest density pick distance to an existing atom [4.5]
      -m|--merge)     remove symmetry related peaks if they get closer than [2.3]
    -l|--list)      key "check_list" contains residues closer than [2.5] to peaks
    -i|--ion)       key "ion_list" conatins WAT atoms with fo-fc dens higher than [2.0]
      -w|--what)      what to do: [CHECK/NEW/BOTH] [BOTH]
         --doit)      create the macro
    

    Generates new solvent molecules on the basis of peaks in a difference density map, checks their consistency within an 2Fo-Fc map, their distance to hydrogen bond donors and overlap with already existing atoms and symmetry overlap.

    The newly created solvent molecule (H2O) obtain segment name WAT2. HINT: Modify your RE_IMAGE command to see the newly created solvents in a different color.

    The macro invoked by default is the file MAIN_CMDS:gen_solvent.cmds, which calls MAIN_UTILS:gen_solvent.com, created by "menu_gen_solv.sh" script.

    Subroutine "gen_solvent.com" arguments: